[groff] 06/08: [ms]: Fix documentation style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 49a458a7b965621b969507ad3c72a4253dcabcfd
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 4 18:26:58 2021 +1000

    [ms]: Fix documentation style nits.
    
    * Consistently say "AT&T ms" instead of "AT&T troff ms" or "troff ms".
    * Drop period from non-sentential footnote.
    * Drop duplicate full citation of Lesk 1978 from our Texinfo manual.
    * Move full citation of Lesk 1978 to its first mention.
    * Fix missing parenthesis.
    * Fix missing words.
    * Drop junk arguments from ms .I call.
    * Fix incorrect quotation glyph.
---
 doc/groff.texi      | 62 +++++++++++++++++++++++++----------------------------
 doc/ms.ms           | 42 +++++++++++++++++++-----------------
 tmac/groff_ms.7.man | 42 ++++++++++++++++++------------------
 3 files changed, 72 insertions(+), 74 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index d8f0e73..7b54458 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2978,10 +2978,10 @@ Several paragraph types are available, differing in how 
indentation is
 applied: to left, right, or both margins; to the first output line of
 the paragraph, all output lines, or all but the first.  All paragraphing
 macro calls cause the insertion of vertical space in the amount stored
-in the @code{PD} register, except at page breaks.  The @code{PORPHANS}
-register (@pxref{ms Document Control Settings}) operates in conjunction
-with each of these macros to inhibit the printing of orphaned lines at
-the bottom of any page.
+in the @code{PD} register, except at page or column breaks.  The
+@code{PORPHANS} register (@pxref{ms Document Control Settings}) operates
+in conjunction with each of these macros to inhibit the printing of
+orphaned lines at the bottom of any page.
 
 @Defmac {LP, , ms}
 Set a paragraph without any (additional) indentation.
@@ -4158,18 +4158,18 @@ Uppercase 
 @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
 
 This section lists the (minor) differences between the @code{groff}
-@file{ms} macros and @acronym{AT&T} @code{troff} @file{ms} macros.
+@file{ms} macros and @acronym{AT&T} @file{ms} macros.
 
 @itemize @bullet
 @item
 The internals of @code{groff} @file{ms} differ from the internals of
-@acronym{AT&T} @code{troff} @file{ms}.  Documents that depend upon
-implementation details of @acronym{AT&T} @code{troff} @file{ms} may not
-format properly with @code{groff} @file{ms}.  Such details include
-macros whose function was not documented in 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.}
+@acronym{AT&T} @file{ms}.  Documents that depend upon implementation
+details of @acronym{AT&T} @code{troff} @file{ms} may not format properly
+with @code{groff} @file{ms}.  Such details include macros whose function
+was not documented in 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}
 @c XXX: We support RT anyway; maybe we should stop?
 
 @item
@@ -4186,13 +4186,10 @@ Multiple line spacing is not supported.  Use a larger 
vertical spacing
 instead.
 
 @item
-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}.)
+The @acronym{AT&T} @file{ms} manual 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
@@ -4211,14 +4208,14 @@ also: accessing an undefined register automatically 
defines it.
 
 @item
 Displays are left-adjusted by default, not indented.  In @acronym{AT&T}
-@code{troff} @file{ms}, @samp{.DS} is synonymous with @samp{.DS I}; in
-@code{groff} @file{ms}, it is synonymous with @samp{.DS L}.
+@file{ms}, @samp{.DS} is synonymous with @samp{.DS I}; in @code{groff}
+@file{ms}, it is synonymous with @samp{.DS L}.
 
 @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''.  In @code{groff}
-@file{ms}, it does.
+Right-adjusted displays are available.  The @acronym{AT&T} @file{ms}
+manual observes that ``it is tempting to assume that @samp{.DS 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
@@ -4238,10 +4235,9 @@ you may need to handle a non-decimal page number format, 
as @code{groff}
 
 @Defmpreg {GS, ms}
 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
-@code{groff} @file{ms} or another implementation should use this
-register.
+it is not used by the @acronym{AT&T} @file{ms} macros.  Documents that
+need to determine whether they are being formatted with @code{groff}
+@file{ms} or another implementation should use this register.
 @endDefmpreg
 
 @menu
@@ -4252,7 +4248,7 @@ register.
 @c ---------------------------------------------------------------------
 
 @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, 
Differences from AT&T ms
-@subsubsection @code{troff} macros not appearing in @code{groff}
+@subsubsection @acronym{AT&T} @file{ms} macros not appearing in @code{groff} 
@file{ms}
 
 Macros missing from @code{groff} @file{ms} are specific to Bell Labs and
 Berkeley.  The macros known to be missing are:
@@ -4294,10 +4290,10 @@ setting code examples); @code{groff} @file{ms} does not.
 @c ---------------------------------------------------------------------
 
 @node Additional ms Macros,  , Missing ms Macros, Differences from AT&T ms
