[groff] 16/32: [ms]: Fix documentation nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d822643db4a7ddef267cabfdffab6b23b34afdc3
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Oct 4 18:28:53 2022 -0500

    [ms]: Fix documentation nits.
    
    * doc/groff.texi:
      - Recast early historical note.
      - Sync description of scaling units with doc/ms.ms (as edited below).
      - Recast introduction to document description macros for grammatical
        number.
      - Tighten wording in descriptions of `TL`, `AU`, `AI`, `DA`, `ND`, and
        `AB` macros, and typographical symbol strings, and elsewhere.
      - Annotate `FAM` string as a GNU extension.
      - Characterize purpose of paragraphing macros.
      - Update examples of lists to use more ergonomic idioms that ease
        document maintenance.  Present the creation and use of
        auto-incrementing registers.
      - Say "number format" instead of "assigned format" for greater
        intelligibility to the novice, since we don't fully present the
        concept of register formats in this chapter.
    
    * doc/ms.ms:
      - Bump document date.
      - Recast early historical note.
      - Simplify definition of vees in scaling unit table; the term
        "vertical spacing" is defined later.
      - Advise reader that individual formatter requests will be discussed
        ad hoc.
      - Revise definition of `\~` escape sequence.
      - Correct parameter table; "leading" is not a synonym for "vertical
        spacing".
      - Recast introduction to document description macros for grammatical
        number.
      - Tighten wording in descriptions of `TL`, `AU`, `AI`, `DA`, `ND`, and
        `AB` macros, and typographical symbol strings.
      - Annotate `FAM` string as a GNU extension.
      - Characterize purpose of paragraphing macros.
      - Update examples of lists to use more ergonomic idioms that ease
        document maintenance.  Present the creation and use of
        auto-incrementing registers.
      - Fix examples to use `\[rs]` special character escape sequences
        instead of doubled backslashes.
      - Realign example with its output.
      - Add keep to bracket introduction of boxed keeps with their macro
        synopses.
      - Say "number format" instead of "assigned format" for greater
        intelligibility to the novice, since we don't fully present the
        concept of register formats in this document.
    
    * tmac/groff_ms.7.man:
      - Permit `RP` options to break only at dash literals.
      - Restore sentence that was omitted for space.
      - Tighten wording in descriptions of `TL`, `AU`, `AI`, `DA`, `ND`, and
        `AB` macros, and typographical symbol strings.
      - Annotate `FAM` string as a GNU extension.
      - Characterize purpose of paragraphing macros.
      - Say "number format" instead of "assigned format", here simply for
        alignment with the other ms documentation.  The non-novice man page
        reader should know what we mean.
---
 doc/groff.texi      | 154 +++++++++++++++++++++++++++------------------------
 doc/ms.ms           | 156 +++++++++++++++++++++++++++++++++-------------------
 tmac/groff_ms.7.man |  63 +++++++++++----------
 3 files changed, 216 insertions(+), 157 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 4c0c19ecc..344c3db8f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2454,12 +2454,13 @@ and Tenth Edition Research Unix have been recreated.
 @subsection Introduction
 
 The @file{ms} macros are the oldest surviving package for @code{roff}
-systems.@footnote{Although manual pages are even older, the @file{man}
-macros originated in Seventh Edition Unix (1979).  @file{ms} shipped
-with Sixth Edition (1975) and was documented by Mike Lesk in a Bell Labs
-internal memorandum.}  While the @file{man} package was designed for
-brief reference documents, the @file{ms} macros are also suitable for
-longer works intended for printing and possible publication.
+systems.@footnote{While manual @emph{pages} are older, early ones used
+macros supplanted by the @file{man} package of Seventh Edition Unix
+(1979).  @file{ms} shipped with Sixth Edition (1975) and was documented
+by Mike Lesk in a Bell Labs internal memorandum.}  While the @file{man}
+package was designed for brief reference documents, the @file{ms} macros
+are also suitable for longer works intended for printing and possible
+publication.
 
 @menu
 * ms basic information::
