[groff] 06/06: [ms]: Rework section heading documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 222be9c3add460d2c089563bdb950082b5b380e1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Feb 14 17:59:25 2021 +1100

    [ms]: Rework section heading documentation.
    
    * doc/groff.texi
      (Document Control Settings): Add SN-STYLE string.
      (Headings in ms):
      - Expand introduction.  Qualify point size as being configurable.
        Summarize available macros.  Describe where section heading text
        occurs in input and how it is formatted on output.
      - <NH> Rename metasyntactic variable from "curr-level" to "level".
        Provide model for section numbering format.  Describe meaning of
        parameter.  Say "with a gap in an ascending sequence" instead of
        "out of order", which was too general.  Explain how ".NH S ..."
        affects subsequent automatic numbering.  Add example.
      - <SN-STYLE> Repair sentence fragment (see commit 3afcaf0e).
      - <SH> Recast description to say precisely what it does instead of "in
        a manner analogous" to .SH.  Remove ungrammatical commas.  Recast
        explanation of PSINCR/GROWPS mechanism.  Supply new example.
      - <HORPHANS> Elaborate description.  Clarify that display (and tbl,
        eqn, pic region) macros suppress its effect.
    
    * doc/ms.ms
      (Document control settings): Add SN-STYLE string.
      (Headings):
      - Resync revised language with our Texinfo manual (above).
      (generally):
      - Use two empty requests where vertical space is expected.
      - Refer to macro package as "ms" instead of "-ms".
    
    * tmac/groff_ms.7.man
      (Document control settings): Add SN-STYLE string.  Add note of
      alternative alias setting.
      (Usage/Paragraphs):
      - Move paragraph describing HORPHANS register from here...
      (Usage/Headings):
      - ...hither.
      - Resync revised language with our Texinfo manual (above), omitting
        examples.
---
 doc/groff.texi      | 145 ++++++++++++++++++------
 doc/ms.ms           | 276 +++++++++++++++++++++++++++++++++++++++++-----
 tmac/groff_ms.7.man | 309 +++++++++++++++++++++-------------------------------
 3 files changed, 482 insertions(+), 248 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 09d6a0e..fc4e0d9 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2792,19 +2792,28 @@ Default: 0.
 @endDefmpreg
 
 @Defmpreg {HORPHANS, ms}
-Defines the minimum number of lines of the following paragraph that
-should be kept together with any section heading introduced by the
-@code{NH} or @code{SH} macros.  If a section heading is placed close to
-the bottom of a page, and there is insufficient space to accommodate
-both the heading and at least @code{HORPHANS} lines of the following
-paragraph, before an automatic page break, then the page break is forced
-before the heading.
+Defines the minimum number of lines of an immediately succeeding
+paragraph that should be kept together with any section heading
+introduced by the @code{NH} or @code{SH} macros.  If a section heading
+is placed close to the bottom of a page, and there is insufficient space
+to accommodate both the heading and at least @code{HORPHANS} lines of
+the following paragraph, before an automatic page break, then the page
+break is forced before the heading.
 
 Effective: next paragraph.
 
 Default: 1.
 @endDefmpreg
 
+@Defstr {SN-STYLE, ms}
+Defines the style used to print section numbers within numbered section
+headings.  @xref{Headings in ms}.
+
+Effective: next section heading.
+
+Default: alias of @code{SN-DOT}
+@endDefstr
+
 @unnumberedsubsubsec Footnote Settings
 
 @Defmpreg {FI, ms}
@@ -3129,21 +3138,55 @@ printing of orphan lines at the bottom of any page.
 @cindex @code{ms} macros, headings
 
 Use headings to create a hierarchical structure for your document.  The
