[groff] 04/08: [docs]: Update discussion of strings.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 17ee46a895e0ce94211c442300a52bfe090e0819
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Nov 30 21:13:48 2022 -0600

    [docs]: Update discussion of strings.
    
    * Fix copy-and-paste error; drop confusing reference to "delimiters".
      Strings have no "delimited" interpolation form (where the user can
      choose the delimiter).
      Thanks to Dave Kemper for noting this.
    * Motivate the utility of strings; i.e., why you'd use 'em.
    * Shift more facts about basic string usage earlier in the discussion,
      to accommodate impatient readers.
    * Drop term "variable", which we generally don't use in *roff.
    * Drop introduction of term "interpolation", which is now introduced
      much earlier, in section "Text" (over 80 pages in PDF version of our
      Texinfo manual).
    * Clarify what sort of arguments to string interpolations must be
      quoted.  Thanks to Dave Kemper for noticing this one, too.
    * Present macro-like argument interpolation of strings in more detail.
    * (groff.texi) Replace example of nested string interpolation with a
      more straightforward example of argumentful interpolation.
    * Clarify that treatment of \newline in a string definition is not
      unusual or an exceptional case of syntax.
    * (groff.texi) Add cross reference to new "Punning Names" node.
    * Motivate availability of `ds1` and `as1` requests.
    * (groff.7.man) Add internal cross references to "Strings" section.
    * Sync text of man page with groff.texi, approximately as usual.
    * Lightly recast.
---
 doc/groff.texi  |  92 ++++++++++++++++++--------------
 man/groff.7.man | 160 +++++++++++++++++++++++++++++++++++++++-----------------
 2 files changed, 163 insertions(+), 89 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index d75719539..85430cd1b 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -11993,12 +11993,15 @@ string-valued register @samp{.M}; it is associated 
with the environment
 
 @c =====================================================================
 
+@c BEGIN Keep (roughly) parallel with section "Strings" of groff(7).
 @node Strings, Conditionals and Loops, Colors, gtroff Reference
 @section Strings
 @cindex strings
 
 GNU @code{troff} has string variables primarily for user convenience.
-Only one string is predefined by the language.
+Conventionally, if a macro definition needs only to interpolate text,
+without invoking any requests or calling any other macros, a string is
+defined instead.  Only one string is predefined by the language.
 
 @Defstr {.T}
 @stindex .T
@@ -12007,10 +12010,12 @@ Contains the name of the output device (for example, 
@samp{utf8} or
 @samp{pdf}).
 @endDefmpstr
 
-The @code{ds} (or @code{ds1}) request creates a string with a specified
-name and contents and the @code{\*} escape sequence dereferences its
-name, retrieving the contents.  Dereferencing an undefined string name
-defines it as empty.
+The @code{ds} request creates a string with a specified name and
+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}.
 
 @DefreqList {ds, name [@Var{contents}]}
 @DefreqItemx {ds1, name [@Var{contents}]}
@@ -12026,35 +12031,37 @@ defines it as empty.
 @cindex expansion of strings (@code{\*})
 @cindex string arguments
 @cindex arguments, of strings
-Define a string variable @var{name} with contents @var{contents}.  If
+Define a string called @var{name} with contents @var{contents}.  If
 @var{name} already exists, it is removed first (see @code{rm} below).
-The syntax form using brackets accepts arguments that are handled as
-macro arguments are; recall @ref{Calling Macros}.  In contrast to macro
-invocations, however, a closing bracket as a string argument must be
-enclosed in double quotes.  @code{\\*} is interpreted even in copy mode
-(@pxref{Copy Mode}).
+If @code{ds} is called with only one argument, @var{name} is defined as
+an empty string.
 
-The @code{\*} escape sequence @dfn{interpolates} (expands in place) a
-previously defined string variable @var{name} (one-character
-name@tie{}@var{n}, two-character name @var{nm}).  The delimited form
-need not use the neutral apostrophe; see @ref{Delimiters}.  An argument
-in a string definition must be escaped for correct behavior;
-@xref{Parameters}.
+The @code{\*} escape sequence interpolates a previously defined string
+variable @var{name} (one-character name@tie{}@var{n}, two-character name
+@var{nm}).  The bracketed interpolation form accepts arguments that are
+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 (@pxref{Copy Mode}).  When
+defining strings, argument interpolations must be escaped if they are to
+reference parameters from the calling context; @xref{Parameters}.
 
 @Example
-.ds a \\$1 wildebeest
-.ds b big, \*[a hairy]
-I see a \*[b].
-    @result{} I see a big, hairy wildebeest.
+.ds cite (\\$1, \\$2)
+Gray codes are explored in \*[cite Morgan 1998].
+    @result{} Gray codes are explored in (Morgan, 1998).
 @endExample
 
