From 362f9ddc9f4a2f6178477e8d733fa75c81582376 Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Mon, 1 May 2023 05:49:22 -0500
Subject: [docs]: Revise discussion of debugging.

* Describe backtracing less circularly.
* Use active voice more.
* Drop this section's introductory paragraph from groff(7), which
  doesn't require it, being more of a reference.
* Wrap long input line.
* Bump document date.
---
 doc/groff.texi  | 28 +++++++++++++++-------------
 man/groff.7.man | 26 +++++++++-----------------
 2 files changed, 24 insertions(+), 30 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 1ed08803f..bc4bcd084 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -464,7 +464,7 @@ Documentation License''.
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle Edition 1.23.0
-@subtitle April 2023
+@subtitle May 2023
 @author Trent@tie{}A.@: Fisher
 @author Werner Lemberg
 @author G.@tie{}Branden Robinson
@@ -16477,23 +16477,25 @@ front of it until it works and if you still have problems add a \c.}
 @end flushright
 
 GNU @code{troff} is not the easiest language to debug, in part thanks to
-its design features of recursive interpolation and the use of multi-stage
-pipeline processing in the surrounding system.  Nevertheless there exist
-several features useful for troubleshooting.
+its design features of recursive interpolation and the use of
+multi-stage pipeline processing in the surrounding system.  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
+output of these can be selectively suppressed.  A trace of the
+formatter's input processing stack can be emitted when errors or
+warnings occur by means of GNU @code{troff}'s @option{-b} option, or
+produced on demand with the @code{backtrace} request.  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, and
-diversions), environments, registers, and page location traps to the
-standard error stream.
+would be fruitless.  Examine the state of the formatter with requests
+that write lists of defined names (macros, strings, and diversions),
+environments, registers, and page location traps to the standard error
+stream.
 @c END Keep parallel with section "Debugging" of groff(7).
 
 @Defreq {lf, line [@Var{filename}]}
diff --git a/man/groff.7.man b/man/groff.7.man
index af1ebbbb2..9d9ed70b2 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -7213,15 +7213,6 @@ set and test the enablement of this mode.
 .\" ====================================================================
 .
 .\" BEGIN Keep (roughly) parallel with groff.texi node "Debugging".
-.I groff
-is not the easiest language to debug,
-in part thanks to its design features of recursive interpolation and the
-use of multi-stage pipeline processing in the surrounding system.
-.
-Nevertheless there exist several features useful for troubleshooting.
-.
-.
-.P
 Preprocessors use the
 .B .lf
 request to preserve the identities of line numbers and names of input
@@ -7240,13 +7231,14 @@ and
 options of
 .MR @g@troff @MAN1EXT@ ).
 .
-Backtraces can be automatically produced when errors or warnings occur
-(the
+A trace of the formatter's input processing stack can be emitted when
+errors or warnings occur by means of
+.MR @g@troff @MAN1EXT@ 's
 .B \-b
-option of
-.MR @g@troff @MAN1EXT@ )
-or generated on demand
-.RB ( .backtrace ).
+option,
+or produced on demand with the
+.request .backtrace
+request.
 .
 .BR .tm ,
 .BR .tmc ,
@@ -7262,8 +7254,8 @@ 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\[em]macros,
+Examine the state of the formatter with requests that write lists of
+defined names\[em]macros,
 strings,
 and
 .RB diversions\[em]( .pm );
-- 
cgit v1.2.1