[groff] 30/45: [ms]: Recast presentation of heading feature.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 365c3950257a3e67b110130ce0300a42f7b20b87
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jan 18 16:38:24 2022 +1100

    [ms]: Recast presentation of heading feature.
    
    * Borrow terminology from the me(7) reference manual: use "depth" to
      characterize the levels of (section) headings.  However, drop the
      terms "section" and "sectioning" in reference to these heading macros;
      whether the subdivisions of the document are "sections" in the
      author's mind is not important, and we can get by without imposing
      this term[1].  Since "depth" implies a direction that "level" doesn't,
      simplify some of our discussion of the `PSINCR` and `GROWPS`
      registers.
    * Try again to clearly explain the error case of skipping a heading
      level.
    * Use complete sentences to introduce `NH` and `SH` macros.
    * Improve terminological discipline by using "type size" instead of
      "point size".  Yes, some register names are unfortunate.
    * Reduce use of passive voice.
    
    Also:
    
    * doc/groff.texi: Add some text about the `XA` macro that went missing
      in a previous sync with doc/ms.ms.
    * doc/ms.ms: Bump document date.  Add keep at beginning of "Headings"
      section.
    * tmac/groff_ms.7.man: Replace some `PP` calls with `P`.
    
    [1] Lesk, in Appendix A of the 1978 revision of "Typing Documents on the
        Unix System", defines "NH" and "SH" as specifying "numbered heading"
        and "section heading", respectively.  Does this imply that numbered
        headings _aren't_ also section headings?  I think it is better just
        to kick the term "section" away from descriptions of package
        features since we don't need it.  (It remains useful for application
        examples.)
---
 doc/groff.texi      |  86 +++++++++++++++++++++--------------------
 doc/ms.ms           | 109 ++++++++++++++++++++++++++--------------------------
 tmac/groff_ms.7.man |  99 +++++++++++++++++++++++------------------------
 3 files changed, 146 insertions(+), 148 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 157ce677..b465057a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2837,12 +2837,12 @@ Default: 1.
 @unnumberedsubsubsec Heading Settings
 
 @Defmpreg {PSINCR, ms}
-Defines an increment in point size to be applied to a headings at a
-level more significant (numerically less) than the value specified in
-@code{GROWPS}.  The value of @code{PSINCR} should be specified in points
-with the @dmn{p} scaling indicator and may include a fractional
-component; for example, @w{@samp{.nr PSINCR 1.5p}} sets a point size
-increment of 1.5@dmn{p}.  This is a GNU extension.
+Defines an increment in type size to be applied to a heading at a
+lesser depth than that specified in @code{GROWPS}.  The value of
+@code{PSINCR} should be specified in points with the @dmn{p} scaling
+indicator and may include a fractional component; for example,
+@w{@samp{.nr PSINCR 1.5p}} sets a type size increment of 1.5@dmn{p}.
+This is a GNU extension.
 
 Effective: next heading.
 
@@ -2850,11 +2850,11 @@ Default: 1@dmn{p}.
 @endDefmpreg
 
 @Defmpreg {GROWPS, ms}
-Defines the heading level at which the point size increment set by
-@code{PSINCR} becomes effective.  For each level below the value of
-@code{GROWPS}, the point size is increased by @code{PSINCR}.  Setting
-@code{GROWPS} to any value less than@tie{}2 disables the incremental
-heading size feature.  This is a GNU extension.
+Defines the heading depth at which the type size increment set by
+@code{PSINCR} becomes effective.  For each heading depth less than the
+value of @code{GROWPS}, the type size is increased by @code{PSINCR}.
+Setting @code{GROWPS} to any value less than@tie{}2 disables the
+incremental heading size feature.  This is a GNU extension.
 
 Effective: next heading.
 
@@ -3145,7 +3145,7 @@ footnotes, and inclusions of material such as tables and 
figures.
 
 The @code{FAM} string sets the font family for body text.  If this
 string is undefined at initialization, it is set to @samp{T} (Times).
