[groff] 04/09: [ms]: Fix content nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 553f7a0810d7985c000cbb34d5da9dbd2d6f95af
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Apr 29 18:39:26 2021 +1000

    [ms]: Fix content nits.
    
    * doc/groff.texi
      (ms Document Description Macros): Clarify what terminates .AU macro
      input (a diversion); one .AU terminates another.  This was implied but
      make it explicit.
      (ms Margins): Sync with groff_ms(7).
      (ms Strings and Special Characters) <REFERENCES>: Note specificity of
      REFERENCES string usage to refer(1) preprocessor.  Also note
      under-documentation of refer(1) integration in a comment.
      <ABSTRACT>: Note use of font style escapes in string value.
      <TOC>: Note default.
      <MONTH1, ...>: Parallelize language with foregoing.  Correct number of
      antecedent.  End sentence with "and so on" instead of "etc.".
      (Differences from AT&T ms): Recast items about compatibility mode and
      AT&T ms CW, GW registers.  Move citation of Lesk 1978 earlier.  Use
      Texinfo @cite command for same citation.  Generalize description of GS
      register to acknowledge other ms implementations beyond AT&T and
      groff.  Drop commented-out paragraphs about "Bell localisms" (see
      commit 15f8e92d, 3 March 2021).
      (Additional ms Macros): Drop superfluous "for details" after a
      cross-reference.
    
    * doc/ms.ms
      (Document description macros) <AU>:
      (groff macros not appeating in AT&T troff) <REFERENCES, ABSTRACT, TOC,
      MONTH1, ...>:
    * tmac/groff_ms.7.man
      (Document description macros) <AU>:
      (Differences from troff ms) <compatibility mode, CW/GW>:
      (Localization strings): Sync with our Texinfo manual.
    
    * tmac/groff_ms.7.man (Differences from troff ms)
      <default page offset, GS>: Apply normative styling.
      <display adjustment default, right-adjusted displays, .NH S>: New;
      adapt from our Texinfo manual.
---
 doc/groff.texi      |  70 +++++++++++++++--------------------
 doc/ms.ms           |  39 ++++++++++++++++---
 tmac/groff_ms.7.man | 105 +++++++++++++++++++++++++++++++++++++++++-----------
 3 files changed, 147 insertions(+), 67 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index a691462..9d3e406 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2872,8 +2872,8 @@ following a call to this macro into the title until 
reaching an
 @Defmac {AU, , ms}
 Specify an author's name.  @file{ms} collects text on input lines
 following a call to this macro into the author's name until reaching an
-@code{AI}, @code{AB}, or heading or paragraph macro call.  Call
-@code{AU} repeatedly to specify multiple authors.
+@code{AI}, @code{AB}, another @code{AU}, or heading or paragraph macro
+call.  Call it repeatedly to specify multiple authors.
 @endDefmac
 
 @Defmac {AI, , ms}
@@ -3857,8 +3857,10 @@ after executing the @code{PT} macro.
 @subsubsection Margins
 @cindex @code{ms} macros, margins
 
-You control margins using a set of registers.  @xref{ms Document Control
-Settings}, for details.
+Control margins using registers.  See ``Margin Settings'' in @ref{ms
+Document Control Settings}.  There is no right margin setting; the
+combination of page offset and line length provide the information
+necessary to derive the right margin.
 
 @c ---------------------------------------------------------------------
 
@@ -3989,17 +3991,21 @@ change the string definitions to help in creating 
documents in languages
 other than English.
 
 @Defstr {REFERENCES, ms}
-Contains the string printed at the beginning of the references
-(bibliography) page.  The default is @samp{References}.
+Contains the string printed at the beginning of a references
+(bibliography) page produced with GNU @cite{refer@r{(1)}}.  The default
+is @samp{References}.
+@c XXX: Use of refer(1) with ms is insufficiently documented.
 @endDefstr
 
 @Defstr {ABSTRACT, ms}
 Contains the string printed at the beginning of the abstract.  The
-default is @samp{ABSTRACT}.
+default is @samp{\f[I]ABSTRACT\f[]}; it includes font style escapes to
+set the word in italics.
 @endDefstr
 
 @Defstr {TOC, ms}
 Contains the string printed at the beginning of the table of contents.
+The default is @samp{Table of Contents}.
 @endDefstr
 
 @DefstrList {MONTH1, ms}
@@ -4014,8 +4020,8 @@ Contains the string printed at the beginning of the table 
of contents.
 @DefstrItemx {MONTH10, ms}
 @DefstrItemx {MONTH11, ms}
 @DefstrListEndx {MONTH12, ms}
