[groff] 01/01: Rework documentation of .spreadwarn.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit faf49609f480bcae418a1173fe89fa7c6d981aeb
Author: G. Branden Robinson <address@hidden>
AuthorDate: Sat Apr 11 17:50:57 2020 +1000

    Rework documentation of .spreadwarn.
    
    * doc/groff.texi (.spreadwarn):
    * man/groff.7.man (.spreadwarn):
    * man/groff_diff.7.man (.spreadwarn):
      Recast a lot of wording, some based on suggestions from Dave Kemper.
      Make more prominent the fact that spreading only applies to adjustment
      mode 'b'.  Document warning type used.
    
    Fixes half of Savannah #58035.
---
 ChangeLog            | 13 +++++++++++++
 doc/groff.texi       | 21 ++++++++++-----------
 man/groff.7.man      | 28 ++++++++++++++++++++++------
 man/groff_diff.7.man | 48 ++++++++++++++++++++++++++++++++----------------
 4 files changed, 77 insertions(+), 33 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1b1fb07..07d5fbe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,18 @@
 2020-04-11  G. Branden Robinson <address@hidden>
 
+       Rework documentation of .spreadwarn.
+
+       * doc/groff.texi (.spreadwarn):
+       * man/groff.7.man (.spreadwarn):
+       * man/groff_diff.7.man (.spreadwarn):
+       Recast a lot of wording, some based on suggestions from Dave
+       Kemper.  Make more prominent the fact that spreading only
+       applies to adjustment mode 'b'.  Document warning type used.
+
+       Fixes half of Savannah #58035.
+
+2020-04-11  G. Branden Robinson <address@hidden>
+
        Require Texinfo 5.0 (February 2013) at a minimum.
 
        * m4/groff.m4 (GROFF_MAKEINFO): Check for version 5.0 (increased
diff --git a/doc/groff.texi b/doc/groff.texi
index 3c7841b..fb87924 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14127,12 +14127,13 @@ At startup, it is set to @samp{i}.
 @endDefreq
 
 @Defreq {spreadwarn, [@Var{limit}]}
-Make @code{gtroff} emit a warning if the additional space inserted for
-each space between words in an output line is larger or equal to
-@var{limit}.  A negative value is changed to zero; no argument toggles
-the warning on and off without changing @var{limit}.  The default
-scaling indicator is @samp{m}.  At startup, @code{spreadwarn} is
-deactivated, and @var{limit} is set to 3@dmn{m}.
+Emit a @code{break} warning if the additional space inserted for each
+space between words in an output line adjusted to both margins with
+@w{@samp{.ad b}} is larger than or equal to @var{limit}.  A negative
+value is treated as zero; an absent argument toggles the warning on and
+off without changing @var{limit}.  The default scaling indicator is
+@samp{m}.  At startup, @code{spreadwarn} is inactive and @var{limit} is
+3@dmn{m}.
 
 For example,
 
@@ -14141,11 +14142,9 @@ For example,
 @endExample
 
 @noindent
-causes a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
-interword space in a line.
-
-This request is active only if text is justified to both margins (using
-@w{@samp{.ad b}}).
+causes a warning if @code{break} warnings are not suppressed and
+@code{gtroff} must add 0.2@dmn{m} or more for each interword space in a
+line.  @xref{Warnings}.
 @endDefreq
 
 @cindex warnings
diff --git a/man/groff.7.man b/man/groff.7.man
index e47b789..fc1c958 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2395,14 +2395,30 @@ current font.
 .
 .TPx
 .REQ .spreadwarn
-Toggle the spread warning on and off without changing its value.
+Toggle the spread warning on and off (the default) without changing its
+value.
 .
 .TPx
-.REQ .spreadwarn "limit"
-Emit a warning if each space in an output line is widened by
-.I limit
-or more (default scaling indicator\~\c
-.scaleindicator m ).
+.REQ .spreadwarn N
+Emit a
+.B break
+warning if the additional space inserted for each space between words in
+an output line adjusted to both margins is larger than or equal to
+.IR N .
+.
+A negative
+.I N
+is treated as 0.
+.
+The default scaling indicator is\~\c
+.scaleindicator m .
+.
+At startup,
+.request .spreadwarn
+is inactive and
+.I N
+is
+.scalednumber "3 m" .
 .
 .TPx
 .REQ .ss "N"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index a32b559..c931981 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2138,34 +2138,50 @@ font.
 Without arguments, reset the list of special fonts to be empty.
 .
 .TP
-.BI .spreadwarn\  limit
-Make
-.B troff
-emit a warning if the additional space inserted for each space between
-words in an output line is larger or equal to
+.B .spreadwarn\c
+.RI " [" limit ]
+Emit a
+.B break
+warning if the additional space inserted for each space between words in
+an output line adjusted to both margins with
+.RB \[lq] .ad\~b \[rq]
+is larger than or equal to
 .IR limit .
 .
-A negative value is changed to zero; no argument toggles the warning on
-and off without changing
+A negative value is treated as zero;
+an absent argument toggles the warning on and off without changing
 .IR limit .
 .
-The default scaling indicator is\~\c
+The default scaling indicator is
 .BR m .
 .
 At startup,
-.B spreadwarn
-is deactivated, and
+.B .spreadwarn
+is inactive and
 .I limit
-is set to 3m.
+is 3\~m.
 .
+.IP
 For example,
-.B .spreadwarn\ 0.2m
+.IP
+.RS
+.RS
+.EX
+\&.spreadwarn 0.2m
+.EE
+.RE
+.RE
+.IP
 causes a warning if
-.B troff
-must add 0.2m or more for each interword space in a line.
+.B break
+warnings are not suppressed and
+.
+.I @g@troff
+must add 0.2\~m or more for each interword space in a line.
 .
-This request is active only if text is justified to both margins (using
-.BR .ad\ b ).
+See
+.IR @g@troff (@MAN1EXT@)
+for warning types and control.
 .
 .TP
 .BI .stringdown \~stringvar