[groff] 01/19: [ms]: Fix style nits in docs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c44e627b6f97186829ab65afbe645e4ad5221e57
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jul 5 21:49:42 2022 -0500

    [ms]: Fix style nits in docs.
    
    * doc/ms.ms:
      - Recast description of "\~" to align with current terminology in our
        Texinfo manual.
      - Clarify that type size parameters are ignored on terminal devices
        (n.b., vertical spacing is not).
      - Turn off adjustment of source examples in tbl text blocks.
      - Recast to reduce terminological collisions on the term "box";
        consistently refer to "boxed keeps" as such, to avoid confusion with
        boxes produced by `BX` and the groff extension that is a diversion
        with special behavior.  All are distinct.
      - Say that pages are odd- or even- _numbered_.
      - Drop a hyphen from an attributive phrase.  One says "the second
        numbered page", not "the second-numbered page".
      - Tighten wording.
      - Bump document revision date.
---
 doc/groff.texi      | 45 ++++++++++++++++++++++++---------------------
 doc/ms.ms           | 40 ++++++++++++++++++++--------------------
 tmac/groff_ms.7.man | 36 ++++++++++++++++++------------------
 3 files changed, 62 insertions(+), 59 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 14054386..f264da67 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2677,10 +2677,9 @@ Set string @var{name} to @var{contents}.  If @var{name} 
exists, it is
 removed first.
 @endDefreq
 
-A list of document control registers and strings follows.  They are
-presented in the syntax used to interpolate them.  For any parameter
-whose default is unsatisfactory, define its register or string before
-calling any @file{ms} macro other than @code{RP}.
+A list of document control registers and strings follows.  For any
+parameter whose default is unsatisfactory, define its register or string
+before calling any @file{ms} macro other than @code{RP}.
 
 @unnumberedsubsubsec Margin settings
 
@@ -3189,13 +3188,17 @@ footnotes, and inclusions of material such as tables 
and figures.
 @cindex @file{ms} macros, text settings
 
 The @code{FAM} string sets the font family for body text; the default is
-@samp{T} (Times).  The font family setting is ignored on terminal
-devices.  Setting the @code{FAM} string before the first call of a
-heading, paragraphing, or (non-date) document description macro also
-applies it to headers, footers, and (for @code{FAM}) footnotes.
+@samp{T} (Times).  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 hyphenation mode (as used by the @code{hy} request) is set from the
-@code{HY} register.
+@code{HY} register.  Setting @code{HY} to @samp{0} is equivalent to
+using the @code{nh} request.  This is a Tenth Edition Research Unix
+extension.
 
 @c ---------------------------------------------------------------------
 
@@ -3819,8 +3822,7 @@ One application of @code{ne} is to reserve space on the 
page for a
 figure or illustration to be included later.
 
 @cindex boxes [@file{ms}]
-A keep can also be @dfn{boxed}.  Text in a box is automatically placed
-in a diversion (keep).
+A keep have a frame drawn around it; this is called a @dfn{boxed keep}.
 
 @DefmacList {B1, , ms}
 @DefmacListEndx {B2, , ms}
@@ -3828,10 +3830,10 @@ in a diversion (keep).
 boxed keep.
 @endDefmac
 
-Box macros cause breaks; if you need to box a word or phrase within a
-line, see the @code{BX} macro in @ref{Typeface and decoration}.  Box
-lines are drawn as close as possible to the text they enclose so that
-they are usable within paragraphs.  If you wish to box one or more
+Boxed keep macros cause breaks; if you need to box a word or phrase
+within a line, see the @code{BX} macro in @ref{Typeface and decoration}.
+Box lines are drawn as close as possible to the text they enclose so
+that they are usable within paragraphs.  If you wish to box one or more
 paragraphs, you may improve the appearance by calling @code{B1} after
 the first paragraphing macro, and by adding a small amount of vertical
 space before calling @code{B2}.
@@ -3847,8 +3849,9 @@ speeds.
 .B2
 @endCartoucheExample
 