-If the string named by the @code{\*} escape sequence does not exist, it
-is defined as empty, and a warning in category @samp{mac} is produced.
-@xref{Debugging}, for information about the enablement and suppression
-of warnings.
-
-If @code{ds} is called with only one argument, @var{name} is defined as
-an empty string.
+@c TODO: Consider examples of recursive string calls, particularly where
+@c one interpolation is constructed from the argument of an enclosing
+@c macro, to illustrate ".ds a \$1 \\$1".
+@c
+@c @Example
+@c .ds a \\$1 wildebeest
+@c .ds b big, \*[a hairy]
+@c I see a \*[b].
+@c     @result{} I see a big, hairy wildebeest.
+@c @endExample
 
 @cindex trailing spaces in string definitions and appendments
 @cindex comments, with @code{ds}
@@ -12092,8 +12099,8 @@ 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 in @var{contents} is stripped to allow
-embedding of leading spaces.
+An initial neutral double quote @code{"} in @var{contents} is stripped
+to allow embedding of leading spaces.
 
 @c Examples should be more accessible than Unix nerd stuff like this,
 @c but in general document authors shouldn't want to use "straight"
@@ -12109,9 +12116,9 @@ embedding of leading spaces.
 @cindex strings, multi-line
 @cindex newline character, in strings, escaping
 @cindex escaping newline characters, in strings
-Strings are not limited to a single line of input text.  A string can
-span several lines by escaping the newlines with a backslash.  The
-resulting string is stored @emph{without} the newlines.
+Strings are not limited to a single input line of text.
+@code{\@key{RET}} works just as it does elsewhere.  The resulting string
+is stored @emph{without} the newlines.
 
 @Example
 .ds foo This string contains \
@@ -12121,13 +12128,16 @@ of input.
 
 It is not possible to embed a newline in a string that will be
 interpreted as such when the string is interpolated.  To achieve that
-effect, use @code{\*} to interpolate a macro instead.
-@endDefreq
-
-The @code{ds1} request defines a string such that compatibility mode is
-off when the string is later interpolated.  To be more precise, a
-@dfn{compatibility save} input token is inserted at the beginning of the
-string, and a @dfn{compatibility restore} input token at the end.
+effect, use @code{\*} to interpolate a macro instead; see @ref{Punning
+Names}.
+
+Because strings are similar to macros, they too can be defined so as to
+suppress AT&T @code{troff} compatibility mode when used; see
+@ref{Writing Macros} and @ref{Compatibility Mode}.  The @code{ds1}
+request defines a string such that compatibility mode is off when the
+string is later interpolated.  To be more precise, a @dfn{compatibility
+save} input token is inserted at the beginning of the string, and a
+@dfn{compatibility restore} input token at the end.
 
 @Example
 .nr xxx 12345
@@ -12142,6 +12152,7 @@ string, and a @dfn{compatibility restore} input token 
at the end.
 \*(bb
     @result{} The value of xxx is 12345.
 @endExample
+@endDefreq
 
 @DefreqList {as, name [@Var{contents}]}
 @DefreqListEndx {as1, name [@Var{contents}]}
@@ -12333,6 +12344,7 @@ an error.  @xref{Writing Macros}.
 To remove an alias, call @code{rm} on its name.  The object itself is
 not destroyed until it has no more names.
 @endDefreq
+@c END Keep (roughly) parallel with section "Strings" of groff(7).
 
 
 @c =====================================================================
diff --git a/man/groff.7.man b/man/groff.7.man
index ab08cd5ab..0d7630917 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1467,7 +1467,8 @@ The
 .B als
 request can alias requests,
 permitting them to be wrapped or non-destructively replaced.
-.\" @xref{Strings}.
+.
+See section \[lq]Strings\[rq] below.
 .
 .
 .P
@@ -1507,7 +1508,8 @@ Some requests,
 like
 .BR ds ,
 interpret the remainder of the control line as a single argument.
-.\" @xref{Strings}.
+.
+See section \[lq]Strings\[rq] below.
 .
 .
 .P
@@ -4967,9 +4969,15 @@ then restore it.
 .SH Strings
 .\" ====================================================================
 .
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Strings".
 .I groff
 has string variables primarily for user convenience.
 .
+Conventionally,
+if a macro definition needs only to interpolate text,
+without invoking any requests or calling any other macros,
+a string is defined instead.
+.
 Only one string is predefined by the language.
 .
 .
@@ -4985,42 +4993,44 @@ or
 .P
 The
 .request .ds
-request creates a string with a specified name and contents
-and the
+request creates a string with a specified name and contents and the
 .esc *
 escape sequence dereferences its name,
-retrieving the contents.
+interpolating the contents.
 .
-Dereferencing an undefined string name defines it as empty.
+If the string named by the
+.esc *
+escape sequence does not exist,
+it is defined as empty,
+nothing is interpolated,
+and a warning in category
+.RB \%\[lq] mac \[rq]
+is emitted.
 .
+See section \[lq]Warnings\[rq] in
+.MR @g@troff 1 .
 .
-.P
-The
-.request .as
-request is similar to
-.request .ds
-but appends to a string instead of redefining it.
 .
-If
-.request .as
-is called with only one argument,
-no operation is performed
-(beyond dereferencing it).
+.P
+The bracketed interpolation form accepts arguments that are handled as
+macro arguments are;
+see section \[lq]Calling Macros\[rq] above.
 .
+In contrast to macro calls,
+however,
+if a closing bracket
+.B }
+occurs in a string argument,
+that argument must be enclosed in double quotes.
 .
-.P
-The
-.request .ds1
-request defines a string such that compatibility mode is off when the
-string is later interpolated.
+.B \[rs]*
+is interpreted even in copy mode
+(see subsection \[lq]Copy mode\[rq] below).
 .
-Likewise,
-the
-.request .as1
-request is similar to
-.BR .as ,
-but compatibility mode is switched off when the appended portion of the
-string is later interpolated.
+When defining strings,
+argument interpolations must be escaped if they are to reference
+parameters from the calling context;
+(see section \[lq]Parameters\[rq] below).
 .
 .
 .P
@@ -5039,34 +5049,58 @@ maintenance.
 .
 .
 .P
-To store leading space in a string,
-start it with a double quote.
+An initial neutral double quote
+.B \[dq]
+in the string contents is stripped to allow embedding of leading spaces.
+.
+Strings are not limited to a single input line of text.
+.BI \[rs] newline
+works just as it does elsewhere.
+.
+The resulting string is stored
+.I without
+the newlines.
+.
+It is not possible to embed a newline in a string that will be
+interpreted as such when the string is interpolated.
 .
-A double quote is special only in that position;
-double quotes in any other location are included in the string
-(the effects of escape sequences notwithstanding).
+To achieve that effect,
+use
+.B \[rs]*
+to interpolate a macro instead.\" see @ref{Punning Names}.
 .
 .
 .P
-Macros,
-strings,
-and diversions share a name space;
-see section \[lq]Identifiers\[rq] above.
+The
+.request .as
+request is similar to
+.request .ds
+but appends to a string instead of redefining it.
 .
-Internally,
-the same mechanism is used to store them.
+If
+.request .as
+is called with only one argument,
+no operation is performed
+(beyond dereferencing it).
 .
-You can thus call a macro with string interpolation syntax and vice
-versa.
 .
-Interpolating a string does not hide existing macro arguments.
+.P
+Because strings are similar to macros,
+they too can be defined to suppress AT&T
+.I troff \" AT&T
+compatibility mode enablement when interpolated;
+see section \[lq]Compatibility mode\[rq] below.
 .
-The sequence
-.B \[rs]\[rs]
-can be placed at the end of a line in a macro definition or,
-within a macro definition,
-immediately after the interpolation of a macro as a string to suppress
-the effect of a newline.
+The
+.request .ds1
+request defines a string that suspends compatibility mode when the
+string is later interpolated.
+.
+.request .as1
+is likewise similar to
+.BR .as ,
+with compatibility mode suspended when the appended portion of the
+string is later interpolated.
 .
 .
 .P
@@ -5088,6 +5122,34 @@ and aliasing
 .request .rn ,
 .request .rm ,
 .request .als).
+.\" END Keep (roughly) parallel with groff.texi node "Strings".
+.
+.
+.\" We don't have a "Diversions" section for this to follow yet.  When
+.\" we do, it should become part of a "Punning Names" section.  See
+.\" groff.texi.
+.ig
+.P
+Macros,
+strings,
+and diversions share a name space;
+see section \[lq]Identifiers\[rq] above.
+.
+Internally,
+the same mechanism is used to store them.
+.
+You can thus call a macro with string interpolation syntax and vice
+versa.
+.
+Interpolating a string does not hide existing macro arguments.
+.
+The sequence
+.B \[rs]\[rs]
+can be placed at the end of a line in a macro definition or,
+within a macro definition,
+immediately after the interpolation of a macro as a string to suppress
+the effect of a newline.
+..
 .
 .
 .\" ====================================================================