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

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 4696b9830d1d44c99e4d2de5db686ce86f247838
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Dec 14 16:16:20 2022 -0600

    [ms]: Fix documentation nits.
    
    * (groff.texi, ms.ms) Document behavior of input blank lines.  Draw
      attention to the fact that they space by 1v, whereas paragraphing
      macros do so by \n[PD].
    * (groff.texi, ms.ms) Shift text and drop duplicated clause when
      discussing .RS/.RE.
    * (groff.texi, ms.ms) Tighten advice to use groff preprocessor options,
      better fitting the page in U.S. letter formatting.
    * (groff.texi, ms.ms) Explain another benefit of groff's scaled points
      mechanism, albeit without using that term.
    * (ms.ms) Quote inlined multi-word input examples even when a face
      change is available.
    * (ms.ms) Use poor man's keep to cope with Savannah #63159.
    * Make lengthy, multistemmed sentence grammatical.
    * Tighten wording.
    * (ms.ms) Point reader to copy of Deri's msboxes.pdf document.
    * (ms.ms) Point reader to source of this very document.
---
 doc/groff.texi      | 39 ++++++++++++++++++++-------------------
 doc/ms.ms           | 51 +++++++++++++++++++++++++++++++++------------------
 tmac/groff_ms.7.man | 10 ++++++----
 3 files changed, 59 insertions(+), 41 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 920a4bd7e..f7317009d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3250,7 +3250,8 @@ 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.
+register, except at page or column breaks.  Alternatively, a blank input
+line breaks the output line and vertically spaces by one vee.
 
 The @code{PORPHANS} register defines the minimum number of initial lines
 of any paragraph that must be kept together to avoid isolated lines at
@@ -3757,7 +3758,8 @@ money
 @subsubsection Indented regions
 
 You may need to indent a region of text while otherwise formatting it
-normally.  Indented regions can be nested.
+normally.  Indented regions can be nested; you can change @code{\n[PI]}
+before each call to vary the amount of inset.
 
 @Defmac {RS, , ms}
 Begin a region where headings, paragraphs, and displays are indented
@@ -3768,9 +3770,8 @@ Begin a region where headings, paragraphs, and displays 
are indented
 End the (next) most recent indented region.
 @endDefmac
 
-Indented regions can be nested; you can change @code{\n[PI]} before each
-call to vary the amount of inset.  This feature enables you to easily
-line up text under hanging and indented paragraphs.
+This feature enables you to easily line up text under hanging and
+indented paragraphs.
 @cindex @file{ms} macros, nested lists
 @cindex nested lists [@file{ms}]
 For example, you may wish to structure lists hierarchically.
@@ -4028,10 +4029,9 @@ This input formats a labelled equation.  We used the 
@code{SN-NO-DOT}
 string to base the equation label on the current heading number, giving
 us more flexibility to reorganize the document.
 
-Remember to run any desired preprocessors on the input; @command{groff}
-options will take care of this.  Use @option{-e} for @command{geqn},
-@option{-p} for @command{gpic}, @option{-R} for @command{grefer}, and
-@option{-t} for @command{gtbl}.
+Use @command{groff} options to run preprocessors on the input:@:
+@option{-e} for @command{geqn}, @option{-p} for @command{gpic},
+@option{-R} for @command{grefer}, and @option{-t} for @command{gtbl}.
 
 @c ---------------------------------------------------------------------
 
@@ -4541,9 +4541,10 @@ or larger than@tie{}1,000 (one thousand) as decimal 
fractions multiplied
 by@tie{}1,000.@footnote{Register values are converted to and stored as
 basic units.  @xref{Measurements}.}  This threshold makes use of a
 scaling unit with these parameters practical for high-resolution
-devices while preserving backward compatibility.  For example,
-@samp{groff -rPS=10.5p} at the shell prompt is equivalent to placing
-@samp{.nr PS 10.5p} at the beginning of the document.
+devices while preserving backward compatibility.  It also permits
+expression of non-integral type sizes.  For example, @samp{groff
+-rPS=10.5p} at the shell prompt is equivalent to placing @samp{.nr PS
+10.5p} at the beginning of the document.
 
 @item
 @acronym{AT&T} @file{ms}'s @code{AU} macro supported arguments used with
@@ -4604,8 +4605,8 @@ Several macros described in the Unix Version@tie{}7 
@file{ms}
 documentation are unimplemented by @code{groff} @file{ms} because they
 are specific to the requirements of documents produced internally by
 Bell Laboratories, some of which also require a glyph for the Bell
-System logo that @code{groff} does not support.  These include macros
-implementing several document type formats
+System logo that @code{groff} does not support.  These macros
+implemented several document type formats
 (@code{EG}, @c engineer's notes
 @code{IM}, @c internal memorandum
 @code{MF}, @c memorandum for file
@@ -4625,7 +4626,7 @@ stored the postal addresses of Bell Labs sites
 @code{MH}, @c Murray Hill
 @code{PY}, @c Piscataway
 @code{WH}), @c Whippany
-or lack a stable definition historically
+or lacked a stable definition over time
 (@code{UX}). @c Unix; on 1st use, add footnote id'ing trademark owner
 To compatibly render historical @file{ms} documents using these macros,
 we advise your documents to invoke the @code{rm} request to remove any
