[groff] 24/24: [ms]: Tweak documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d776dc8d3a60d8ff2f1d97ea06b2a38d262b4476
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Aug 23 03:48:36 2023 -0500

    [ms]: Tweak documentation.
    
    * Tighten wording.
    * (doc/groff.texi, tmac/groff_ms.7.man) Apply more poor man's keeps to
      improve pagination.
    * (doc/groff.texi) Note recent localization improvements.
---
 doc/groff.texi      | 30 ++++++++++++++++--------------
 doc/ms.ms           | 14 +++++++-------
 tmac/groff_ms.7.man |  8 ++++----
 3 files changed, 27 insertions(+), 25 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 0f562523f..2b0ac8b24 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2575,8 +2575,7 @@ 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.
+want your paragraph's first line 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
@@ -2609,6 +2608,7 @@ denied than admitted.
 @arrow{}That's what Dijkstra said, anyway.
 @endCartoucheExample
 
+@need 750
 @file{ms} exposes many aspects of document layout to user control via
 @code{groff}'s @dfn{registers} and @dfn{strings}, which store numbers
 and text, respectively.  Measurements in @code{groff} are expressed with
@@ -3074,8 +3074,7 @@ Default: @code{\n[PD] / 2}.
 Defines the ratio of the footnote line length to the current line
 length.  This is a GNU extension.
 
-Effective: next footnote in single-column arrangements, next page
-otherwise.
+Effective: next footnote if single-column layout, next page otherwise.
 
 Default: @code{11/12}.
 @endDefmpstr
@@ -3516,6 +3515,7 @@ the size specified by @code{PS} multiplied by the 
difference of
 interpreted in @code{groff} basic units; the @code{p} scaling unit
 should be employed when assigning a value specified in points.
 
+@need 1000
 The input
 
 @CartoucheExample
@@ -3610,20 +3610,18 @@ bracketed with underscores `_'.  @var{post}, if 
present, is set after
 @Defmac {LG, , ms}
 Set subsequent text in larger type (two points larger than the
 current size) until the next type size, paragraphing, or heading macro
-call.  You can specify this macro multiple times to enlarge the type
-size as needed.
+call.  Call the macro multiple times to enlarge the type size further.
 @endDefmac
 
 @Defmac {SM, , ms}
 Set subsequent text in smaller type (two points smaller than the current
 size) until the next type size, paragraphing, or heading macro call.
-You can specify this macro multiple times to reduce the type size as
-needed.
+Call the macro multiple times to reduce the type size further.
 @endDefmac
 
 @Defmac {NL, , ms}
-Set subsequent text at the normal type size (the amount in the @code{PS}
-register).
+Set subsequent text at the normal type size (the amount in register
+@code{PS}).
 @endDefmac
 
 @var{pre} and @var{post} arguments are typically used to simplify the
@@ -3638,6 +3636,7 @@ The CS course's students found one C language keyword
 most troublesome.
 @endCartoucheExample
 
+@need 1000
 The foregoing example produces output as follows.
 
 @CartoucheExample
@@ -3693,6 +3692,7 @@ definition lists.  If you set the paragraph indentation 
register
 the list without having to ensure that a @var{width} argument remains
 affixed to the first call.
 
+@need 1000
 The following is an example of a bulleted list.
 @cindex example markup, bulleted list [@file{ms}]
 @cindex bulleted list, example markup [@file{ms}]
@@ -3752,6 +3752,7 @@ 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.
 
+@need 1000
 The next example illustrates a glossary-style list.
 @cindex example markup, glossary-style list [@file{ms}]
 @cindex glossary-style list, example markup [@file{ms}]
@@ -4228,10 +4229,10 @@ operator precedence (parentheses are honored).
 @code{groff} @file{ms} provides several strings that you can customize
 for your own purposes, or redefine to adapt the macro package to
 languages other than English.  It is already localized for
-@c cs, de, fr, it, sv
-Czech, German, French, Italian, and Swedish.  Load the desired
-localization macro package after @file{ms}; see the
-@cite{groff_tmac@r{(5)}} man page.
+@c cs, de, es, fr, it, ru, sv
+Czech, German, Spanish, French, Italian, Russian, and Swedish.  Load the
+desired localization macro package after @file{ms}; see
+@cite{groff_tmac@r{(5)}}.
 
 @CartoucheExample
 $ groff -ms -mfr bienvenue.ms
@@ -4465,6 +4466,7 @@ Set the page number to@tie{}1, the page number format to 
lowercase Roman
 numerals, and call @code{PX} (with a @code{no} argument, if present).
 @endDefmac
 
+@need 1000
 Here's an example of typical @file{ms} table of contents preparation.
 We employ horizontal escape sequences @code{\h} to indent the entries by
 sectioning depth.
diff --git a/doc/ms.ms b/doc/ms.ms
index d3d84931d..bc7b340d6 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -165,7 +165,7 @@ Put a macro call on a line by itself.
 .
 Use
 .CW .PP
-if you want your paragraph's first line to be indented,
+if you want your paragraph's first line indented,
 or
 .CW .LP
 if you don't.
@@ -1704,13 +1704,13 @@ type size,
 paragraphing,
 or heading macro call.
 .
-You can
+Call
 .LG
-specify this macro
+the macro
 .LG
 multiple times
 .NL
-to enlarge the type size as needed.
+to enlarge the type size further.
 T}
 _
 \&.SM  T{
@@ -1724,13 +1724,13 @@ type size,
 paragraphing,
 or heading macro call.
 .
-You can
+Call
 .SM
-specify this macro
+the macro
 .SM
 multiple times
 .NL
-to reduce the type size as needed.
+to reduce the type size further.
 T}
 _
 \&.NL  T{
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index ea93f8832..43dcf0b92 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1184,8 +1184,7 @@ type size,
 paragraphing,
 or heading macro call.
 .
-You can specify this macro multiple times to enlarge the type size as
-needed.
+Call the macro multiple times to enlarge the type size further.
 .
 .
 .TP
@@ -1197,8 +1196,7 @@ type size,
 paragraphing,
 or heading macro call.
 .
-You can specify this macro multiple times to reduce the type size as
-needed.
+Call the macro multiple times to reduce the type size further.
 .
 .
 .TP
@@ -1369,6 +1367,8 @@ and
 calls.
 .
 .
+.br
+.ne 2v
 .P
 .I Displays
 turn off filling;