-If you want a box to float, you will need to enclose the @code{B1} and
-@code{B2} calls within a pair of @code{KF} and @code{KE} calls.
+If you want a boxed keep to float, you will need to enclose the
+@code{B1} and @code{B2} calls within a pair of @code{KF} and @code{KE}
+calls.
 
 @cindex displays [@file{ms}]
 @dfn{Displays} turn off filling; lines of verse or program code are
@@ -4183,11 +4186,11 @@ There are multiple ways to produce headers and footers. 
 One is to
 define the strings @code{LH}, @code{CH}, and @code{RH} to set the left,
 center, and right headers, respectively; and @code{LF}, @code{CF}, and
 @code{RF} to set the left, center, and right footers similarly.  This
-approach works best for documents that do not distinguish odd and even
-pages.
+approach works best for documents that do not distinguish odd- and
+even-numbered pages.
 
 Another method is to call macros with arguments that set headers or
-footers for odd or even pages; these variables produce four
+footers for odd- or even-numbered pages; these variables produce four
 combinations, so four macros are available.  Each takes a delimiter
 separating the left, center, and right header or footer texts from each
 other.  You can replace the neutral apostrophes (@code{'}) with any
@@ -4224,7 +4227,7 @@ calls the (normally undefined) @code{HD} macro after 
@code{PT}; you can
 define @code{HD} if you need additional processing after setting the
 header (for example, to draw a line below it).  The @code{HD} hook is a
 Berkeley extension.  Any such macros you (re)define must implement any
-desired specialization for odd-, even-, or first-numbered pages.
+desired specialization for odd-, even-, or first numbered pages.
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 559e54ef..a5f3358f 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 June 2022
-.EH '%''June 2022'
+.ND July 2022
+.EH '%''July 2022'
 .EF ''''
 .OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
 .OF ''''
@@ -316,8 +316,7 @@ Interpolate glyph of special character named
 T}
 \[rs]& non-printing, zero-width dummy character
 \[rs]\[ti]     T{
-Move horizontally by the current font's space width
-(\[lq]non-breaking space\[rq]).
+Insert an unbreakble space that is adjustable like a normal space.
 T}
 \[rs]| T{
 Move horizontally by one-sixth em
@@ -482,8 +481,8 @@ Document control settings
 .
 .
 .LP
-The following list of document parameters is presented in the syntax
-used to interpolate them.
+The document parameters below are presented in the syntax
+used to interpolate their values.
 .
 For any unsatisfactory default,
 define its register,
@@ -846,8 +845,6 @@ the default is
 .CW T \[rq] \[lq]
 (Times).
 .
-The font family setting is ignored on terminal devices.
-.
 The
 .CW PS
 and
@@ -856,6 +853,8 @@ 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,
@@ -1649,6 +1648,7 @@ Cb Cb
 Lf(CR) L.
 Input  Result
 T{
+.na
 The course\[aq]s students found one C language keyword
 .br
 \&.CW static ) \[rs]%(
@@ -1676,6 +1676,7 @@ Cb Cb
 Lf(CR) L.
 Input  Result
 T{
+.na
 The course\[aq]s students found one C language keyword
 .br
 (\[rs]c
@@ -2145,10 +2146,9 @@ included later.
 .
 .
 .PP
-A keep can also be
-.I boxed .
-.
-Text in a box is automatically placed in a diversion (keep).
+A keep have a frame drawn around it;
+this is called a
+.I "boxed keep."
 .
 .
 .TS
@@ -2163,7 +2163,7 @@ _
 .
 .
 .LP
-Box macros cause breaks;
+Boxed keep macros cause breaks;
 if you need to box a word or phrase within a line,
 see the
 .CW BX
@@ -2172,8 +2172,8 @@ macro in section \[lq]Typeface and decoration\[rq] above.
 Box lines are drawn as close as possible to the text they enclose so
 that they are usable within paragraphs.
 .
-If you wish to box one or more paragraphs,
-you may improve the appearance by calling
+If you wish to place one or more paragraphs in a boxed keep,
+you may improve their appearance by calling
 .CW .B1
 after the first paragraphing macro,
 and by adding a small amount of vertical space before calling
@@ -2193,7 +2193,7 @@ Happy Fun Ball may suddenly accelerate to dangerous 
speeds.
 .
 .
 .LP
-If you want a box to float,
+If you want a boxed keep to float,
 you will need to enclose the
 .CW .B1
 and
@@ -2981,13 +2981,13 @@ to set the left,
 center,
 and right footers similarly.
 .
-This approach works best for documents that do not distinguish odd and
-even pages.
+This approach works best for documents that do not distinguish odd- and
+even-numbered pages.
 .
 .
 .PP
 Another method is to call macros with arguments that set headers or
-footers for odd or even pages;
+footers for odd- or even-numbered pages;
 these variables produce four combinations,
 so four macros are available.
 .
@@ -3096,7 +3096,7 @@ hook is a Berkeley extension.
 Any such macros you (re)define must implement any desired specialization
 for odd-,
 even-,
-or first-numbered pages.
+or first numbered pages.
 .
 .
 .KS
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 1a1a822f..d1c2828a 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -8,7 +8,7 @@ groff_ms \- GNU roff manuscript macro package for formatting 
documents
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2022 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -217,12 +217,12 @@ its preparation requires separate processing.
 .SS "Document control settings"
 .\" ====================================================================
 .
-The following tables list the document control registers and strings.
+The following tables list the document control registers,
+strings,
+and special characters.
 .
 For any parameter whose default is unsatisfactory,
-define its register,
-string,
-or special character before calling any
+define it before calling any
 .I ms
 macro other than
 .BR RP .
@@ -586,8 +586,6 @@ the default is
 .RB \[lq] T \[rq]
 (Times).
 .
-The font family setting is ignored on terminal devices.
-.
 The
 .B PS
 and
@@ -596,6 +594,8 @@ 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,
@@ -1251,9 +1251,9 @@ vertical space specified in its argument remaining on the 
page.
 .
 .
 .PP
-A keep can also be boxed.
-.
-Text in a box is automatically placed in a diversion (keep).
+A keep have a frame drawn around it;
+this is called a
+.I boxed keep.
 .
 .
 .TP
@@ -1267,7 +1267,7 @@ End boxed keep.
 .
 .
 .P
-Box macros cause breaks;
+Boxed keep macros cause breaks;
 if you need to box a word or phrase within a line,
 see the
 .B BX
@@ -1276,8 +1276,8 @@ macro in section \[lq]Highlighting\[rq] above.
 Box lines are drawn as close as possible to the text they enclose so
 that they are usable within paragraphs.
 .
-If you wish to box one or more paragraphs,
-you may improve the appearance by calling
+If you wish to place one or more paragraphs in a boxed keep,
+you may improve their appearance by calling
 .B .B1
 after the first paragraphing macro,
 and by adding a small amount of vertical space before calling
@@ -1285,7 +1285,7 @@ and by adding a small amount of vertical space before 
calling
 .
 .
 .P
-If you want a box to float,
+If you want a boxed keep to float,
 you will need to enclose the
 .B .B1
 and
@@ -1771,13 +1771,13 @@ to set the left,
 center,
 and right footers similarly.
 .
-This approach works best for documents that do not distinguish odd and
-even pages.
+This approach works best for documents that do not distinguish odd- and
+even-numbered pages.
 .
 .
 .P
 Another method is to call macros with arguments that set headers or
-footers for odd or even pages;
+footers for odd- or even-numbered pages;
 these variables produce four combinations,
 so four macros are available.
 .
@@ -1873,7 +1873,7 @@ hook is a Berkeley extension.
 Any such macros you (re)define must implement any desired specialization
 for odd-,
 even-,
-or first-numbered pages.
+or first numbered pages.
 .
 .
 .\" ====================================================================