[groff] 10/17: [ms]: Clarify documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit eb2a51b84bae4ac1ce369b807be830328997d46f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Jul 21 03:14:26 2022 -0500

    [ms]: Clarify documentation.
    
    * Update introductory example to specify the output device explicitly,
      to make it correct even if someone's build changes the default.
    * Add paragraph discussing font family availability.
    * Migrate terminology: "unbreakable horizontal space" -> "horizontal
      motion".
    * Document that display distance DD supersedes paragraph distance PD
      (reflecting recent changes prompted by retypesetting Kernighan &
      Cherry's eqn users' guide).
    * Consistently refer to an IP paragraph marker as such.
    * Vary wording.
    * Tighten wording.
---
 doc/groff.texi      | 56 ++++++++++++++++++++++++++++++-----------------------
 doc/ms.ms           | 44 +++++++++++++++++++++++++++--------------
 tmac/groff_ms.7.man |  6 +++---
 3 files changed, 65 insertions(+), 41 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index e6e79683..459806da 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2498,7 +2498,7 @@ can be useful for previewing.
 @CartoucheExample
 $ vi radical.ms
 $ nroff -ms radical.ms | less -R
-$ groff -ms radical.ms > radical.ps
+$ groff -T ps -ms radical.ms > radical.ps
 $ see radical.ps
 @endCartoucheExample
 
@@ -3191,13 +3191,20 @@ 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 @code{PS} and @code{VS} registers set the type
+@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
+sans-serif family (``Helvetica''), and @code{C} a monospaced family
+(``Courier'').  The man page for the output driver documents its font
+repertoire.  Consult the @cite{groff@r{(1)}} man page for lists of
+available output devices and their drivers.
+
 The hyphenation mode (as used by the @code{hy} request) is set from the
 @code{HY} register.  Setting @code{HY} to @samp{0} is equivalent to
 using the @code{nh} request.  This is a Tenth Edition Research Unix
@@ -3551,9 +3558,9 @@ The foregoing example produces output as follows.
 troublesome.}
 @endCartoucheExample
 
-You might prefer to use the output line continuation escape sequence
-@code{\c} to achieve the same result (@pxref{Line Continuation}).  It is
-also portable to older @file{ms} implementations.
+You can use the output line continuation escape sequence @code{\c} to
+achieve the same result (@pxref{Line Continuation}).  It is also
+portable to older @file{ms} implementations.
 
 @CartoucheExample
 The course's students found one C language keyword
@@ -3576,13 +3583,13 @@ Begin and end subscripting, respectively.
 @endDefmpstr
 
 Rather than calling the @code{CW} macro, in @code{groff} @file{ms} you
-might prefer to change the font family to Courier---a monospaced
-typeface---by setting the @code{FAM} string to @samp{C}.  You can then
-use all four style macros above, returning to the default family (Times)
-with @samp{.ds FAM T}.  Because changes to @code{FAM} take effect only
-at the next paragraph, @code{CW} remains useful to ``inline'' a change
-to the font family, similarly to the practice of this document in noting
-syntactical elements of @file{ms} and @code{groff}.
+might prefer to change the font family to Courier by setting the
+@code{FAM} string to @samp{C}.  You can then use all four style macros
+above, returning to the default family (Times) with @samp{.ds FAM T}.
+Because changes to @code{FAM} take effect only at the next paragraph,
+@code{CW} remains useful to ``inline'' a change to the font family,
+similarly to the practice of this document in noting syntactical
+elements of @file{ms} and @code{groff}.
 
 @c ---------------------------------------------------------------------
 
@@ -3702,10 +3709,10 @@ line as the term or label (if it fits) @emph{then} 
breaks the line.
 \p Firearms,
 @endCartoucheExample
 
-Finally, you may append unbreakable horizontal space to the term or
-label with the @code{\h} escape sequence; using the same amount as the
-indentation will ensure that it's too wide for @code{groff} to treat it
-as ``fitting'' on the same line as the paragraph text.
+Finally, you may append a horizontal motion to the marker with the
+@code{\h} escape sequence; using the same amount as the indentation will
+ensure that the marker is too wide for @code{groff} to treat it as
+``fitting'' on the same line as the paragraph text.
 
 @CartoucheExample
 .IP guns\h'0.4i'
@@ -3840,14 +3847,14 @@ 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}.
 
-@c Wrap example at 56 columns.
+@c Wrap example at 58 columns.
 @CartoucheExample
 .LP
 .B1
 .I Warning:
 Happy Fun Ball may suddenly accelerate to dangerous
 speeds.
-.sp \n[PD]/2
+.sp \n[PD]/2 \" space by half the inter-paragraph distance
 .B2
 @endCartoucheExample
 
@@ -3899,12 +3906,13 @@ End any display.
 @endDefmac
 
 The distance stored in the @code{DD} register is inserted before and
