[groff] 09/12: [docs]: Fix content, style nits re: strings.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1fd04772d69b235b4921f8e0f1b9fc12ded69b60
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Nov 5 09:18:27 2023 -0600

    [docs]: Fix content, style nits re: strings.
    
    * Clarify clobbering behavior of `als` request.
    * Tighten wording.
    * Drop repeated information.
    * Fix slipshod grammar (an argument to a request is "unlike
      other"...requests?).
    * Improve example.
    * Favor active voice over passive.
---
 doc/groff.texi  | 38 +++++++++++++++++++-------------------
 man/groff.7.man | 20 ++++++++++++--------
 2 files changed, 31 insertions(+), 27 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 47df012b2..ad9978504 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -12436,8 +12436,7 @@ contents and the @code{\*} escape sequence dereferences 
its name,
 interpolating its contents.  If the string named by the @code{\*} escape
 sequence does not exist, it is defined as empty, nothing is
 interpolated, and a warning in category @samp{mac} is emitted.
-@xref{Warnings}, for information about the enablement and suppression of
-warnings.
+@xref{Warnings}, regarding the enablement and suppression of warnings.
 
 @DefreqList {ds, name [@Var{contents}]}
 @DefreqItemx {ds1, name [@Var{contents}]}
@@ -12469,9 +12468,8 @@ The @code{\*} escape sequence interpolates a previously 
defined string
 handled as macro arguments are; recall @ref{Calling Macros}.  In
 contrast to macro calls, however, if a closing bracket @samp{]} occurs
 in a string argument, that argument must be enclosed in double quotes.
-@code{\*} is interpreted even in copy mode.  When defining strings,
-argument interpolations must be escaped if they are to reference
-parameters from the calling context; @xref{Parameters}.
+When defining strings, argument interpolations must be escaped if they
+are to reference parameters from the calling context; @xref{Parameters}.
 
 @Example
 .ds cite (\\$1, \\$2)
@@ -12493,11 +12491,11 @@ Gray codes are explored in \*[cite Morgan 1998].
 @cindex trailing spaces in string definitions and appendments
 @cindex comments, with @code{ds}
 @cindex @code{ds} request, and comments
-@strong{Caution:@:} Unlike other requests, the second argument to the
-@code{ds} request consumes the remainder of the input line, including
-trailing spaces.  This means that comments on a line with such a request
-can introduce unwanted space into a string when they are set off from
-the material they annotate, as is conventional.
+@strong{Caution:@:} The @code{ds} request, unlike others, treats the
+remainder of the input line as its second argument, including trailing
+spaces.  This means that comments on a line with such a request can
+introduce unwanted space into a string when they are set off from the
+material they annotate, as is conventional.
 
 @Example
 .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water
@@ -12517,7 +12515,7 @@ document maintenance.
 
 @Example
 .ds author Alice Pleasance Liddell\"
-.ds empty \" might be appended to later with .as
+.ds friends \" empty; append to with .as
 @endExample
 
 @cindex trailing double quotes in strings
@@ -12526,11 +12524,11 @@ document maintenance.
 @cindex leading spaces with @code{ds}
 @cindex spaces with @code{ds}
 @cindex @code{ds} request, and leading spaces
-An initial neutral double quote @code{"} in @var{contents} is stripped
-to allow embedding of leading spaces.  Any other @code{"} is interpreted
-literally, but it is wise to use the special character escape sequence
-@code{\[dq]} instead if the string might be interpolated as part of a
-macro argument; see @ref{Calling Macros}.
+The formatter removes an initial neutral double quote @code{"} in
+@var{contents} to permit the embedding of leading spaces.  Any other
+@code{"} is interpreted literally, but it is wise to use the special
+character escape sequence @code{\[dq]} instead if the string might be
+interpolated as part of a macro argument; see @ref{Calling Macros}.
 
 @c Examples should be more accessible than Unix nerd stuff like this,
 @c but in general document authors shouldn't want to use "straight"
@@ -12727,9 +12725,11 @@ This request is incorrectly documented in the 
@acronym{AT&T}
 @cindex diversion, creating alias of (@code{als})
 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 in category
-@samp{mac} is produced, and the request is ignored.  @xref{Warnings},
-for information about the enablement and suppression of warnings.
+stored object.  If @var{new} already exists, its contents are lost
+unless already aliased.  If @var{old} is undefined, a warning in
+category @samp{mac} is produced, and the request is ignored.
+@xref{Warnings}, for information about the enablement and suppression of
+warnings.
 
 To understand how the @code{als} request works, consider two different
 storage pools:@: one for objects (macros, strings, etc.), and another
diff --git a/man/groff.7.man b/man/groff.7.man
index 6dac1fdce..774a4ee25 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2425,6 +2425,11 @@ macro,
 or diversion
 .IR old .
 .
+If
+.I new
+already exists,
+its contents are lost unless already aliased.
+.
 .TPx
 .REQ .am "macro"
 Append to
@@ -5686,9 +5691,6 @@ if a closing bracket
 occurs in a string argument,
 that argument must be enclosed in double quotes.
 .
-.B \[rs]*
-is interpreted even in copy mode.
-.
 When defining strings,
 argument interpolations must be escaped if they are to reference
 parameters from the calling context;
@@ -5696,9 +5698,9 @@ see section \[lq]Parameters\[rq] below.
 .
 .
 .P
-An initial neutral double quote
+The formatter removes an initial neutral double quote
 .B \[dq]
-in the string contents is stripped to allow embedding of leading spaces.
+in the string contents to permit the embedding of leading spaces.
 .
 Any other
 .B \[dq]
@@ -5763,9 +5765,11 @@ string is later interpolated.
 .
 .P
 .B Caution:
-Unlike other requests,
-the second argument to these requests consumes the remainder of the
-input line,
+The
+.B ds
+request,
+unlike others,
+treats the remainder of the input line as its second argument,
 including trailing spaces.
 .
 Ending string definitions