[groff] 06/18: [docs]: Clarify interactions with aliased names.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5476a2819db2c1f31d60829b9670b9e93a254c9b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Apr 1 18:27:28 2023 -0500

    [docs]: Clarify interactions with aliased names.
---
 doc/groff.texi       | 59 +++++++++++++++++++++++++++++-----------------------
 man/groff.7.man      | 55 +++++++++++++++++++++++++++++++++++-------------
 man/groff_diff.7.man | 13 ++++++++++++
 3 files changed, 86 insertions(+), 41 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 70f0481e0..2603c63f8 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -464,7 +464,7 @@ Documentation License''.
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle Edition 1.23.0
-@subtitle March 2023
+@subtitle April 2023
 @author Trent@tie{}A.@: Fisher
 @author Werner Lemberg
 @author G.@tie{}Branden Robinson
@@ -2688,8 +2688,7 @@ Set register @var{reg} to @var{value}.  If @var{reg} 
doesn't exist, GNU
 @endDefreq
 
 @Defreq {ds, name contents}
-Set string @var{name} to @var{contents}.  If @var{name} exists, it is
-removed first.
+Set string @var{name} to @var{contents}.
 @endDefreq
 
 A list of document control registers and strings follows.  For any
@@ -12166,9 +12165,9 @@ warnings.
 @cindex string arguments
 @cindex arguments, of strings
 Define a string called @var{name} with contents @var{contents}.  If
-@var{name} already exists, it is removed first (see @code{rm} below).
-If @code{ds} is called with only one argument, @var{name} is defined as
-an empty string.
+@var{name} already exists as an alias, the target of the alias is
+redefined; see @code{als} and @code{rm} below.  If @code{ds} is called
+with only one argument, @var{name} is defined as an empty string.
 
 The @code{\*} escape sequence interpolates a previously defined string
 variable @var{name} (one-character name@tie{}@var{n}, two-character name
@@ -12479,6 +12478,11 @@ an error.  @xref{Writing Macros}.
 @cindex diversion, removing alias for (@code{rm})
 To remove an alias, call @code{rm} on its name.  The object itself is
 not destroyed until it has no more names.
+
+When a request, macro, string, or diversion is aliased, redefinitions
+and appendments ``write through'' alias names.  To replace an alias with
+a separately defined object, you must use the @code{rm} request on its
+name first.
 @endDefreq
 @c END Keep (roughly) parallel with section "Strings" of groff(7).
 
@@ -13003,22 +13007,23 @@ defined as empty.  @xref{Identifiers}.
 
 @Defreq {de, name [@Var{end}]}
 Define a macro @var{name}, replacing the definition of any existing
-request, macro, string, or diversion called @var{name}.  GNU
-@code{troff} enters ``copy mode'', storing subsequent input lines as the
-macro definition.  If the optional second argument is not specified, the
-definition ends with the control line @samp{..} (two dots).
-Alternatively, @var{end} identifies a macro whose call syntax at the
-start of a control line ends the definition of @var{name}; @var{end} is
-then called normally.  A macro definition must end in the same
-conditional block (if any) in which it began (@pxref{Conditional
-Blocks}).  Spaces or tabs are permitted after the control character in
-the line containing this ending token (either @samp{.} or
-@samp{@var{end}}), but a tab immediately after the token prevents its
-recognition as the end of a macro definition.  The macro @var{end} can
-be called with arguments.@footnote{While it is possible to define and
-call a macro @samp{.}, you can't use it as an end macro: during a macro
-definition, @samp{..} is never handled as calling @samp{.}, even if
-@samp{.de @var{name} .} explicitly precedes it.}
+request, macro, string, or diversion called @var{name}.  If
+@var{name} already exists as an alias, the target of the alias is
+redefined; recall @ref{Strings}.  GNU @code{troff} enters ``copy mode'',
+storing subsequent input lines as the macro definition.  If the optional
+second argument is not specified, the definition ends with the control
+line @samp{..} (two dots).  Alternatively, @var{end} identifies a macro
+whose call syntax at the start of a control line ends the definition of
+@var{name}; @var{end} is then called normally.  A macro definition must
+end in the same conditional block (if any) in which it began
+(@pxref{Conditional Blocks}).  Spaces or tabs are permitted after the
+control character in the line containing this ending token (either
+@samp{.} or @samp{@var{end}}), but a tab immediately after the token
+prevents its recognition as the end of a macro definition.  The macro
+@var{end} can be called with arguments.@footnote{While it is possible to
+define and call a macro @samp{.}, you can't use it as an end macro:
+during a macro definition, @samp{..} is never handled as calling
+@samp{.}, even if @samp{.de @var{name} .} explicitly precedes it.}
 @c
 @c @Example
 @c .de .
@@ -14947,10 +14952,12 @@ create and alter diversions.
 @cindex appending to a diversion (@code{da})
 @cindex diversion, appending (@code{da})
 Start collecting formatted output in a diversion called @var{name}.  The
-@code{da} request appends to the existing diversion called @var{name},
-creating it if necessary.  The pending output line is diverted as well.
-Switching to another (empty) environment (with the @code{ev} request)
-avoids the inclusion of the current partially collected line;
+@code{da} request appends to a diversion called @var{name}, creating it
+if necessary.  If @var{name} already exists as an alias, the target of
+the alias is replaced or appended to; recall @ref{Strings}.  The pending
+output line is diverted as well.  Switching to another environment (with
+the @code{ev} request) before invoking @code{di} or @code{da} avoids
+including any pending output line in the diversion; see
 @ref{Environments}.
 
 Invoking @code{di} or @code{da} without an argument stops diverting
diff --git a/man/groff.7.man b/man/groff.7.man
index ab459eb78..688bdd1cc 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5220,14 +5220,26 @@ or
 .P
 The
 .request .ds
-request creates a string with a specified name and contents and the
-.esc *
-escape sequence dereferences its name,
-interpolating the contents.
+request creates a string with a specified name and contents.
+.
+If the identifier named by
+.request .ds
+already exists as an alias,
+the target of the alias is redefined.
+.
+If
+.request .ds
+is called with only one argument,
+the named string becomes empty.
 .
-If the string named by the
+.
+.P
+The
 .esc *
-escape sequence does not exist,
+escape sequence dereferences a string's name,
+interpolating its contents.
+.
+If the name does not exist,
 it is defined as empty,
 nothing is interpolated,
 and a warning in category
@@ -5237,8 +5249,6 @@ is emitted.
 See section \[lq]Warnings\[rq] in
 .MR @g@troff 1 .
 .
-.
-.P
 The bracketed interpolation form accepts arguments that are handled as
 macro arguments are;
 see section \[lq]Calling macros\[rq] above.
@@ -5360,9 +5370,20 @@ and aliasing
 .request .rn ,
 .request .rm ,
 .request .als).
