[groff] 23/28: Fix documentation style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 30914d8b90ed423d17b699bfbfac9879a3137fd4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 29 04:26:31 2020 +1000

    Fix documentation style nits.
    
    * doc/groff.texi (Strings): Recast introduction to string definition
      requests to make it more clear that declaration and initialization are
      the same process, for the benefit of those coming from other
      programming languages, and to better distinguish the concepts of
      string names and string contents.  Separate definition summary from
      interpolation summary.  Clarify that an .as request dereferences the
      name it is given.  Note in .as1, and in parallel with existing .ds1
      language, that the effect on compatibility mode occurs when the string
      (appendment) is later interpolated.  Improve summary of string name
      manipulation requests by identifying their functions with verbs.  Fix
      grammar nits.
    
    * man/groff.7.man (Escape Sequences): Improve parallel construction by
      using gerunds consistently.
    
    * man/groff.7.man (Strings):
    * man/groff_diff.7.man (Language/New requests) <.as1>: Parallelize with
      updates to our Texinfo manual, above.
---
 doc/groff.texi       | 42 +++++++++++++++++++++++-------------------
 man/groff.7.man      | 28 +++++++++++++++-------------
 man/groff_diff.7.man |  4 ++--
 3 files changed, 40 insertions(+), 34 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index ae64151..034d29b 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10428,9 +10428,10 @@ This string contains the current output device (for 
example,
 @samp{utf8} or @samp{pdf}).
 @endDefstr
 
-The @code{ds} (or @code{ds1}) request creates a string and the @code{\*}
-escape dereferences name, retrieving its contents.  Dereferencing an
-undefined string name defines it as empty.
+The @code{ds} (or @code{ds1}) request creates a string with a specified
+name and contents and the @code{\*} escape dereferences its name,
+retrieving the contents.  Dereferencing an undefined string name defines
+it as empty.
 
 @DefreqList {ds, name [@Var{string}]}
 @DefreqItemx {ds1, name [@Var{string}]}
@@ -10446,20 +10447,21 @@ undefined string name defines it as empty.
 @cindex expansion of strings (@code{\*})
 @cindex string arguments
 @cindex arguments, of strings
-Define and access a string variable @var{name} (one-character
-name@tie{}@var{n}, two-character name @var{nm}).  If @var{name} already
-exists, @code{ds} overwrites the previous definition.  The syntax form
-using brackets accepts arguments that are handled as macro arguments
-are; recall @ref{Request and Macro Arguments}.  In contrast to macro
-invocations, however, a closing bracket as a string argument must be
-enclosed in double quotes.
+Define a string variable @var{name} with contents @var{string}.  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{Request and Macro Arguments}.  In
+contrast to macro invocations, however, a closing bracket as a string
+argument must be enclosed in double quotes.
 
 The @code{\*} escape @dfn{interpolates} (expands in place) a previously
-defined string variable.  More precisely, the stored string is pushed
-onto the input stack, which is then parsed normally.  Similarly to
-number registers, it is possible to nest strings; i.e., string variables
-can be called within string variables.  An argument in a string
-definition must be escaped for correct behavior; @xref{Parameters}.
+defined string variable @var{name} (one-character name@tie{}@var{n},
+two-character name @var{nm}).  More precisely, the stored string is
+pushed onto the input stack, which is then parsed normally.  Similarly
+to number registers, it is possible to nest strings; i.e., string
+variables can be called within string variables.  An argument in a
+string definition must be escaped for correct behavior;
+@xref{Parameters}.
 
 @Example
 .ds a \\$1 wildebeest
@@ -10512,7 +10514,7 @@ creeping into them during source document maintenance.
 @cindex @code{ds} request, and leading spaces
 To store leading space in a string, start it with a double quote.  A
 double quote is special only in that position; double quotes in any