-@file{ms} macros print headings in @strong{bold}, using the same font
-family and point size as the body text.
-
-The following describes the heading macros:
+@file{ms} macros print headings in @strong{bold} using the same font
+family and, by default, point size as the body text.  Numbered and
+unnumbered section headings are available.  Text lines after heading
+macros 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{section-level-index} @dots{}, ms}
+Numbered heading.
+
+The @var{level} argument instructs @file{ms} to number sections in the
+form @var{x.y.z}, to any depth desired, with the numbering of each level
+increasing automatically and being reset 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 invoking @samp{.NH 3} after @samp{.NH 1}, @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 section numbering, if used, resumes using the
+specified section numbers as their predecessors.
+@endDefmac
 
-@DefmacList {NH, @Var{curr-level}, ms}
-@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
-Numbered heading.  The argument is either a numeric argument to indicate
-the level of the heading, or the letter@tie{}@code{S} followed by
-numeric arguments to set the heading level explicitly.
+An example may be illustrative.  The blank line after each section
+heading is omitted from the output shown.
 
-If you specify heading levels out of sequence, such as invoking
-@samp{.NH 3} after @samp{.NH 1}, @code{groff} @file{ms} prints a warning
-on the standard error stream.
-@endDefmac
+@Example
+.NH 1
+Animalia
+.NH 2
+Arthropoda
+.NH 3
+Crustacea
+.NH 2
+Chordata
+.NH S 6 6 6
+Daimonia
+.NH 1
+Plantae
+    @result{} 1.  Animalia
+    @result{} 1.1.  Arthropoda
+    @result{} 1.1.1.  Crustacea
+    @result{} 1.2.  Chordata
+    @result{} 6.6.6.  Daimonia
+    @result{} 7.  Plantae
+@endExample
 
 @DefstrList {SN-STYLE, ms}
 @DefstrItemx {SN-DOT, ms}
@@ -3153,13 +3196,12 @@ available in the strings @code{SN-DOT} (as it appears 
in a printed
 section heading with default formatting, followed by a terminating
 period), and @code{SN-NO-DOT} (with the terminating period omitted).
 
-You may control the style used to print section numbers within numbered
+You can control the style used to print section numbers within numbered
 section headings by defining an appropriate alias for the string
 @code{SN-STYLE}.  By default, @code{SN-STYLE} is aliased to
-@code{SN-DOT}.
-
-If you prefer to omit the terminating period, from section numbers
-appearing in numbered section headings, you may define the alias
+@code{SN-DOT}.  If you prefer to omit the terminating period from
+section numbers appearing in numbered section headings, you may define
+the alias as follows.
 
 @Example
 .als SN-STYLE SN-NO-DOT
@@ -3175,18 +3217,53 @@ next use of @code{NH}, following redefinition of the 
alias for
 Unnumbered subheading.
 
 The optional @var{match-level} argument is a GNU extension.  It is a
-number indicating the level of the heading, in a manner analogous to the
-@var{curr-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.  @xref{ms Document
-Control Settings}.
+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.  @xref{ms Document Control Settings}.
 @endDefmac
 
+If the @code{GROWPS} register is set to a value greater than the
+@var{level} argument to @code{NH} or @code{SH}, the point size of
+the a heading produced by these macros increases by @code{PSINCR} units
+over the size specified by @code{PS}, multiplied by the difference
+between @var{level} and @code{GROWPS}.  The value stored in
+@code{PSINCR} is interpreted in @code{groff} basic units; the @code{p}
+scaling factor should be employed when assigning a value specified in
+points.  For example, the sequence
+
+@Example
+.nr PS 10
+.nr GROWPS 3
+.nr PSINCR 1.5p
+.NH 1
+Carnivora
+.NH 2
+Felinae
+.NH 3
+Felis catus
+.SH 2
+Machairodontinae
+@endExample
+
+@noindent
+will cause ``1. Carnivora'' to be printed in 13-point text, followed by
+``1.1. Felinae'' in 11.5-point text, while ``1.1.1. Felis catus'' and
+all more deeply nested heading levels will remain in the 10-point text
+specified by the @code{PS} register.  ``Machairodontinae'' is printed at
+11.5 points, since it corresponds to heading level\~2.
+
 The @code{HORPHANS} register (@pxref{ms Document Control Settings})
-operates in conjunction with the @code{NH} and @code{SH} macros, to
-inhibit the printing of orphaned section headings at the bottom of any
-page.
+operates in conjunction with the @code{NH} and @code{SH} macros to
+inhibit the printing of orphaned section headings at the bottom of a
+page; it specifies the minimum number of lines of an immediately
+subsequent paragraph that must be kept on the same page as the heading.
+
+If insufficient space remains on the current page to accommodate the
+heading and this number of lines of paragraph text, a page break is
+forced before the heading is printed.  Any display macro or
+@code{tbl}, @code{pic}, or @code{eqn} region suppresses this grouping.
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index ac35df0..0cc64da 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -327,6 +327,7 @@ headings
 T}     \[rs]n[PSINCR]  Point size increment    next heading    1p
 \^     \[rs]n[GROWPS]  Size increase level 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]
 _
 Footnotes      \[rs]n[FI]      Indentation     next footnote   2n
 \^     \[rs]n[FF]      Format  next footnote   0