-@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}
+@subsubsection @code{groff} @file{ms} macros not appearing in @acronym{AT&T} 
@file{ms}
 
 The @code{groff} @file{ms} macros have a few minor extensions to the
-@acronym{AT&T} @code{troff} @file{ms} macros.
+@acronym{AT&T} @file{ms} macros.
 
 @Defmac {AM, , ms}
 Use improved accent marks.  @xref{ms Strings and Special Characters},
@@ -4320,7 +4316,7 @@ The following additional registers appear in @code{groff} 
@file{ms}.
 Specifies a minimum space (``gutter width'') between columns (for
 multi-column output); this takes the place of the @code{GW} register
 that was introduced in the Seventh Edition Unix (1979) version of the
-@acronym{AT&T} @code{troff} @file{ms} macros.
+@acronym{AT&T} @file{ms} macros.
 @endDefmpreg
 
 Several new strings are available as well.  You can change these to
diff --git a/doc/ms.ms b/doc/ms.ms
index f11409f..dc410d6 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -269,7 +269,7 @@ consisting of paragraphs interspersed with headings
 and augmented by lists, footnotes, tables, and other
 common constructs.
 .
-See section \[lq]Body text\[lq] below.
+See section \[lq]Body text\[rq] below.
 .
 .
 .IP "\fBTable of contents\fP"
@@ -365,7 +365,7 @@ Other       \[rs]n[DD]      Display distance (spacing)      
next \[ps]      0.5v
 .
 .
 .LP
-Changes to the footnote length ratio
+Changes to the footnote line length ratio
 .CW \[rs]*[FR]
 take effect with the next footnote written in single-column
 arrangements,
@@ -473,7 +473,7 @@ author's name until reaching an
 .CW .AB ,
 another
 .CW .AU ,
-or heading or paragraph macro.
+or heading or paragraph macro call.
 .
 Call it repeatedly to specify multiple authors.
 T}
