[groff] 22/26: [docs]: Revise discussion of \O escape sequences.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 9813080b2b9e93c123ca8d1392fc3aa45dc86400
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun May 15 02:56:28 2022 -0500

    [docs]: Revise discussion of \O escape sequences.
    
    * Recast for more consistent use of terminology.
    * Horizontal motions corresponding to glyphs are still honored, but
      those corresponding to rules are not.
    * Document the additional information emitted by \O2.
    
    Also adjust dead-tree typography.
    
    Also fix straggling use of "escape" where "escape sequence" is meant.
---
 doc/groff.texi       |  85 +++++++++++++++----------------
 man/groff.7.man      |  36 +++++++------
 man/groff_diff.7.man | 140 +++++++++++++++++++++++++++++----------------------
 3 files changed, 144 insertions(+), 117 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index c6e18408..2b4a575c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14973,68 +14973,69 @@ line emitted in the environment.
 @node Suppressing Output, Colors, Environments, gtroff Reference
 @section Suppressing Output
 
-@Defesc {\\O, , num, }
+@Defesc {\\O, [, num, ]}
 @cindex suppressing output (@code{\O})
 @cindex output, suppressing (@code{\O})
-Disable or enable output depending on the value of @var{num}:
+Suppress GNU @code{troff} output of glyphs and geometric primitives.
+The sequences @code{\O2}, @code{\O3}, @code{\O4}, and @code{\O5} are
+intended for internal use by @code{grohtml}.
 
 @table @samp
 @item \O0
-Disable any glyphs from being emitted to the device driver, provided
-that the escape occurs at the outer level (see @code{\O[3]} and
-@code{\O[4]}).  Motion is not suppressed so effectively @code{\O[0]}
-means @emph{pen up}.
+Disable the emission of glyphs and geometric primitives to the output
+driver, provided that this sequence occurs at the outermost level
+(see @code{\O3} and @code{\04} below).  Horizontal motions corresponding
+to non-overstruck glyph widths still occur.
 
 @item \O1
-Enable output of glyphs, provided that the escape occurs at the outer
-level.
+Enable the emission of glyphs and geometric primitives to the output
+driver, provided that this sequence occurs at the outermost level.
 @end table
 
 @vindex opminx
 @vindex opminy
 @vindex opmaxx
 @vindex opmaxy
-@code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
-@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
-@xref{Register Index}.  These four registers mark the top left and
-bottom right hand corners of a box that encompasses all written glyphs.
-
-For example the input text:
-
-@Example
-Hello \O[0]world \O[1]this is a test.
-@endExample
-
-@noindent
-produces the following output:
-
-@Example
-Hello       this is a test.
-@endExample
+@code{\O0} and @code{\O1} also reset the four registers @code{opminx},
+@code{opminy}, @code{opmaxx}, and @code{opmaxy} to @minus{}1.  These
+four registers mark the top left and bottom right hand corners of a box
+encompassing all written glyphs.
 
 @table @samp
 @item \O2
-Provided that the escape occurs at the outer level, enable output of
-glyphs and also write out to @code{stderr} the page number and four
-registers encompassing the glyphs previously written since the last call
-to @code{\O}.
+Provided that this sequence occurs at the outermost level, enable
+emission of glyphs and geometric primitives, and write to the standard
+error stream the page number and values of the four aforementioned
+registers encompassing glyphs written since the last interpolation of a
+@code{\O} sequence, as well as the page offset, line length, image file
+name (if any), horizontal and vertical device motion quanta, and input
+file name.  Numeric values are in basic units.
 
 @item \O3
-Begin a nesting level.  At startup, @code{gtroff} is at outer level.
-The current level is contained within the read-only register @code{.O}.
-@xref{Built-in Registers}.
+Begin a nesting level.  This is an internal mechanism for @code{grohtml}
+while producing images.  At startup, @code{gtroff} is at the outermost
+level.  These sequences are generated when processing the source
+document with @command{pre-grohtml}, which uses @command{gtroff} with
+the @code{ps} output device, Ghostscript, and the PNM tools to produce
+images in PNG format.  They start a new page if the device is not
+@code{html} or @code{xhtml}, to reduce the possibility of images
+crossing a page boundary.
 
 @item \O4
