[groff] 03/17: [ms]: Fix documentation style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5408e1340cb438252b0ad4dac91c3eb53a95811d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jul 17 06:18:10 2022 -0500

    [ms]: Fix documentation style nits.
    
    * Drop redundant sentence from ms.ms and our Texinfo manual, which have
      the "Basic information" section.
    * Annotate the 4.2BSD `HD` macro as originally undocumented.
    * Improve introduction to body text macros.
    * Vary wording.
---
 doc/groff.texi      | 18 ++++++++++--------
 doc/ms.ms           | 12 ++++--------
 tmac/groff_ms.7.man |  7 +++++--
 3 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 126348f3..112e0b2f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2612,8 +2612,7 @@ Wallace said my exposure had been
 
 The @file{ms} macro package expects a certain amount of structure:
 a well-formed document contains at least one paragraphing or heading
-macro call.  To compose a document from scratch, begin it by calling
-@code{LP} or @code{PP}.  Longer documents have a structure as follows.
+macro call.  Longer documents have a structure as follows.
 
 @table @strong
 @item Document type
@@ -3168,8 +3167,9 @@ added features are more in line with user demand.
 @cindex @file{ms} macros, body text
 
 A variety of macros, registers, and strings can be used to structure and
-style the body of your document.  Examples include paragraphs, headings,
-footnotes, and inclusions of material such as tables and figures.
+style the body of your document.  They organize your text into
+paragraphs, headings, footnotes, and inclusions of material such as
+tables and figures.
 
 @menu
 * Text settings in ms::
@@ -3401,7 +3401,7 @@ define the alias as follows.
 Any such change in numbering style becomes effective from the next use
 of @code{NH} following redefinition of the alias for @code{SN-STYLE}.
 The formatted number of the current heading is available in the
-@code{SN} string (a feature first documented by Berkeley); this feature
+@code{SN} string (a feature first documented by Berkeley); this string
 facilitates its inclusion in, for example, table captions, equation
 labels, and @code{XS}/@code{XA}/@code{XE} table of contents entries.
 @endDefmpstr
@@ -4238,9 +4238,11 @@ be written, and @code{BT} (``bottom trap'') when the 
footer is to be.
 The page location trap that @file{ms} sets up to format the header also
 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.
+header (for example, to draw a line below it).
+@c Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
+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.
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 64340c1e..b670ece8 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -369,12 +369,6 @@ macro package expects a certain amount of structure:
 a well-formed document contains at least one paragraphing or heading
 macro call.
 .
-To compose a document from scratch,
-begin it by calling
-.CW .LP
-or
-.CW .PP .
-.
 Longer documents have a structure as follows.
 .
 .
@@ -837,7 +831,8 @@ registers,
 and strings can be used to structure and style the body of your
 document.
 .
-Examples include paragraphs,
+They organize your text into
+paragraphs,
 headings,
 footnotes,
 and inclusions of material such as tables and figures.
@@ -1279,7 +1274,7 @@ following redefinition of the alias for
 The formatted number of the current heading is available in
 .CW \[rs]*[SN]
 (a feature first documented by Berkeley);
-this feature facilitates its inclusion in,
+this string facilitates its inclusion in,
 for example,
 table captions,
 equation labels,
@@ -3146,6 +3141,7 @@ if you need additional processing after setting the header
 (for example,
 to draw a line below it).
 .
+.\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
 The
 .CW HD
 hook is a Berkeley extension.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 7dd5c7a9..888fe918 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -107,7 +107,9 @@ macro package expects a certain amount of structure:
 a well-formed document contains at least one paragraphing or heading
 macro call.
 .
-To compose a document from scratch,
+.\" This sentence is unique to the man page because we omit the "Basic
+.\" information" section from ms.ms.
+To compose a simple document from scratch,
 begin it by calling
 .B .LP
 or
@@ -894,7 +896,7 @@ following redefinition of the alias for
 The formatted number of the current heading is available in
 .B \[rs]*[SN]
 (a feature first documented by Berkeley);
-this feature facilitates its inclusion in,
+this string facilitates its inclusion in,
 for example,
 table captions,
 equation labels,
@@ -1887,6 +1889,7 @@ you can define
 .B .HD
 if you need additional processing after setting the header.
 .
+.\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
 The
 .B HD
 hook is a Berkeley extension.