@@ -2471,12 +2472,12 @@ longer works intended for printing and possible 
publication.
 @subsubsection Basic information
 
 @file{ms} documents are plain text files; prepare them with your
-preferred text editor.  If you're in a hurry to get started, be advised
-that @file{ms} needs one of its macros called at the beginning of a
-document so that it can initialize.  A @dfn{macro} is a formatting
-instruction to @file{ms}.  Put a macro call on a line by itself.  Use
-@samp{.PP} if you want your paragraph's first line to be indented, or
-@samp{.LP} if you don't.
+preferred text editor.  If you're in a hurry to start, know that
+@file{ms} needs one of its macros called at the beginning of a document
+so that it can initialize.  A @dfn{macro} is a formatting instruction to
+@file{ms}.  Put a macro call on a line by itself.  Use @samp{.PP} if you
+want your paragraph's first line to be indented, or @samp{.LP} if you
+don't.
 
 After that, start typing normally.  It is a good practice to start each
 sentence on a new line, or to put two spaces after sentence-ending
@@ -2528,20 +2529,22 @@ points (1/72 inch)
 picas (1/6 inch)
 
 @item v
-vees; height of a line using the current font
-
-@item n
-ens; width of an ``n'' using the current font
+vees; current vertical spacing
 
 @item m
-ems; width of an ``M'' using the current font
+ems; width of an ``M'' in the current font
+
+@item n
+ens; one-half em
 @end table
 
 Set registers with the @code{nr} request and strings with the @code{ds}
 request.  @dfn{Requests} are like macro calls; they go on lines by
 themselves and start with the @dfn{control character}, a dot (@code{.}).
 The difference is that they directly instruct the formatter program,
-rather than the macro package.
+rather than the macro package.  We'll discuss a few as applicable.  It
+is wise to specify a scaling unit when setting any register that
+represents a length, size, or distance.
 
 @CartoucheExample
 .nr PS 10.5p \" Use 10.5-point type.
@@ -2593,9 +2596,8 @@ interpreted as macro calls or requests.  Suffix @samp{.}, 
@samp{?}, and
 @samp{!} with @code{\&} when needed to cancel end-of-sentence detection.
 
 @CartoucheExample
-After the criticality accident, Dr.\&
-Wallace said my exposure had been
-\&.5 to \&.6 Sv of neutrons.
+My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\&
+Wallace after the criticality incident.
 @endCartoucheExample
 
 @c ---------------------------------------------------------------------
@@ -3032,12 +3034,12 @@ Default: @code{\w'000'}
 @cindex @file{ms} macros, document description
 @cindex document description macros, [@file{ms}]
 
-All but the simplest documents bear a title.@footnote{Distinguish a
+Only the simplest document lacks a title.@footnote{Distinguish a
 document title from ``titles'', which are what @code{roff} systems call
-headers and footers collectively.}  As their level of sophistication (or
-complexity) increases, they tend to acquire dates of revision,
+headers and footers collectively.}  As its level of sophistication (or
+complexity) increases, it tends to acquire a date of revision,
 explicitly identified authors, sponsoring institutions for authors, and,
-at the rarefied heights, an abstract of their content.  Define these
+at the rarefied heights, an abstract of its content.  Define these
 data by calling the macros below in the order shown; @code{DA} or
 @code{ND} can be called to set the document date (or other identifier)
 at any time before (a) the abstract, if present, or (b) its information
@@ -3063,42 +3065,42 @@ suppresses this alteration.  Optional arguments can 
occur in any order.
 
 @Defmac {TL, , ms}
 Specify the document title.  @file{ms} collects text on input lines
-following a call to this macro into the title until reaching an
-@code{AU}, @code{AB}, or heading or paragraphing macro call.
+following this call into the title until reaching @code{AU}, @code{AB},
+or a heading or paragraphing macro call.
 @endDefmac
 
 @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}, another @code{AU}, or heading or paragraphing
