[groff] 24/35: groff_out(5): Perform some spot cleaning.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 51d1c5a1aa24cae293fe00b1169146bae4d5c651
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 23 23:30:21 2021 +1100

    groff_out(5): Perform some spot cleaning.
    
    * Say "current" when it is meant, instead of "actual".
    * Drop the mysterious and terse notation "No position changing", which
      seems to come out of the blue in every context it occurs.  It appears
      to refer to an old within-groff dispute[1] over which output commands
      should and should not update the drawing position.  (For my money, and
      as far as I understand the dispute, we should indeed get rid of the
      current "STUPID_DRAWING_POSITIONING".  What else produces ditroff
      output that our output drivers are expected to interpret?  There's
      plenty of room in the command name space to have a declarator for the
      endpoint convention used, if it comes to that.)
    * Recast descriptions of "t", "u", and "Dt" commands.
    * Replace most of the "Postprocessing" subsection with similar material
      adapted from groff(1).
    * Recast "Files" section.
    * Add link to and description of John Gardner's "Roff.js" viewer to "See
      also" section.
    * Set "groff" and "troff" in italics, not bold.
    * Set ellipses (...) in roman, not italics.
    * Replace inconsistent bold "<end-of-line>" notation with roman
      "<line-break>".
    * Break some input lines at multi-word parentheticals.
    
    [1] https://lists.gnu.org/archive/html/groff/2001-11/msg00145.html
---
 man/groff_out.5.man | 171 ++++++++++++++++++++++++++--------------------------
 1 file changed, 85 insertions(+), 86 deletions(-)

diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index 3ebfae5..d7277a1 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -35,13 +35,13 @@ groff_out \- GNU roff intermediate output format
 .\" ================= Document configuration
 .
 .\" Number register to decide whether the commands '{' and '}' are used
-.\" 0: disable (actual default); 1: enable
+.\" 0: disable (current default); 1: enable
 .nr @USE_ENV_STACK 0
 .
 .ig
 Unfortunately, old versions of groff used an illogical position change
 after some D\~commands (Dp, DP, Dt).  If the register
-@STUPID_DRAWING_POSITIONING is 1 (actual default) then change position
+@STUPID_DRAWING_POSITIONING is 1 (current default) then change position
 after these commands, otherwise the position is not changed.
 ..
 .nr @STUPID_DRAWING_POSITIONING 1
@@ -141,7 +141,7 @@ As the GNU
 processor
 .MR groff @MAN1EXT@
 is a wrapper program around
-.B @g@troff
+.I @g@troff
 that automatically calls a
 postprocessor, this output does not show up normally.
 .
@@ -152,13 +152,13 @@ within the
 .IR system .
 .
 The
-.B groff
+.I groff
 program provides the option
 .B \-Z
 to inhibit postprocessing, such that the produced
 .I intermediate output
 is sent to standard output just like calling
-.B @g@troff
+.I @g@troff
 manually.
 .
 .
@@ -166,7 +166,7 @@ manually.
 In this document, the term
 .I @g@troff output
 describes what is output by the GNU
-.B @g@troff
+.I @g@troff
 program, while
 .I intermediate output
 refers to the language that is accepted by the parser that prepares
@@ -207,7 +207,7 @@ versions are denoted as
 The
 .I intermediate output
 produced by
-.B groff
+.I groff
 is fairly readable, while
 .I classical troff
 output was hard to understand because of strange habits that are
@@ -221,7 +221,7 @@ still supported, but not used any longer by
 .\" ====================================================================
 .
 During the run of
-.BR @g@troff ,
+.IR @g@troff ,
 the
 .I roff
 input is cracked down to the information on what has to be printed at
@@ -251,7 +251,7 @@ for device controlling.
 had strange requirements on whitespace.
 .
 The
-.B groff
+.I groff
 output parser, however, is smart about whitespace by making it
 maximally optional.
 .
@@ -533,7 +533,7 @@ preceding argument ends with a string argument.
 .if \n[@USE_ENV_STACK]=1 \{\
 .TP
 .command {
-Open a new environment by copying the actual device configuration data
+Open a new environment by copying the current device configuration data
 to the environment stack.
 .
 The current environment is setup by the device specification and
@@ -542,10 +542,11 @@ manipulated by the setting commands.
 .
 .TP
 .command }
-Close the actual environment (opened by a preceding
+Close the current environment
+(opened by a preceding
 .BR { \~command)
 and restore the previous environment from the environment
-stack as the actual device configuration data.
+stack as the current device configuration data.
 .
 .\}              \" endif @USE_ENV_STACK
 .
@@ -627,8 +628,6 @@ These commands are generated by the
 escape sequence
 .BR \*[@backslash]m .
 .
-No position changing.
-.
 These commands are a
 .I groff
 extension.
@@ -739,75 +738,84 @@ must be issued before any of these commands.
 Set type size to
 .I n
 scaled points
-(this is unit\~\c
-.B z
+.RB unit\~ z
 in GNU
-.BR @g@troff ).
+.IR troff ). \" GNU
 .
-.I Classical troff
-used the unit
-.I points
-(\c
-.BR p )
+AT&T
+.I troff \" AT&T
+used unscaled points
+.RB ( p )
 instead;
 see section \[lq]Compatibility\[rq] below.
 .
 .
 .TP
-.command t xyz\|.\|.\|. \[la]white-space\[ra]
+.command t xyz\f[R]\|.\|.\|. \[la]white-space\[ra]
 .TQ
 .command t "xyz\|.\|.\|.\& dummy-arg" \[la]white-space\[ra]
-Print a word, i.e., a sequence of glyphs with single-letter names
+Typeset a word
+.IR xyz ;
+that is,
+set a sequence of ordinary glyphs named
 .IR x ,
 .IR y ,
 .IR z ,
-etc., 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).
+\&.\|.\|.\|,
+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).
+.\" XXX: Why?
 .