-Setting the @code{FAM} string before the first call of a sectioning,
+Setting the @code{FAM} string before the first call of a heading,
 paragraphing, or (non-date) document description macro also applies it
 to headers, footers, and footnotes.
 
@@ -3258,29 +3258,30 @@ software.
 
 Use headings to create a sequential or hierarchical structure for your
 document.  The @file{ms} macros print headings in @strong{bold} using
-the same font family and, by default, point size as the body text.
+the same font family and, by default, type size as the body text.
 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{level}, ms}
-@DefmacListEnd {NH, @t{S} @Var{heading-level-index} @dots{}, ms}
-Automatically numbered heading.
+@DefmacList {NH, @Var{depth}, ms}
+@DefmacListEnd {NH, @t{S} @Var{heading-depth-index} @dots{}, ms}
+Set an automatically numbered heading.
 
-The @var{level} argument instructs @file{ms} to number headings in the
+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 level increasing automatically and being reset to zero when a more
+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 you specify heading levels with a gap in an ascending sequence, such
-as by calling @samp{.NH 1} and then @samp{.NH 1} as the next such call,
-@code{groff} @file{ms} emits a warning on the standard error stream.
+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
+@samp{.NH 1} and then @samp{.NH 3}---@code{groff} @file{ms} emits a
+warning on the standard error stream.
 
-Alternatively, a first argument of@tie{}@code{S} can be given, followed
-by integral arguments to number the levels of the heading explicitly.
-Further automatic numbering, if used, resumes using the specified
-heading level indices as their predecessors.
+Alternatively, you can give @code{NH} a first argument of@tie{}@code{S},
+followed by integers arguments to number the the heading depths
+explicitly.  Further automatic numbering, if used, resumes using the
+specified indices as their predecessors.
 @c Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
 This feature is a Berkeley extension.
 @endDefmac
@@ -3343,15 +3344,14 @@ its inclusion in @code{XS}/@code{XA}/@code{XE} table of 
contents
 entries.
 @endDefmpstr
 
-@Defmac {SH, [@Var{match-level}], ms}
-Unnumbered heading.
+@Defmac {SH, [@Var{depth}], ms}
+Set an unnumbered heading.
 
-The optional @var{match-level} argument is a GNU extension.  It is a
-number indicating the level of the heading corresponding to the
-@var{level} argument to @code{NH}.  Its purpose is to match the point
-size at which the heading is printed to the size of a numbered heading
-at the same level when the @code{GROWPS} and @code{PSINCR} heading size
-adjustment mechanism is in effect.
+The optional @var{depth} argument is a GNU extension indicating the
+heading depth corresponding to the @var{depth} argument of @code{NH}.
+It matches the type size at which the heading is set to that of a
+numbered heading at the same depth when the @code{GROWPS} and
+@code{PSINCR} heading size adjustment mechanism is in effect.
 @endDefmac
 
 If the @code{GROWPS} register is set to a value greater than the
@@ -4065,7 +4065,7 @@ By default, @file{ms} prints no header on any page 
numbered ``1''
 Print the header on page@tie{}1.  To be effective, this macro must be
 called before the header trap is sprung on any page numbered ``1''; in
 practice, unless your page numbering is unusual, this means that you
-should call it early, before @code{TL} or any sectioning or paragraphing
+should call it early, before @code{TL} or any heading or paragraphing
 macro.  This is a Berkeley extension.
 @endDefmac
 
@@ -4156,14 +4156,16 @@ document, depending on the output format and 
circumstances.
 
 Define an entry to appear in the table of contents by bracketing its
 text between calls to the @code{XS} and @code{XE} macros.  A typical
