[groff] 05/31: [docs]: Fix content, style, and markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit acae9d3827237c702ea5fc3315a7f35273f757e0
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Aug 11 17:32:11 2022 -0500

    [docs]: Fix content, style, and markup nits.
    
    * man/groff_font.5.man:
      - Tighten wording.
      - Use RS/RE macro pairs to inset syntax synopsis within a paragraph
        instead of `IP`, which starts a new one.
    
    * src/roff/groff/groff.1.man:
      - Mention the "pager problem"; these programs often do violence to the
        terminal escape sequences emitted by grotty(1).  Tell the reader
        where to find more information.
      - Update example to use installed groff command names.
      - Recast to avoid using examples as a hatch to escape
        sentence-terminal puncutation.
      - Fix man page rendering example to remove ".man" suffix, an artifact
        of the groff source tree.
      - Tighten wording.
    
    * doc/groff.texi (Invocation Examples): Sync with content of "Examples"
      section of groff(1), and annotate synchrony.
      (Font Description File Format): Sync with groff_font(5) changes.
      (Invoking groff): Mark chapter as reviewed for quotation mark usage.
---
 doc/groff.texi             | 97 +++++++++++++++++++++++++++-------------------
 man/groff_font.5.man       | 27 ++++++-------
 src/roff/groff/groff.1.man | 23 ++++++-----
 3 files changed, 83 insertions(+), 64 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 073fa98b3..b79f7655a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -846,6 +846,9 @@ contributed much of the material on the @file{ms} macro 
package.
 @c =====================================================================
 @c =====================================================================
 
+@codequotebacktick on
+@codequoteundirected on
+
 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
 @chapter Invoking @code{groff}
 @cindex invoking @code{groff}
@@ -1307,9 +1310,6 @@ Do not postprocess the output of @code{gtroff}.  Normally 
@code{groff}
 automatically runs the appropriate postprocessor.
 @end table
 
-@codequotebacktick off
-@codequoteundirected off
-
 
 @c =====================================================================
 
@@ -1581,57 +1581,73 @@ groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
 
 @c =====================================================================
 
+@c BEGIN Keep parallel with groff(1), section "Examples".
 @node Invocation Examples,  , Paper Size, Invoking groff
 @section Invocation Examples
 @cindex invocation examples
 @cindex examples of invocation
 
-This section lists several common uses of @code{groff} and the
-corresponding command lines.
+@code{roff} systems are best known for formatting man pages.  Once a
+@command{man} librarian program has located a man page, it may execute
+a @code{groff} command much like the following.
 
 @Example
-groff file
+groff -t -man -Tutf8 /usr/share/man/man1/groff.1
 @endExample
 
-@noindent
-This command processes @file{file} without a macro package or a
-preprocessor.  The output device is the default, @samp{ps}, and the
-output is sent to @code{stdout}.
+The librarian will also pipe the output through a pager, which might not
+interpret the SGR terminal escape sequences @command{groff} emits for
+boldface, underlining, or italics; see the @cite{grotty@r{(1)}} man page
+for a discussion.
+
+To process a @code{roff} input file using the preprocessors
+@command{gtbl} and @command{gpic} and the @file{me} macro package in the
+way to which AT&T @code{troff} users were accustomed, one would type (or
+script) a pipeline.
 
 @Example
-groff -t -mandoc -Tascii file | less
+gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty
 @endExample
 
-@noindent
-This is basically what a call to the @code{man} program does.  GNU
-@code{troff} processes the man page @file{file} with the @file{mandoc}
-macro file (which in turn loads either the @file{man} or the @file{mdoc}
-macro package), using the @command{tbl} preprocessor and the
-@code{ascii} output device.  Finally, the @command{less} pager displays
-the result.
+Using @command{groff}, this pipe can be shortened to an equivalent
+command.
+
+@Example
+groff -p -t -me -T utf8 foo.me
+@endExample
+
+An even easier way to do this is to use @command{grog} to guess the
+preprocessor and macro options and execute the result by using the
+command substitution feature of the shell.
 
 @Example
-groff -X -m me file
+$(grog -Tutf8 foo.me)
+@endExample
+
+Each command-line option to a postprocessor must be specified with any
+required leading dashes @samp{-}
+@c No GNU roff postprocessor uses long options for anything except
+@c --help or --version.
+@c or @samp{--}
+because @command{groff} passes the arguments as-is to the postprocessor;
+this permits arbitrary arguments to be transmitted.  For example, to
+pass a title to the @command{gxditview} postprocessor,
+the shell commands
+
+@Example
+groff -X -P -title -P 'trial run' mydoc.t
 @endExample
 
 @noindent
-Preview @file{file} with @code{gxditview}, using the @file{me} macro
-package.  Since no @option{-T} option is specified, use the default
-device (@samp{ps}).  You can say either @w{@samp{-m me}} or
-@w{@samp{-me}}; the latter is an anachronism from the early days of
-Unix.@footnote{The same is true for the other major macro packages that
-come with @code{groff}: @file{man}, @file{mdoc}, @file{ms}, @file{mm},
-and @file{mandoc}.  This won't work in general; for example, to load
-@file{trace.tmac}, either @samp{-mtrace} or @w{@samp{-m trace}} must be
-used.}
+and
 
 @Example