-Prints the full name of the month in dates.  The default is
-@samp{January}, @samp{February}, etc.
+Contain the full names of the calendar months.  The defaults are in
+English: @samp{January}, @samp{February}, and so on.
 @endDefstr
 
 The following special characters are available.@footnote{For an
@@ -4163,8 +4169,9 @@ The general error-handling policy of @code{groff} 
@file{ms} is to detect
 and report errors, rather than silently to ignore them.
 
 @item
-@code{groff} @file{ms} does not work in compatibility mode (that is,
-with the @option{-C} option).
+@code{groff} @file{ms} does not work in GNU @code{troff}'s
+@acronym{AT&T} compatibility mode.  If loaded when that mode is enabled,
+it aborts processing with a diagnostic message.
 
 @item
 There is no special support for terminal devices.
@@ -4177,9 +4184,13 @@ Multiple line spacing is not supported.  Use a larger 
vertical spacing
 instead.
 
 @item
-Some Unix @code{ms} documentation says that the @code{CW} and @code{GW}
-registers can be used to control the column width and gutter width,
-respectively.  These registers are not used in @code{groff} @file{ms}.
+The @acronym{AT&T} @code{troff} @file{ms} manual@footnote{@cite{Typing
+Documents on the UNIX System: Using the -ms Macros with Troff and
+Nroff}; M.@: E.@: Lesk; Bell Laboratories; 1978.} describes @code{CW}
+and @code{GW} registers that can be used to control the column width and
+gutter width, respectively.  These registers are not used in
+@code{groff} @file{ms}.  (However, see @code{MINGW} in @ref{ms Multiple
+Columns}.)
 
 @item
 Macros that cause a reset (paragraphs, headings, etc.@:) may change the
@@ -4204,10 +4215,8 @@ Displays are left-adjusted by default, not indented.  In 
@acronym{AT&T}
 @item
 Right-adjusted displays are available.  The @acronym{AT&T} @code{troff}
 @file{ms} manual observes that ``it is tempting to assume that @samp{.DS
-R} will right adjust lines, but it doesn't
-work''.@footnote{``Typing Documents on the UNIX System: Using the -ms
-Macros with Troff and Nroff''; M.@: E.@: Lesk; Bell Laboratories; 1978.}
-In @code{groff} @file{ms}, it does.
+R} will right adjust lines, but it doesn't work''.  In @code{groff}
+@file{ms}, it does.
 
 @item
 @code{groff} @file{ms} handles @code{S} as the first argument to the
@@ -4218,29 +4227,10 @@ In @code{groff} @file{ms}, it does.
 This register is set to@tie{}1 by the @code{groff} @file{ms} macros, but
 it is not used by the @acronym{AT&T} @code{troff} @file{ms} macros.
 Documents that need to determine whether they are being formatted with
-@acronym{AT&T} @samp{troff -ms} or @code{groff} @file{ms} should use
-this register.
+@code{groff} @file{ms} or another implementation should use this
+register.
 @endDefmpreg
 
-@c Emulations of a few ancient Bell Labs macros can be re-enabled by
-@c calling the otherwise undocumented @code{SC} section-header macro.
-@c Calling @code{SC} enables @code{UC} for marking up a product or
-@c application name, and the pair @code{P1}/@code{P2} for surrounding
-@c code example displays.
-@c
-@c These are not enabled by default because (a)@tie{}they were not
-@c documented in the original @code{ms} manual@footnote{@slanted{Ibid.}}
-@c and (b)@tie{}the @code{P1} and @code{UC} macros collide with
-@c different macros with the same names in the Berkeley version of
-@c @code{ms}.
-@c
-@c These @code{groff} emulations are sufficient to give back the 1976
-@c Kernighan@tie{}& Cherry @command{eqn} manual @cite{Typesetting
-@c Mathematics---User's Guide} its section headings, and restore some
-@c text that had gone missing as arguments of undefined macros.  No
-@c warranty express or implied is offered as to how well the typographic
-@c details these produce match the original Bell Labs macros.
-
 @menu
 * Missing ms Macros::
 * Additional ms Macros::
@@ -4322,7 +4312,7 @@ that was introduced in the Seventh Edition Unix (1979) 
version of the
 
 Several new strings are available as well.  You can change these to
 handle (for example) the local language.  @xref{ms Strings and Special
-Characters}, for details.
+Characters}.
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 697c41e..0c45b34 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -471,11 +471,11 @@ collects text on input lines following a call to this 
macro into the
 author's name until reaching an
 .CW .AI ,
 .CW .AB ,
+another
+.CW .AU ,
 or heading or paragraph macro.
 .
