[groff] 24/41: [ms]: Fix content and style nits in docs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f571736b1199b6d126703a825ff8aac46811f7fa
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Mar 16 20:38:05 2022 +1100

    [ms]: Fix content and style nits in docs.
    
    * doc/groff.texi:
    * doc/ms.ms:
    * tmac/groff_ms.7.man:
      - Content:
        + Annotate `NH` argument as optional, and document its default (1).
        + Consistently refer to heading numbers, not "section" numbers.
        + Generalize introduction to indented regions, to avoid excessively
          strict inferences.
      - Style:
        + Recast caveat about use of `in` request.
        + Say that macros are "called", not "invoked".
        + Consistently refer to heading numbers, not "section" numbers.
        + Annotate `NH` argument as optional, and document its default (1).
        + Say that macros are "called", not "invoked".
        + Generalize introduction to indented regions, to avoid excessively
        + Recast caveat about use of `in` request.
        + Tighten introduction to columnation macros.
    
    * doc/ms.ms:
      - Content:
        + Say "Tenth Edition" rather than "Version 10" Unix.
      - Style:
        + Diversify wording.
---
 doc/groff.texi      | 71 +++++++++++++++++++++++++++--------------------------
 doc/ms.ms           | 46 +++++++++++++++++-----------------
 tmac/groff_ms.7.man | 47 ++++++++++++++++++-----------------
 3 files changed, 83 insertions(+), 81 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index cacb6e86..61a7d693 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2507,15 +2507,16 @@ documentation.
 
 The @file{ms} (``manuscript'') package is suitable for the preparation
 of letters, memoranda, reports, and books.  These @code{groff}
-macros feature cover page and table of contents generation, automatic
-section numbering, several different paragraph styles, a variety of text
-styling options, footnotes, multi-column page layouts, and indexing.
-@file{ms} supports the @command{tbl}, @command{eqn}, @command{pic}, and
-@command{refer} preprocessors for inclusion of tables, mathematical
-equations, diagrams, and standardized bibliographic citations.  This
-implementation is mostly compatible with the documented interface and
-behavior of AT&T Unix Version@tie{}7 @file{ms}.  Several extensions from
-4.2BSD (Berkeley) @c Few changes were made in 4.3, Tahoe, Reno, or 4.4.
+macros feature cover page and table of contents generation,
+automatically numbered headings, several different paragraph styles, a
+variety of text styling options, footnotes, multi-column page layouts,
+and indexing.  @file{ms} supports the @command{tbl}, @command{eqn},
+@command{pic}, and @command{refer} preprocessors for inclusion of
+tables, mathematical equations, diagrams, and standardized bibliographic
+citations.  This implementation is mostly compatible with the documented
+interface and behavior of AT&T Unix Version@tie{}7 @file{ms}.  Several
+extensions from 4.2BSD (Berkeley)
+@c Few changes were made in 4.3, Tahoe, Reno, or 4.4.
 and Tenth Edition Research Unix have been recreated.
 
 @menu
@@ -2579,7 +2580,7 @@ We have used an arrow @arrow{} in the above to indicate a 
tab character.
 @cindex @code{ms} macros, general structure
 
 The @file{ms} macro package expects a certain amount of structure:
-a well-formed document contains at least one paragraphing or sectioning
+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.
 
@@ -3267,15 +3268,16 @@ Headings are available with and without automatic 
numbering.  Text lines
 immediately after heading macro calls are treated as part of the
 heading, rendered on the same output line in the same style.
 
-@DefmacList {NH, @Var{depth}, ms}
+@DefmacList {NH, [@Var{depth}], ms}
 @DefmacListEnd {NH, @t{S} @Var{heading-depth-index} @dots{}, ms}
 Set an automatically numbered heading.
 
-The @var{depth} argument instructs @file{ms} to number headings in the
-form @var{a.b.c@dots{}}, to any depth desired, with the numbering of
-each depth increasing automatically and being reset to zero when a more
-significant level is increased.  ``1''@tie{}is the most significant or
-coarsest division of the document.  Only nonzero values are output.
+@file{ms} produces a numbered heading the form @var{a.b.c@dots{}}, to
+any depth desired, with the numbering of each depth increasing
+automatically and being reset to zero when a more significant level is
+increased.  ``1''@tie{}is the most significant or coarsest division of
+the document.  Only nonzero values are output.  If the argument is
+omitted, @var{depth} is taken to be @samp{1}.
 
 If you specify @var{depth} such that an ascending gap occurs relative to
 the previous @code{NH} call---that is, you ``skip a depth'', as by
@@ -3323,11 +3325,10 @@ normally precedes each heading is omitted.
 @DefmpstrItemx {SN-DOT, ms}
 @DefmpstrItemx {SN-NO-DOT, ms}
 @DefmpstrListEndx {SN, ms}