-.\" END Keep (roughly) parallel with groff.texi node "Strings".
 .
 .
+.P
+When a request,
+macro,
+string,
+or diversion is aliased,
+redefinitions and appendments \[lq]write through\[rq] alias names.
+.
+To replace an alias with a separately defined object,
+you must use the
+.B rm
+request on its name first.
+.\" END Keep (roughly) parallel with groff.texi node "Strings".
 .
 .
 .\" ====================================================================
@@ -6346,11 +6367,11 @@ see
 .
 The
 .B .de
-request defines a macro replacing the definition of any existing
-request,
-macro,
-string,
-or diversion of the same name.
+request defines a macro named for its argument.
+.
+If that name already exists as an alias,
+the target of the alias is redefined;
+see section \[lq]Strings\[rq] above.
 .
 .I @g@troff
 enters \[lq]copy mode\[rq]
@@ -6738,9 +6759,13 @@ request creates a diversion,
 including any partially collected line.
 .
 .B da
-appends to an existing diversion,
+appends to a diversion,
 creating one if it does not already exist.
 .
+If the diversion's name already exists as an alias,
+the target of the alias is replaced or appended to;
+see section \[lq]Strings\[rq] above.
+.
 .B box
 and
 .B boxa
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 1e0ecd8a4..e1a17c598 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1270,6 +1270,19 @@ on its name.
 The object itself is not destroyed until it has no more names.
 .
 .
+.IP
+When a request,
+macro,
+string,
+or diversion is aliased,
+redefinitions and appendments \[lq]write through\[rq] alias names.
+.
+To replace an alias with a separately defined object,
+you must use the
+.B rm
+request on its name first.
+.
+.
 .TP
 .BI .am1\~ xx\~yy
 Similar to