bugGNU roff - Bugs: bug #63002, doc/groff.texi: correct \o example

 
 

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

Submitter:  Dave <barx>
Submitted:  Sat 03 Sep 2022 10:06:49 AM UTC
   
 
Category:  Core Severity:  2 - Minor
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sun 25 Sep 2022 10:42:27 PM UTC, comment #7: 


commit e3797bc081d0a47f27219a1f43547e9d4d58e165
Author:     G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 17 05:12:38 2022 -0500
Commit:     G. Branden Robinson <g.branden.robinson@gmail.com>
CommitDate: Mon Sep 19 17:06:42 2022 -0500

    doc/groff.texi: Fix \o example.

    Finish correcting the overstriking example, which had multiple errors.

    (Re-)Fixes <https://savannah.gnu.org/bugs/?63002>.  Thanks to Dave
    Kemper for his osprey gaze.


G. Branden Robinson <gbranden>
Group administrator
Sat 17 Sep 2022 10:11:13 AM UTC, comment #6: 

Hi Dave,

Whoops!

I forgot to sync the example text with my experimental specimen.


$ cat EXPERIMENTS/overstrike.roff
A caf\o
e\(aa
in Paris
.pl \n(nlu
$ ./build/test-groff -Tutf8 EXPERIMENTS/overstrike.roff
A caf´ in Paris


(As discussed in another ticket, the destructive overstrike is an unfortunate property of video terminals.)

G. Branden Robinson <gbranden>
Group administrator
Sat 17 Sep 2022 04:01:46 AM UTC, comment #5: 

This commit fixes the first problem originally reported, but the second (that the newline between "caf" and "\o" outputs (in fill mode) a space, resulting not in "café" but in "caf é") remains in the reconfigured example.

Dave <barx>
Group Member
Fri 16 Sep 2022 05:23:14 PM UTC, comment #4: 


commit 21263eccb2dcbc30508c54cf16515ea8d78a4af2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   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.


G. Branden Robinson <gbranden>
Group administrator
Tue 13 Sep 2022 08:55:25 PM UTC, comment #3: 


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,



G. Branden Robinson <gbranden>
Group administrator
Tue 13 Sep 2022 04:53:18 PM UTC, comment #2: 

comment #1:

> I independently discovered this while chasing down Bjarni's bug #63011,


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.

> I have a big diff fixing this report, those other problems, ...


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.)

Dave <barx>
Group Member
Tue 13 Sep 2022 02:36:32 PM UTC, comment #1: 


original submission:

> This example in the Texinfo manual doesn't produce the claimed output.


> @Example
> A caf
> \o
> e\'
>
>
> in Paris
>   @result{} A café in Paris
> @endExample


> First, there are three newline characters (one ending the line, and two more forming blank lines) following the overstruck "e\'" sequence; the first of these closes the \o escape,


...and funnily enough, as it happens, is also treated as the end of an input line.

> as the example is intended to illustrate, but the other two cause a break, which puts the result not all on one line as shown.


Yup.

> Second, the newline between "caf" and "\o" outputs (in fill mode) a space, resulting not in "café" but in "caf é".


Yup.

When I last looked at this, a couple of years ago, I got deeply confused and gave up.

> Example input that produces the claimed output would be:


> @Example
> A caf\o
> e\'
> in Paris


> This is also visually tighter while still illustrating the ability of newlines to delimit \o's argument.


Yes.

I independently discovered this while chasing down Bjarni's bug #63011, and also discovered some worse lies in this part of the manual regarding which escape sequences do and don't accept newlines as delimiters.  So now I have a big diff fixing this report, those other problems, and syncing the relevant syntactical info to groff(7) as well.  The latter had been punting the reader to our Texinfo manual--bad form.

G. Branden Robinson <gbranden>
Group administrator
Sat 03 Sep 2022 10:06:49 AM UTC, original submission:  

This example in the Texinfo manual doesn't produce the claimed output.

@Example
A caf
\o
e\'


in Paris
  @result{} A café in Paris
@endExample

First, there are three newline characters (one ending the line, and two more forming blank lines) following the overstruck "e\'" sequence; the first of these closes the \o escape, as the example is intended to illustrate, but the other two cause a break, which puts the result not all on one line as shown.

Second, the newline between "caf" and "\o" outputs (in fill mode) a space, resulting not in "café" but in "caf é".

Example input that produces the claimed output would be:

@Example
A caf\o
e\'
in Paris

This is also visually tighter while still illustrating the ability of newlines to delimit \o's argument.

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 11 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-09-25 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
    2022-09-17 gbranden StatusNone In Progress
    2022-09-17 barx StatusFixed None
        Open/ClosedClosed Open
    2022-09-16 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
    2022-09-13 gbranden Attached File- Added johnny_carson_carnac_with_envelope.jpeg, #53688
    2022-09-13 gbranden StatusNone In Progress
        Assigned toNone gbranden
        Planned ReleaseNone 1.23.0

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code