[groff] 07/08: Recast descriptions of .aln and .rr requests.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 8e377599210062e540ab55482de996a864dc432b
Author: G. Branden Robinson <address@hidden>
AuthorDate: Mon May 18 21:41:41 2020 +1000

    Recast descriptions of .aln and .rr requests.
    
    "The new name and the old name are exactly equivalent." was not helpful
    to me in understanding the alias mechanism.  Moreover, aliases in groff
    do not work like lexical substitutions (which are a significant theme in
    the rest of the language).
    
    Parallelize descriptions between Texinfo manual and groff_diff(7), and
    use abbreviated description in groff(7).  Use same metasyntactic
    argument names in all three places.  The pair "new" and "old" are not
    perfect, but better than "xx" and "yy" (follwing CSTR #54) which
    communicate nothing; "ident1" and "ident2" (same); or "alias" and
    "register" which could imply a kind of second-order or subordinate
    status for the alias.  I think this is what "The new name and the old
    name are exactly equivalent." was trying to get across, but there is
    obviously a sense in which they aren't--strcmp(), for example (although
    ".aln a a" on an existing number register 'a' does work as a no-op).
    
    Update description of .rr request to note that, technically, it deletes
    names rather than the objects themselves.  Parallelize metasyntactic
    argument name between Texinfo manual and groff(7).
---
 doc/groff.texi       | 21 ++++++++++++++++-----
 man/groff.7.man      | 15 +++++++++------
 man/groff_diff.7.man | 28 +++++++++++++++++++---------
 3 files changed, 44 insertions(+), 20 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 40d1ab6..1d35d71 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -5777,7 +5777,9 @@ with a @samp{0}:
 @cindex number register, removing (@code{rr})
 @cindex register, removing (@code{rr})
 Remove number register @var{ident}.  If @var{ident} doesn't exist, the
-request is ignored.
+request is ignored.  Technically, only the name is removed; the
+register's contents are still accessible under aliases created with
+@code{aln}, if any.
 @endDefreq
 
 @Defreq {rnn, ident1 ident2}
@@ -5788,15 +5790,24 @@ Rename number register @var{ident1} to @var{ident2}.  
If either
 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
 @endDefreq
 
-@Defreq {aln, ident1 ident2}
+@Defreq {aln, new old}
 @cindex alias, number register, creating (@code{aln})
 @cindex creating alias, for number register (@code{aln})
 @cindex number register, creating alias (@code{aln})
 @cindex register, creating alias (@code{aln})
-Create an alias @var{ident1} for a number register @var{ident2}.  The
-new name and the old name are exactly equivalent.  If @var{ident1} is
-undefined, a warning of type @samp{reg} is generated, and the request is
+Create an alias @var{new} for an existing number register @var{old},
+causing the names to refer to the same stored object.  If @var{old} is
+undefined, a warning of type @samp{reg} is generated and the request is
 ignored.  @xref{Debugging}, for information about warnings.
+
+@cindex alias, number register, removing (@code{aln})
+@cindex removing alias, for number register (@code{aln})
+@cindex number register, removing alias (@code{aln})
+@cindex register, removing alias (@code{aln})
+To remove a number register alias, call @code{rr} on its name.  A number
+register's contents do not become inaccessible until it has no more
+names.
+
 @endDefreq
 
 @c ---------------------------------------------------------------------
diff --git a/man/groff.7.man b/man/groff.7.man
index 9bf7bfe..9104e04 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1173,9 +1173,12 @@ to
 (\f[CI]c\/\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
 .
 .TPx
-.REQ .aln "alias register"
-Create alias name for
-.IR register .
+.REQ .aln "new old"
+Create alias
+(additional name)
+.I new
+for existing number register named
+.IR old .
 .
 .TPx
 .REQ .als "alias object"
@@ -2327,9 +2330,9 @@ to
 .IR reg2 .
 .
 .TPx
-.REQ .rr "register"
-Remove
-.IR register .
+.REQ .rr "ident"
+Remove name of number register
+.IR ident .
 .
 .TPx
 .REQ .rs
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 91ca7d8..dda4f03 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -733,18 +733,28 @@ does not ignore the terminating newline.
 .\" ====================================================================
 .
 .TP
-.BI .aln\~ xx\~yy
+.BI .aln\~ "new old"
 Create an alias
-.I xx
-for number register object named
-.IR yy .
-The new name and the old name are exactly equivalent.
+.I new
+for an existing number register named
+.IR old ,
+causing the names to refer to the same stored object.
 .
 If
-.I yy
-is undefined, a warning of type
-.B reg
-is generated, and the request is ignored.
+.I old
+is undefined,
+a warning of type
+.RB \[lq] reg \[rq]
+is generated and the request is ignored.
+.
+To remove a number register alias,
+call
+.B .rr
+on its name.
+.
+A number register's contents do not become inaccessible until it has no
+more names.
+.
 .
 .TP
 .BI .als\~ xx\~yy