-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.
+Each glyph is set at the current drawing position,
+and the position is then advanced horizontally by the glyph's width.
 .
-The widths of the glyph are read from the font file, scaled for the
-current type size, and rounded to a multiple of the horizontal
-resolution.
+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 resolution.
 .
-Special characters (glyphs with names longer than a single letter)
-cannot be printed using this command; use the
+Only ordinary characters can be set using this command;
+use the
 .B C
-command for those glyphs.
+command to emplace special characters.
 .
-This command is a
+The
+.BR t \~command
+is a
 .I groff
-extension; it is only used for devices whose
+extension and is output only for devices whose
 .I DESC
 file contains the
 .B tcommand
-keyword; see
+directive;
+see
 .MR groff_font @MAN5EXT@ .
 .
 .
 .TP
-.command u "n xyz\|.\|.\|." \[la]white-space\[ra]
-Print word with track kerning.
+.command u "n xyz\f[R]\|.\|.\|." \[la]white-space\[ra]
+Typeset word
+.I xyz
+with track kerning.
 .
-This is the same as the
-.B t
-command except that after printing each glyph, the current
-horizontal position is increased by the sum of the width of that
-glyph and\~\c
-.I n
-(an integer in
-basic units\~\c
-.BR u ).
-This command is a
+As
+.BR t ,
+but after placing each glyph,
+the drawing position is further advanced horizontally
+.RI by\~ n
+basic units
+.RB ( u ).
+.
+The
+.BR u \~command
+is a
 .I groff
-extension; it is only used for devices whose
+extension and is output only for devices whose
 .I DESC
 file contains the
 .B tcommand
-keyword; see
+directive;
+see
 .MR groff_font @MAN5EXT@ .
 .
 .
@@ -871,7 +879,7 @@ is terminated by a
 .
 .
 .P
-.B @g@troff
+.I @g@troff
 output follows the classical spacing rules (no space between command
 and subcommand, all arguments are preceded by a single space
 character), but the parser allows optional space between the command
@@ -1028,8 +1036,6 @@ and
 .B \*[@backslash]M
 (with no other corresponding graphics commands).
 .
-No position changing.
-.
 This command is a
 .I groff
 extension.
@@ -1104,8 +1110,6 @@ Df \-1
 sets all colors to blue.
 .
 .P
-No position changing.
-.
 This command is a
 .I groff
 extension.
@@ -1134,7 +1138,7 @@ and from there back to the starting position.
 .
 .ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\
 For historical reasons, the position is changed by adding the sum of
-all arguments with odd index to the actual horizontal position and the
+all arguments with odd index to the current horizontal position and the
 even ones to the vertical position.
 .
 Although this doesn't make sense it is kept for compatibility.
@@ -1157,12 +1161,10 @@ The same macro as the corresponding
 command with the same arguments, but draws a solid polygon in the
 current fill color rather than an outlined polygon.
 .
-.ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\
+.if \n[@STUPID_DRAWING_POSITIONING]=1 \{\
 The position is changed in the same way as with
 .BR Dp .
 .\}
-.el \
-No position changing.
 .
 This command is a
 .I groff
@@ -1171,31 +1173,28 @@ extension.
 .
 .TP
 .D-command t n
-Set the current line thickness to\~\c
-.I n
-(an integer in basic units\~\c
-.BR u )
+Set the current line thickness
+.RI to\~ n
+(an integer in basic
+.RB units\~ u )
 if
 .IR n \|>\|0;
 if
 .IR n \|=\|0
-select the smallest available line thickness; if
-.IR n \|<\|0
-set the line thickness proportional to the type size (this is the
-default before the first
-.B Dt
-command was specified).
-.
-.ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\
-For historical reasons, the horizontal position is changed by adding
-the argument to the actual horizontal position, while the vertical
-position is not changed.
-.
-Although this doesn't make sense it is kept for compatibility.
-.
+select the smallest available line thickness;
+otherwise,
+the line thickness is made proportional to the type size,
+which is the default.
+.
+.if \n[@STUPID_DRAWING_POSITIONING]=1 \{\
+For historical reasons,
+the horizontal position is changed by adding the argument to the current
+horizontal position,
+while the vertical position is not changed.
+.
+Although this doesn't make sense,
+it is kept for compatibility.
 .\}
-.el \
-No position changing.
 .
 This command is a
 .I groff
@@ -1230,7 +1229,7 @@ of characters terminated by the next tab, space, or 
newline character.
 All characters of the subcommand word but the first are simply ignored.
 .
 For example,
-.B @g@troff
+.I @g@troff
 outputs the initialization command
 .B x\ i
 as
@@ -1261,7 +1260,7 @@ Use
 as the intended name for the current file in error reports.
 .
 This is useful for remembering the original file name when
-.B groff
+.I groff
 uses an internal piping mechanism.
 .
 The input file is not changed by this command.
@@ -1360,7 +1359,7 @@ Generate trailer information, if any.
 .
 In
 .BR groff ,
-this is actually just ignored.
+this is currently ignored.
 .
 .
 .TP
@@ -1541,7 +1540,7 @@ generated from the same input for three different devices.
 The input is the sentence
 .I hell world
 fed into
-.B groff
+.I groff
 on the command line.
 .
 .