[groff] 22/40: [ms]: Tweak descriptions of preprocessor macros.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2bed3e15ee272b57f1be59c3127dbba5b5ff5e82
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Feb 4 08:43:47 2022 +1100

    [ms]: Tweak descriptions of preprocessor macros.
    
    * Be more precise about how preprocessor tokens are recognized, and call
      them "tokens" rather than "tags".  (Is our HTML hangover wearing off?)
    * Fix solecism.
    * Be more clear about what the preprocessors are used for.
    * Include (and align) citations of tbl(1) and refer(1) man pages, since
      they are complete and not merely coverage of GNU extensions.
---
 doc/groff.texi      | 31 ++++++++++++++++++-------------
 doc/ms.ms           | 24 ++++++++++++++++++------
 tmac/groff_ms.7.man | 22 ++++++++++++++++------
 3 files changed, 52 insertions(+), 25 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b1f8ef9e..c52e73e4 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3843,39 +3843,44 @@ The @file{ms} package is often used with the 
@code{tbl}, @code{pic},
 @pindex pic
 @pindex eqn
 @pindex refer
-Mark text meant for preprocessors by enclosing it in pairs of tags
-as follows, with no space between the dot and the macro name.
+Mark text meant for preprocessors by enclosing it in pairs of tokens
+as follows, with nothing between the dot and the macro name.  The
+preprocessors match these tokens only at the start of an input line.
 
 @DefmacList {TS, [@code{H}], ms}
 @DefmacListEndx {TE, , ms}
-Denote a table to be processed by the @code{tbl} preprocessor.  The
+Demarcate a table to be processed by the @code{tbl} preprocessor.  The
 optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} to
 repeat table rows (often column headings) at the top of each new page
 the table spans, if applicable; calling the @code{TH} macro marks the
-end of such rows.
+end of such rows.  The GNU @cite{tbl@r{(1)}} man page provides a
+comprehensive reference to the preprocessor and offers examples of its
+use.
 @endDefmac
 
 @DefmacList {PS, , ms}
 @DefmacListEndx {PE, , ms}
-Denote a graphic to be processed by the @code{pic} preprocessor.  You
+Demarcate a diagram to be processed by the @code{pic} preprocessor.  You
 can create @code{pic} input manually or by using a program such as
 @code{xfig}.
 @endDefmac
 
 @DefmacList {EQ, [@Var{align}], ms}
 @DefmacListEndx {EN, , ms}
-Denote an equation to be processed by the @code{eqn} preprocessor.  The
-equation is center-aligned by default; the optional @var{align} argument
-can be @samp{C}, @samp{L}, or @samp{I} to center, left-align, or indent
-it by the amount stored in the @code{DI} register, respectively.
+Demarcate an equation to be processed by the @code{eqn} preprocessor.
+The equation is center-aligned by default; the optional @var{align}
+argument can be @samp{C}, @samp{L}, or @samp{I} to center, left-align,
+or indent it by the amount stored in the @code{DI} register,
+respectively.
 @endDefmac
 
 @DefmacList {[, , ms}
 @DefmacListEndx {], , ms}
-Denote a reference to be processed by the @code{refer} preprocessor.
-The GNU @cite{refer@r{(1)}} man page provides a comprehensive reference
-to the preprocessor and the format of the bibliographic database.  Type
-@samp{man refer} at the command line to view it.
+Demarcate a bibliographic citation to be processed by the @code{refer}
+preprocessor.  The GNU @cite{refer@r{(1)}} man page provides a
+comprehensive reference to the preprocessor and the format of its
+bibliographic database.  Type @samp{man refer} at the command line to
+view it.
 @endDefmac
 
 When @code{refer} emits collected references (as might be done on a
diff --git a/doc/ms.ms b/doc/ms.ms
index b207b067..ce3139ce 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -2024,9 +2024,11 @@ distance is also applied to regions of the document 
preprocessed with
 and
 .I eqn .
 .
-Mark text meant for preprocessors by enclosing it in pairs of tags as
+Mark text meant for preprocessors by enclosing it in pairs of tokens as
 follows,
-with no space between the dot and the macro name.
+with nothing between the dot and the macro name.
+.
+The preprocessors match these tokens only at the start of an input line.
 .
 .
 .TS
@@ -2043,7 +2045,7 @@ T{
 .br
 \&.TE
 T}     T{
-Denote a table to be processed by the
+Demarcate a table to be processed by the
 .I tbl
 preprocessor.
 .
@@ -2060,6 +2062,11 @@ if applicable;
 calling the
 .CW TH
 macro marks the end of such rows.
+.
+The GNU
+.I tbl (1)
+man page provides a comprehensive reference to the preprocessor and
+offers examples of its use.
 T}
 _
 T{
@@ -2067,7 +2074,7 @@ T{
 .br
 \&.PE
 T}     T{
-Denote a graphic to be processed by the
+Demarcate a diagram to be processed by the
 .I pic
 preprocessor.
 .
@@ -2085,7 +2092,7 @@ T{
 .br
 \&.EN
 T}     T{
-Denote an equation to be processed by the
+Demarcate an equation to be processed by the
 .I eqn
 preprocessor.
 .
@@ -2109,9 +2116,14 @@ T{
 .br
 \&.]
 T}     T{
-Denote a reference to be processed by the
+Demarcate a bibliographic citation to be processed by the
 .I refer
 preprocessor.
+.
+The GNU
+.I refer (1)
+man page provides a comprehensive reference to the preprocessor and the
+format of its bibliographic database.
 T}
 .TE
 .KE
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index c40648a6..65f6d0fa 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1371,16 +1371,18 @@ distance is also applied to regions of the document 
preprocessed with
 and
 .IR \%@g@tbl .
 .
-Mark text meant for preprocessors by enclosing it in pairs of tags as
+Mark text meant for preprocessors by enclosing it in pairs of tokens as
 follows,
-with no space between the dot and the macro name.
+with nothing between the dot and the macro name.
+.
+The preprocessors match these tokens only at the start of an input line.
 .
 .
 .TP
 .BR .TS " [" H "]
 .TQ
 .B .TE
-Denote a table to be processed by the
+Demarcate a table to be processed by the
 .I tbl
 preprocessor.
 .
@@ -1396,12 +1398,16 @@ calling the
 .B TH
 macro marks the end of such rows.
 .
+.MR @g@tbl @MAN1EXT@
+provides a comprehensive reference to the preprocessor and offers
+examples of its use.
+.
 .
 .TP
 .B .PS
 .TQ
 .B .PE
-Denote a graphic to be processed by the
+Demarcate a diagram to be processed by the
 .I pic
 preprocessor.
 .
@@ -1411,7 +1417,7 @@ preprocessor.
 .RI " [" align ]
 .TQ
 .B .EN
-Denote an equation to be processed by the
+Demarcate an equation to be processed by the
 .I eqn
 preprocessor.
 .
@@ -1433,10 +1439,14 @@ respectively.
 .B .[
 .TQ
 .B .]
-Denote a reference to be processed by the
+Demarcate a bibliographic citation to be processed by the
 .I refer
 preprocessor.
 .
+.MR @g@refer @MAN1EXT@
+provides a comprehensive reference to the preprocessor and the format of
+its bibliographic database.
+.
 .
 .P
 When