@@ -502,7 +502,7 @@ _
 \&.DA \f[R][\f[I]x\f[] .\|.\|.\&]      T{
 Print the current date,
 or any
-.I x , arguments\~ x
+.I x , arguments\~
 in footers,
 and,
 if
@@ -516,7 +516,7 @@ _
 \&.ND \f[R][\f[I]x\f[] .\|.\|.\&]      T{
 Print the current date,
 or any
-.I x , arguments\~ x
+.I x , arguments\~
 if
 .CW .RP
 is also called,
@@ -639,7 +639,7 @@ All paragraphing macro calls cause the insertion of 
vertical space in
 the amount stored in the
 .CW PD
 register,
-except at page breaks.
+except at page or column breaks.
 .KE
 .
 .
@@ -2443,7 +2443,7 @@ This section lists the (minor) differences between the
 .I "groff ms"
 macros and
 .Acr AT&T
-.I "troff ms"
+.I ms
 macros.
 .
 .
@@ -2451,7 +2451,7 @@ macros.
 The internals of
 .I "groff ms"
 differ from the internals of AT&T
-.I "troff ms" .
+.I ms .
 .
 Documents that depend upon implementation details of AT&T
 .I ms
@@ -2460,7 +2460,7 @@ may not format properly with
 .
 Such details include macros whose function was not documented in the
 AT&T
-.I "troff ms"
+.I ms
 manual [Lesk 1978].
 .\" TODO: Use refer(1).
 .\" XXX: We support RT anyway; maybe we should stop?
@@ -2484,7 +2484,7 @@ If you redefine the
 macro \" I wouldn't mention that, but Lesk 1978 encourages doing so. :-/
 and desire special treatment of certain page numbers
 (like
-.CW 1 \[rq], \[lq]
+.CW 1 \[rq]), \[lq]
 you may need to handle a non-decimal page number format,
 as
 .I "groff ms" 's
@@ -2501,13 +2501,15 @@ register to
 .
 .
 .NH 2
-.BI troff
+AT&T
+.BI ms
 macros not appearing in
-.BI groff
+.BI "groff ms"
 .XS
-       \fItroff\fP
+       AT&T
+.I ms
 macros not appearing in
-.I groff
+.I "groff ms"
 .XE
 .LP
 Macros missing from
@@ -2548,22 +2550,22 @@ does not.
 .
 .
 .NH 2
-.BI groff
+.BI "groff ms"
 macros not appearing in
 AT&T
-.BI troff
+.BI ms
 .XS
-       \fIgroff\fP
+       \f[I]groff ms\f[]
 macros not appearing in
 AT&T
-.I troff
+.I ms
 .XE
 .LP
 The
 .I "groff ms"
 macros have a few minor extensions compared to the
 .Acr AT&T
-.I "troff ms"
+.I ms
 macros.
 .IP \&.AM 0.5i
 Improved accent marks.
@@ -2571,7 +2573,7 @@ Improved accent marks.
 Indented display.
 The default behavior of
 .Acr AT&T
-.I "troff ms"
+.I ms
 was to indent; the
 .I groff
 default prints displays flush left with the body text.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index a7ff892..7a6037a 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -66,7 +66,7 @@ macros are mostly compatible with the documented behavior of 
the 4.3
 BSD Unix
 .I ms
 macros (see
-.I Differences from troff ms
+.I Differences from AT&T ms
 below for details).
 .
 The
@@ -462,7 +462,7 @@ All paragraphing macro calls cause the insertion of 
vertical space in
 the amount stored in the
 .B PD
 register,
-except at page breaks.
+except at page or column breaks.
 .
 .
 .PP
@@ -953,8 +953,7 @@ End the most recent indented region.
 .
 .PP
 You can use
-.BR .RS /
-.B .RE
+.BR .RS / .RE
 regions to line up text under hanging and indented paragraphs.
 .
 For example,
@@ -1184,7 +1183,7 @@ option is used.
 .\" ====================================================================
 .
 A footnote is typically anchored to a place in the text with a
-.I marker ,
+.IR marker ,
 which is a small integer,
 a symbol,
 or arbitrary user-specified text.
@@ -1518,7 +1517,7 @@ and
 .
 .
 .\" ====================================================================
-.SH "Differences from troff ms"
+.SH "Differences from AT&T ms"
 .\" ====================================================================
 .
 The
@@ -1538,7 +1537,7 @@ Other differences include:
 The internals of
 .I groff ms
 differ from the internals of AT&T
-.IR "troff ms" .
+.IR ms .
 .
 Documents that depend upon implementation details of AT&T
 .I ms
@@ -1547,8 +1546,13 @@ may not format properly with
 .
 Such details include macros whose function was not documented in the
 AT&T
-.I troff ms
-manual [Lesk 1978].
+.I ms
+manual
+(\[lq]Typing Documents on the UNIX System: Using the \-ms Macros with
+Troff and Nroff\[rq],
+M.\& E.\& Lesk,
+Bell Laboratories,
+1978).
 .\" TODO: Use refer(1)?
 .\" XXX: We support RT anyway; maybe we should stop?
 .
@@ -1598,14 +1602,8 @@ Multiple line spacing is not supported
 .
 .IP \[bu]
 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
+.I ms
+manual describes
 .B CW
 and
 .B GW
@@ -1666,7 +1664,7 @@ Displays are left-adjusted by default,
 not indented.
 .
 In AT&T
-.IR "troff ms" ,
+.IR ms ,
 .B .DS
 is synonymous with
 .RB \[lq] ".DS I" \[rq];
@@ -1680,7 +1678,7 @@ it is synonymous with
 Right-adjusted displays are available.
 .
 The AT&T
-.I troff ms
+.I 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].
@@ -1739,7 +1737,7 @@ is set to\~1 by the
 .I groff ms
 macros,
 but is not used by the AT&T
-.I troff ms
+.I ms
 macros.
 .
 Documents that need to determine whether they are being formatted with
@@ -1916,7 +1914,9 @@ Constructed names used to implement arrays are of the form
 .
 .
 .PP
-Thus the groff ms macros reserve the following names:
+Thus the
+.I groff ms
+macros reserve the following names:
 .
 .IP \[bu] 3n
 Names containing the characters