[bug #63002] doc/groff.texi: correct \o example

[G. Branden Robinson]

Follow-up Comment #3, bug #63002 (project groff):


[comment #2 comment #2:]
> I think bug #62983 was Patient Zero: that's the one that had me trawling the
documentation for \o; and I'm guessing the current bug, bringing to light \o's
newline-as-delimiter facet, is what prompted Bjarni's.

Sounds plausible.

> When I thought about attaching a patch here, I decided against it partly
because I thought you might find other stuff you wanted to correct at the same
time anyway, so it wouldn't actually save you any work.  (I'd marvel at my
clairvoyance if it weren't merely an application of pattern recognition.)

Right again, Carnac!


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..3dca31cf4 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6733,7 +6733,7 @@ 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:
+what that escape sequence expects.
 
 @Example
 \l'1.5i\(bu'
@@ -6742,23 +6742,10 @@ what that escape expects.  Example:
 @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<E9> in Paris
-@endExample
-
-@noindent
-possible, but it is better not to use this feature to avoid confusion.
+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,22 +6776,41 @@ 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.
+@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}, allowed delimiters
-@cindex @code{\B}, allowed delimiters
-@cindex @code{\Z}, allowed delimiters
-@cindex @code{\C}, allowed delimiters
+@cindex @code{\b}, allowed delimiters
+@cindex @code{\o}, 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{\X}, allowed delimiters
+@cindex @code{\Z}, allowed delimiters
+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<E9> in Paris
+@endExample
+
+@noindent
+The use of newlines as delimiters in escape sequences is discouraged.
 
 @cindex @code{\D}, allowed delimiters
 @cindex @code{\h}, allowed delimiters
@@ -6819,14 +6825,13 @@ escape sequences: @code{\A}, @code{\B}, @code{\Z},
@code{\C}, and
 @cindex @code{\x}, allowed delimiters
 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 numerals, and delimiters
 @cindex digits, and delimiters
-The digits @code{0}-@code{9}.
+the numerals @code{0}-@code{9} and the decimal point @code{.}
 
 @item
 @cindex operators, as delimiters
@@ -6848,7 +6853,7 @@ The digits @code{0}-@code{9}.
 @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
@@ -6857,7 +6862,7 @@ The (single-character) operators @samp{+-/*%<>=&:().}.
 @cindex character, tab
 @cindex newline character
 @cindex character, newline
-The space, tab, and newline characters.
+the space and tab characters
 
 @item
 @cindex @code{\%}, as delimiter
@@ -6873,9 +6878,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,


(file #53688)

    _______________________________________________________

Additional Item Attachment:

File name: johnny_carson_carnac_with_envelope.jpeg Size:91 KB
   
<https://file.savannah.gnu.org/file/johnny_carson_carnac_with_envelope.jpeg?file_id=53688>



    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?63002>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/