@@ -632,57 +633,276 @@ RAM and disk space over time.
 .DE
 .B2
 .KE
+.
+.
 .NH 2
 Headings
 .XS
        Headings
 .XE
+.
+.
 .LP
-Use headings to create a hierarchical structure
-for your document.
+Use headings to create a hierarchical structure for your document.
+.
 The
-.I -ms
+.I ms
 macros print headings in
-.B bold ,
-using the same font family and point size as the body text.
-.KS
-.PP
-The following table describes the heading macros:
+.B bold
+using the same font family and,
+by default,
+point size as the body text.
+.
+Numbered and unnumbered section headings are available.
+.
+Text lines after heading macros are treated as part of the heading,
+rendered on the same output line in the same style.
+.
+.
 .TS
 box;
 cb cb
 afCR lx .
 Macro  Description
 _
-\&.NH \fIxx\fP T{
+\&.NH \f[I]level\f[]   T{
 Numbered heading.
 .
-The argument
-.I xx
-is either a numeric argument to indicate the
-level of the heading,
-or
-.I "S xx xx" "..."
-to set the heading level explicitly.
+The
+.I level
+argument instructs
+.I ms
+to number sections in the form
+.I x.y.z ,
+to any depth desired,
+with the numbering of each level increasing automatically and being
+reset when a more significant level is increased.
 .
-The section headings in this document use the
-.CW .NH
-macro to show the level of each section.
+.CW 1\~ is
+the most significant or coarsest division of the document.
 .
+Only nonzero values are output.
 .
-.sp \n[PD]u
-If you specify heading levels out of sequence,
-such as invoking
-.CW ".NH\ 3"
+If you specify heading levels with a gap in an ascending sequence,
+such as by invoking
+.CW ".NH\~3" \[rq] \[lq]
 after
-.CW ".NH\ 1" ,
-.I groff
-prints a warning on standard error.
+.CW ".NH\~1" \[rq], \[lq]
+.I "groff ms"
+emits a warning on the standard error stream.
+.
+.
+.sp \n[PD]u
+Alternatively,
+a first argument
+.CW S "" of\~
+can be given,
+followed by integral arguments to number the levels of the heading
+explicitly.
+.
+Further automatic section numbering,
+if used,
+resumes using the specified section numbers as their predecessors.
 T}
+.TE
+.
+.
+.PP
+An example may be illustrative.
+.
+.
+.TS
+box center;
+cb | cb
+lfCR | lB.
+Code   Output
 _
-\&.SH  Unnumbered subheading.
+T{
+.nf
+\&.NH 1
+Animalia
+\&.NH 2
+Arthropoda
+\&.NH 3
+Crustacea
+\&.NH 2
+Chordata
+\&.NH S 6 6 6
+Daimonia
+\&.NH 1
+Plantae
+.fi
+T}     T{
+.nf
+1.  Animalia
+.sp
+1.1.  Arthropoda
+.sp
+1.1.1.  Crustacea
+.sp
+1.2.  Chordata
+.sp
+6.6.6.  Daimonia
+.sp
+7.  Plantae
+.fi
+T}
 .TE
-.KE
+.
+.
+.PP
+After invocation of
+.CW .NH ,
+the assigned section number is made available in the strings
+.CW SN\-DOT
+(as it appears in a printed section heading with default formatting,
+followed by a terminating period)
+and
+.CW SN\-NO\-DOT
+(with the terminating period omitted).
+.
+.
+.PP
+You can control the style used to print section numbers within numbered
+section headings by defining an appropriate alias for the string
+.CW SN\-STYLE .
+.
+By default,
+.CW \[rs]*[SN\-STYLE]
+is aliased to
+.CW \[rs]*[SN\-DOT] .
+.
+If you prefer to omit the terminating period from section numbers
+appearing in numbered section headings,
+you may define the alias as follows.
+.
+.
+.TS
+box center;
+lfCR.
+\&.als SN\-STYLE SN\-NO\-DOT
+.TE
+.
+.
+.LP
+Any such change in section numbering style becomes effective from the
+next use of
+.CW .NH ,
+following redefinition of the alias for
+.CW \[rs]*[SN\-STYLE] .
+.
+.
+.TS
+box;
+cb cb
+afCR lx .
+Macro  Description
+_
+\&.SH [\f[I]level\f[]] T{
+Unnumbered heading.
+.
+The optional
+.I level
+argument is a GNU extension indicating the heading level corresponding
+to the
+.I level
+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
+.CW \[rs]n[GROWPS]
+and
+.CW \[rs]n[PSINCR]
+heading size adjustment mechanism is in effect.
+T}
+.TE
+.
+.
+.LP
+If the
+.CW GROWPS
+register is set to a value greater than the
+.I level
+argument to
+.CW .NH
+or
+.CW .SH ,
+the point size of a heading produced by these macros increases by
+.CW \[rs]n[PSINCR]
+units over the size specified by
+.CW \[rs]n[PS] ,
+multiplied by the difference between
+.I level
+and
+.CW \[rs]n[GROWPS] .
+.
+The value stored in
+.CW \[rs]n[PSINCR]
+is interpreted in
+.I groff
+basic units;
+the
+.CW p \[rq] \[lq]
+scaling factor should be employed when assigning a value specified in
+points.
+.
+For example,
+the sequence
+.
+.TS
+box center;
+lfCR.
+\&.nr PS 10
+\&.nr GROWPS 3
+\&.nr PSINCR 1.5p
+\&.NH 1
+Carnivora
+\&.NH 2
+Felinae
+\&.NH 3
+Felis catus
+\&.SH 2
+Machairodontinae
+.TE
+.
+.
+.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
+.CW PS
+register.
+.
+\[lq]Machairodontinae\[rq] is printed at 11.5 points,
+since it corresponds to heading level\~2.
+.
+.
+.PP
+The
+.CW \[rs]n[HORPHANS]
+register operates in conjunction with the
+.CW NH
+and
+.CW SH
+macros to inhibit the printing of orphaned section headings at the
+bottom of a page;
+it specifies the minimum number of lines of the subsequent paragraph
+that must be kept on the same page as the heading.
+.
+If insufficient space remains on the current page to accommodate the
+heading and this number of lines of paragraph text,
+a page break is forced before the heading is printed.
+.
+Any display macro or
+.I tbl ,
+.I pic ,
+or
+.I eqn
+region suppresses this grouping.
+.
+.
 .KS
 .NH 2
 Highlighting
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index b5a05e5..c17f1c7 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -209,11 +209,20 @@ _
 \[rs]n[PSINCR] Point size increment    next heading    1p
 \[rs]n[GROWPS] Size increase level 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]
 _
 .TE
 .
 .
 .LP