-Call
-.CW .AU
-repeatedly to specify multiple authors.
+Call it repeatedly to specify multiple authors.
 T}
 _
 \&.AI  T{
@@ -2464,14 +2464,43 @@ register that was documented but apparently not 
implemented in
 .I troff .
 Several new string registers are available as well.
 You can change these to handle (for example) the local language.
+.
+.
 .IP REFERENCES 0.5i
-Contains the string printed at the beginning of the
-references (bibliography) page.
+Contains the string printed at the beginning of a references
+(bibliography) page produced with GNU
+.I refer (1).
+.
+The default is
+.CW References \[rq]. \[lq]
+.\" XXX: Use of refer(1) with ms is insufficiently documented.
+.
+.
 .IP ABSTRACT
 Contains the string printed at the beginning of the abstract.
+.
+The default is
+.CW \[rs]f[I]ABSTRACT\[rs]f[] \[rq]; \[lq]
+it includes font style escapes to set the word in italics.
+.
+.
 .IP TOC
 .br
 Contains the string printed at the beginning of the table of contents.
+.
+The default is
+.CW "Table of Contents" \[rq]. \[lq]
+.
+.
+.IP "MONTH1, MONTH2, MONTH3, .\|.\|.\|, MONTH10, MONTH11, MONTH12"
+Contain the full names of the calendar months.
+.
+The defaults are in English:
+.CW January \[rq], \[lq]
+.CW February \[rq],\[lq]
+and so on.
+.
+.
 .\" ------------------------
 .if t .bp
 .NH 1
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index d6fb60f..3c77d9c 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -360,11 +360,11 @@ collects text on input lines following a call to this 
macro into the
 author's name until reaching an
 .BR .AI ,
 .BR .AB ,
-or heading or paragraph macro.
+another
+.BR .AU ,
+or heading or paragraph macro call.
 .
-Call
-.B .AU
-repeatedly to specify multiple authors.
+Call it repeatedly to specify multiple authors.
 .
 .
 .TP
@@ -1552,9 +1552,13 @@ does not.)
 .
 .IP \[bu]
 .I groff ms
-does not work in compatibility mode (e.g., with the
-.B \-C
-option).
+does not work in
+.IR \%@g@troff 's
+compatibility mode.
+.
+If loaded when that mode is enabled,
+it aborts processing with a diagnostic message.
+.
 .
 .IP \[bu]
 There is no support for typewriter-like devices.
@@ -1567,19 +1571,34 @@ does not provide cut marks.
 Multiple line spacing is not supported
 (use a larger vertical spacing instead).
 .
+.
 .IP \[bu]
-Some Unix
-.I ms
-documentation says that the
+The AT&T
+.I troff ms
+manual
+(\[lq]Typing Documents on the UNIX System: Using the \-ms Macros with
+Troff and Nroff\[rq];
+M.\& E.\& Lesk;
+Bell Laboratories;
+1978)
+describes
 .B CW
 and
 .B GW
-registers can be used to control the column width and gutter width,
+registers that can be used to control the column width and gutter width,
 respectively.
 .
 These registers are not used in
 .IR "groff ms" .
 .
+(However,
+see
+.B MINGW
+in the \[lq]Other Settings\[rq] table of subsection \[lq]Document
+control settings\[rq],
+above.
+.
+.
 .IP \[bu]
 Macros that cause a reset
 (paragraphs, headings, etc.\&)
@@ -1603,17 +1622,58 @@ macros.
 .IP \[bu]
 To make
 .I groff ms
-use the default page offset (which also specifies the left margin),
+use the default page offset
+(which also specifies the left margin),
 the
 .B PO
 register must stay undefined until the first
 .B ms
-macro is evaluated.
+macro is called.
 .
 This implies that
 .B PO
-should not be used early in the document, unless it is changed also:
-remember that accessing an undefined register automatically defines it.
+should not be used early in the document,
+unless it is changed also:
+accessing an undefined register automatically defines it.
+.
+.
+.IP \[bu]
+Displays are left-adjusted by default,
+not indented.
+.
+In AT&T
+.IR "troff ms" ,
+.B .DS
+is synonymous with
+.RB \[lq] ".DS I" \[rq];
+in
+.IR "groff ms" ,
+it is synonymous with
+.RB \[lq] ".DS L" \[rq].
+.
+.
+.IP \[bu]
+Right-adjusted displays are available.
+.
+The AT&T
+.I troff ms
+manual observes that \[lq]it is tempting to assume that \[oq].DS R\[cq]
+will right adjust lines,
+but it doesn't work\[rq].
+.
+In
+.IR "groff ms" ,
+it does.
+.
+.
+.IP \[bu]
+.I groff ms
+handles
+.RB \[lq] S \[rq]
+as the first argument to the
+.B NH
+macro specially,
+allowing explicit numbering of headings.
 .
 .
 .IP \[bu]
@@ -1622,16 +1682,13 @@ The register
 is set to\~1 by the
 .I groff ms
 macros,
-but is not used by the Unix
-.I ms
+but is not used by the AT&T
+.I troff ms
 macros.
 .
 Documents that need to determine whether they are being formatted with
-Unix
-.I ms
-or
 .I groff ms
-should use this register.
+or another implementation should use this register.
 .
 .
 .\" ====================================================================
@@ -1649,7 +1706,7 @@ lfCR lfCR.
 String Default
 _
 REFERENCES     References
-ABSTRACT       ABSTRACT
+ABSTRACT       \[rs]f[I]ABSTRACT\[rs]f[]
 TOC    Table of Contents
 MONTH1 January
 MONTH2 February
@@ -1667,6 +1724,10 @@ _
 .TE
 .RE
 .
+The default for
+.B ABSTRACT
+includes font style escapes to set the word in italics.
+.
 .
 .PP
 The