-after each pair of display macros; this is a Berkeley extension.  The
-@code{DI} register is a GNU extension; its value is an indentation
-applied to displays created with @samp{.DS} and @samp{.ID} without
-arguments, to @samp{.DS I} without an indentation argument, and to
-indented equations set with @samp{.EQ}.  Changes to either register take
-effect at the next display boundary.
+after each pair of display macros, replacing any adjacent
+inter-paragraph distance; this is a Berkeley extension.  The @code{DI}
+register is a GNU extension; its value is an indentation applied to
+displays created with @samp{.DS} and @samp{.ID} without arguments, to
+@samp{.DS I} without an indentation argument, and to indented equations
+set with @samp{.EQ}.  Changes to either register take effect at the next
+display boundary.
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index e3a93a31..b5073c82 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -186,7 +186,7 @@ box center;
 lf(CB).
 \f[CR]$\f[] vi radical.ms
 \f[CR]$\f[] nroff \-ms radical.ms | less \-R
-\f[CR]$\f[] groff \-ms radical.ms > radical.ps
+\f[CR]$\f[] groff \-T ps \-ms radical.ms > radical.ps
 \f[CR]$\f[] see radical.ps
 .TE
 .
@@ -503,11 +503,11 @@ macro other than
 .CW RP .
 .
 The \[lq]Next\[rq] heading indicates that changes to the parameter are
-effective as of the next listed element encountered.
+effective as of the next new element processed of the listed type.
 .
 For entries marked
 .I special ,
-see the discussion in the applicable section below.
+see the discussion in the applicable section.
 .
 .
 .TS H
@@ -868,8 +868,7 @@ The
 .CW FAM
 string sets the font family for body text;
 the default is
-.CW T \[rq] \[lq]
-(Times).
+.CW T \[rq] \[lq].
 .
 The
 .CW PS
@@ -892,6 +891,24 @@ footnotes.
 .
 .
 .PP
+Which font families are available depends on the output device;
+as a convention,
+.CW T
+selects a serif family (\[lq]Times\[rq]),
+.CW H
+a sans-serif family (\[lq]Helvetica\[rq]),
+and
+.CW C
+a monospaced family (\[lq]Courier\[rq]).
+.
+The man page for the output driver documents its font repertoire.
+.
+Consult the
+.I groff (1)
+man page for lists of available output devices and their drivers.
+.
+.
+.PP
 The
 .CW HY
 register defines the automatic hyphenation mode used with the
@@ -1690,7 +1707,7 @@ T}
 .TE
 .
 .KS
-You might prefer to use the output line continuation escape sequence
+You can use the output line continuation escape sequence
 .CW \[rs]c
 to achieve the same result.
 .
@@ -1728,8 +1745,7 @@ Rather than calling the
 macro,
 in
 .I "groff ms"
-you might prefer to change the font family to Courier\[em]a monospaced
-typeface\[em]by setting
+you might prefer to change the font family to Courier by setting
 .CW \[rs]*[FAM]
 to
 .CW C \[rq]. \[lq]
@@ -1952,12 +1968,11 @@ or label
 breaks the line.
 .
 Finally,
-you may append unbreakable horizontal space to the term or label with
-the
+you may append a horizontal motion to the marker with the
 .CW \[rs]h
 escape sequence;
-using the same amount as the indentation will ensure that it's too wide
-for
+using the same amount as the indentation will ensure that the marker is
+too wide for
 .I groff
 to treat it as \[lq]fitting\[rq] on the same line as the paragraph text.
 .
@@ -2213,7 +2228,7 @@ lf(CR).
 \&.B1
 \&.I Warning:
 Happy Fun Ball may suddenly accelerate to dangerous speeds.
-\&.sp \[rs]n[PD]/2
+\&.sp \[rs]n[PD]/2 \[rs]" space by half the inter-paragraph distance
 \&.B2
 .TE
 .KE
@@ -2286,7 +2301,8 @@ cf(CR) s | lx .
 .PP
 The distance stored in
 .CW \[rs]n[DD]
-is inserted before and after each pair of display macros;
+is inserted before and after each pair of display macros,
+replacing any adjacent inter-paragraph distance;
 this is a Berkeley extension.
 .
 The
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 58eecd89..a46570bb 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -600,8 +600,7 @@ The
 .B FAM
 string sets the font family for body text;
 the default is
-.RB \[lq] T \[rq]
-(Times).
+.RB \[lq] T \[rq].
 .
 The
 .B PS
@@ -1404,7 +1403,8 @@ End any display.
 .P
 The distance stored in
 .B \[rs]n[DD]
-is inserted before and after each pair of display macros;
+is inserted before and after each pair of display macros,
+replacing any adjacent inter-paragraph distance;
 this is a Berkeley extension.
 .
 The