+.B \[rs]*[SN\-STYLE]
+can alternatively be made an alias of
+.B \[rs]*[SN\-NO\-DOT]
+with the
+.B als
+request.
+.
+.
 .TS
 cb   s  s  s
 cb   cb cb cb
@@ -453,232 +462,160 @@ a page break is forced before the first line of the 
paragraph is
 printed.
 .
 .
-.PP
-Similarly,
-when a section heading
-(see subsection \[lq]Headings\[rq] below)
-precedes any of these paragraph types,
-the
-.B HORPHANS
-document control register specifies the
-.I minimum
-number of lines of the paragraph
-which must be kept on the same page as the heading.
-.
-If insufficient space remains on the current page
-to accommodate the heading and this number of lines of paragraph text,
-then a page break is forced
-.I before
-the heading is printed.
-.
-.
 .\" ====================================================================
 .SS Headings
 .\" ====================================================================
 .
-Use headings to create a hierarchical structure
-for your document.
+Use headings to create a hierarchical structure for your document.
 .
-By default,
-the
+The
 .I ms
 macros print headings in
 .B bold
-using the same font family and point size as the body text.
-.
-For output devices which support scalable fonts,
-this behaviour may be modified by defining the document control
-registers
-.B GROWPS
-and
-.BR PSINCR ;
-these are GNU extensions.
+using the same font family and,
+by default,
+point size as the body text.
 .