-After invocation of @code{NH}, the assigned number is made available in
-the strings @code{SN-DOT} (as it appears in a printed heading with
-default formatting, followed by a terminating period) and
-@code{SN-NO-DOT} (with the terminating period omitted).  These are GNU
-extensions.
+After @code{NH} is called, the assigned number is made available in the
+strings @code{SN-DOT} (as it appears in a printed heading with default
+formatting, followed by a terminating period) and @code{SN-NO-DOT} (with
+the terminating period omitted).  These are GNU extensions.
 
 You can control the style used to print numbered headings by defining an
 appropriate alias for the string @code{SN-STYLE}.  By default,
@@ -3342,7 +3343,7 @@ define the alias as follows.
 @noindent
 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 section is available in the
+The formatted number of the current heading is available in the
 @code{SN} string (a feature first documented by Berkeley), facilitating
 its inclusion in @code{XS}/@code{XA}/@code{XE} table of contents
 entries.
@@ -3651,8 +3652,8 @@ money
 @node Indented regions in ms, ms keeps and displays, Lists in ms, ms Body Text
 @subsubsection Indented regions
 
-You may need to indent a region of text while still letting @code{groff}
-automatically break lines and fill the text.
+You may need to indent a region of text while otherwise formatting it
+normally.
 
 @Defmac {RS, , ms}
 Begin a region where headings, paragraphs, and displays are indented by
@@ -3886,7 +3887,7 @@ view it.
 
 When @code{refer} emits collected references (as might be done on a
 ``Works Cited'' page), it interpolates the @code{REFERENCES} string as
-an unnumbered section heading (@code{SH}).
+an unnumbered heading (@code{SH}).
 
 @menu
 * Example multi-page table::
@@ -4125,9 +4126,9 @@ margin.
 @cindex @code{ms} macros, multiple columns
 @cindex multiple columns [@code{ms}]
 
-The @file{ms} macros can set text in as many columns as reasonably fit
-on the page.  The following macros force a page break if a multi-column
-layout is active when they are called.
+@file{ms} can set text in as many columns as reasonably fit on the page.
+The following macros force a page break if a multi-column layout is
+active when they are called.
 
 @Defmac {1C, , ms}
 Arrange page text in a single column (the default).
@@ -4466,13 +4467,13 @@ put the date, in U.S.@: traditional format (e.g., 
``January 1, 2021''),
 in the center footer (the @code{CF} string).
 
 @item