-End a nesting level.  The current level is contained within the
-read-only register @code{.O}.  @xref{Built-in Registers}.
-
-@item \O[5@var{P}@var{filename}]
-This escape is @code{grohtml} specific.  Provided that this escape
-occurs at the outer nesting level write the @code{filename} to
-@code{stderr}.  The position of the image, @var{P}, must be specified
-and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left,
-right, centered, inline).  @var{filename} is associated with the
-production of the next inline image.
+End a nesting level.
+@end table
+
+The current nesting level is accessible via the read-only register
+@code{.O}.  @xref{Built-in Registers}.
+
+@table @samp
+@item \O[5@var{P}@var{file}]
+Provided that this sequence occurs at the outermost level, write the
+name @code{file} to the standard error stream at position @var{P}, which
+must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i},
+corresponding to left, right, centered, and inline alignments within the
+document, respectively.  @var{file} is a name associated with the
+production of the next image.
 @end table
 @endDefesc
 
diff --git a/man/groff.7.man b/man/groff.7.man
index ac54d08c..a9e4e5c0 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4148,23 +4148,30 @@ and so on.
 .TP
 .ESC O0
 At the outermost suppression level,
-disable glyph emission to the output driver.
+disable emission of glyphs and geometric primitives to the output
+driver.
 .
 .
 .TP
 .ESC O1
 At the outermost suppression level,
-enable glyph emission to the output driver.
+enable emission of glyphs and geometric primitives to the output driver.
 .
 .
 .TP
 .ESC O2
 At the outermost suppression level,
-enable glyph emission to the output driver and write to the standard
-error stream the page number and four bounding box registers enclosing
-glyphs written since the previous
+enable glyph and geometric primitive emission to the output driver and
+write to the standard error stream the page number,
+four bounding box registers enclosing glyphs written since the previous
 .B \[rs]O
-escape sequence.
+escape sequence,
+the page offset,
+line length,
+image file name
+(if any),
+horizontal and vertical device motion quanta,
+and input file name.
 .
 .
 .TP
@@ -4178,22 +4185,19 @@ End a nested suppression level.
 .
 .
 .TP
-.ESC[] O "\f[CB]5\f[]Pfilename"
+.ESC[] O "\f[CB]5\f[]Pfile"
 At the outermost suppression level,
-write
-.I filename
-to the standard error stream;
+write the name
+.I file
+to the standard error stream at
+.RI position\~ P ,
 .IR P \~indicates
-the position of an image and must be one of
+which must be one of
 .BR l ,
 .BR r ,
 .BR c ,
 or
-.B i
-(left,
-right,
-centered,
-inline).
+.BR i .
 .
 .
 .TP
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index a8c35350..8092daaa 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -594,106 +594,126 @@ restores the previous fill color.
 Interpolate register
 .IR xxx .
 .
+.
 .TP
 .BI \[rs]O n
 .TQ
 .BI \[rs]O[ n ]
-Suppress troff output.
+Suppress
+.I @g@troff
+output of glyphs and geometric primitives.
 .
-The escape sequences
+The sequences
 .BR \[rs]O2 ,
 .BR \[rs]O3 ,
 .BR \[rs]O4 ,
 and
 .B \[rs]O5
 are intended for internal use by
-.BR \%grohtml .
+.MR grohtml @MAN1EXT@ .
+.
 .
 .RS
 .TP
 .B \[rs]O0
-Disable glyphs from being emitted to the device driver,
-provided that the escape occurs at the outer level
+.TQ
+.B \[rs]O1
+Disable and enable,
+respectively,
+the emission of glyphs and geometric primitives to the output driver,
+provided that this sequence occurs at the outermost level
 (see
 .B \[rs]O3
 and
 .BR \[rs]O4 ).
 .
