[groff] 05/07: Update debugging documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 69128dec78451523c74b5d31f4798d59af37aaba
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Nov 28 02:57:57 2020 +1100

    Update debugging documentation.
    
    * doc/groff.texi (Debugging): Update with a more helpful introduction,
      summarizing available procedures.  Mention backtracing since it is
      much more useful now (post-groff 1.22.4.)
    
    * man/groff.7 (Debugging): Add new section summarizing material added to
      our Texinfo manual.
    
    * man/groff_diff.7.man (Debugging): Add new section describing groff
      extensions.
---
 ChangeLog            | 13 ++++++++++
 doc/groff.texi       | 24 +++++++++++++++----
 man/groff.7.man      | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 man/groff_diff.7.man | 50 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 151 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index db5defc..e75c418 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2020-11-28  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (Debugging): Update with a more helpful
+       introduction, summarizing available procedures.  Mention
+       backtracing since it is much more useful now (post-groff
+       1.22.4.)
+
+       * man/groff.7 (Debugging): Add new section summarizing
+       material added to our Texinfo manual.
+
+       * man/groff_diff.7.man (Debugging): Add new section describing
+       groff extensions.
+
 2020-11-22  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/groff.texi (Traps): Update.  Organize subsubsections "Page
diff --git a/doc/groff.texi b/doc/groff.texi
index 0fbfc9a..65ec47f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14787,8 +14787,24 @@ tokens are removed.
 @section Debugging
 @cindex debugging
 
-@code{gtroff} is not easy to debug, but there are some useful features
-and strategies for debugging.
+GNU @code{troff} is not the easiest language to debug, in part thanks to
+its design features of recursive interpolation and multi-stage pipeline
+processing.  Nevertheless there exist several features useful for
+troubleshooting.
+
+Preprocessors use the @code{lf} request to preserve the identity of the
+line numbers and names of input files.  GNU @code{troff} emits a variety
+of error diagnostics and supports several categories of warning; the
+output of these can be selectively suppressed.  Backtraces can be
+enabled when errors or warnings occur, or triggered on demand.  The
+@code{tm} and related requests can be used to emit customized diagnostic
+messages or for instrumentation while troubleshooting.  The @code{ex}
+and @code{ab} requests cause early termination with successful and error
+exit codes respectively, to halt further processing when continuing
+would be fruitless.  The state of the formatter can be examined with
+requests that write lists of defined names (macros, strings, diversions,
+or boxes), environments, registers, and page location traps to the
+standard error stream.
 
 @Defreq {lf, line [@Var{filename}]}
 @pindex soelim
@@ -14817,8 +14833,8 @@ Other @code{troff} implementations (including the 
original
 @DefreqListEndx {tmc, string}
 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
-Send @var{string} to the standard error output; this is very useful for
-printing debugging messages among other things.
+Send @var{string}, which consumes the remainder of the input line, to
+the standard error stream.
 
 @cindex @code{tm} request, and copy mode
 @cindex copy mode, and @code{tm} request
diff --git a/man/groff.7.man b/man/groff.7.man
index 78c1901..d11aac2 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5281,6 +5281,74 @@ see
 .
 .
 .\" ====================================================================
+.SH Debugging
+.\" ====================================================================
+.
+.I groff
+is not the easiest language to debug,
+in part thanks to its design features of recursive interpolation and
+multi-stage pipeline processing.
+.
+Nevertheless there exist several features useful for troubleshooting.
+.
+.
+.P
+Preprocessors use the
+.B .lf
+request to preserve the identity of the line numbers and names of input
+files.
+.
+.I groff
+emits a variety of error diagnostics and supports several categories of
+warning;
+the output of these can be selectively suppressed with
+.B .warn
+(and see the
+.BR -E ,
+.BR -w ,
+and
+.B -W
+options of
+.IR \%@g@troff (@MAN1EXT@)).
+.
+Backtraces can be automatically produced when errors or warnings occur
+(the
+.B \-b
+option of
+.IR \%@g@troff (@MAN1EXT@))
+or generated on demand
+.RB ( .backtrace ).
+.
+.BR .tm ,
+.BR .tmc ,
+and
+.B .tm1
+can be used to emit customized diagnostic messages or for
+instrumentation while troubleshooting.
+.
+.B .ex
+and
+.B .ab
+cause early termination with successful and error exit codes
+respectively,
+to halt further processing when continuing would be fruitless.
+.
+The state of the formatter can be examined with requests that write
+lists of defined macros,
+strings,
+diversions,
+and boxes
+.RB ( .pm );
+environments
+.RB ( .pev ),
+registers
+.RB ( .pnr ),
+and page location traps
+.RB ( .ptr )
+to the standard error stream.
+.
+.
+.\" ====================================================================
 .SH Authors
 .\" ====================================================================
 .
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index c3df561..babe863 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4536,6 +4536,56 @@ The first three output commands are guaranteed to be:
 .
 .
 .\" ====================================================================
+.SH Debugging
+.\" ====================================================================
+.
+In addition to AT&T
+.I troff
+debugging features,
+.I groff
+emits more error diagnostics when syntactical or semantic nonsense is
+encountered and supports several categories of warning;
+the output of these can be selectively suppressed with
+.B .warn
+(and see the
+.BR -E ,
+.BR -w ,
+and
+.B -W
+options of
+.IR \%@g@troff (@MAN1EXT@)).
+.
+Backtraces can be automatically produced when errors or warnings occur
+(the
+.B \-b
+option of
+.IR \%@g@troff (@MAN1EXT@))
+or generated on demand
+.RB ( .backtrace ).
+.
+.
+.P
+.I groff
+also adds more flexible diagnostic output requests
+.RB ( .tmc
+and
+.BR .tm1 ).
+.
+More aspects of formatter state can be examined with requests that write
+lists of
+defined macros,
+strings,
+diversions,
+and boxes
+.RB ( .pm );
+environments
+.RB ( .pev ),
+and page location traps
+.RB ( .ptr )
+to the standard error stream.
+.
+.
+.\" ====================================================================
 .SH "Implementation Differences"
 .\" ====================================================================
 .