[groff] 04/08: Improve diversion trap documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d45d1e66f9034e7899161ccacddc7371334a88da
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Sep 25 18:18:55 2020 +1000

    Improve diversion trap documentation.
    
    doc/groff.texi (Page Location Traps): Reword to clarify that .wh and .dt
    can't be used for the same purposes.
    (Diversion Traps): Clarify that _any_ fewer than two arguments to .dt
    clear the trap (not just none).  Use more idiomatic English.
    
    man/groff.7.man (Requests/Request short reference): Document form of .dt
    for clearing diversion trap.  Clarify that "trap" argument to .dt is a
    macro name.
---
 doc/groff.texi  | 14 +++++++-------
 man/groff.7.man | 12 +++++++++++-
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index c015ac5..480853a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -12300,11 +12300,11 @@ setting footnotes
 @cindex vertical position trap enable register (@code{.vpt})
 Enable vertical position traps if @var{flag} is non-zero, or disables
 them otherwise.  Vertical position traps are traps set by the @code{wh}
-or @code{dt} requests.  Traps set by the @code{it} request are not
-vertical position traps.  The parameter that controls whether vertical
-position traps are enabled is global.  Initially vertical position traps
-are enabled.  The current setting of this is available in the
-@code{.vpt} read-only number register.
+request, or by @code{dt} within a diversion.  Traps set by the @code{it}
+request are not vertical position traps.  The parameter that controls
+whether vertical position traps are enabled is global.  Initially
+vertical position traps are enabled.  The current setting of this is
+available in the @code{.vpt} read-only number register.
 
 Note that a page can't be ejected if @code{vpt} is set to zero.
 @endDefreq
@@ -12508,9 +12508,9 @@ most cases, this is not the expected behaviour.
 @cindex diversion trap, setting (@code{dt})
 @cindex trap, diversion, setting (@code{dt})
 Set a trap @emph{within} a diversion.  @var{dist} is the location of the
-trap (identical to the @code{wh} request; default scaling indicator is
+trap (as with the @code{wh} request, the default scaling indicator is
 @samp{v}) and @var{macro} is the name of the macro to be invoked.  If
-called without arguments, the diversion trap is removed.
+called with fewer than two arguments, the diversion trap is removed.
 
 Note that there exists only a single diversion trap.
 
diff --git a/man/groff.7.man b/man/groff.7.man
index 3e90a0b..5c7a7fa 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1636,13 +1636,23 @@ Same as
 .request .ds
 but with compatibility mode switched off during string expansion.
 .
+.
+.TPx
+.REQ .dt
+Clear diversion trap.
+.
+.
 .TPx
 .REQ .dt "N trap"
-Set diversion trap to position
+Set diversion trap to
+macro
+.I trap
+at position
 .I N
 (default scaling indicator\~\c
 .scaleindicator v ).
 .
+.
 .TPx
 .REQ .ec
 Reset escape character to