+Numbered and unnumbered section headings are available.
 .
-.PP
-The following heading macros are available.
+Text lines after heading macros are treated as part of the heading,
+rendered on the same output line in the same style.
 .
 .
 .TP
-.BI .NH\~ xx
+.BI .NH\~ level
 Numbered heading.
 .
-The argument
-.I xx
-is either a numeric argument to indicate the
-level of the heading, or
-.B S\~\c
-.IR xx\~xx\~ .\|.\|.\&
-to set the section number explicitly.
-.
-If you specify heading levels out of sequence,
-such as invoking
-.B .NH\~3
-after
-.BR .NH\~1 ,
+The
+.I level
+argument instructs
 .I ms
-reports a warning to the standard error stream.
+to number sections in the form
+.IR x . y . z ,
+to any depth desired,
+with the numbering of each level increasing automatically and being
+reset when a more significant level is increased.
 .
+.RB \[lq] 1 \[rq]\~is
+the most significant or coarsest division of the document.
 .
-.IP
-If the
-.B GROWPS
-register is set to a value greater than the level of the heading,
-then the point size of the heading will be increased by
-.B PSINCR
-units over the text size specified by the
-.B PS
-register,
-for each level by which the heading level is less than
-the value of
-.BR GROWPS .
-.
-For example,
-the sequence:
+Only nonzero values are output.
 .
-.RS
-.IP
-.ne 12v
-.EX
-\&.nr PS 10
-\&.nr GROWPS 3
-\&.nr PSINCR 1.5p
-\&.
-\&.NH 1
-Top Level Heading
-\&.
-\&.NH 2
-Second Level Heading
-\&.
-\&.NH 3
-Third Level Heading
-.EE
-.RE
-.
-.
-.IP
-will cause \[lq]1. Top Level Heading\[rq]
-to be printed in 13-point text,
-followed by \[lq]1.1. Second Level Heading\[rq]
-in 11.5-point text,
-while \[lq]1.1.1. Third Level Heading\[rq] and all more deeply nested
-heading levels will remain in the 10-point text specified by the
-.B PS
-register.
-.
-.
-.IP
-The value stored in
-.B \[rs]n[PSINCR]
-is interpreted in
-.I groff
-basic units;
-the
-.B p
-scaling factor should be employed when assigning a value specified in
-points.
+If you specify heading levels with a gap in an ascending sequence,
+such as by invoking
+.RB \[lq] ".NH\~3" \[rq]
+after
+.RB \[lq] ".NH\~1" \[rq],
+.I groff ms
+emits a warning on the standard error stream.
 .
 .
-.IP
-The style used to represent the section number within a numbered heading
-is controlled by the
-.B SN\-STYLE
-string,
-which may be set to either of the
+.PP
+After invocation of
+.BR .NH ,
+the assigned section number is made available in the strings
 .B SN\-DOT
