[groff] 03/04: doc/groff.texi: Tweak style of Strings node.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5fe877ce242fa31cc540d6467c96d9b324a595b6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Jul 16 22:04:07 2020 +1000

    doc/groff.texi: Tweak style of Strings node.
    
    * doc/groff.texi (Strings):
      Add style recommendation to end string definitions with empty
      comments when a substantive one is unnecessary; as I recall, Werner
      Lemberg made this exhortation fairly strongly on the groff list a year
      or two ago.  Supply example.
    
      Update example output to use @error{} for output to standard error and
      use contemporary groff quotation style in diagnostic messages.
    
      Screen for backticks and apostrophes; bracket node with
      @codequotebacktick and @codequoteundirected accordingly.  Say "GNU
      troff" instead of "gtroff".  Follow "i.e." with a comma.  Say
      "read/write" instead of "read-write".  Hyphenate phrasal adjective
      "previously-defined".  Apply "-ly" suffix to "similar" when it is used
      adverbially.  (Seriously?)  Use semicolon in preference to comma
      splice.  Recast strange language regarding storage of leading space in
      string definitions.
    
      Today I learned, to my delight and convenience, that "appendment" is
      an English word.
---
 doc/groff.texi | 43 ++++++++++++++++++++++++++++---------------
 1 file changed, 28 insertions(+), 15 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index ae34cec..558e2a3 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10364,12 +10364,14 @@ with a default scale indicator of @samp{z}.
 @section Strings
 @cindex strings
 
-@code{gtroff} has string variables, which are entirely for user
-convenience (i.e.@: there are no built-in strings except @code{.T}, but
-even this is a read-write string variable).
+@codequotebacktick on
+@codequoteundirected on
+GNU @code{troff} has string variables, which are entirely for user
+convenience (i.e., there are no built-in strings except @code{.T}, but
+even that is a read/write string variable).
 
-Although the following requests can be used to create strings,
-simply using an undefined string will cause it to be defined as empty.
+Although the following requests can be used to create strings, simply
+using an undefined string will cause it to be defined as empty.
 @xref{Identifiers}.
 
 @DefreqList {ds, name [@Var{string}]}
@@ -10401,10 +10403,10 @@ This is \*[foo nice].
 @endExample
 
 The @code{\*} escape @dfn{interpolates} (expands in place) a
-previously defined string variable.  To be more precise, the stored
-string is pushed onto the input stack, which is then parsed by
-@code{gtroff}.  Similar to number registers, it is possible to nest
-strings, i.e., string variables can be called within string variables.
+previously-defined string variable.  To be more precise, the stored
+string is pushed onto the input stack, which is then parsed by GNU
+@code{troff}.  Similarly to number registers, it is possible to nest
+strings; i.e., string variables can be called within string variables.
 
 If the string named by the @code{\*} escape does not exist, it is
 defined as empty, and a warning of type @samp{mac} is emitted (see
@@ -10432,13 +10434,21 @@ escape adjacent with the end of the string.
 .ds TeX T\h'-.2m'\v'.2m'E\v'-.2m'\h'-.1m'X\" Knuth's TeX
 @endExample
 
+It is good style to end string definitions (and appendments; see below)
+with a comment, even an empty one, to prevent unwanted space from
+creeping into them.
+
+@Example
+.ds author Alice Pleasance Liddell\"
+@endExample
+
 @cindex trailing quotes
 @cindex quotes, trailing
 @cindex leading spaces with @code{ds}
 @cindex spaces with @code{ds}
 @cindex @code{ds} request, and leading spaces
-To produce leading space the string can be started with a double quote.
-No trailing quote is needed; in fact, any trailing quote is included in
+To store leading space in a string, start it with a double quote.  No
+trailing quote is needed; in fact, any trailing quote is included in
 your string.
 
 @Example
@@ -10476,7 +10486,7 @@ restore} input token at the end.
 .cp 1
 .
 \*(aa
-    @result{} warning: number register `[' not defined
+    @error{} warning: number register '[' not defined
     @result{} The value of xxx is 0xxx].
 \*(bb
     @result{} The value of xxx is 12345.
@@ -10699,8 +10709,9 @@ Rename the request, macro, diversion, or string 
@var{xx} to @var{yy}.
 @cindex string, removing (@code{rm})
 @cindex removing diversion (@code{rm})
 @cindex diversion, removing (@code{rm})
-Remove the request, macro, diversion, or string @var{xx}.  @code{gtroff}
-treats subsequent invocations as if the object had never been defined.
+Remove the request, macro, diversion, or string @var{xx}.  GNU
+@code{troff} treats subsequent invocations as if the object had never
+been defined.
 @endDefreq
 
 @anchor{als}
@@ -10770,10 +10781,12 @@ Remove (chop) the last character from the macro, 
string, or diversion
 named @var{xx}.  This is useful for removing the newline from the end of
 diversions that are to be interpolated as strings.  This command can be
 used repeatedly; see @ref{Gtroff Internals}, for details on nodes
-inserted additionally by @code{gtroff}.
+inserted additionally by GNU @code{troff}.
 @endDefreq
 
 @xref{Identifiers}, and @ref{Comments}.
+@codequoteundirected off
+@codequotebacktick off
 
 
 @c =====================================================================