-groff -man -rD1 -z file
+groff -X -Z mydoc.t | gxditview -title 'trial run' -
 @endExample
 
 @noindent
-Check @file{file} with the @file{man} macro package, forcing
-double-sided printing---don't produce any output.
+are equivalent.
+@c END Keep parallel with groff(1), section "Examples".
 
 @menu
 * grog::
@@ -1680,6 +1696,9 @@ As this example shows, it is still necessary to redirect 
the output to
 something meaningful (i.e., either a file or a pager program like
 @code{less}).
 
+@codequotebacktick off
+@codequoteundirected off
+
 
 
 @c =====================================================================
@@ -18168,8 +18187,8 @@ featural description of the glyph: it is a bit mask 
recording whether
 the glyph is an ascender, descender, both, or neither.  When a @code{\w}
 escape sequence is interpolated, these values are bitwise or-ed
 together for each glyph and stored in the @code{nr} register.  In font
-descriptions for @code{nroff}-mode output devices (terminals), all
-glyphs might have a type of zero.
+descriptions for terminal devices, all glyphs might have a type of zero,
+regardless of their appearance.
 
 @table @code
 @item 0
@@ -18205,20 +18224,20 @@ For efficiency, these data are now compiled directly 
into
 arrays for PostScript fonts containing more than 256 glyphs.  Anything
 on the line after the @var{entity-name} field or @samp{--} is ignored.
 
-A line in the @code{charset} section can also have the following format.
+A line in the @code{charset} section can also have the form
 
 @Example
 @var{name} "
 @endExample
 
 @noindent
-This notation indicates that @var{name} is another name for the glyph
-named on the preceding line.  Such aliases can be chained.
+identifying @var{name} as another name for the glyph mentioned in the
+preceding line.  Such aliases can be chained.
 
 @kindex kernpairs
-The word @code{kernpairs} starts a list of kerning adjustments to be
-made to adjacent glyph pairs from this font.  It contains a sequence of
-lines formatted as follows.
+The directive @code{kernpairs} starts a list of kerning adjustments to
+be made to adjacent glyph pairs from this font.  It contains a sequence
+of lines formatted as follows.
 
 @Example
 @var{g1} @var{g2} @var{n}
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 94b81e5bf..afcf52bd0 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -874,10 +874,9 @@ and stored in the
 .B ct
 register.
 .
-In font descriptions for
-.IR nroff -mode \" generic
-output devices (terminals),
-all glyphs might have a type of zero.
+In font descriptions for terminal devices,
+all glyphs might have a type of zero,
+regardless of their appearance.
 .
 .
 .TP
@@ -968,35 +967,31 @@ is ignored.
 .P
 A line in the
 .B charset
-section can also have the following format.
+section can also have the form
 .
-.
-.IP
+.RS
 .IB name\~ \[dq]
+.RE
 .
-.
-.P
-This notation indicates that
+identifying
 .I name
-is another name for the glyph mentioned in the preceding line.
+as another name for the glyph mentioned in the preceding line.
 .
 Such aliases can be chained.
 .
 .
 .P
-The word
+The directive
 .B \%kernpairs
 starts a list of kerning adjustments to be made to adjacent glyph pairs
 from this font.
 .
 It contains a sequence of lines formatted as follows.
 .
-.
-.IP
+.RS
 .I g1 g2 n
+.RE
 .
-.
-.P
 The foregoing means that when glyph
 .I g1
 is typeset immediately before
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index c79ea5790..44fc97bbd 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -1794,25 +1794,30 @@ Once a
 librarian program has located a man page,
 it may execute a
 .I groff
-command much like the following,
-constructing a pipeline to page the output.
-.
+command much like the following.
 .
 .RS
-.P
 .EX
-groff \-t \-man \-Tutf8 /usr/share/man/man1/groff.1.man | less \-R
+groff \-t \-man \-Tutf8 /usr/share/man/man1/groff.1
 .EE
 .RE
 .
+The librarian will also pipe the output through a pager,
+which might not interpret the SGR terminal escape sequences
+.I groff
+emits for boldface,
+underlining,
+or italics;
+see section \[lq]Limitations\[rq] below.
+.
 .
 .P
 To process a
 .I roff
 input file using the preprocessors
-.I tbl \" AT&T
+.I @g@tbl
 and
-.I pic \" AT&T
+.I @g@pic
 and the
 .I me
 macro package in the way to which AT&T
@@ -1825,14 +1830,14 @@ a pipeline.
 .
 .IP
 .EX
-pic foo.me | tbl | troff \-me \-Tutf8 | grotty
+@g@pic foo.me | @g@tbl | @g@troff \-me \-Tutf8 | grotty
 .EE
 .
 .
 .P
 Using
 .IR groff ,
-this pipe can be shortened to the equivalent command
+this pipe can be shortened to an equivalent command.
 .
 .IP
 .EX