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 <[email protected]> + + [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 <[email protected]> [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/
