[groff] 05/10: man/groff_tmac.5.man: Correct erroneous reference.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit bbbcafc81188537bce6c40ffeb6b5d0ac707c7d5
Author: Dave Kemper <saint.snit@gmail.com>
AuthorDate: Sun Mar 14 04:57:34 2021 +0000

    man/groff_tmac.5.man: Correct erroneous reference.
    
    ...to PSPIC where PDFPIC was intended.
    
    Also:
    * (plagiarizing Branden from commit a8f804ff): Say "output driver"
      instead of "output device" when referring to postprocessors rather
      than the hardware that handles their output.
    * (plagiarizing Branden): Stop using "-T" as if it were part of the name
      of an output driver.  The "-T" option takes the name of an output
      driver as an argument; to pretend otherwise is pedagogically unsound.
    * Change predictions of mom's future to commentary on her past and
      present.
    * Remove spaces in .BR parameter lists that were unnecessarily bolding
      trailing punctuation.
    * Drop unnecessary hyphens ("typesetting" in place of "type-setting,"
      "run time" used nonattributively) and add clarifying ones
      ("colon-separated list").
    * Streamline and clarify clunky wording.
    
    Fixes <https://savannah.gnu.org/bugs/?60229>.
---
 ChangeLog            |   8 +++
 man/groff_tmac.5.man | 155 +++++++++++++++++++++++++--------------------------
 2 files changed, 85 insertions(+), 78 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index cb0e152..f081f84 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2021-03-14  Dave Kemper <saint.snit@gmail.com>
+
+       * man/groff_tmac.5.man: Correct erroneous reference to PSPIC
+       where PDFPIC was intended.  Fix numerous smaller style and
+       content problems.
+
+       Fixes <https://savannah.gnu.org/bugs/?60229>.
+
 2021-03-03  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/groff.texi (Optional man extensions) <CW, EX, PN, Pn>:
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 8a9c34c..2358b0d 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -9,7 +9,7 @@ groff_tmac \- macro files in the GNU roff typesetting system
 .\"
 .\" Copyright (C) 2000-2020 Free Software Foundation, Inc.
 .\"
-.\" This file is part of groff, the GNU roff type-setting system.
+.\" This file is part of groff, the GNU roff typesetting system.
 .\"
 .\" Permission is granted to copy, distribute and/or modify this
 .\" document under the terms of the GNU Free Documentation License,
@@ -32,14 +32,14 @@ groff_tmac \- macro files in the GNU roff typesetting system
 .
 The
 .BR roff (@MAN7EXT@)
-type-setting system provides a set of macro packages suitable for
+typesetting system provides a set of macro packages suitable for
 special kinds of documents.
 .
 Each macro package stores its macros and definitions in a file called
 the package's
 .BR "tmac file" .
 .
-The name is deduced from
+The name is derived from
 .RB \[oq] T\c
 .IB roff MAC\c
 .IR ros \[cq].
@@ -63,8 +63,8 @@ directories.
 provides all classical macro packages, some more full packages, and
 some secondary packages for special purposes.
 .
-Note that it is not possible to use multiple primary macro packages at
-the same time; saying e.g.,
+Multiple primary macro packages cannot be used simultaneously; saying,
+e.g.,
 .
 .IP
 .EX
@@ -83,7 +83,7 @@ or
 .P
 fails.
 .
-Exception to this is the use of man pages written with either the
+An exception to this is the use of man pages written with either the
 .B mdoc
 or the
 .B man
@@ -118,7 +118,7 @@ man\~pages; see
 .I andoc
 .TQ
 .I mandoc
-Use this file in case you don't know whether the
+Use this file if you don't know whether the
 .B man
 macros or the
 .B mdoc
@@ -155,13 +155,12 @@ macro package; see
 .
 .TP
 .I mom
-The new
+The
 .I mom
 macro package, only available in groff.
 .
-As this is not based on other packages, it can be freely designed.
-.
-So it is expected to become quite a nice, modern macro package.
+As this was not based on other packages, it was freely designed as
+quite a nice, modern macro package.
 .
 See
 .BR groff_mom (@MAN7EXT@).
@@ -204,7 +203,7 @@ selects hyphenation patterns for traditional orthography, 
and
 does the same for the new orthography
 (\[oq]Recht\%schreib\%reform\[cq]).
 .
-It should be used as the last macro package on the command line.
+It should be the last macro package on the command line.
 .
 .
 .TP
@@ -233,10 +232,10 @@ sets the input encoding to latin-9 to get proper support 
of the
 Swedish localization support, including the me, mom, and ms macro
 packages.
 .
-Note that Swedish for the mm macros is handled separately; see
+Swedish for the mm macros is handled separately; see
 .BR groff_mmse (@MAN7EXT@).
 .
-It should be used as the last macro package on the command line.
+It should be the last macro package on the command line.
 .
 .
 .\" ====================================================================
@@ -260,7 +259,7 @@ specified as the first macro argument on the command line.
 .I groff
 loads latin1 by default at start-up.
 .
