[groff] 06/35: [ms]: Fix content and style nits in docs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5d86222a062cb5b2afd711a7d2697be71b1ad9cb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jul 8 01:06:04 2022 -0500

    [ms]: Fix content and style nits in docs.
    
    * Distinguish spaces from horizontal motions.
    * Consistently refer to "GNU extensions".
    * Tighten wording.
    * Vary wording.
    * Adjust dead-tree typography (using keeps in ms(7) and .br/.ne in
      man(7)).
---
 doc/groff.texi      | 32 +++++++++++++++-----------------
 doc/ms.ms           | 36 ++++++++++++++++--------------------
 tmac/groff_ms.7.man | 38 ++++++++++++++++++--------------------
 3 files changed, 49 insertions(+), 57 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 4fcf0e56..fc7ebeb4 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3218,8 +3218,8 @@ Interpolate an em dash.
 @DefmpstrList {Q, ms}
 @DefmpstrListEndx {U, ms}
 Interpolate typographer's quotation marks where available, and neutral
-quotes otherwise.  @code{\*Q} is the left quote and @code{\*U} the
-right.  (As a mnemonic, think of ``quote'' and ``unquote''.)
+double quotes otherwise.  @code{\*Q} is the left quote and @code{\*U}
+the right.
 @endDefmpstr
 
 @c ---------------------------------------------------------------------
