[groff] 04/09: [ms]: Tweak GROWPS/PSINCR explanation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 20809364504bde106741d1606633f16decb1dcb5
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Jul 1 17:31:17 2021 +1000

    [ms]: Tweak GROWPS/PSINCR explanation.
    
    Take another stab at making this feature clear.  Tighten some wording.
---
 doc/groff.texi      | 20 +++++++++-----------
 doc/ms.ms           | 27 +++++++++++++--------------
 tmac/groff_ms.7.man | 23 +++++++++++------------
 3 files changed, 33 insertions(+), 37 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 6b39181..4bb3fa2 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -424,7 +424,7 @@ developing GNU and promoting software freedom.''
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle Edition 1.23.0
-@subtitle June 2021
+@subtitle July 2021
 @author by Trent A.@tie{}Fisher
 @author and Werner Lemberg
 
@@ -2784,8 +2784,8 @@ Default: 1.
 @unnumberedsubsubsec Heading Settings
 
 @Defmpreg {PSINCR, ms}
-Defines an increment in point size to be applied to headings at nesting
-levels more significant (numerically less) than the value specified in
+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
@@ -2798,12 +2798,10 @@ Default: 1@dmn{p}.
 
 @Defmpreg {GROWPS, ms}
 Defines the heading level at which the point size increment set by
-@code{PSINCR} becomes effective.  Headings more significant (numerically
-less) than that specified by @code{GROWPS} are printed at the point size
-set by @code{PS}; 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.
+@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.
 
 Effective: next heading.
 
@@ -3182,8 +3180,8 @@ 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.
+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.
 
 Alternatively, a first argument of@tie{}@code{S} can be given, followed
 by integral arguments to number the levels of the heading explicitly.
diff --git a/doc/ms.ms b/doc/ms.ms
index 915f3a6..c13de29 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -20,8 +20,8 @@
 .nr VS 13
 .ie t .nr PI 3.5n
 .el   .nr PI 4n
-.ND June 2021
-.EH '%''June 2021'
+.ND July 2021
+.EH '%''July 2021'
 .EF ''''
 .OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
 .OF ''''
@@ -852,10 +852,11 @@ document.
 Only nonzero values are output.
 .
 If you specify heading levels with a gap in an ascending sequence,
-such as by invoking
+such as by
+.CW ".NH\~1" \[rq] \[lq]
+and then
 .CW ".NH\~3" \[rq] \[lq]
-after
-.CW ".NH\~1" \[rq], \[lq]
+as the next such call,
 .I "groff ms"
 emits a warning on the standard error stream.
 T}
@@ -993,8 +994,10 @@ T}
 .PP
 The
 .CW PSINCR
-register defines an increment in point size to be applied to headings
-at nesting levels more significant
+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
 .CW \[rs]n[GROWPS] .
@@ -1026,13 +1029,9 @@ by
 .CW \[rs]n[PSINCR]
 becomes effective.
 .
-Headings more significant
-(numerically less)
-than that specified by
-.CW \[rs]n[GROWPS]
-are printed at the point size set by
-.CW \[rs]n[PS] ;
-for each level below the value of
+For each heading
+.I level
+below the value of
 .CW \[rs]n[GROWPS] ,
 the point size is increased by
 .CW \[rs]n[PSINCR] .
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 49aaef7..433dfb0 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -666,10 +666,11 @@ 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
+such as by
+.RB \[lq] ".NH\~1" \[rq]
+and then
 .RB \[lq] ".NH\~3" \[rq]
-after
-.RB \[lq] ".NH\~1" \[rq],
+as the next such call,
 .I groff ms
 emits a warning on the standard error stream.
 .
@@ -751,8 +752,10 @@ heading size adjustment mechanism is in effect.
 .PP
 The
 .B PSINCR
-register defines an increment in point size to be applied to headings
-at nesting levels more significant
+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
 .BR \[rs]n[GROWPS] .
@@ -772,13 +775,9 @@ by
 .B \[rs]n[PSINCR]
 becomes effective.
 .
-Headings more significant
-(numerically less)
-than that specified by
-.B \[rs]n[GROWPS]
-are printed at the point size set by
-.BR \[rs]n[PS] ;
-for each level below the value of
+For each heading
+.I level
+below the value of
 .BR \[rs]n[GROWPS] ,
 the point size is increased by
 .BR \[rs]n[PSINCR] .