-macro call.  Call it repeatedly to specify multiple authors.
+following this call into the author's name until reaching @code{AI},
+@code{AB}, another @code{AU}, or a heading or paragraphing macro call.
+Call it repeatedly to specify multiple authors.
 @endDefmac
 
 @Defmac {AI, , ms}
 Specify the preceding author's institution.  An @code{AU} call is
 usefully followed by at most one @code{AI} call; if there are more, the
 last @code{AI} call controls.  @file{ms} collects text on input lines
-following a call to this macro into the author's institution until
-reaching an @code{AU}, @code{AB}, or heading or paragraphing macro call.
+following this call into the author's institution until reaching
+@code{AU}, @code{AB}, or a heading or paragraphing macro call.
 @endDefmac
 
 @Defmac {DA, [@Var{x} @dots{}], ms}
 Typeset the current date, or any arguments @var{x}, in the center
-footer, and, if @code{RP} is also called, left-aligned after other
-document description information on the cover page.
+footer, and, if @code{RP} is also called, left-aligned at the end of the
+description information on the cover page.
 @endDefmac
 
 @Defmac {ND, [@Var{x} @dots{}], ms}
 Typeset the current date, or any arguments @var{x}, if @code{RP} is also
-called, left-aligned after other document description information on the
-cover page.  This is the @code{groff} @file{ms} default.
+called, left-aligned at the end of the document description on the cover
+page.  This is @code{groff} @file{ms}'s default.
 @endDefmac
 
 @Defmac {AB, [@code{no}], ms}
-Begin the abstract.  @file{ms} collects text on input lines following a
-call to this macro into the abstract until reaching an @code{AE} call.
-By default, @file{ms} places the word ``ABSTRACT'' centered and in
-italics above the text of the abstract.  The optional argument @code{no}
+Begin the abstract.  @file{ms} collects text on input lines following
+this call into the abstract until reaching an @code{AE} call.  By
+default, @file{ms} places the word ``ABSTRACT'' centered and in italics
+above the text of the abstract.  The optional argument @code{no}
 suppresses this heading.
 @endDefmac
 
@@ -3170,13 +3172,13 @@ tables and figures.
 @subsubsection Text settings
 @cindex @file{ms} macros, text settings
 
-The @code{FAM} string sets the font family for body text; the default is
-@samp{T}.  The @code{PS} and @code{VS} registers set the type
-size and vertical spacing (distance between text baselines),
-respectively.  The font family and type size are ignored on terminal
-devices.  Setting these parameters before the first call of a heading,
-paragraphing, or (non-date) document description macro also applies them
-to headers, footers, and (for @code{FAM}) footnotes.
+The @code{FAM} string, a GNU extension, sets the font family for body
+text; the default is @samp{T}.  The @code{PS} and @code{VS} registers
+set the type size and vertical spacing (distance between text
+baselines), respectively.  The font family and type size are ignored on
+terminal devices.  Setting these parameters before the first call of a
+heading, paragraphing, or (non-date) document description macro also
+applies them to headers, footers, and (for @code{FAM}) footnotes.
 
 Which font families are available depends on the output device; as a
 convention, @code{T} selects a serif family (``Times''), @code{H} a
@@ -3196,9 +3198,9 @@ extension.
 @subsubsection Typographical symbols
 @cindex @file{ms} macros, obtaining typographical symbols
 
-@file{ms} provides a handful of strings to obtain typographical symbols
-not easily entered with the keyboard.  Many others are available as
-special character escape sequences---see the @cite{groff_char@r{(7)}}
+@file{ms} provides a few strings to obtain typographical symbols not
+easily entered with the keyboard.  These and many others are available
+as special character escape sequences---see the @cite{groff_char@r{(7)}}
 man page.
 
 @Defmpstr {-, ms}
@@ -3218,14 +3220,16 @@ the right.
 @subsubsection Paragraphs
 @cindex @file{ms} macros, paragraph handling
 