-application is to call them immediately after @code{NH} or @code{SH}
-pairs, supplements an entry---for instance, when it requires multiple
-output lines, whether because a heading is too long to fit or because
-style dictates that page numbers not be repeated.  In a document with a
-multi-level sectioning structure, you may wish to indent the text thus
-wrapped to correspond to its sectioning depth; this can be done in the
-entry text by prefixing it with tabs or horizontally spacing escape
-sequences, or by providing a second argument to the @code{XA} macro.
+application is to call them immediately after @code{NH} or @code{SH} and
+repeat the heading text within them.  The @code{XA} macro, used within
+@samp{.XS}/@samp{.XE} pairs, supplements an entry---for instance, when
+it requires multiple output lines, whether because a heading is too long
+to fit or because style dictates that page numbers not be repeated.  You
+may wish to indent the text thus wrapped to correspond to its heading
+depth; this can be done in the entry text by prefixing it with tabs or
+horizontally spacing escape sequences, or by providing a second argument
+to the @code{XA} macro.
+
 @code{XS} and @code{XA} automatically associate the page number where
 they are called with the text following them, but they accept arguments
 to override this behavior.  At the end of the document, call @code{TC}
diff --git a/doc/ms.ms b/doc/ms.ms
index fe218b85..5df1a9a3 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -4,7 +4,7 @@
 .  ftr CB B
 .  ftr CI I
 .  ftr CBI BI
-.  \" Redefine CW so to use bold instead for a visible font change.
+.  \" Redefine CW to use bold instead for a visible font change.
 .  als CW B
 .\}
 .\" This document doesn't require the minus sign but we do want a copy-
@@ -22,8 +22,8 @@
 .nr TC-MARGIN \w'00' \" expect 2-digit page numbers at most
 .ie t .nr PI 3.5n
 .el   .nr PI 4n
-.ND October 2021
-.EH '%''October 2021'
+.ND January 2022
+.EH '%''January 2022'
 .EF ''''
 .OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
 .OF ''''
@@ -346,7 +346,7 @@ Paragraphs  \[rs]n[PI]      Indentation     next paragraph  
5n
 \^     \[rs]n[PORPHANS]        # of initial lines kept next paragraph  1
 _
 Headings       \[rs]n[PSINCR]  Point size increment    next heading    1p
-\^     \[rs]n[GROWPS]  Size increase level limit       next heading    0
+\^     \[rs]n[GROWPS]  Size increase depth limit       next heading    0
 \^     \[rs]n[HORPHANS]        # of following lines kept       next heading    
1
 \^     \[rs]*[SN\-STYLE]       Numbering style (alias) next heading    
\[rs]*[SN\-DOT]
 _
@@ -690,7 +690,7 @@ it is set to
 .
 Setting
 .CW \[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,
@@ -873,6 +873,7 @@ T}
 .KE
 .
 .
+.KS
 .NH 2
 Headings
 .XS
@@ -889,7 +890,7 @@ macros print headings in
 .B bold
 using the same font family and,
 by default,
-point size as the body text.
+type size as the body text.
 .
 Headings are available with and without automatic numbering.
 .
@@ -904,11 +905,11 @@ cb cb
 lf(CR) lx .
 Macro  Description
 _
