[groff] 21/35: [docs]: Revise `warn` request discussion.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 77994c0d007e0ac2397e307da80ac9e08d88e264
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 23 22:33:49 2021 +1100

    [docs]: Revise `warn` request discussion.
    
    Be more clear about their division into categories.  Remove any
    suggestion that they are organized into "levels".
---
 doc/groff.texi       | 31 +++++++++++++++++--------------
 man/groff.7.man      | 22 +++++++++++++++++-----
 man/groff_diff.7.man | 37 ++++++++++++++++++++++++-------------
 3 files changed, 58 insertions(+), 32 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 51a9dc2..bca6c9c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -15494,22 +15494,23 @@ line.  @xref{Warnings}.
 @endDefreq
 
 @cindex warnings
-@code{gtroff} has command-line options for printing out more warnings
-(@option{-w}) and for printing backtraces (@option{-b}) when a warning
-or an error occurs.  The most verbose level of warnings is @option{-ww}.
+GNU @code{troff} has command-line options for reporting warnings
+(@option{-w}) and backtraces (@option{-b}) when a warning or an error
+occurs.
 
-@DefreqList {warn, [@Var{flags}]}
+@DefreqList {warn, [@Var{n}]}
 @DefregListEndx {.warn}
-@cindex level of warnings (@code{warn})
-@cindex warnings, level (@code{warn})
-Control the level of warnings checked for.  The @var{flags} are the sum
-of the numbers associated with each warning that is to be enabled; all
-other warnings are disabled.  The number associated with each warning is
-listed below.  For example, @samp{.warn 0} disables all warnings, and
-@samp{.warn 1} disables all warnings except that about missing glyphs.
-If no argument is given, all warnings are enabled.
-
-The read-only register @code{.warn} contains the current warning level.
+@cindex warning level (@code{warn})
+Select the categories, or ``types'', of reported warnings.
+@var{n}@tie{}is the sum of the numeric codes associated with each
+warning category that is to be enabled; all other categories are
+disabled.  The categories and their associated codes are listed in
+@ref{Warnings}.  For example, @samp{.warn 0} disables all warnings, and
+@samp{.warn 1} disables all warnings except those about missing glyphs.
+If no argument is given, all warning categories are enabled.
+
+The read-only register @code{.warn} contains the sum of the numeric
+codes of enabled warning categories.
 @endDefreq
 
 @menu
@@ -15533,6 +15534,8 @@ the @code{warn} request and the @code{.warn} register.
 Warnings of each category are produced under the following
 circumstances.
 
+@cindex categories, warning
+@cindex warning categories
 @table @samp
 @item char
 @itemx 1
diff --git a/man/groff.7.man b/man/groff.7.man
index 8e9ff24..0fea286 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3060,14 +3060,25 @@ Set vertical base line spacing to
 (default scaling indicator\~\c
 .scaleindicator p ).
 .
+.
 .TPx
 .REQ .warn
-Enable all warnings.
+Enable all warning categories.
+.
 .
 .TPx
-.REQ .warn "n"
-Set warnings code to
-.IR n .
+.REQ .warn\~0
+Disable all warning categories.
+.
+.
+.TPx
+.REQ .warn n
+Enable warnings in categories whose codes sum
+.RI to\~ n ;
+.\" TODO: Move that table here, perhaps.
+see
+.MR @g@troff @MAN1EXT@ .
+.
 .
 .TPx
 .REQ .warnscale "si"
@@ -4779,9 +4790,10 @@ Number of basic units per vertical unit of output device 
resolution.
 .REG .w
 Width of previous glyph.
 .
+.
 .TPx
 .REG .warn
-The sum of the number codes of the currently enabled warnings.
+The sum of the numeric codes of currently enabled warning categories.
 .
 .
 .TPx
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 39984c9..cb41a31 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3368,25 +3368,34 @@ enabled is global.
 Initially,
 vertical position traps are enabled.
 .
+.
 .TP
-.BI .warn\~ n
-Control warnings.
-.IR n \~\c
-is the sum of the numbers associated with each warning that is to be
-enabled; all other warnings are disabled.
+.B .warn\~\c
+.RI [ n ]
+Select the categories,
+or \[lq]types\[rq],
+of reported warnings.
 .
-The number associated with each warning is listed in
+.IR n \~is
+the sum of the numeric codes associated with each warning category that
+is to be enabled;
+all other categories are disabled.
+.
+The categories and their associated codes are listed in section
+\[lq]Warnings\[rq] of
 .MR @g@troff @MAN1EXT@ .
+.\" TODO: Maybe move that table to groff(7).
 .
 For example,
-.B .warn 0
-disables all warnings, and
-.B .warn 1
-disables all warnings except that about missing glyphs.
+.RB \[lq] ".warn 0" \[rq]
+disables all warnings,
+and
+.RB \[lq] ".warn 1" \[rq]
+disables all warnings except those about missing glyphs.
+.
+If no argument is given,
+all warning categories are enabled.
 .
-If
-.I n
-is not given, all warnings are enabled.
 .
 .TP
 .BI .warnscale\~ si
@@ -3935,6 +3944,7 @@ and 0\~otherwise.
 .B \[rs]n[.vpt]
 1\~if vertical position traps are enabled, 0\~otherwise.
 .
+.
 .TP
 .B \[rs]n[.warn]
 The sum of the numbers associated with each of the currently enabled
@@ -3942,6 +3952,7 @@ warnings.
 .
 The number associated with each warning is listed in
 .MR @g@troff @MAN1EXT@ .
+.\" TODO: Maybe move that table to groff(7).
 .
 .
 .TP