-Several paragraph types are available, differing in how indentation
-applies to them: 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 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 isolated lines at the bottom of any page.
+Paragraphing macros @dfn{break}, or terminate, any pending output line
+so that a new paragraph can begin.  Several paragraph types are
+available, differing in how indentation applies to them: 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 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 isolated lines at the bottom
+of any page.
 
 @Defmac {LP, , ms}
 Set a paragraph without any (additional) indentation.
@@ -3386,7 +3390,7 @@ define the alias as follows.
 Any such change in numbering style becomes effective from the next use
 of @code{NH} following redefinition of the alias for @code{SN-STYLE}.
 The formatted number of the current heading is available in the
-@code{SN} string (a feature first documented by Berkeley); this string
+@code{SN} string (a feature first documented by Berkeley), which
 facilitates its inclusion in, for example, table captions, equation
 labels, and @code{XS}/@code{XA}/@code{XE} table of contents entries.
 @endDefmpstr
@@ -3579,15 +3583,19 @@ The @var{marker} argument to the @code{IP} macro can be 
employed to
 present a variety of lists; for instance, you can use a bullet glyph
 (@code{\[bu]}) for unordered lists, a number (or auto-incrementing
 register) for numbered lists, or a word or phrase for glossary-style or
-definition lists.
+definition lists.  If you set the paragraph indentation register
+@code{PI} before calling @code{IP}, you can later reorder the items in
+the list without having to ensure that a @var{width} argument remains
+affixed to the first call.
 
 The following is an example of a bulleted list.
 @cindex example markup, bulleted list [@file{ms}]
 @cindex bulleted list, example markup [@file{ms}]
 
 @CartoucheExample
+.nr PI 2n
 A bulleted list:
-.IP \[bu] 2n
+.IP \[bu]
 lawyers
 .IP \[bu]
 guns
@@ -3610,9 +3618,10 @@ The following is an example of a numbered list.
 @cindex numbered list, example markup [@file{ms}]
 
 @CartoucheExample
-.nr step 1 1
+.nr step 0 1
+.nr PI 3n
 A numbered list:
-.IP \n[step] 3n
+.IP \n+[step]
 lawyers
 .IP \n+[step]
 guns
@@ -3630,8 +3639,15 @@ A numbered list:
 3. money
 @endExample
 
-Note the use of the auto-incrementing register @var{step} in the
-foregoing example.  The next illustrates a glossary-style list.
+Here we have employed the @code{nr} request to create a register of our
+own, @samp{step}.  We initialized it to zero and assigned it an
+auto-increment of 1.  Each time we use the escape sequence
+@samp{\n+[PI]} (note the plus sign), the formatter applies the increment
+just before interpolating the register's value.  Preparing the @code{PI}
+register as well enables us to rearrange the list without the tedium of
+updating macro calls.
+
+The next example illustrates a glossary-style list.
 @cindex example markup, glossary-style list [@file{ms}]
 @cindex glossary-style list, example markup [@file{ms}]
 
@@ -3746,9 +3762,6 @@ and Howe.
 Guns
 @endCartoucheExample
 
-@noindent
-produces
-
 @Example
 @bullet{} Lawyers:
 
@@ -3761,9 +3774,6 @@ produces
 @bullet{} Guns
 @endExample
 
-@noindent
-as output.
-
 @c ---------------------------------------------------------------------
 
 @node ms keeps and displays, ms Insertions, Indented regions in ms, ms Body 
Text
@@ -4200,7 +4210,7 @@ and even-numbered (verso) pages, respectively; the 
@code{OF} and
 @endDefmac
 
 By default, @file{ms} places no header on any page numbered ``1''
-(regardless of its assigned format).
+(regardless of its number format).
 
 @Defmac {P1, , ms}
 Typeset the header even on page@tie{}1.  To be effective, this macro
