[groff] 02/06: [docs]: Revise output command descriptions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e36523130c55c69098f02cd2e8bdcc221e414200
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 30 08:02:17 2023 -0500

    [docs]: Revise output command descriptions.
    
    * doc/groff.texi (Simple Commands): Recast for clarity and idiomatic
      English.
    
    * man/groff_out.5.man (Simple commands): Sync.  Adjust dead-tree
      pagination.
---
 doc/groff.texi      | 159 ++++++++++++++++++++++++++--------------------------
 man/groff_out.5.man |  36 +++++++-----
 2 files changed, 101 insertions(+), 94 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 0ce81b30c..714e8a8d5 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17681,125 +17681,122 @@ stack as the actual device configuration data.
 \}              \" endif @USE_ENV_STACK
 @end ignore
 
-@item C @var{xxx}@angles{whitespace}
-Print a special character named @var{xxx}.  The trailing syntactical
-space or line break is necessary to allow glyph names of arbitrary
-length.  The glyph is printed at the current print position; the glyph's
-size is read from the font file.  The print position is not changed.
+@item C @var{id}@angles{whitespace}
+Typeset the glyph of the special character @var{id}.  Trailing
+syntactical space is necessary to allow special character names of
+arbitrary length.  The drawing position is not advanced.
 
 @item c @var{g}
-Print glyph@tie{}@var{g} at the current print
-position;@footnote{@samp{c} is actually a misnomer since it outputs a
-glyph.} the glyph's size is read from the font file.  The print position
-is not changed.
+Typeset the glyph of the ordinary character@tie{}@var{c}.  The drawing
+position is not advanced.
 
 @item f @var{n}
-Set font to font number@tie{}@var{n} (a non-negative integer).
+Select the font mounted at position@tie{}@var{n}.  @var{n}@tie{}cannot
+be negative.
 
 @item H @var{n}
