[groff] 09/14: [docs]: Document the ms(7) REFERENCES string.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e8119c2df2420444a92cac3ff6e0fc5bc7ff42f7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Oct 20 09:15:51 2021 +1100

    [docs]: Document the ms(7) REFERENCES string.
    
    This string appeared in a table with no further explanation.  Fix that.
    
    Also stop characterizing eqn, pic, refer, and tbl as "standard groff
    preprocessors"; that's a dubious and unstable concept.  (Who
    standardizes that?  How does this notion differ from what happens to
    appear in a groff release?)
    
    * doc/ms.ms: Also encompass the caveat about multi-page kept tables in a
      keep with the adjacent example.
---
 doc/groff.texi      |  8 ++++++--
 doc/ms.ms           | 25 +++++++++++++++----------
 tmac/groff_ms.7.man | 21 ++++++++++++---------
 3 files changed, 33 insertions(+), 21 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index cac88e4..d3a4c70 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3780,8 +3780,8 @@ boundary.
 @cindex equations [@code{ms}]
 @cindex references [@code{ms}]
 
-The @file{ms} macros support the standard @code{groff} preprocessors:
-@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
+The @file{ms} package is often used with the @code{tbl}, @code{pic},
+@code{eqn}, and @code{refer} preprocessors.
 @pindex tbl
 @pindex pic
 @pindex eqn
@@ -3821,6 +3821,10 @@ to the preprocessor and the format of the 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
+``Works Cited'' page), it interpolates the @code{REFERENCES} string as
+an unnumbered section heading (@code{SH}).
+
 @menu
 * Example multi-page table::
 @end menu
diff --git a/doc/ms.ms b/doc/ms.ms
index 8e69793..a6695ad 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -1978,14 +1978,13 @@ Tables, figures, equations, and references
 .LP
 The
 .I ms
-macros support the standard
-.I groff
-preprocessors:
+package is often used with the
 .I tbl ,
 .I pic ,
 .I eqn ,
 and
-.I refer .
+.I refer
+preprocessors.
 .
 The
 .CW \[rs]n[DD]
@@ -2083,16 +2082,22 @@ T}      T{
 Denote a reference 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 the bibliographic database.
 T}
 .TE
 .KE
 .
 .
+.PP
+When
+.I refer
+emits collected references
+(as might be done on a \[lq]Works Cited\[rq] page),
+it interpolates the string
+.CW \[rs]*[REFERENCES]
+as an unnumbered section heading
+.CW .SH ). (
+.
+.
 .KS
 .NH 3
 An example multi-page table
@@ -2129,7 +2134,6 @@ GH-1978\[->]Fribulating gonkulator
 .fi
 T}
 .TE
-.KE
 .
 .
 .PP
@@ -2139,6 +2143,7 @@ particularly if the
 .I tbl
 .CW allbox
 option is used.
+.KE
 .
 .
 .KS
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index a425c5b..135c76d 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1303,14 +1303,13 @@ Changes to either register take effect at the next 
display boundary.
 .
 The
 .I ms
-macros support the standard
-.I groff
-preprocessors:
+package is often used with the
 .IR \%@g@tbl ,
 .IR \%@g@pic ,
 .IR \%@g@eqn ,
 and
-.IR \%@g@refer .
+.I \%@g@refer
+preprocessors.
 .
 The
 .B \[rs]n[DD]
@@ -1386,12 +1385,16 @@ Denote a reference to be processed by the
 .I refer
 preprocessor.
 .
-The GNU
-.MR @g@refer @MAN1EXT@
-manual page provides a comprehensive reference
-to the preprocessor and the format of the
-bibliographic database.
 .
+.P
+When
+.I \%@g@refer
+emits collected references
+(as might be done on a \[lq]Works Cited\[rq] page),
+it interpolates the string
+.B \[rs]*[REFERENCES]
+as an unnumbered section heading
+.RB ( .SH ).
 .
 .
 .P