[groff] 09/23: [docs]: Fix Savannah #63002.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 21263eccb2dcbc30508c54cf16515ea8d78a4af2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Sep 13 09:48:34 2022 -0500

    [docs]: Fix Savannah #63002.
    
    [docs]: Fix errors in documentation regarding which escape sequences
    accept newlines as argument delimiters, and other inaccuracies.
    
    * doc/groff.texi (Escape Sequences): Cover general cases before
      exceptional ones.  Leaders can be used as argument delimiters.  Call
      out letters and numerals as (usually) usable as well.  Correct an
      almost completely inaccurate list of escape sequences that accept a
      newline as an argument delimiter: \A, \b, \o, \w, and \X do; \B and \Z
      do not.  Correct example of use of newline as delimiter with \o escape
      sequence.  Stop referring to the decimal point as an "operator".  Drop
      "newline" from a list of prohibited delimiters by several escape
      sequences since it has already been discussed.
    
    * man/groff.7.man (Escape sequences): Replace weaksauce cross reference
      to our Texinfo manual with a proper discussion of acceptable
      delimiters in escape sequences, synced with the foregoing change.
      Stop using quotation marks around escape sequences, except for "\ "
      which obviously needs it.
    
    Fixes <https://savannah.gnu.org/bugs/?63002>.  Thanks to Dave Kemper for
    the report.
    
    Also adjust dead-tree typography, preventing widow.
    
    Also add thin space escape sequence to let a backslash breathe after an
    opening quotation mark.
---
 ChangeLog       |  26 ++++++++++
 doc/groff.texi  | 142 ++++++++++++++++++++++++++++---------------------------
 man/groff.7.man | 144 +++++++++++++++++++++++++++++++++++++++++++++++++-------
 3 files changed, 225 insertions(+), 87 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 0a6cdfb42..f1ebe1242 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,29 @@
+2022-09-13  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [docs]: Fix errors in documentation regarding which escape
+       sequences accept newlines as argument delimiters, and other
+       inaccuracies.
+
+       * doc/groff.texi (Escape Sequences): Cover general cases before
+       exceptional ones.  Leaders can be used as argument delimiters.
+       Call out letters and numerals as (usually) usable as well.
+       Correct an almost completely inaccurate list of escape sequences
+       that accept a newline as an argument delimiter: \A, \b, \o, \w,
+       and \X do; \B and \Z do not.  Correct example of use of newline
+       as delimiter with \o escape sequence.  Stop referring to the
+       decimal point as an "operator".  Drop "newline" from a list of
+       prohibited delimiters by several escape sequences since it has
+       already been discussed.
+
+       * man/groff.7.man (Escape sequences): Replace weaksauce cross
+       reference to our Texinfo manual with a proper discussion of
+       acceptable delimiters in escape sequences, synced with the
+       foregoing change.  Stop using quotation marks around escape
+       sequences, except for "\ " which obviously needs it.
+
+       Fixes <https://savannah.gnu.org/bugs/?63002>.  Thanks to Dave
+       Kemper for the report.
+
 2022-09-13  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [troff]: Don't throw a spurious warning when using newline as
diff --git a/doc/groff.texi b/doc/groff.texi
index aef05293a..c9e95cd24 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6725,40 +6725,25 @@ Examples:
 \*[TeX]
 @endExample
 