-Note that these macro packages don't work on EBCDIC hosts.
+These macro packages don't work on EBCDIC hosts.
 .
 .
 .TP
@@ -275,8 +274,8 @@ it doesn't work on architectures which are based on ASCII.
 .
 .
 .P
-Note that it can happen that some input encoding characters are not
-available for a particular output device.
+Some input encoding characters may not be available for a particular
+output device.
 .
 For example, saying
 .
@@ -288,11 +287,11 @@ groff \-Tlatin1 \-mlatin9 ...
 .P
 fails if you use the Euro character in the input.
 .
-Usually, this limitation is present only for devices which have a
+Usually, this limitation is present only for drivers which have a
 limited set of output glyphs
-.RB ( \-Tascii ,
-.BR \-Tlatin1 );
-for other devices it is usually sufficient to install proper
+.RB ( ascii ,
+.BR latin1 );
+for other drivers it is usually sufficient to install proper
 fonts which contain the necessary glyphs.
 .
 .
@@ -301,8 +300,8 @@ fonts which contain the necessary glyphs.
 .\" ====================================================================
 .
 The macro packages in this section are not intended for stand-alone
-usage, but can be used to add special functionality to any other
-macro package or to plain groff.
+usage, but can add special functionality to any other macro package
+or to plain groff.
 .
 .
 .TP
@@ -317,7 +316,7 @@ Switch to the EC and TC font families.
 .
 To be used with
 .BR \%grodvi (@MAN1EXT@)
-\[en] this man page also gives more details of how to use it.
+\[em] this man page also gives more details of how to use it.
 .
 .
 .TP
@@ -333,18 +332,18 @@ is a macro package, not a preprocessor like
 .
 .I hdtbl
 works only with the
-.B \-Tps
+.B ps
 and
-.B \-Tpdf
-output devices.
+.B pdf
+output drivers.
 .
 See
-.BR groff_hdtbl (@MAN7EXT@) .
+.BR groff_hdtbl (@MAN7EXT@).
 .
 .
 .TP
 .I papersize
-This macro file is already loaded at start-up by
+This macro file is automatically loaded at start-up by
 .B @g@troff
 so it isn't necessary to call it explicitly.
 .
@@ -389,11 +388,11 @@ orientation:
 .TP
 .I pdfpic
 A single macro is provided in this file,
-.BR PSPIC ,
-to include a PDF graphic in a document, i.e., under the output device
-.BR \-Tpdf .
+.BR PDFPIC ,
+to include a PDF graphic in a document, i.e., under the output driver
+.BR pdf .
 .
-For all other devices,
+For all other drivers,
 .I pspic
 is used.
 .
@@ -402,10 +401,10 @@ So
 is an extension of
 .IR pspic .
 .
-By that you can now even replace all
+This means you can safely replace all
 .B PSPIC
-by
-.BR PDFPIC ,
+with
+.BR PDFPIC ;
 nothing gets lost by that.
 .
 The options of
@@ -428,7 +427,7 @@ preprocessor.
 They center each picture.
 .
 Use it only if your macro package doesn't provide proper
-definitions for those two macros (actually, most of them already do).
+definitions for those two macros (most of them already do).
 .
 .
 .TP
@@ -437,16 +436,16 @@ A single macro is provided in this file,
 .BR PSPIC ,
 to include a PostScript graphic in a document.
 .
-The following output devices support inclusion of PS images:
-.BR \-Tps ,
-.BR \-Tdvi ,
-.BR \-Thtml ,
+The
+.BR ps ,
+.BR dvi ,
+.BR html ,
 and
-.BR \-Txhtml ;
-for all other devices the image is replaced with a hollow rectangle
-of the same size.
+.B xhtml
+output drivers support inclusion of PS images; for all other drivers
+the image is replaced with a hollow rectangle of the same size.
 .
-This macro file is already loaded at start-up by
+This macro file is automatically loaded at start-up by
 .B @g@troff
 so it isn't necessary to call it explicitly.
 .
@@ -502,12 +501,11 @@ The
 .B \-L
 and
 .B \-R
-options cause the graphic to be left-aligned and right-aligned,
-respectively.
+options left-align and right-align the graphic, respectively.
 .
 The
 .B \-I
-option causes the graphic to be indented by\~\c
+option indents the graphic by\~\c
 .I n
 (default scaling indicator is\~\c
 .BR m ).
@@ -540,8 +538,8 @@ for formatting permuted index entries as produced by the GNU
 .BR ptx (1)
 program.
 .
-In case you need a different formatting, copy the macro into
-your document and adapt it to your needs.
+If you need different formatting, copy the macro into your document and
+adapt it to your needs.
 .
 .
 .TP
@@ -550,7 +548,7 @@ defines special character escape sequences based on the 
glyph mnemonics
 specified in RFC 1345 and the digraph table of the text editor Vim.
 .
 See
-.BR groff_rfc1345 (@MAN7EXT@) .
+.BR groff_rfc1345 (@MAN7EXT@).
 .
 .
 .TP