-Macros that cause @code{groff} @file{ms} to internally reset its
-paragraph rendering parameters (paragraphs, headings, and displays,
-among others) may change the indentation; they do so not by incrementing
-or decrementing it, but by setting it absolutely.  This can cause
-problems for documents that define additional macros of their own that
-try to manipulate indentation.  The solution is to use, not the
-@code{in} request, but the @file{ms} @code{RS} and @code{RE} macros.
+Many @code{groff} @file{ms} macros, including those for paragraphs,
+headings, and displays, cause a reset of paragraph rendering parameters,
+and may change the indentation; they do so not by incrementing or
+decrementing it, but by setting it absolutely.  This can cause problems
+for documents that define additional macros of their own that try to
+manipulate indentation.  The solution is to use, not the @code{in}
+request, but the @file{ms} @code{RS} and @code{RE} macros.
 
 @item
 To make @code{groff} @file{ms} use the default page offset (which also
diff --git a/doc/ms.ms b/doc/ms.ms
index 7f9bb23c..b93a3ec4 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -49,7 +49,7 @@ and books.
 These
 .I groff
 macros feature cover page and table of contents generation,
-automatic section numbering,
+automatically numbered headings,
 several different paragraph styles,
 a variety of text styling options,
 footnotes,
@@ -191,7 +191,7 @@ document
 The
 .I ms
 macro package expects a certain amount of structure:
-a well-formed document contains at least one paragraphing or sectioning
+a well-formed document contains at least one paragraphing or heading
 macro call.
 .
 To compose a document from scratch,
@@ -925,14 +925,11 @@ cb cb
 lf(CR) lx .
 Macro  Description
 _
-\&.NH \f[I]depth\f[]   T{
+\&.NH [\f[I]depth\f[]] T{
 Set an automatically numbered heading.
 .
-The
-.I depth
-argument instructs
 .I ms
-to number headings in the form
+produces a numbered heading in the form
 .CW
 .I a .\c
 .I b .\c
@@ -947,6 +944,11 @@ document.
 .
 Only nonzero values are output.
 .
+If the argument is omitted,
+.I depth
+is taken to be
+.CW 1 .
+.
 If you specify
 .I depth
 such that an ascending gap occurs relative to the previous
@@ -1023,8 +1025,9 @@ T}
 .
 .
 .PP
-After invocation of
-.CW .NH ,
+After
+.CW .NH
+is called,
 the assigned number is made available in the strings
 .CW SN\-DOT
 (as it appears in a printed heading with default formatting,
@@ -1065,7 +1068,7 @@ of
 following redefinition of the alias for
 .CW \[rs]*[SN\-STYLE] .
 .
-The formatted number of the current section is available in
+The formatted number of the current heading is available in
 .CW \[rs]*[SN]
 (a feature first documented by Berkeley),
 facilitating its inclusion in
@@ -1704,9 +1707,8 @@ Indented regions
 .
 .
 .LP
-You may need to indent a region of text while still letting
-.I groff
-automatically break lines and fill the text.
+You may need to indent a region of text while otherwise formatting it
+normally.
 .
 .
 .TS
@@ -2737,7 +2739,7 @@ Margins
 .LP
 Control margins using registers.
 .
-These are summarized in the \[lq]Margins\[rq] section of the table in
+These are summarized in the \[lq]Margins\[rq] portion of the table in
 section \[lq]Document control settings\[rq] above.
 .
 There is no explicit right margin setting;
@@ -2758,10 +2760,8 @@ Multiple columns
 .
 .
 .LP
-The
 .I ms
-macros can set text in as many columns as will reasonably fit on the
-page.
+can set text in as many columns as reasonably fit on the page.
 .
 The following macros force a page break if a multi-column layout is
 active when they are called.
@@ -3088,7 +3088,7 @@ they cannot be used with AT&T
 .I troff .
 .
 .I "groff ms"
-supports several features described above as Berkeley and Version 10
+supports several features described above as Berkeley and Tenth Edition
 Research Unix extensions,
 and adds several of its own.
 .
@@ -3147,14 +3147,14 @@ string).
 .
 .
 .PP
-Macros that cause
+Many
 .I "groff ms"
-to internally reset its paragraph rendering parameters
-(paragraphs,
+macros,
+including those for paragraphs,
 headings,
 and displays,
-among others)
-may change the indentation;
+cause a reset of paragraph rendering parameters,
+and may change the indentation;
 they do so not by incrementing or decrementing it,
 but by setting it absolutely.
 .
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index d4c89644..c13b8b26 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -68,7 +68,7 @@ and books.
 These
 .I groff
 macros support cover page and table of contents generation,
-automatic section numbering,
+automatically numbered headings,
 several different paragraph styles,
 a variety of text styling options,
 footnotes,
@@ -105,7 +105,7 @@ and Tenth Edition Research Unix have been recreated.
 The
 .I ms
 macro package expects a certain amount of structure:
-a well-formed document contains at least one paragraphing or sectioning
+a well-formed document contains at least one paragraphing or heading
 macro call.
 .
 To compose a document from scratch,
@@ -618,7 +618,7 @@ it is set to
 .
 Setting
 .B \[rs]*[FAM]
-before the first call of a sectioning,
+before the first call of a heading,
 paragraphing,
 or (non-date) document description macro also applies it to headers,
 footers,
@@ -766,14 +766,12 @@ rendered on the same output line in the same style.
 .
 .
 .TP
-.BI .NH\~ depth
+.B .NH\c
+.RI \~[ depth ]
 Set an automatically numbered heading.
 .
-The
-.I depth
-argument instructs
 .I ms
-to number heading in the form
+produces a numbered heading in the form
 .IR a . b . c .\|.\|.,
 to any level desired,
 with the numbering of each depth increasing automatically and being
@@ -784,6 +782,11 @@ the most significant or coarsest division of the document.
 .
 Only nonzero values are output.
 .
+If the argument is omitted,
+.I depth
+is taken to be
+.BR 1 .
+.
 If you specify
 .I depth
 such that an ascending gap occurs relative to the previous
@@ -817,8 +820,9 @@ This feature is a Berkeley extension.
 .
 .
 .P
-After invocation of
-.BR .NH ,
+After
+.B .NH
+is called,
 the assigned number is made available in the strings
 .B SN\-DOT
 (as it appears in a printed heading with default formatting,
@@ -851,7 +855,7 @@ of
 following redefinition of the alias for
 .BR \[rs]*[SN\-STYLE] .
 .
-The formatted number of the current section is available in
+The formatted number of the current heading is available in
 .B \[rs]*[SN]
 (a feature first documented by Berkeley),
 facilitating its inclusion in
@@ -1125,9 +1129,8 @@ respectively.
 .SS "Indented regions"
 .\" ====================================================================
 .
-You may need to indent a region of text while still letting
-.I groff
-automatically break lines and fill the text.
+You may need to indent a region of text while otherwise formatting it
+normally.
 .
 .
 .TP
@@ -1832,10 +1835,8 @@ provides the information necessary to derive the right 
margin.
 .SS "Multiple columns"
 .\" ====================================================================
 .
-The
 .I ms
-macros can set text in as many columns as will reasonably fit on the
-page.
+can set text in as many columns as reasonably fit on the page.
 .
 The following macros force a page break if a multi-column layout is
 active when they are called.
@@ -2103,7 +2104,7 @@ argument,
 the
 .I text
 arguments are augmented,
-by prefixing the current section number,
+by prefixing the current heading number,
 (which is also deduced from the last preceding use of
 .BR .NH ).
 .
@@ -2275,14 +2276,14 @@ string).
 .
 .
 .IP \[bu]
-Macros that cause
+Many
 .I groff ms
-to internally reset its paragraph rendering parameters
-(paragraphs,
+macros,
+including those for paragraphs,
 headings,
 and displays,
-among others)
-may change the indentation;
+cause a reset of paragraph rendering parameters,
+and may change the indentation;
 they do so not by incrementing or decrementing it,
 but by setting it absolutely.
 .