diff --git a/doc/ms.ms b/doc/ms.ms
index 5a6dc8b11..b2308fc62 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -22,8 +22,8 @@
 .nr TC-MARGIN \w'00' \" expect 2-digit page numbers at most
 .ie t .nr PI 3.5n
 .el   .nr PI 4n
-.ND August 2022
-.EH '%''August 2022'
+.ND October 2022
+.EH '%''October 2022'
 .EF ''''
 .OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
 .OF ''''
@@ -97,10 +97,12 @@ macros are the oldest surviving package for
 systems.\**
 .
 .FS
-Although manual pages are even older,
-the
+While manual
+.I pages
+are older,
+early ones used macros supplanted by the
 .I man
-macros originated in Seventh Edition Unix (1979).
+package of Seventh Edition Unix (1979).
 .
 .I ms
 shipped with Sixth Edition (1975) and was documented by Mike Lesk in a
@@ -134,8 +136,8 @@ Basic information
 documents are plain text files;
 prepare them with your preferred text editor.
 .
-If you're in a hurry to get started,
-be advised that
+If you're in a hurry to start,
+know that
 .I ms
 needs one of its macros called at the beginning of a document so that it
 can initialize.
@@ -237,7 +239,7 @@ i   inches (\[sd])
 c      centimeters
 p      points (1/72\[sd])
 P      picas (1/6\[sd])
-v      \[lq]vees\[rq]; line height at the current vertical spacing
+v      \[lq]vees\[rq]; current vertical spacing
 m      \[lq]ems\[rq]; width of an \[lq]M\[rq] in the current font
 n      \[lq]ens\[rq]; one-half em
 .TE
@@ -261,6 +263,8 @@ a dot
 The difference is that they directly instruct the formatter program,
 rather than the macro package.
 .
+We'll discuss a few as applicable.
+.
 It is wise to specify a scaling unit when setting any register that
 represents a length,
 size,
@@ -328,7 +332,7 @@ Interpolate glyph of special character named
 T}
 \[rs]& non-printing, zero-width dummy character
 \[rs]\[ti]     T{
-Insert an unbreakble space that is adjustable like a normal space.
+Insert an unbreakble space of adjustable width like a normal space.
 T}
 \[rs]| T{
 Move horizontally by one-sixth em
@@ -361,9 +365,8 @@ when needed to cancel end-of-sentence detection.
 .TS
 box center;
 lf(CR).
-After the criticality accident, Dr.\[rs]&
-Wallace said my exposure had been
-\[rs]&.5 to \[rs]&.6 Sv of neutrons.
+My exposure was \[rs]&.5 to \[rs]&.6 Sv of neutrons, said Dr.\[rs]&
+Wallace after the criticality incident.
 .TE
 .
 .
@@ -538,8 +541,7 @@ T}  \[rs]*[LH]      Left header text        header  
\f[I]empty
 \^     \[rs]*[RF]      Right footer text       footer  \f[I]empty
 _
 Text   \[rs]n[PS]      Type (point) size       paragraph       10p
-\^     \[rs]n[VS]      Vertical spacing (leading)      paragraph\
-       12p
+\^     \[rs]n[VS]      Vertical spacing        paragraph       12p
 \^     \[rs]n[HY]      Hyphenation mode        paragraph       6
 \^     \[rs]*[FAM]     Font family     paragraph       T
 _
@@ -562,7 +564,7 @@ Footnotes   \[rs]n[FI]      Indentation     footnote        
2n
 \^     \[rs]n[FF]      Format  footnote        0
 \^     \[rs]n[FPS]     Type (point) size       footnote\
        \[rs]n[PS]\-2p
-\^     \[rs]n[FVS]     Vertical spacing (leading)      footnote\
+\^     \[rs]n[FVS]     Vertical spacing        footnote\
        \[rs]n[FPS]+2p
 \^     \[rs]n[FPD]     Paragraph distance (spacing)    footnote\
        \[rs]n[PD]/2
@@ -601,7 +603,7 @@ Document description macros
 .
 .
 .LP