@@ -560,7 +558,7 @@ Use this for tracing macro calls.
 It is only useful for debugging.
 .
 See
-.BR groff_trace (@MAN7EXT@) .
+.BR groff_trace (@MAN7EXT@).
 .
 .
 .TP
@@ -579,9 +577,10 @@ which can allow easier processing with critical equipment.
 .
 .TP
 .I www
-Additions of elements known from the HTML format, as used in the
-internet (World Wide Web) pages; this includes URL links and mail
-addresses; see
+Additions of elements known from the HTML format, as used in World
+Wide Web pages; this includes URL links and mail addresses.
+.
+See
 .BR groff_www (@MAN7EXT@).
 .
 .
@@ -719,7 +718,7 @@ There are several ways to use a macro package in a document.
 The classical way is to specify the troff/groff option
 .B \-m
 .I name
-at run-time; this makes the contents of the macro package
+at run time; this makes the contents of the macro package
 .I name
 available.
 .
@@ -735,7 +734,7 @@ Alternatively, it is also possible to include a macro file 
by adding
 the request
 .B .so
 .I filename
-into the document; the argument must be the full file name of an
+to the document; the argument must be the full file name of an
 existing file, possibly with the directory where it is kept.
 .
 In groff, this was improved by the similar request
@@ -747,7 +746,7 @@ does.
 .
 .
 .P
-Note that in order to resolve the
+In order to resolve the
 .B .so
 and
 .B .mso
@@ -775,7 +774,7 @@ and is used in some document called
 .
 .
 .P
-At run-time, the formatter call for this is
+At run time, the formatter call for this is
 .
 .IP
 .EX
@@ -784,7 +783,7 @@ At run-time, the formatter call for this is
 .
 .
 .P
-To include the macro file directly in the document either
+To include the macro file directly in the document, use either
 .
 .IP
 .EX
@@ -792,7 +791,7 @@ To include the macro file directly in the document either
 .EE
 .
 .P
-is used or
+or
 .
 .IP
 .EX
@@ -831,7 +830,7 @@ request or the option
 .\" This section does not fit into the framework of this document.
 .
 There is a convention that is supported by many modern roff
-type-setters and
+typesetters and
 .BR man (1)
 programs, the
 .I preprocessor word
@@ -910,7 +909,7 @@ file.
 .P
 Macros without arguments are just like strings.
 .
-But the full power of macros reveals when arguments are passed with a
+But the full power of macros occurs when arguments are passed with a
 macro call.
 .
 Within the macro definition, the arguments are available as the escape
@@ -1002,7 +1001,7 @@ which results in
 and
 .RI \[rs]\[rs] [.$] .
 The same applies to the macro name because it could be called with an
-alias name, so
+alias, so
 .RI \[rs]\[rs] $0 .
 .
 .
@@ -1029,7 +1028,7 @@ and
 Writing groff macros is easy when the escaping mechanism is temporarily
 disabled.
 .
-In groff, this is done by enclosing the macro definition(s) into a
+In groff, this is done by enclosing the macro definition(s) within a
 pair of
 .B .eo
 and
@@ -1133,7 +1132,7 @@ C\~programming language, but their usage is quite 
different.
 .
 .P
 In their simplest form, diversions are multi-line strings, but
-they get their power when diversions are used dynamically within macros.
+diversions get their power when used dynamically within macros.
 .
 The (formatted) information stored in a diversion can be retrieved by
 calling the diversion just like a macro.
@@ -1141,17 +1140,17 @@ calling the diversion just like a macro.
 .
 .P
 Most of the problems arising with diversions can be avoided if you
-remain aware of the fact that diversions always store complete lines.
+remember that diversions always store complete lines.
 .
-If diversions are used when the line buffer has not been flushed,
-strange results are produced; not knowing this, many people get
-desperate about diversions.
+Using diversions when the line buffer has not been flushed produces
+strange results; not knowing this, many people get desperate about
+diversions.
 .
-To ensure that a diversion works, line breaks should be added at the
-right places.
+To ensure that a diversion works, add line breaks at the right
+places.
 .
-To be on the secure side, enclose everything that has to do with
-diversions into a pair of line breaks; for example, by explicitly using
+To be safe, enclose everything that has to do with diversions within
+a pair of line breaks; for example, by explicitly using
 .B .br
 requests.
 .
@@ -1162,10 +1161,10 @@ This is a bit of overkill, but it works nicely.
 .
 .
 .P
-[If you really need diversions which should ignore the current partial
+(If you really need diversions which should ignore the current partial
 line, use environments to save the current partial line and/\:or use the
 .B .box
-request.]
+request.)
 .
 .
 .P
@@ -1191,12 +1190,12 @@ as with classical packages is possible as well, but 
deprecated.
 .P
 The macro files are kept in the
 .IR "tmac directories" ;
-a colon separated list of these constitutes the
+a colon-separated list of these constitutes the
 .IR "tmac path" .
 .
 .
 .P
-The search sequence for macro files is (in that order):
+The search sequence for macro files is (in this order):
 .
 .IP \(bu
 the directories specified with troff/groff's