[docs]: Clarify interactions with aliased names.

2 files changed, 53 insertions, 15 deletions

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