[groff] 08/08: Recast description of .als request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d7dff68220fd32cda264fd1470e7804ef782edab
Author: G. Branden Robinson <address@hidden>
AuthorDate: Mon May 18 22:37:44 2020 +1000

    Recast description of .als request.
    
    Similar to previous commit, 8e377599210062e540ab55482de996a864dc432b.
    
    * doc/groff.texi: Replace characterization of "exact equivalence" and
      analogy to Unix filesystem hard and soft links with more direct
      explanation.  Use @error{} command instead of @result{} for error
      output.  Update error message in example to reflect change in
      diagnostic message made in 1992 (:-|).  Rework explanation of example
      to make it more intelligible (to my brain, anyway).  Add @xref{} to
      "Writing Macros" node, which provides helpful context.  Talk about
      "removing" an alias instead of "undoing" it.  Add conceptual index
      (@cindex) node for discussion of when objects get created.
    
    * man/groff.7.man: Update terse description of .als.
    
    * man/groff_diff.7.man: Parallelize with Texinfo recast.
---
 doc/groff.texi       | 46 ++++++++++++++++++++++---------------------
 man/groff.7.man      | 12 +++++++++---
 man/groff_diff.7.man | 55 +++++++++++++++++++++++++++++++++-------------------
 3 files changed, 68 insertions(+), 45 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 1d35d71..145ea0f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10634,19 +10634,18 @@ treats subsequent invocations as if the object had 
never been defined.
 @cindex string, creating alias (@code{als})
 @cindex macro, creating alias (@code{als})
 @cindex diversion, creating alias (@code{als})
-Create an alias named @var{new} for the request, string, macro, or
-diversion object named @var{old}.  The new name and the old name are
-exactly equivalent (it is similar to a hard rather than a soft link).  If
-@var{old} is undefined, @code{gtroff} generates a warning of type
-@samp{mac} and ignores the request.
+Create an alias @var{new} for the existing request, string, macro, or
+diversion object named @var{old}, causing the names to refer to the same
+stored object.  If @var{old} is undefined, a warning of type @samp{mac}
+is generated and the request is ignored.
 
 To understand how the @code{als} request works it is probably best to
 think of two different pools: one pool for objects (macros, strings,
-etc.), and another one for names.  As soon as an object is defined,
-@code{gtroff} adds it to the object pool, adds its name to the name
-pool, and creates a link between them.  When @code{als} creates an
-alias, it adds a new name to the name pool that gets linked to the same
-object as the old name.
+etc.), and another for names.  As soon as an object is defined, GNU
+@code{troff} adds it to the object pool, adds its name to the name pool,
+and creates a link between them.  When @code{als} creates an alias, it
+adds a new name to the name pool that gets linked to the same object as
+the old name.
 
 Now consider this example.
 
@@ -10661,15 +10660,17 @@ Now consider this example.
 ..
 .
 .bar
-    @result{} input stack limit exceeded
+    @error{} input stack limit exceeded
+    @error{} (probable infinite loop)
 @endExample
 
 @noindent
-The definition of macro @code{bar} replaces the old object this name is
-linked to.  However, the alias to @code{foo} is still active!  In
-other words, @code{foo} is still linked to the same object as
-@code{bar}, and the result of calling @code{bar} is an infinite,
-recursive loop that finally leads to an error.
+In the above, @code{bar} remains an @emph{alias}---another name
+for---the object referred to by @code{foo}, which the second @code{de}
+request replaces.  Alternatively, imagine that the @code{de} request
+@emph{dereferences} its argument before replacing it.  Either way, the
+result of calling @code{bar} is a recursive loop that finally leads to
+an error.  @xref{Writing Macros}.
 
 @cindex alias, string, removing (@code{rm})
 @cindex alias, macro, removing (@code{rm})
@@ -10680,8 +10681,8 @@ recursive loop that finally leads to an error.
 @cindex string, removing alias (@code{rm})
 @cindex macro, removing alias (@code{rm})
 @cindex diversion, removing alias (@code{rm})
-To undo an alias, simply call @code{rm} on the aliased name.  The object
-itself is not destroyed until there are no more aliases.
+To remove an alias, simply call @code{rm} on its name.  The object
+itself is not destroyed until it has no more names.
 @endDefreq
 
 @Defreq {chop, xx}
@@ -11212,11 +11213,12 @@ Using @file{trace.tmac}, you can trace calls to 
@code{am} and
 @xref{Strings}, for the @code{als} and @code{rn} request to create an
 alias and rename a macro, respectively.
 
-The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and @code{as}
+@cindex object creation
+The @code{am}, @code{as}, @code{da}, @code{de}, @code{di}, and @code{ds}
 requests (together with their variants) only create a new object if the
-name of the macro, diversion or string is currently undefined
-or if it is defined to be a request; normally they modify the value of
-an existing object.
+name of the macro, diversion, or string is currently undefined or if it
+is defined as a request; normally, they modify the value of an existing
+object.
 
 @Defreq {return, [@Var{anything}]}
 Exit a macro, immediately returning to the caller.
diff --git a/man/groff.7.man b/man/groff.7.man
index 9104e04..f71598e 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1181,9 +1181,15 @@ for existing number register named
 .IR old .
 .
 .TPx
-.REQ .als "alias object"
-Create alias name for request, string, macro, or diversion
-.IR object .
+.REQ .als "new old"
+Create alias
+(additional name)
+.I new
+for existing request,
+string,
+macro,
+or diversion
+.IR old .
 .
 .TPx
 .REQ .am "macro"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index dda4f03..a85ccf6 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -757,32 +757,47 @@ more names.
 .
 .
 .TP
-.BI .als\~ xx\~yy
+.BI .als\~ "new old"
 Create an alias
-.I xx
-for request, string, macro, or diversion object named
-.IR yy .
-.
-The new name and the old name are exactly equivalent (it is
-similar to a hard rather than a soft link).
+.I new
+for the existing request,
+string,
+macro,
+or diversion named
+.IR old ,
+causing the names to refer to the same stored object.
 .
 If
-.I yy
-is undefined, a warning of type
-.B mac
-is generated, and the request is ignored.
+.I old
+is undefined,
+a warning of type
+.RB \[lq] mac \[rq]
+is generated and the request is ignored.
 .
 The
-.BR de ,
-.BR am ,
-.BR di ,
-.BR da ,
-.BR ds ,
+.BR .am ,
+.BR .as ,
+.BR .da ,
+.BR .de ,
+.BR .di ,
 and
-.B as
-requests only create a new object if the name of the macro, diversion
-or string is currently undefined or if it is defined to be a
-request; normally they modify the value of an existing object.
+.B .ds
+requests
+(together with their variants)
+only create a new object if the name of the macro,
+diversion,
+or string is currently undefined
+or if it is defined as a request;
+normally,
+they modify the value of an existing object.
+.
+To remove an alias,
+simply call
+.B .rm
+on its name.
+.
+The object itself is not destroyed until it has no more names.
+.
 .
 .TP
 .BI .am1\~ xx\~yy