-All but the simplest documents bear a title.\**
+Only the simplest document lacks a title.\**
 .
 .FS
 Distinguish a document title from \[lq]titles\[rq],
@@ -610,15 +612,15 @@ which are what
 systems call headers and footers collectively.
 .FE
 .
-As their level of sophistication
+As its level of sophistication
 (or complexity)
 increases,
-they tend to acquire dates of revision,
+it tends to acquire a date of revision,
 explicitly identified authors,
 sponsoring institutions for authors,
 and,
 at the rarefied heights,
-an abstract of their content.
+an abstract of its content.
 .
 Define these data by calling the macros below in the order shown;
 .CW .DA
@@ -697,24 +699,24 @@ _
 Specify the document title.
 .
 .I ms
-collects text on input lines following a call to this macro into the
-title until reaching an
+collects text on input lines following this call into the title
+until reaching
 .CW .AU ,
 .CW .AB ,
-or heading or paragraphing macro call.
+or a heading or paragraphing macro call.
 T}
 _
 \&.AU  T{
 Specify an author's name.
 .
 .I ms
-collects text on input lines following a call to this macro into the
-author's name until reaching an
+collects text on input lines following this call into the author's name
+until reaching
 .CW .AI ,
 .CW .AB ,
 another
 .CW .AU ,
-or heading or paragraphing macro call.
+or a heading or paragraphing macro call.
 .
 Call it repeatedly to specify multiple authors.
 T}
@@ -733,11 +735,11 @@ the last
 call controls.
 .
 .I ms
-collects text on input lines following a call to this macro into the
-author's institution until reaching an
+collects text on input lines following this call into the author's
+institution until reaching
 .CW .AU ,
 .CW .AB ,
-or heading or paragraphing macro call.
+or a heading or paragraphing macro call.
 T}
 _
 \&.DA \f[R][\f[I]x\f[] .\|.\|.\&]      T{
@@ -749,8 +751,7 @@ and,
 if
 .CW .RP
 is also called,
-left-aligned after other document description information on the cover
-page.
+left-aligned at the end of the document description on the cover page.
 T}
 _
 \&.ND \f[R][\f[I]x\f[] .\|.\|.\&]      T{
@@ -760,11 +761,10 @@ or any
 if
 .CW .RP
 is also called,
-left-aligned after other document description information on the cover
-page.
+left-aligned at the end of the document description on the cover page.
 .
-This is the
-.I "groff ms"
+This is
+.I "groff ms" 's
 default.
 T}
 _
@@ -772,8 +772,8 @@ _
 Begin the abstract.
 .
 .I ms
-collects text on input lines following a call to this macro into the
-abstract until reaching an
+collects text on input lines following this call into the abstract
+until reaching an
 .CW .AE
 call.
 .
@@ -867,7 +867,9 @@ Text settings
 .LP
 The
 .CW FAM
-string sets the font family for body text;
+string,
+a GNU extension,
+sets the font family for body text;
 the default is
 .CW T \[rq]. \[lq]
 .
@@ -937,10 +939,11 @@ Typographical symbols
 .
 .LP
 .I ms
-provides a handful of strings to obtain typographical symbols not easily
+provides a few strings to obtain typographical symbols not easily
 entered with the keyboard.
 .
-Many others are available as special character escape sequences\*[-]see
+These and many others are available as special character escape
+sequences\*[-]see
 the
 .I groff_char (7)
 man page.
@@ -976,6 +979,11 @@ Paragraphs
 .
 .
 .LP
+Paragraphing macros
+.I break ,
+or terminate,
+any pending output line so that a new paragraph can begin.
+.
 Several paragraph types are available,
 differing in how indentation
 applies to them:
@@ -1307,8 +1315,8 @@ following redefinition of the alias for
 .
 The formatted number of the current heading is available in
 .CW \[rs]*[SN]
-(a feature first documented by Berkeley);
-this string facilitates its inclusion in,
+(a feature first documented by Berkeley),
+which facilitates its inclusion in,
 for example,
 table captions,
 equation labels,