-or the
-.B SN\-NO\-DOT
-styles
-(described below),
-by aliasing it accordingly.
-.
-By default,
-.B SN\-STYLE
-is initialised by defining the alias
-.
-.
-.RS
-.IP
-.EX
-\&.als SN\-STYLE SN\-DOT
-.EE
-.RE
-.
-.
-.IP
-it may be changed to the
+(as it appears in a printed section heading with default formatting,
+followed by a terminating period)
+and
 .B SN\-NO\-DOT
-style,
-if preferred,
-by defining the alternative alias
-.
+(with the terminating period omitted).
 .
-.RS
-.IP
-.EX
-\&.als SN\-STYLE SN\-NO\-DOT
-.EE
-.RE
 .
+.PP
+You can control the style used to print section numbers within numbered
+section headings by defining an appropriate alias for the string
+.BR SN\-STYLE .
 .
-.IP
-Any such change becomes effective with the first use of
-.B .NH
-.I after
-the new alias is defined.
+By default,
+.B \[rs]*[SN\-STYLE]
+is aliased to
+.BR \[rs]*[SN\-DOT] .
 .
+If you prefer to omit the terminating period from section numbers
+appearing in numbered section headings,
+you may alias it to
+.BR \[rs]*[SN\-NO\-DOT] .
 .
-.IP
-After invoking
+Any such change in section numbering style becomes effective from the
+next use of
 .BR .NH ,
-the assigned heading number is available in the strings
-.B SN\-DOT
-(as it appears in the default formatting style for numbered headings,
-with a terminating period following the number),
-and
-.B SN\-NO\-DOT
-(with this terminating period omitted).
+following redefinition of the alias for
+.BR \[rs]*[SN\-STYLE] .
 .
 .
 .TP
 .B .SH\c
-.RI " [" xx ]
+.RI " [" level ]
 Unnumbered subheading.
 .
-The use of the optional
-.I xx
-argument is a GNU extension,
-which adjusts the point size of the unnumbered subheading
-to match that of a numbered heading,
-introduced using
-.BI .NH\~ xx
-with the same value of
-.IR xx .
-.
-For example,
-given the same settings for
-.BR PS ,
-.BR GROWPS ,
+The optional
+.I level
+argument is a GNU extension indicating the heading level corresponding
+to the
+.I level
+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
+.B \[rs]n[GROWPS]
 and
-.B PSINCR
-as used in the preceding
-.B .NH
-example,
-the sequence:
+.B \[rs]n[PSINCR]
+heading size adjustment mechanism is in effect.
 .
 .
-.RS
-.IP
-.ne 2v
-.EX
-\&.SH 2
-An Unnumbered Subheading
-.EE
-.RE
+.PP
+If the
+.B GROWPS
+register is set to a value greater than the
+.I level
+argument to
+.B .NH
+or
+.BR .SH ,
+the point size of a heading produced by these macros increases by
+.B \[rs]n[PSINCR]
+units over the size specified by
+.BR \[rs]n[PS] ,
+multiplied by the difference between
+.I level
+and
+.BR \[rs]n[GROWPS] .
+.
+The value stored in
+.B \[rs]n[PSINCR]
+is interpreted in
+.I groff
+basic units;
+the
+.RB \[lq] p \[rq]
+scaling factor should be employed when assigning a value specified in
+points.
 .
 .
-.IP
-will print \[lq]An Unnumbered Subheading\[rq] in 11.5-point text.
+.PP
+The
+.B \[rs]n[HORPHANS]
+register operates in conjunction with the
+.B NH
+and
+.B SH
+macros to inhibit the printing of orphaned section headings at the
+bottom of a page;
+it specifies the minimum number of lines of the subsequent paragraph
+that must be kept on the same page as the heading.
+.
+If insufficient space remains on the current page to accommodate the
+heading and this number of lines of paragraph text,
+a page break is forced before the heading is printed.
+.
+Any display macro or
+.IR tbl ,
+.IR pic ,
+or
+.I eqn
+region suppresses this grouping.
 .
 .
 .\" ====================================================================