@@ -3478,7 +3478,7 @@ until the next highlighting, paragraphing, or heading 
macro call.
 
 @Defmac {R, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
 As @code{B}, but use the roman style (upright text of normal weight)
-instead of bold.
+instead of bold.  Argument recognition is a GNU extension.
 @endDefmac
 
 @Defmac {I, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
@@ -3500,9 +3500,9 @@ instead of bold.  This is a Tenth Edition Research Unix 
extension.
 @Defmac {BX, [@Var{text}], ms}
 Typeset @var{text} and draw a box around it.  On terminal devices,
 reverse video is used instead (see the implementation note below).
-If you want @var{text} to contain space, use horizontal motion escape
-sequences of appropriate width (@code{\~}, @code{\^}, @code{\|},
-@code{\0} or @code{\h}).
+If you want @var{text} to contain space, use unbreakable space or
+horizontal motion escape sequences (@code{\~}, @code{\SP}, @code{\^},
+@code{\|}, @code{\0} or @code{\h}).
 @endDefmac
 
 @Defmac {UL, [@Var{text} [@Var{post}]], ms}
@@ -4067,8 +4067,7 @@ corresponding @code{FS} call as long as each @code{FS} 
call occurs
 Footnote text is formatted as paragraphs are, using analogous
 parameters.  The registers @code{FI}, @code{FPD}, @code{FPS}, and
 @code{FVS} correspond to @code{PI}, @code{PD}, @code{PS}, and @code{CS},
-respectively. The @code{FPD}, @code{FPS}, and @code{FVS} registers are
-GNU extensions.
+respectively; @code{FPD}, @code{FPS}, and @code{FVS} are GNU extensions.
 
 The @code{FF} register controls the formatting of automatically numbered
 footnote paragraphs and those for which @code{FS} is given a marker
@@ -4189,13 +4188,12 @@ center, and right headers, respectively; and @code{LF}, 
@code{CF}, and
 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-numbered pages; these variables produce four
-combinations, so four macros are available.  Each takes a delimiter
+Another method is to call macros that set headers or footers for odd- or
+even-numbered pages.  Each such macro takes a delimited argument
 separating the left, center, and right header or footer texts from each
-other.  You can replace the neutral apostrophes (@code{'}) with any
-character not appearing in the header or footer text.  These macros are
-Berkeley extensions.
+other.  You can replace the neutral apostrophes (@code{'}) shown below
+with any character not appearing in the header or footer text.  These
+macros are Berkeley extensions.
 
 @DefmacList {OH, 
@code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
 @DefmacItemx {EH, 
@code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
@@ -4450,8 +4448,8 @@ multiplied by 1000.  See the @code{PS} register in 
@ref{ms Document
 Control Settings}.
 
 @item
-@acronym{AT&T} @file{ms}'s @code{AU} macro recognized arguments that
-were used with some cover sheet types; @code{groff} @file{ms} does not.
+@acronym{AT&T} @file{ms}'s @code{AU} macro supported arguments used with
+some document types; @code{groff} @file{ms} does not.
 
 @item
 Right-aligned displays are available.  The @acronym{AT&T} @file{ms}
@@ -4552,7 +4550,7 @@ original at hand.  For informal purposes, a simple 
definition of
 @cindex strings [@file{ms}]
 
 @code{groff} @file{ms} retains support for some legacy features solely
-to support rendering of historical documents; contemporary ones should
+to support formatting of historical documents; contemporary ones should
 not use them because they can render poorly.  See the
 @cite{groff_char@r{(7)}} man page.
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 100b3cdb..9c77e065 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -911,15 +911,12 @@ _
 _
 \[rs]*[Q]      T{
 Interpolate typographer's quotation marks where available,
-and neutral quotes otherwise.
+and neutral double quotes otherwise.
 .
 .CW \[rs]*[Q]
 is the left quote and
 .CW \[rs]*[U]
 the right.
-.
-(As a mnemonic,
-think of \*[Q]quote\*[U] and \*[Q]unquote\*[U].)
 T}
 \[rs]*[U]      \^
 .TE
@@ -1504,8 +1501,7 @@ but use the roman style
 (upright text of normal weight)
 instead of bold.
 .
-Arguments are recognized only by
-.I "groff ms."
+Argument recognition is a GNU extension.
 T}
 _
 \&.I \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]]       T{
@@ -1552,8 +1548,10 @@ reverse video is used instead
 If you want
 .I text
 to contain space,
-use horizontal motion escape sequences of appropriate width
+use unbreakable space or horizontal motion escape sequences
 .CW \[rs]\[ti] , (
+.CW \[rs]\c
+.I space ,
 .CW \[rs]\[ha] ,
 .CW \[rs]| ,
 .CW \[rs]0 ,
@@ -2162,6 +2160,7 @@ _
 .TE
 .
 .
+.KS
 .LP
 Boxed keep macros cause breaks;
 if you need to box a word or phrase within a line,
@@ -2190,6 +2189,7 @@ Happy Fun Ball may suddenly accelerate to dangerous 
speeds.
 \&.sp \[rs]n[PD]/2
 \&.B2
 .TE
+.KE
 .
 .
 .LP
@@ -2680,14 +2680,12 @@ correspond to
 .CW PS ,
 and
 .CW VS ,
-respectively.
-.
-The
+respectively;
 .CW FPD ,
 .CW FPS ,
 and
 .CW FVS
-registers are GNU extensions.
+are GNU extensions.
 .
 .
 .KS
@@ -2986,17 +2984,15 @@ even-numbered pages.
 .
 .
 .PP
-Another method is to call macros with arguments that set headers or
-footers for odd- or even-numbered pages;
-these variables produce four combinations,
-so four macros are available.
+Another method is to call macros that set headers or footers for odd- or
+even-numbered pages.
 .
-Each takes a delimiter separating the left,
+Each such macro takes a delimited argument separating the left,
 center,
 and right header or footer texts from each other.
 .
-You can replace the neutral apostrophes (\[aq]) with any character not
-appearing in the header or footer text.
+You can replace the neutral apostrophes (\[aq]) shown below with any
+character not appearing in the header or footer text.
 .
 These macros are Berkeley extensions.
 .
@@ -3632,7 +3628,7 @@ is preferable.
 AT&T
 .I ms 's
 .CW AU
-macro recognized arguments that were used with some cover sheet types;
+macro supported arguments used with some document types;
 .I "groff ms"
 does not.
 .
@@ -3824,7 +3820,7 @@ Legacy features
 .
 .LP
 .I "groff ms"
-retains support for some legacy features solely to support rendering of
+retains support for some legacy features solely to support formatting of
 historical documents;
 contemporary ones should not use them because they can render poorly.
 .
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index f7ed1270..6513ccfe 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -606,6 +606,8 @@ and
 footnotes.
 .
 .
+.br
+.ne 2v
 .P
 The
 .B HY
@@ -645,16 +647,13 @@ Interpolate an em dash.
 .TQ
 .B \[rs]*[U]
 Interpolate typographer's quotation marks where available,
-and neutral quotes otherwise.
+and neutral double quotes otherwise.
 .
 .B \[rs]*[Q]
 is the left quote and
 .B \[rs]*[U]
 the right.
 .
-(As a mnemonic,
-think of \[lq]quote\[rq] and \[lq]unquote\[rq].)
-.
 .
 .\" ====================================================================
 .SS Paragraphs
@@ -1035,8 +1034,7 @@ but use the roman style
 (upright text of normal weight)
 instead of bold.
 .
-Arguments are recognized only by
-.I groff ms.
+Argument recognition is a GNU extension.
 .
 .
 .TP
@@ -1082,8 +1080,10 @@ reverse video is used instead.
 If you want
 .I text
 to contain space,
-use horizontal motion escape sequences of appropriate width
+use unbreakable space or horizontal motion escape sequences
 .RB ( \[rs]\[ti] ,
+.BI \[rs] space\c
+,
 .BR \[rs]\[ha] ,
 .BR \[rs]| ,
 .BR \[rs]0 ,
@@ -1284,6 +1284,8 @@ and by adding a small amount of vertical space before 
calling
 .B .B2 .
 .
 .
+.br
+.ne 2v
 .P
 If you want a boxed keep to float,
 you will need to enclose the
@@ -1620,14 +1622,12 @@ correspond to
 .BR PS ,
 and
 .BR VS ,
-respectively.
-.
-The
+respectively;
 .BR FPD ,
 .BR FPS ,
 and
 .B FVS
-registers are GNU extensions.
+are GNU extensions.
 .
 .
 .P
@@ -1776,17 +1776,15 @@ even-numbered pages.
 .
 .
 .P
-Another method is to call macros with arguments that set headers or
-footers for odd- or even-numbered pages;
-these variables produce four combinations,
-so four macros are available.
+Another method is to call macros that set headers or footers for odd- or
+even-numbered pages.
 .
-Each takes a delimiter separating the left,
+Each such macro takes a delimited argument separating the left,
 center,
 and right header or footer texts from each other.
 .
-You can replace the neutral apostrophes (\[aq]) with any character not
-appearing in the header or footer text.
+You can replace the neutral apostrophes (\[aq]) shown below with any
+character not appearing in the header or footer text.
 .
 These macros are Berkeley extensions.
 .
@@ -2428,7 +2426,7 @@ accessing an undefined register automatically defines it.
 AT&T
 .IR ms 's
 .B AU
-macro recognized arguments that were used with some cover sheet types;
+macro supported arguments used with some document types;
 .I groff ms
 does not.
 .
@@ -2586,7 +2584,7 @@ or lack a stable definition historically
 .\" ====================================================================
 .
 .I "groff ms"
-retains support for some legacy features solely to support rendering of
+retains support for some legacy features solely to support formatting of
 historical documents;
 contemporary ones should not use them because they can render poorly.
 .