-Move right to the absolute vertical position@tie{}@var{n} (a
-non-negative integer in basic units @samp{u} relative to left edge of
-current page.
+Horizontally move the drawing position to @var{n}@tie{}basic units from
+the left edge of the page.  @var{n}@tie{}cannot be negative.
 
 @item h @var{n}
-Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
-to the right.  The @acronym{AT&T} @code{troff} manual allows negative
-values for @var{n} also, but GNU @code{troff} doesn't use them.
+Move the drawing position right @var{n} basic units.  @acronym{AT&T}
+@code{troff} allowed negative @var{n}; GNU @code{troff} does not produce
+such values, but @code{groff}'s output driver library handles them.
 
 @item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
-Set the color for text (glyphs), line drawing, and the outline of
-graphic objects using different color schemes; the analogous command
-for the filling color of graphic objects is @samp{DF}.  The color
-components are specified as integer arguments between 0 and 65535.  The
-number of color components and their meaning vary for the different
-color schemes.  These commands are generated by @code{gtroff}'s escape
-sequence @code{\m}.  No position changing.  These commands are a
-@code{gtroff} extension.
+Select the stroke color using the @var{component}s in the color space
+@var{scheme}.  Each @var{component} is an integer between 0 and 65535.
+The quantity of components and their meanings vary with each
+@var{scheme}.  This command is a @code{groff} extension.
 
 @table @code
 @item mc @var{cyan} @var{magenta} @var{yellow}
-Set color using the CMY color scheme, having the 3@tie{}color components
-@var{cyan}, @var{magenta}, and @var{yellow}.
+Use the CMY color scheme with components cyan, magenta, and yellow.
 
 @item md
-Set color to the default color value (black in most cases).  No
-component arguments.
+Use the default color (no components; black in most cases).
 
 @item mg @var{gray}
-Set color to the shade of gray given by the argument, an integer between
-0 (black) and 65535 (white).
+Use a grayscale color scheme with a component ranging between 0 (black)
+and 65535 (white).
 
 @item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
-Set color using the CMYK color scheme, having the 4@tie{}color
-components @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
+Use the CMYK color scheme with components cyan, magenta, yellow, and
+black.
 
 @item mr @var{red} @var{green} @var{blue}
-Set color using the RGB color scheme, having the 3@tie{}color components
-@var{red}, @var{green}, and @var{blue}.
+Use the RGB color scheme with components red, green, and blue.
 @end table
 
 @item N @var{n}
-Print glyph with index@tie{}@var{n} (a non-negative integer) of the
-current font.  This command is a @code{gtroff} extension.
+Typeset the glyph with index@tie{}@var{n} in the current font.
+@var{n}@tie{}is normally a non-negative integer.  The drawing position
+is not advanced.  The @code{html} and @code{xhtml} devices use this
+command with negative@tie{}@var{n} to produce unbreakable space; the
+absolute value of @var{n} is taken and interpreted in basic units.
 
 @item n @var{b} @var{a}
-Inform the device about a line break, but no positioning is done by this
-command.  In @acronym{AT&T} @code{troff}, the integer arguments @var{b}
-and@tie{}@var{a} informed about the space before and after the current
-line to make the intermediate output more human readable without
-performing any action.  In @code{groff}, they are just ignored, but they
-must be provided for compatibility reasons.
+Indicate a break.  No action is performed; the command is present to
+make the output more easily parsed.  The integers @var{b}
+and@tie{}@var{a} describe the vertical space amounts before and after
+the break, respectively.  GNU @code{troff} issues this command but
+@code{groff}'s output driver library ignores it.  See @code{v} and
+@code{V} below.
 
 @item p @var{n}
-Begin a new page in the output.  The page number is set to@tie{}@var{n}.
-This page is completely independent of pages formerly processed even if
-those have the same page number.  The vertical position on the output is
-automatically set to@tie{}0.  All positioning, writing, and drawing is
-always done relative to a page, so a @samp{p} command must be issued
-before any of these commands.
+Begin a new page, setting its number to@tie{}@var{n}.  Each page is
+independent, even from those using the same number.  The vertical
+drawing position is set to@tie{}0.  All positioning, writing, and
+drawing commands are interpreted in the context of a page, so a
+@code{p}@tie{}command must precede them.
 
 @item s @var{n}
-Set type size to @var{n}@tie{}scaled points (this is unit @samp{z}).
-@acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
-@xref{Output Language Compatibility}.
-
-@item t @var{xxx}@angles{whitespace}
-@itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
-Print a word, i.e., a sequence of characters @var{xxx} representing
-output glyphs which names are single characters, terminated by a space
+Set type size to @var{n} scaled points (unit@tie{}@code{z} in GNU
+@code{troff}.
+@acronym{AT&T} @code{troff} used unscaled points @code{p} instead;
+see @ref{Output Language Compatibility}.
+
+@item t @var{xyz}@angles{whitespace}
+@itemx t @var{xyz} @var{dummy-arg}@angles{whitespace}
+Typeset a word @var{xyz}; that is, set a sequence of ordinary glyphs
+named @var{x}, @var{y}, @var{z}, @dots{}, terminated by a space
 character or a line break; an optional second integer argument is
 ignored (this allows the formatter to generate an even number of
-arguments).  The first glyph should be printed at the current position,
-the current horizontal position should then be increased by the width of
-the first glyph, and so on for each glyph.  The widths of the glyphs are
-read from the font file, scaled for the current type size, and rounded
-to a multiple of the horizontal motion quantum.  Special characters
-cannot be printed using this command (use the @samp{C} command for
-special characters).  This command is a @code{gtroff} extension; it is
-only used for devices whose @file{DESC} file contains the
-@code{tcommand} keyword (@pxref{DESC File Format}).
-
-@item u @var{n} @var{xxx}@angles{whitespace}
-Print word with track kerning.  This is the same as the @samp{t} command
-except that after printing each glyph, the current horizontal position
-is increased by the sum of the width of that glyph and@tie{}@var{n} (an
-integer in basic units @samp{u}).  This command is a @code{gtroff}
-extension; it is only used for devices whose @file{DESC} file contains
-the @code{tcommand} keyword (@pxref{DESC File Format}).
+arguments). @c XXX: Why?
+Each glyph is set at the current drawing position, and the position is
+then advanced horizontally by the glyph's width.  A glyph's width is
+read from its metrics in the font description file, scaled to the
+current type size, and rounded to a multiple of the horizontal motion
+quantum.  Only ordinary characters can be set using this command; use
+the @code{C} command to emplace special characters.  The
+@code{t}@tie{}command is a @code{groff} extension and is output only for
+devices whose @file{DESC} file contains the @code{tcommand} directive;
+see @ref{DESC File Format}.
+
+@item u @var{n} @var{xyz}@angles{whitespace}
+Typeset word @var{xyz} with track kerning.  As @code{t}, but after
+placing each glyph, the drawing position is further advanced
+horizontally by@tie{}@var{n} basic units (@code{u}).  The
+@code{u}@tie{}command is a @code{groff} extension and is output only for
+devices whose @file{DESC} file contains the @code{tcommand} directive;
+see @ref{DESC File Format}.
 
 @item V @var{n}
-Move down to the absolute vertical position@tie{}@var{n} (a non-negative
-integer in basic units @samp{u}) relative to upper edge of current page.
+Vertically move the drawing position to @var{n}@tie{}basic units from
+the top edge of the page.  @var{n}@tie{}cannot be negative.
 
 @item v @var{n}
-Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative
-integer).  The @acronym{AT&T} @code{troff} manual allows negative values
-for @var{n} also, but GNU @code{troff} doesn't use them.
+Move the drawing position down @var{n} basic units.  @acronym{AT&T}
+@code{troff} allowed negative @var{n}; GNU @code{troff} does not produce
+such values, but @code{groff}'s output driver library handles them.
 
 @item w