-\&.NH \f[I]level\f[]   T{
-Automatically numbered heading.
+\&.NH \f[I]depth\f[]   T{
+Set an automatically numbered heading.
 .
 The
-.I level
+.I depth
 argument instructs
 .I ms
 to number headings in the form
@@ -917,40 +918,45 @@ to number headings in the form
 .I b .\c
 .R
 .I c .\|.\|.,
-to any depth desired,
-with the numbering of each level increasing automatically and being
-reset to zero when a more significant level is increased.
+to any level desired,
+with the numbering of each depth increasing automatically and being
+reset to zero when a more significant depth increases.
 .
 \[lq]1\[rq]\~is the most significant or coarsest division of the
 document.
 .
 Only nonzero values are output.
 .
-If you specify heading levels with a gap in an ascending sequence,
-such as by
+If you specify
+.I depth
+such that an ascending gap occurs relative to the previous
+.CW NH
+call\[em]that is,
+you \[lq]skip a depth\[rq],
+as by
 .CW ".NH\~1" \[rq] \[lq]
 and then
-.CW ".NH\~3" \[rq] \[lq]
-as the next such call,
-.I "groff ms"
+.CW ".NH\~3" \[rq]\c \[lq]
+.I "groff ms" "" \[em]
 emits a warning on the standard error stream.
 T}
-\&.NH S \f[I]heading-level-index\f[]\f[R] .\|.\|.\f[]  T{
+\&.NH S \f[I]heading-depth-index\f[]\f[R] .\|.\|.\f[]  T{
 Alternatively,
+you can give
+.CW NH
 a first argument
-.CW S "" of\~
-can be given,
-followed by integral arguments to number the levels of the heading
-explicitly.
+.CW S , of\~
+followed by integers to number the heading depths explicitly.
 .
 Further automatic numbering,
 if used,
-resumes using the specified heading level indices as their predecessors.
+resumes using the specified indices as their predecessors.
 .
 .\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
 This feature is a Berkeley extension.
 T}
 .TE
+.KE
 .
 .
 .PP
@@ -1055,19 +1061,19 @@ cb cb
 lf(CR) lx .
 Macro  Description
 _
-\&.SH [\f[I]level\f[]] T{
-Unnumbered heading.
+\&.SH [\f[I]depth\f[]] T{
+Set an unnumbered heading.
 .
 The optional
-.I level
-argument is a GNU extension indicating the heading level corresponding
+.I depth
+argument is a GNU extension indicating the heading depth corresponding
 to the
-.I level
+.I depth
 argument of
 .CW .NH .
 .
-It matches the point size at which the heading is printed to that of a
-numbered heading at the same level when the
+It matches the type size at which the heading is set to that of a
+numbered heading at the same depth when the
 .CW \[rs]n[GROWPS]
 and
 .CW \[rs]n[PSINCR]
@@ -1079,12 +1085,8 @@ T}
 .PP
 The
 .CW PSINCR
-register defines an increment in point size to be applied to a heading
-at a
-.I level
-more significant
-(numerically less)
-than the value specified in
+register defines an increment in type size to be applied to a heading at
+a lesser depth than that specified in
 .CW \[rs]n[GROWPS] .
 .
 The value of
@@ -1103,22 +1105,20 @@ lf(CR).
 .
 .
 .LP
-sets a point size increment of 1.5 points.
+sets a type size increment of 1.5 points.
 .
 .
 .PP
 The
 .CW GROWPS
-register defines the heading level at which the point size increment set
-by
+register defines the heading depth above which the type size increment
+set by
 .CW \[rs]n[PSINCR]
 becomes effective.
 .
-For each heading
-.I level
-below the value of
+For each heading depth less than the value of
 .CW \[rs]n[GROWPS] ,
-the point size is increased by
+the type size is increased by
 .CW \[rs]n[PSINCR] .
 .
 Setting
@@ -1128,23 +1128,23 @@ to a value less than\~2 disables the incremental 
heading size feature.
 .
 .PP
 In other words,
-if the
+if the value of
 .CW GROWPS
 register is greater than the
-.I level
+.I depth
 argument to a
 .CW .NH
 or
 .CW .SH
 call,
-the point size of a heading produced by these macros increases by
+the type size of a heading produced by these macros increases by
 .CW \[rs]n[PSINCR]
 units over
 .CW \[rs]n[PS]
 multiplied by the difference of
 .CW \[rs]n[GROWPS]
 and
-.I level .
+.I depth .
 .
 .
 For example,
@@ -1170,13 +1170,13 @@ Machairodontinae
 .LP
 will cause \[lq]1. Carnivora\[rq] to be printed in 13-point text,
 followed by \[lq]1.1. Felinae\[rq] in 11.5-point text,
-while \[lq]1.1.1. Felis catus\[rq] and all more deeply nested
-heading levels will remain in the 10-point text specified by the
+while \[lq]1.1.1. Felis catus\[rq] and all more deeply nested headings
+will remain in the 10-point text specified by the
 .CW PS
 register.
 .
 \[lq]Machairodontinae\[rq] is printed at 11.5 points,
-since it corresponds to heading level\~2.
+since it corresponds to heading depth\~2.
 .
 .
 .PP
@@ -2097,7 +2097,7 @@ emits collected references
 (as might be done on a \[lq]Works Cited\[rq] page),
 it interpolates the string
 .CW \[rs]*[REFERENCES]
-as an unnumbered section heading
+as an unnumbered heading
 .CW .SH ). (
 .
 .
@@ -2589,7 +2589,7 @@ unless your page numbering is unusual,
 this means that you should call it early,
 before
 .CW .TL
-or any sectioning or paragraphing macro.
+or any heading or paragraphing macro.
 .
 This is a Berkeley extension.
 T}
@@ -2809,9 +2809,8 @@ when it requires multiple output lines,
 whether because a heading is too long to fit or because style dictates
 that page numbers not be repeated.
 .
-In a document with a multi-level sectioning structure,
-you may wish to indent the text thus wrapped to correspond to its
-sectioning depth;
+You may wish to indent the text thus wrapped to correspond to its
+heading depth;
 this can be done in the entry text by prefixing it with tabs or
 horizontally spacing escape sequences,
 or by providing a second argument to the
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 6f7671ef..a9e0c246 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -262,7 +262,7 @@ Heading settings
 Parameter      Definition      Effective       Default
 _
 \[rs]n[PSINCR] Point size increment    next heading    1p
-\[rs]n[GROWPS] Size increase level limit       next heading    0
+\[rs]n[GROWPS] Size increase depth limit       next heading    0
 \[rs]n[HORPHANS]       # of following lines kept       next heading    1
 \[rs]*[SN\-STYLE]      Numbering style (alias) next heading    \[rs]*[SN\-DOT]
 _
@@ -708,7 +708,7 @@ macros print headings in
 .B bold
 using the same font family and,
 by default,
-point size as the body text.
+type size as the body text.
 .
 Headings are available with and without automatic numbering.
 .
@@ -718,53 +718,57 @@ rendered on the same output line in the same style.
 .
 .
 .TP
-.BI .NH\~ level
-Automatically numbered heading.
+.BI .NH\~ depth
+Set an automatically numbered heading.
 .
 The
-.I level
+.I depth
 argument instructs
 .I ms
 to number heading in the form
 .IR a . b . c .\|.\|.,
-to any depth desired,
-with the numbering of each level increasing automatically and being
-reset to zero when a more significant level is increased.
+to any level desired,
+with the numbering of each depth increasing automatically and being
+reset to zero when a more significant depth is increased.
 .
 .RB \[lq] 1 \[rq]\~is
 the most significant or coarsest division of the document.
 .
 Only nonzero values are output.
 .
-If you specify heading levels with a gap in an ascending sequence,
-such as by
+If you specify
+.I depth
+such that an ascending gap occurs relative to the previous
+.B NH
+call\[em]that is,
+you \[lq]skip a depth\[rq],
+as by
 .RB \[lq] ".NH\~1" \[rq]
 and then
-.RB \[lq] ".NH\~3" \[rq]
-as the next such call,
+.RB \[lq] ".NH\~3" \[rq],
 .I groff ms
 emits a warning on the standard error stream.
 .
 .
 .TP
-.BI ".NH S\~" heading-level-index\~\c
+.BI ".NH S\~" heading-depth-index\~\c
 \&.\|.\|.
 Alternatively,
+you can give
+.B NH
 a first argument
-.RB of\~\[lq] S \[rq]
-can be given,
-followed by integral arguments to number the levels of the heading
-explicitly.
+.RB of\~\[lq] S \[rq],
++followed by integers to number the heading depths explicitly.
 .
 Further automatic numbering,
 if used,
-resumes using the specified heading level indices as their predecessors.
+resumes using the specified indices as their predecessors.
 .
 .\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
 This feature is a Berkeley extension.
 .
 .
-.PP
+.P
 After invocation of
 .BR .NH ,
 the assigned number is made available in the strings
@@ -778,7 +782,7 @@ and
 These are GNU extensions.
 .
 .
-.PP
+.P
 You can control the style used to print numbered headings by defining an
 appropriate alias for the string
 .BR SN\-STYLE .
@@ -809,34 +813,30 @@ table of contents entries.
 .
 .TP
 .B .SH\c
-.RI " [" level ]
-Unnumbered heading.
+.RI \~[ depth ]
++Set an unnumbered heading.
 .
 The optional
-.I level
-argument is a GNU extension indicating the heading level corresponding
+.I depth
+argument is a GNU extension indicating the heading depth corresponding
 to the
-.I level
+.I depth
 argument of
 .BR .NH .
 .
-It matches the point size at which the heading is printed to that of a
-numbered heading at the same level when the
+It matches the type size at which the heading is set to that of a
+numbered heading at the same depth when the
 .B \[rs]n[GROWPS]
 and
 .B \[rs]n[PSINCR]
 heading size adjustment mechanism is in effect.
 .
 .
-.PP
+.P
 The
 .B PSINCR
-register defines an increment in point size to be applied to a heading
-at a
-.I level
-more significant
-(numerically less)
-than the value specified in
+register defines an increment in type size to be applied to a heading at
+a lesser depth than that specified in
 .BR \[rs]n[GROWPS] .
 .
 The value of
@@ -846,19 +846,17 @@ should be specified in points with the
 scaling indicator and may include a fractional component.
 .
 .
-.PP
+.P
 The
 .B GROWPS
-register defines the heading level at which the point size increment set
-by
+register defines the heading depth above which the type size increment
+set by
 .B \[rs]n[PSINCR]
 becomes effective.
 .
-For each heading
-.I level
-below the value of
++For each heading depth less than the value of
 .BR \[rs]n[GROWPS] ,
-the point size is increased by
+the type size is increased by
 .BR \[rs]n[PSINCR] .
 .
 Setting
@@ -866,28 +864,28 @@ Setting
 to a value less than\~2 disables the incremental heading size feature.
 .
 .
-.PP
+.P
 In other words,
-if the
+if the value of
 .B GROWPS
 register is greater than the
-.I level
+.I depth
 argument to a
 .B .NH
 or
 .B .SH
 call,
-the point size of a heading produced by these macros increases by
+the type size of a heading produced by these macros increases by
 .B \[rs]n[PSINCR]
 units over
 .B \[rs]n[PS]
 multiplied by the difference of
 .B \[rs]n[GROWPS]
 and
-.IR level .
+.IR depth .
 .
 .
-.PP
+.P
 The
 .B \[rs]n[HORPHANS]
 register operates in conjunction with the
@@ -1397,7 +1395,7 @@ emits collected references
 (as might be done on a \[lq]Works Cited\[rq] page),
 it interpolates the string
 .B \[rs]*[REFERENCES]
-as an unnumbered section heading
+as an unnumbered heading
 .RB ( .SH ).
 .
 .
@@ -1848,9 +1846,8 @@ when it requires multiple output lines,
 whether because a heading is too long to fit or because style dictates
 that page numbers not be repeated.
 .
-In a document with a multi-level sectioning structure,
-you may wish to indent the text thus wrapped to correspond to its
-sectioning depth;
+You may wish to indent the text thus wrapped to correspond to its
+heading depth;
 this can be done in the entry text by prefixing it with tabs or
 horizontally spacing escape sequences,
 or by providing a second argument to the