-other location are included in the string (the effect of escape
+other location are included in the string (the effects of escape
 sequences notwithstanding).
 
 @c Examples should be more accessible than Unix nerd stuff like this,
@@ -10704,14 +10706,15 @@ string, and a @dfn{compatibility restore} input token 
at the end.
 The @code{as} request is similar to @code{ds} but appends @var{string}
 to the string stored as @var{name} instead of redefining it.  If
 @var{name} doesn't exist yet, it is created.  If @code{as} is called
-with only one argument, no operation is performed.
+with only one argument, no operation is performed (beyond dereferencing
+it).
 
 @Example
 .as salutation " with shallots, onions and garlic,\"
 @endExample
 
 The @code{as1} request is similar to @code{as}, but compatibility mode
-is switched off while the appended portion of the string is
+is switched off when the appended portion of the string is later
 interpolated.  To be more precise, a @dfn{compatibility save} input
 token is inserted at the beginning of the appended string, and a
 @dfn{compatibility restore} input token at the end.
@@ -10720,7 +10723,8 @@ token is inserted at the beginning of the appended 
string, and a
 Several requests exist to perform rudimentary string operations.
 Strings can be queried (@code{length}) and modified (@code{chop},
 @code{substring}, @code{stringup}, @code{stringdown}), and their names
-can be manipulated (@code{rn}, @code{rm}, @code{als}).
+can be manipulated through renaming, removal, and aliasing (@code{rn},
+@code{rm}, @code{als}).
 
 @Defreq {length, reg anything}
 @cindex length of a string (@code{length})
diff --git a/man/groff.7.man b/man/groff.7.man
index c3acbbe..bd3a954 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2865,7 +2865,7 @@ In the latter convention,
 the user selects a delimiter character;
 the neutral apostrophe
 .RB \[lq] \[aq] \[rq]
-is a popular choice and used in this document.
+is a popular choice and shown in this document.
 .
 Some characters cannot be used as delimiters;
 see section \[lq]Escapes\[rq] in the
@@ -2899,7 +2899,7 @@ setting the point size;
 interpolating special characters,
 number registers,
 and strings into the text;
-and placement or suppression of break and hyphenation points.
+and placing or suppressing break and hyphenation points.
 .
 As with requests,
 use of escapes in source documents may interact poorly with a macro
@@ -3906,10 +3906,11 @@ or
 .P
 The
 .request .ds
-request creates a string and the
+request creates a string with a specified name and contents
+and the
 .esc *
 escape dereferences its name,
-retrieving its contents.
+retrieving the contents.
 .
 Dereferencing an undefined string name defines it as empty.
 .
@@ -3917,16 +3918,15 @@ Dereferencing an undefined string name defines it as 
empty.
 .P
 The
 .request .as
-requests is similar to
+request is similar to
 .request .ds
-but appends its arguments
-(after the first)
-to a string instead of redefining it.
+but appends to a string instead of redefining it.
 .
 If
 .request .as
 is called with only one argument,
-no operation is performed.
+no operation is performed
+(beyond dereferencing it).
 .
 .
 .P
@@ -3949,8 +3949,8 @@ the
 request is similar to
 .request .as\c
 ,
-but compatibility mode is switched off while the appended portion of the
-string is interpolated.
+but compatibility mode is switched off when the appended portion of the
+string is later interpolated.
 .
 .
 .P
@@ -3974,7 +3974,7 @@ start it with a double quote.
 .
 A double quote is special only in that position;
 double quotes in any other location are included in the string
-(the effect of escape sequences notwithstanding).
+(the effects of escape sequences notwithstanding).
 .
 .
 .P
@@ -4000,7 +4000,9 @@ and modified
 .request .substring ,
 .request .stringup ,
 .request .stringdown ),
-and their names can be manipulated
+and their names can be manipulated through renaming,
+removal,
+and aliasing
 (\c
 .request .rn ,
 .request .rm ,
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 78a0662..36c9e26 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1041,8 +1041,8 @@ request but compatibility mode is switched off during 
execution.
 .BI .as1\~ "name string"
 Similar to
 .BR .as ,
-but compatibility mode is switched off while the appended portion of the
-string is interpolated.
+but compatibility mode is switched off when the appended portion of the
+string is later interpolated.
 .
 To be more precise,
 a \[lq]compatibility save\[rq] token is inserted at the beginning of the