-@cindex @code{'}, delimiting arguments
-@cindex argument delimiting characters
-@cindex characters, argument delimiting
-@cindex delimiting characters for arguments
-Other escape sequences may require several arguments and/or some special
-format.  In such cases the argument is traditionally enclosed in single
-quotes (and quotes are always used in this manual for the definitions of
-escape sequences).  The enclosed text is then processed according to
-what that escape expects.  Example:
+@cindex @code{'}, as delimiter
+@cindex delimiters, for escape sequence arguments
+@cindex arguments, for escape sequences, delimiting
+@cindex escape sequence argument delimiters
+Other escape sequences may require several parameters and/or a
+particular format.  In such cases the argument is traditionally enclosed
+in neutral apostrophes, and we use these exclusively in this manual when
+presenting escape sequences.  The escape sequence interprets the
+delimited contents.
 
 @Example
-\l'1.5i\(bu'
+\l'1.5i\(bu' \" draw 1.5 inches of bullets
 @endExample
 
-@cindex @code{\o}, possible quote characters
-@cindex @code{\b}, possible quote characters
-@cindex @code{\X}, possible quote characters
-The quote character can be replaced with any other character
-that does not occur in the argument (even a newline or a space
-character) in the following escape sequences: @code{\o}, @code{\b}, and
-@code{\X}.  This makes e.g.
-
-@Example
-A caf
-\o
-e\'
-
-
-in Paris
-  @result{} A caf� in Paris
-@endExample
-
-@noindent
-possible, but it is better not to use this feature to avoid confusion.
+@cindex @code{"}, as delimiter
+The neutral apostrophe in the foregoing example can be replaced with
+any character that does not occur in the argument.  The neutral double
+quote @code{"} is another popular choice.  Letters, numerals, and
+leaders can be used.
 
 @cindex @code{\%}, as delimiter
 @cindex @code{\@key{SP}}, as delimiter
@@ -6789,44 +6774,66 @@ possible, but it is better not to use this feature to 
avoid confusion.
 @cindex @code{\t}, as delimiter
 @cindex @code{\u}, as delimiter
 The following escape sequences (which are handled similarly to
-characters since they don't take a parameter) are also allowed as
+characters since they don't take an argument) are also allowed as
 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
 @code{\?}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, @code{\:},
 @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
-@code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.  Again, don't
-use these if possible.
-
-@cindex @code{\A}, allowed delimiters
-@cindex @code{\B}, allowed delimiters
-@cindex @code{\Z}, allowed delimiters
-@cindex @code{\C}, allowed delimiters
-@cindex @code{\w}, allowed delimiters
-No newline characters as delimiters are allowed in the following
-escape sequences: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and
-@code{\w}.
-
-@cindex @code{\D}, allowed delimiters
-@cindex @code{\h}, allowed delimiters
-@cindex @code{\H}, allowed delimiters
-@cindex @code{\l}, allowed delimiters
-@cindex @code{\L}, allowed delimiters
-@cindex @code{\N}, allowed delimiters
-@cindex @code{\R}, allowed delimiters
-@cindex @code{\s}, allowed delimiters
-@cindex @code{\S}, allowed delimiters
-@cindex @code{\v}, allowed delimiters
-@cindex @code{\x}, allowed delimiters
+@code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.  However,
+using them this way is discouraged; it can make the input confusing to
+read.
+
+@cindex @code{\A}, delimiters allowed by
+@cindex @code{\b}, delimiters allowed by
+@cindex @code{\o}, delimiters allowed by
+@cindex @code{\w}, delimiters allowed by
+@cindex @code{\X}, delimiters allowed by
+@cindex @code{\Z}, delimiters allowed by
+@cindex newline, as delimiter
+A few escape sequences,
+@code{\A},
+@code{\b},
+@code{\o},
+@code{\w},
+@code{\X},
+and @code{\Z}, accept a newline as a delimiter.  A newline that serves
+as an ending delimiter continues to be recognized as an input line
+ending.
+
+@Example
+A caf
+\o
+e\(aa
+in Paris
+  @result{} A caf� in Paris
+@endExample
+
+@noindent
+The use of newlines as delimiters in escape sequences is discouraged.
+
+@cindex @code{\D}, delimiters allowed by
+@cindex @code{\h}, delimiters allowed by
+@cindex @code{\H}, delimiters allowed by
+@cindex @code{\l}, delimiters allowed by
+@cindex @code{\L}, delimiters allowed by
+@cindex @code{\N}, delimiters allowed by
+@cindex @code{\R}, delimiters allowed by
+@cindex @code{\s}, delimiters allowed by
+@cindex @code{\S}, delimiters allowed by
+@cindex @code{\v}, delimiters allowed by
+@cindex @code{\x}, delimiters allowed by
 Finally, the escape sequences @code{\D}, @code{\h}, @code{\H},
 @code{\l}, @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S},
-@code{\v}, and @code{\x} can't use the following characters as
-delimiters:
+@code{\v}, and @code{\x} prohibit many delimiters.
 
 @itemize @bullet
 @item
-@cindex numbers, and delimiters
-@cindex digits, and delimiters
-The digits @code{0}-@code{9}.
+@cindex numerals, as delimiters
+@cindex digits, as delimiters
+@cindex @code{.}, as delimiter
+@cindex decimal point, as delimiter
+@cindex dot, as delimiter
+the numerals @code{0}-@code{9} and the decimal point @code{.}
 
 @item
 @cindex operators, as delimiters
@@ -6847,17 +6854,12 @@ The digits @code{0}-@code{9}.
 @end ifinfo
 @cindex @code{(}, as delimiter
 @cindex @code{)}, as delimiter
-@cindex @code{.}, as delimiter
-The (single-character) operators @samp{+-/*%<>=&:().}.
+the (single-character) operators @samp{+-/*%<>=&:()}
 
 @item
-@cindex space character
-@cindex character, space
-@cindex tab character
-@cindex character, tab
-@cindex newline character
-@cindex character, newline
-The space, tab, and newline characters.
+@cindex space character, as delimiter
+@cindex tab character, as delimiter
+the space and tab characters
 
 @item
 @cindex @code{\%}, as delimiter
@@ -6873,9 +6875,9 @@ The space, tab, and newline characters.
 @cindex @code{\c}, as delimiter
 @cindex @code{\e}, as delimiter
 @cindex @code{\p}, as delimiter
-All escape sequences except @code{\%}, @code{\:}, @code{\@{},
+any escape sequences other than @code{\%}, @code{\:}, @code{\@{},
 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
-@code{\/}, @code{\c}, @code{\e}, and @code{\p}.
+@code{\/}, @code{\c}, @code{\e}, and @code{\p}
 @end itemize
 
 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
diff --git a/man/groff.7.man b/man/groff.7.man
index 96bbacbb3..6bec04656 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3601,7 +3601,7 @@ to requests and macros
 .
 An escape sequence is introduced by the escape character,
 a backslash
-.RB \[lq] \[rs] \[rq]
+.B \[rs]
 (but see the
 .B .ec
 request).
@@ -3630,26 +3630,134 @@ and an argument of arbitrary length is enclosed in 
brackets
 In the latter convention,
 the user selects a delimiter character;
 the neutral apostrophe
-.RB \[lq] \[aq] \[rq]
+.B \[aq]
 is a popular choice and shown in this document.
 .
-Some characters cannot be used as delimiters;
-see subsection \[lq]Escape Sequences\[rq] in the
-.I groff
-Texinfo manual for details.
-.\" TODO: Reproduce that material here, as tersely as possible.
+The neutral double quote
+.B \[dq]
+is another popular choice.
+.
+Letters,
+numerals,
+and leaders can be used.
+.
+.
+.P
+The following escape sequences
+(which are handled similarly to characters since they don't take an
+argument)
+are also allowed as delimiters:
+.BR \[rs]% ,
+.RB \[lq] \|\[rs]\~ "\[rq] (backslash-space),"
+.BR \[rs]| ,
+.BR \[rs]\[ha] ,
+.BR \[rs]{ ,
+.BR \[rs]} ,
+.BR \[rs]\[aq] ,
+.BR \[rs]\[ga] ,
+.BR \[rs]\- ,
+.BR \[rs]_ ,
+.BR \[rs]! ,
+.BR \[rs]? ,
+.BR \[rs]) ,
+.BR \[rs]/ ,
+.BR \[rs], ,
+.BR \[rs]& ,
+.BR \[rs]: ,
+.BR \[rs]\[ti] ,
+.BR \[rs]0 ,
+.BR \[rs]a ,
+.BR \[rs]c ,
+.BR \[rs]d ,
+.BR \[rs]e ,
+.BR \[rs]E ,
+.BR \[rs]p ,
+.BR \[rs]r ,
+.BR \[rs]t ,
+and
+.BR \[rs]u .
+.
+However,
+using them this way is discouraged;
+it can make the input confusing to read.
 .
+.
+.P
+A few escape sequences,
+.BR \[rs]A ,
+.BR \[rs]b ,
+.BR \[rs]o ,
+.BR \[rs]w ,
+.BR \[rs]X ,
+and
+.BR \[rs]Z ,
+accept a newline as a delimiter.
+.
+A newline that serves as an ending delimiter continues to be
+recognized as an input line ending.
+.
+The use of newlines as delimiters in escape sequences is discouraged.
+.
+.
+.P
+The escape sequences
+.BR \[rs]D ,
+.BR \[rs]h ,
+.BR \[rs]H ,
+.BR \[rs]l ,
+.BR \[rs]L ,
+.BR \[rs]N ,
+.BR \[rs]R ,
+.BR \[rs]s ,
+.BR \[rs]S ,
+.BR \[rs]v ,
+and
+.B \[rs]x
+prohibit many delimiters.
+.
+.
+.RS
+.IP \[bu] 2n
+the numerals 0\[en]9 and the decimal point
+.RB \[lq] . \[rq]
+.
+.
+.IP \[bu]
+the (single-character) operators
+.B +\-/*%<>=&:()
+.
+.
+.IP \[bu]
+any escape sequences other than
+.BR \[rs]% ,
+.BR \[rs]: ,
+.BR \[rs]{ ,
+.BR \[rs]} ,
+.BR \[rs]\[aq] ,
+.BR \[rs]\[ga] ,
+.BR \[rs]\- ,
+.BR \[rs]_ ,
+.BR \[rs]! ,
+.BR \[rs]/ ,
+.BR \[rs]c ,
+.BR \[rs]e ,
+and
+.B \[rs]p
+.RE
+.
+.
+.P
 A few escape sequences are idiosyncratic,
 and support both of the foregoing conventions
-.RB (\[lq] \[rs]s \[rq]),
-designate their own terminating character
-.RB (\[lq] \[rs]? \[rq]),
+.RB ( \|\[rs]s ),
+designate their own termination sequence
+.RB ( \|\[rs]? ),
 consume input until the next newline
-.RB (\[lq] \[rs]! \[rq],
-.RB \[lq] \[rs]" \[rq],
-.RB \[lq] \[rs]# \[rq]),
+.RB ( \|\[rs]! ,
+.BR \|\[rs]" ,
+.BR \|\[rs]# ),
 or support an additional modifier character
-.RB (\[lq] \[rs]s \[rq]
+.RB ( \|\[rs]s
 again).
 .
 .
@@ -3672,6 +3780,8 @@ consult its documentation to learn of \[lq]safe\[rq] 
sequences or
 alternative facilities it provides to achieve the desired result.
 .
 .
+.br
+.ne 2v
 .P
 If the escape character is followed by a character that does not
 identify a defined operation,
@@ -5593,7 +5703,7 @@ restrictions imposed by the hyphenation mode are
 .I not
 respected for words whose hyphenations have been explicitly specified
 with the hyphenation character
-.RB (\[lq] \[rs]% \[rq]
+.RB (\[lq] \|\[rs]% \[rq]
 by default)
 or the
 .B .hw
@@ -5767,7 +5877,7 @@ returning to the enclosing context.
 .
 Macro call and string interpolation parameters can be accessed using
 escape sequences starting with
-.RB \[lq] \[rs]$ \[rq].
+.RB \[lq] \|\[rs]$ \[rq].
 .
 The
 .B \[rs]n[.$]
@@ -5914,7 +6024,7 @@ expects them as control characters if you mean to use 
them literally.
 Macro definitions can be nested to arbitrary depth.
 .
 In
-.RB \[lq] \[rs]\[rs] \[rq],
+.RB \[lq] \|\[rs]\[rs] \[rq],
 each escape character is interpreted twice\[em]once in copy mode,
 when the macro is defined,
 and once outside of it,