@@ -1862,6 +1870,15 @@ a number
 for numbered lists,
 or a word or phrase for glossary-style or definition lists.
 .
+If you set the paragraph indentation register
+.CW PI
+before calling
+.CW IP ,
+you can later reorder the items in the list without having to ensure
+that a
+.I width
+argument remains affixed to the first call.
+.
 .
 .TS H
 box center;
@@ -1872,8 +1889,9 @@ _
 .TH
 T{
 .nf
+\&.nr PI 2n
 A bulleted list:
-\&.IP \[rs][bu] 2n
+\&.IP \[rs][bu]
 lawyers
 \&.IP \[rs][bu]
 guns
@@ -1881,8 +1899,9 @@ guns
 money
 .fi
 T}     T{
+.nr PI 2n
 A bulleted list:
-.IP \[bu] 2
+.IP \[bu]
 lawyers
 .IP \[bu]
 guns
@@ -1892,19 +1911,21 @@ T}
 _
 T{
 .nf
-\&.nr step 1 1
+\&.nr step 0 1
+\&.nr PI 3n
 A numbered list:
-\&.IP \\n[step] 3n
+\&.IP \[rs]n+[step].
 lawyers
-\&.IP \\n+[step]
+\&.IP \[rs]n+[step].
 guns
-\&.IP \\n+[step]
+\&.IP \[rs]n+[step].
 money
 .fi
 T}     T{
-.nr step 1 1
+.nr step 0 1
+.nr PI 3n
 A numbered list:
-.IP \n[step]. 3
+.IP \n+[step].
 lawyers
 .IP \n+[step].
 guns
@@ -1939,7 +1960,28 @@ T}
 .
 .
 .PP
-In the last example above,
+In the enumerated list example,
+we employed the
+.CW nr
+request to create a register of our own,
+.CW step .
+.
+We initialized it to zero and assigned it an auto-increment of 1.
+.
+Each time we use the escape sequence
+.CW \[rs]n+[PI]
+(note the plus sign),
+the formatter applies the increment just before interpolating the
+register's value.
+.
+Preparing the
+.CW PI
+register as well enables us to rearrange the list without the tedium of
+updating macro calls.
+.
+.
+.PP
+In the glossary example,
 observe how the
 .CW IP
 macro places the definition on the same line as the term if it has
@@ -2072,18 +2114,18 @@ _
 T{
 .nf
 .CW
-\&.IP \\[bu] 2
+\&.IP \[rs][bu] 2
 Lawyers:
 \&.RS
-\&.IP \\[bu]
+\&.IP \[rs][bu]
 Dewey,
-\&.IP \\[bu]
+\&.IP \[rs][bu]
 Cheatham,
 and
-\&.IP \\[bu]
+\&.IP \[rs][bu]
 Howe.
 \&.RE
-\&.IP \\[bu]
+\&.IP \[rs][bu]
 Guns
 .R
 \&.\|.\|.
@@ -2185,6 +2227,7 @@ is to reserve space on the page for a figure or 
illustration to be
 included later.
 .
 .
+.KS
 .PP
 A
 .I "boxed keep"
@@ -2200,6 +2243,7 @@ _
 \&.B1  Begin a keep with a box drawn around it.
 \&.B2  End boxed keep.
 .TE
+.KE
 .
 .
 .KS
@@ -3124,7 +3168,7 @@ T}
 By default,
 .I ms
 places no header on any page numbered \[lq]1\[rq]
-(regardless of its assigned format).
+(regardless of its number format).
 .
 .
 .TS
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 5714d063a..a629703e4 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -459,7 +459,7 @@ but not the date)
 at the top of the first page.
 .
 If the optional
-.B no\-repeat\-info
+.B no\-\:\%repeat\-\:\%info
 argument is given,
 .I ms
 produces a cover page but does not repeat any of its information on
