[groff] 21/22: [man pages]: Update preprocessor introductions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0ee49756cddc65f63363235513bfa194fc86aadb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Aug 3 00:19:35 2021 +1000

    [man pages]: Update preprocessor introductions.
    
    Make clarifications and parallelize discussions.  Try to require less
    troff foreknowledge.
---
 src/preproc/eqn/eqn.1.man     | 41 +++++++++++++++++------
 src/preproc/pic/pic.1.man     | 47 +++++++++++++++++---------
 src/preproc/refer/refer.1.man | 45 ++++++++++++++++++++-----
 src/preproc/tbl/tbl.1.man     | 76 +++++++++++++++++++++++++++++--------------
 4 files changed, 151 insertions(+), 58 deletions(-)

diff --git a/src/preproc/eqn/eqn.1.man b/src/preproc/eqn/eqn.1.man
index a8560de..7c73824 100644
--- a/src/preproc/eqn/eqn.1.man
+++ b/src/preproc/eqn/eqn.1.man
@@ -78,31 +78,52 @@
 .SH Description
 .\" ====================================================================
 .
-The GNU version of
+The GNU implemenation of
 .I eqn \" GNU
 is part of the
 .IR groff (@MAN7EXT@)
 document formatting system.
 .
 .I \%@g@eqn
-compiles descriptions of equations embedded in
+is a
+.IR \%@g@troff (@MAN1EXT@)
+preprocessor that translates descriptions of equations embedded in
 .IR roff (@MAN7EXT@)
-input files into commands that are understood by
+input files into the language understood by
 .IR \%@g@troff (@MAN1EXT@).
 .
+It copies the contents of each
+.I file
+to the standard output stream,
+except that lines between
+.B .EQ
+and
+.B .EN
+(or \[lq]inline\[rq] within a pair of user-specified delimiters)
+are interpreted as equation descriptions.
+.
 Normally,
-it should be invoked using the
+.I \%@g@eqn
+is not executed directly by the user,
+but invoked by specifying the
 .B \-e
-option of
+option to
 .IR groff (@MAN1EXT@).
 .
-Although its syntax is compatible with
-AT&T
+While GNU
+.IR eqn 's \" GNU
+input syntax is highly compatible with AT&T
 .IR eqn , \" AT&T
-its output cannot be processed with AT&T
+the output
+.I \%@g@eqn
+produces cannot be processed by AT&T
 .IR troff ; \" AT&T
-it must be processed with GNU
-.IR troff . \" GNU
+GNU
+.I troff \" GNU
+(or a
+.I troff \" generic
+implementing relevant GNU extensions)
+must be used.
 .
 If no
 .I file
diff --git a/src/preproc/pic/pic.1.man b/src/preproc/pic/pic.1.man
index 78b02b6..93349df 100644
--- a/src/preproc/pic/pic.1.man
+++ b/src/preproc/pic/pic.1.man
@@ -81,28 +81,46 @@
 .SH Description
 .\" ====================================================================
 .
-This manual page describes the GNU version of
-.IR pic , \" GNU
-which is part of the
-.I groff
+The GNU implementation of
+.I pic \" generic
+is part of the
+.IR groff (@MAN1EXT@)
 document formatting system.
 .
 .I \%@g@pic
-compiles descriptions of pictures embedded within
+is a
+.IR \%@g@troff (@MAN1EXT@)
+preprocessor that compiles descriptions of diagrammatic pictures
+embedded in
 .I troff \" generic
-or \*[tx] input files into commands that are understood by \*[tx] or
-.IR troff .
-.
-Each picture starts with a line beginning with
-.B .PS
-and ends with a line beginning with
-.BR .PE .
+or \*[tx] input files into the language understood by \*[tx] or
+.IR troff . \" generic
 .
-Anything outside of
+It copies the contents of each
+.I file
+to the standard output stream,
+except that lines between
 .B .PS
 and
 .B .PE
-is passed through without change.
+are interpreted as picture descriptions.
+.
+Normally,
+.I \%@g@pic
+is not executed directly by the user,
+but invoked by specifying the
+.B \-p
+option to
+.IR groff (@MAN1EXT@).
+.
+If no
+.I file
+operands are given on the command line,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+the standard input stream is read.
 .
 .
 .LP