-Describe an adjustable space. This performs no action; it is present for
-documentary purposes.  The spacing itself must be performed explicitly
-by a move command.
+Indicate an inter-word space.  No action is performed; the command is
+present to make the output more easily parsed.  Only adjustable,
+breakable inter-word spaces are thus described; those resulting from
+horizontal motion escape sequences are not.  GNU @code{troff} issues
+this command but @code{groff}'s output driver library ignores it.  See
+@code{h} and @code{H} above.
 @end table
 
 @node Graphics Commands, Device Control Commands, Simple Commands, Command 
Reference
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index e2555a8f2..2673f6ffd 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -519,9 +519,9 @@ stack as the current device configuration data.
 .
 .
 .TP
-.command C xxx \[la]white-space\[ra]
+.command C id \[la]white-space\[ra]
 Typeset the glyph of the special character
-.IR xxx .
+.IR id .
 .
 Trailing syntactical space is necessary to allow special character names
 of arbitrary length.
@@ -535,7 +535,7 @@ The drawing position is not advanced.
 .TP
 .command c c
 Typeset the glyph of the ordinary character
-.IR c .
+.RI character\~ c .
 .
 The drawing position is not advanced.
 .\" XXX: Why does it matter that we read its size if we don't advance
@@ -664,20 +664,22 @@ is taken and interpreted in basic units.
 .
 .TP
 .command n b\~a
-Describe a break.
+Indicate a break.
 .
-In AT&T
-.IR troff ,
-the integer arguments
+No action is performed;
+the command is present to make the output more easily parsed.
+.
+The integers
 .I b
 .RI and\~ a
 describe the vertical space amounts before and after the break,
-respectively,
-to make the output more readable by humans.
+respectively.
 .
 GNU
 .I troff \" GNU
-reports these values but its output driver library ignores them.
+issues this command but
+.IR groff 's
+output driver library ignores it.
 .
 See
 .B v
@@ -820,15 +822,21 @@ output driver library handles them.
 .
 .TP
 .command w
-Describe an inter-word space.
+Indicate an inter-word space.
 .
-This performs no action;
-it is present to make the output more readable by humans.
+No action is performed;
+the command is present to make the output more easily parsed.
 .
 Only adjustable,
 breakable inter-word spaces are thus described;
 those resulting from horizontal motion escape sequences are not.
 .
+GNU
+.I troff \" GNU
+issues this command but
+.IR groff 's
+output driver library ignores it.
+.
 See
 .B h
 and
@@ -1816,6 +1824,8 @@ describes the output device
 .IR name .
 .
 .
+.br
+.ne 4v
 .\" ====================================================================
 .SH Authors
 .\" ====================================================================