-.TP
-.B \[rs]O1
-Enable output of glyphs, provided that the escape occurs at the outer
-level.
-.IP
-.B \[rs]O0
-and
-.B \[rs]O1
-also reset the registers
-.BR \[rs]n[opminx] ,
-.BR \[rs]n[opminy] ,
-.BR \[rs]n[opmaxx] ,
+Horizontal motions corresponding to non-overstruck glyph widths still
+occur.
+.
+These sequences also reset the registers
+.BR opminx ,
+.BR opminy ,
+.BR opmaxx ,
 and
-.B \[rs]n[opmaxy]
+.B opmaxy
 to\~\-1.
 .
-These four registers mark the top left and bottom right hand corners
-of a box which encompasses all written glyphs.
+These four registers mark the top left and bottom right hand corners of
+a box encompassing all written glyphs.
+.
 .
 .TP
 .B \[rs]O2
-Provided that the escape occurs at the outer level, enable output of
-glyphs and also write out to stderr the page number and four registers
-encompassing the glyphs previously written since the last call to
-.BR \[rs]O .
+Provided that this sequence occurs at the outermost level,
+enable emission of glyphs and geometric primitives,
+and write to the standard error stream the page number and values of the
+four aforementioned registers encompassing glyphs written since the last
+interpolation of a
+.B \[rs]O
+sequence,
+as well as the page offset,
+line length,
+image file name (if any),
+horizontal and vertical device motion quanta,
+and input file name.
+.
+Numeric values are in basic units.
+.
 .
 .TP
 .B \[rs]O3
-Begin a nesting level.
-.
-At startup,
-.B troff
-is at outer level.
+.TQ
+.B \[rs]O4
+Begin and end a nesting level,
+respectively.
 .
-This is really an internal mechanism for
-.B \%grohtml
+This is an internal mechanism for
+.I \%grohtml
 while producing images.
 .
-They are generated by running the troff source through
-.B troff
-to the PostScript device and
-.B ghostscript
-to produce images in PNG format.
+At startup,
+.I @g@troff
+is at the outermost level.
 .
-The
-.B \[rs]O3
-escape starts a new page if the device is not html (to reduce the
-possibility of images crossing a page boundary).
+These sequences are generated when processing the source document with
+.IR pre\-grohtml ,
+which uses
+.I @g@troff
+with the
+.B ps
+output device,
+Ghostscript,
+and the PNM tools to produce images in PNG format.
+.
+They start a new page if the device is not
+.B html
+or
+.BR xhtml ,
+to reduce the possibility of images crossing a page boundary.
 .
-.TP
-.B \[rs]O4
-End a nesting level.
 .
 .TP
-.BI \[rs]O5[ Pfilename ]
-This escape is
-.B \%grohtml
-specific.
-.
-Provided that this escape occurs at the outer nesting level, write
-.I filename
-to stderr.
-.
-The position of the image,
+.BI \[rs]O5[ Pfile ]
+Provided that this sequence occurs at the outermost level,
+write the name
+.I file
+to the standard error stream at position
 .IR P ,
-must be specified and must be one of
+which must be one of
 .BR l ,
 .BR r ,
 .BR c ,
 or
-.B i
-(left, right, centered, inline).
+.BR i ,
+corresponding to
+left,
+right,
+centered,
+and inline alignments within the document,
+respectively.
 .
-.I filename
-is associated with the production of the next inline image.
+.I file
+is is a name associated with the production of the next image.
 .RE
 .
 .
@@ -721,6 +741,8 @@ is a numeric expression with a default scaling unit
 .RB of\~\[lq] z \[rq].
 .
 .
+.br
+.ne 5v
 .TP
 .BI \[rs]V x
 .TQ
@@ -769,7 +791,7 @@ may not contain tabs or leaders.
 .B \[rs]#
 Everything up to and including the next newline is ignored.
 .
-This escape is interpreted even in copy mode.
+This escape sequence is interpreted even in copy mode.
 .
 .B \[rs]#
 is like