@@ -122,7 +140,6 @@ obtained with
 these will center each picture.
 .
 .
-.
 .\" ====================================================================
 .SH Options
 .\" ====================================================================
diff --git a/src/preproc/refer/refer.1.man b/src/preproc/refer/refer.1.man
index ee4b55f..7a843d1 100644
--- a/src/preproc/refer/refer.1.man
+++ b/src/preproc/refer/refer.1.man
@@ -69,26 +69,55 @@
 .SH Description
 .\" ====================================================================
 .
-This file documents the GNU version of
-.IR \%refer , \" generic
-which is part of the
+The GNU implementation of
+.I \%refer \" generic
+is part of the
 .IR groff (@MAN1EXT@)
 document formatting system.
 .
 .I \%@g@refer
-copies the contents of each
+is a
+.IR \%@g@troff (@MAN1EXT@)
+preprocessor that prepares bibilographic citations by looking up
+keywords specified in a
+.IR roff (@MAN7EXT@)
+input document,
+obviating the need to type such annotations,
+and permitting the citation style in formatted output to be altered
+independently and systematically.
+.
+It copies the contents of each
 .I file
 to the standard output stream,
-except that lines between
+except that it interprets lines between
 .B .[
 and
 .B .]\&
-are interpreted as citations,
+as citations to be translated into
+.I groff
+input,
 and lines between
 .B .R1
 and
 .B .R2
-are interpreted as commands about how citations are to be processed.
+as instructions regarding how citations are to be processed.
+.
+Normally,
+.I \%@g@refer
+is not executed directly by the user,
+but invoked by specifying the
+.B \-R
+option to
+.IR groff (@MAN1EXT@).
+.
+If no
+.I file
+operands are given on the command line,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+the standard input stream is read.
 .
 .
 .LP
@@ -143,7 +172,7 @@ The interpretation of lines between
 .B .R1
 and
 .B .R2
-as commands is a new feature of GNU
+as prepreocessor commands is a new feature of GNU
 .IR \%refer . \" GNU
 .
 Documents making use of this feature can still be processed by AT&T
diff --git a/src/preproc/tbl/tbl.1.man b/src/preproc/tbl/tbl.1.man
index dcb4e36..26275da 100644
--- a/src/preproc/tbl/tbl.1.man
+++ b/src/preproc/tbl/tbl.1.man
@@ -60,34 +60,60 @@
 .SH Description
 .\" ====================================================================
 .
-This manual page describes the GNU version of
-.BR tbl ,
-which is part of the groff document formatting system.
+The GNU implementation of
+.I tbl \" generic
+is part of the
+.IR groff (@MAN1EXT@)
+document formatting system.
 .
-.B tbl
-compiles descriptions of tables embedded within
-.B troff
-input files into commands that are understood by
-.BR troff .
+.I \%@g@tbl
+is a
+.IR \%@g@troff (@MAN1EXT@)
+preprocessor that translates descriptions of tables embedded within a
+.IR roff (@MAN7EXT@)
+input files into the language understood by
+.IR \%@g@troff (@MAN1EXT@).
+.
+It copies the contents of each
+.I file
+to the standard output stream,
+except that lines between
+.B .TS
+and
+.B .TE
+are interpreted as table descriptions.
 .
-Normally, it should be invoked using the
+While GNU
+.IR tbl 's \" GNU
+input syntax is highly compatible with AT&T
+.IR tbl , \" AT&T
+the output
+.I \%@g@tbl
+produces cannot be processed by AT&T
+.IR troff ;
+GNU
+.I troff \" GNU
+(or a
+.I troff \" generic
+implementing relevant GNU extensions)
+must be used.
+.
+Normally,
+.I \%@g@gtbl
+is not executed directly by the user,
+but invoked by specifying the
 .B \-t
-option of
-.B groff.
-.
-It is highly compatible with Unix
-.BR tbl .
-.
-The output generated by GNU
-.B tbl
-cannot be processed with Unix
-.BR troff ;
-it must be processed with GNU
-.BR troff .
-.
-If no files are given on the command line or a filename of
-.B \-
-is given, the standard input is read.
+option to
+.IR groff (@MAN1EXT@).
+.
+If no
+.I file
+operands are given on the command line,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+the standard input stream is read.
 .
 .
 .\" ====================================================================