@@ -4652,10 +4653,10 @@ readability of the document's substance.
 @cindex special characters [@file{ms}]
 @cindex strings [@file{ms}]
 
-@code{groff} @file{ms} retains support for some legacy features solely
-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.
+@code{groff} @file{ms} retains some legacy features solely 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.
 
 @unnumberedsubsubsec AT&T accent mark strings
 
diff --git a/doc/ms.ms b/doc/ms.ms
index c6dbdc7e9..341572c79 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -1003,6 +1003,10 @@ the amount stored in the
 .CW PD
 register,
 except at page or column breaks.
+.
+Alternatively,
+a blank input line breaks the output line and vertically spaces by one
+vee.
 .KE
 .
 .
@@ -2076,7 +2080,10 @@ Indented regions
 You may need to indent a region of text while otherwise formatting it
 normally.
 .
-Indented regions can be nested.
+Indented regions can be nested;
+you can change
+.CW \[rs]n[PI]
+before each call to vary the amount of inset.
 .
 .
 .TS
@@ -2098,11 +2105,6 @@ T}
 .
 .
 .PP
-Indented regions can be nested;
-you can change
-.CW \[rs]n[PI]
-before each call to vary the amount of inset.
-.
 This feature enables you to easily line up text under hanging and
 indented paragraphs.
 .
@@ -2592,14 +2594,10 @@ giving us more flexibility to reorganize the document.
 p ~ = ~ q sqrt { 1 + ~ ( x / q sup 2 ) }
 .EN
 .
-.
-.PP
-Remember to run any desired preprocessors on the input;
+Use
 .I groff
 options
-will take care of this.
-.
-Use
+to run preprocessors on the input:
 .CW \-e
 for
 .I eqn ,
@@ -3952,10 +3950,12 @@ This threshold makes use of a scaling unit with these 
parameters
 practical for high-resolution devices while preserving backward
 compatibility.
 .
+It also permits expression of non-integral type sizes.
+.
 For example,
-.CW "groff \-rPS=10.5p"
+.CW "groff \-rPS=10.5p" \[rq] \[lq]
 at the shell prompt is equivalent to placing
-.CW ".nr PS 10.5p"
+.CW ".nr PS 10.5p" \[rq] \[lq]
 at the beginning of the document.
 .
 .
@@ -4079,6 +4079,8 @@ or another implementation should test this register.
 .\" XXX: We can't use a keep here because the wrong page number will be
 .\" recorded in the table of contents; see Savannah #63159.
 .\"KS
+.br
+.ne 6v
 .NH 2
 Unix Version\~7
 .BI ms
@@ -4101,7 +4103,7 @@ some of which also require a glyph for the Bell System 
logo that
 .I groff
 does not support.
 .
-These include macros implementing several document type formats
+These macros implemented several document type formats
 (\c
 .CW EG , \" engineer's notes
 .CW IM , \" internal memorandum
@@ -4124,7 +4126,7 @@ stored the postal addresses of Bell Labs sites
 .CW MH , \" Murray Hill
 .CW PY , \" Piscataway
 .CW WH ), \" Whippany
-or lack a stable definition historically
+or lacked a stable definition over time
 (\c
 .CW UX ). \" Unix; on 1st use, add footnote identifying trademark owner
 .
@@ -4169,8 +4171,8 @@ Legacy features
 .
 .LP
 .I "groff ms"
-retains support for some legacy features solely to support formatting of
-historical documents;
+retains some legacy features solely to support formatting of historical
+documents;
 contemporary ones should not use them because they can render poorly.
 .
 See
@@ -4338,6 +4340,19 @@ enabling colored,
 bordered boxes when the
 .CW pdf
 output device is used.
+.
+This document is distributed with
+.I groff
+as the file
+.I msboxes.pdf .
+.
+.
+.LP
+This manual was composed using
+.I "groff ms" ;
+the curious may consult its source in the file
+.I ms.ms
+to see how its formatting was achieved.
 .\" ------------------------
 .TC
 .
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 770b8b5e8..386e701df 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -2406,6 +2406,8 @@ This threshold makes use of a scaling unit with these 
parameters
 practical for high-resolution devices while preserving backward
 compatibility.
 .
+It also permits expression of non-integral type sizes.
+.
 For example,
 .RB \[lq] "groff \-rPS=10.5p" \[rq]
 at the shell prompt is equivalent to placing
@@ -2560,7 +2562,7 @@ some of which also require a glyph for the Bell System 
logo that
 .I groff
 does not support.
 .
-These include macros implementing several document type formats
+These macros implemented several document type formats
 (\c
 .BR EG , \" engineer's notes
 .BR IM , \" internal memorandum
@@ -2583,7 +2585,7 @@ stored the postal addresses of Bell Labs sites
 .BR MH , \" Murray Hill
 .BR PY , \" Piscataway
 .BR WH ), \" Whippany
-or lack a stable definition historically
+or lacked a stable definition over time
 (\c
 .BR UX ). \" Unix; on 1st use, add footnote identifying trademark owner
 .
@@ -2593,8 +2595,8 @@ or lack a stable definition historically
 .\" ====================================================================
 .
 .I "groff ms"
-retains support for some legacy features solely to support formatting of
-historical documents;
+retains some legacy features solely to support formatting of historical
+documents;
 contemporary ones should not use them because they can render poorly.
 .
 See