@@ -473,16 +473,15 @@ Normally,
 sets the page number following the cover page to\~1.
 .
 Specifying the optional
-.B no\-renumber
+.B no\-\:\%renumber
 argument suppresses this alteration.
 .
 Optional arguments can occur in any order.
-.\" Including the next sentence harms U.S. letter pagination... :-/
-.\"
-.\".RB \[lq] no \[rq]
-.\"is recognized as a synonym of
-.\".B no\-repeat\-info
-.\"for AT&T compatibility.
+.
+.RB \[lq] no \[rq]
+is recognized as a synonym of
+.B no\-\:\%repeat\-\:\%info
+for AT&T compatibility.
 .
 .
 .TP
@@ -490,11 +489,11 @@ Optional arguments can occur in any order.
 Specify the document title.
 .
 .I ms
-collects text on input lines following a call to this macro into the
-title until reaching an
+collects text on input lines following this call into the title until
+reaching
 .BR .AU ,
 .BR .AB ,
-or heading or paragraphing macro call.
+or a heading or paragraphing macro call.
 .
 .
 .TP
@@ -502,13 +501,13 @@ or heading or paragraphing macro call.
 Specify an author's name.
 .
 .I ms
-collects text on input lines following a call to this macro into the
-author's name until reaching an
+collects text on input lines following this call into the author's name
+until reaching
 .BR .AI ,
 .BR .AB ,
 another
 .BR .AU ,
-or heading or paragraphing macro call.
+or a heading or paragraphing macro call.
 .
 Call it repeatedly to specify multiple authors.
 .
@@ -528,11 +527,11 @@ the last
 call controls.
 .
 .I ms
-collects text on input lines following a call to this macro into the
-author's institution until reaching an
+collects text on input lines following this call into the author's
+institution until reaching
 .BR .AU ,
 .BR .AB ,
-or heading or paragraphing macro call.
+or a heading or paragraphing macro call.
 .
 .
 .TP
@@ -546,8 +545,7 @@ and,
 if
 .B .RP
 is also called,
-left-aligned after other document description information on the cover
-page.
+left-aligned at the end of the document description on the cover page.
 .
 .
 .TP
@@ -559,11 +557,10 @@ or any
 if
 .B .RP
 is also called,
-left-aligned after other document description information on the cover
-page.
+left-aligned at the end of the document description on the cover page.
 .
-This is the
-.I groff ms
+This is
+.IR "groff ms" 's
 default.
 .
 .
@@ -572,8 +569,8 @@ default.
 Begin the abstract.
 .
 .I ms
-collects text on input lines following a call to this macro into the
-abstract until reaching an
+collects text on input lines following this call into the abstract until
+reaching an
 .B .AE
 call.
 .
@@ -598,7 +595,9 @@ End the abstract.
 .
 The
 .B FAM
-string sets the font family for body text;
+string,
+a GNU extension,
+sets the font family for body text;
 the default is
 .RB \[lq] T \[rq].
 .
@@ -646,10 +645,11 @@ This is a Tenth Edition Research Unix extension.
 .\" ====================================================================
 .
 .I ms
-provides a handful of strings to obtain typographical symbols not easily
+provides a few strings to obtain typographical symbols not easily
 entered with the keyboard.
 .
-Many others are available as special character escape sequences\[em]see
+These and many others are available as special character escape
+sequences\[em]see
 .MR groff_char @MAN7EXT@ .
 .
 .
@@ -675,6 +675,11 @@ the right.
 .SS Paragraphs
 .\" ====================================================================
 .
+Paragraphing macros
+.IR break ,
+or terminate,
+any pending output line so that a new paragraph can begin.
+.
 Several paragraph types are available,
 differing in how indentation
 applies to them:
@@ -1858,7 +1863,7 @@ macros define footers for them.
 By default,
 .I ms
 places no header on any page numbered \[lq]1\[rq]
-(regardless of its assigned format).
+(regardless of its number format).
 .
 .
 .TP