[groff] 14/14: [docs]: Document input line trap cancellation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 15a08ee3c69577f4e978442bc7fa4c0479b55129
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Jan 19 19:10:19 2023 -0600

    [docs]: Document input line trap cancellation.
    
    ...and replacement.
---
 doc/groff.texi  | 17 +++++++++++------
 man/groff.7.man | 23 ++++++++++++++++-------
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index bd70d8391..d9e62cf74 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14546,14 +14546,19 @@ error to invoke @code{dt} in the top-level diversion.
 @cindex input line traps
 @cindex traps, input line
 
-@DefreqList {it, n name}
-@DefreqListEndx {itc, n name}
-@cindex setting input line trap (@code{it})
-@cindex input line trap, setting (@code{it})
-@cindex trap, input line, setting (@code{it})
+@DefreqList {it, [@Var{n} @Var{name}]}
+@DefreqListEndx {itc, [@Var{n} @Var{name}]}
+@cindex setting input line trap (@code{it}, @code{itc})
+@cindex input line trap, setting (@code{it}, @code{itc})
+@cindex trap, input line, setting (@code{it}, @code{itc})
+@cindex clearing input line trap (@code{it}, @code{itc})
+@cindex input line trap, clearing (@code{it}, @code{itc})
+@cindex trap, input line, clearing (@code{it}, @code{itc})
 Set an input line trap, calling macro @var{name} after processing the
 next @var{n}@tie{}productive input lines (@pxref{Manipulating Filling
-and Adjustment}).
+and Adjustment}).  Any existing input line trap in the environment is
+replaced.  Without arguments, @code{it} and @code{itc} clear any
+input line trap that has not yet sprung.
 
 Consider a macro @samp{.ST @var{s n}} which sets the next
 @var{n}@tie{}input lines in the font style@tie{}@var{s}.
diff --git a/man/groff.7.man b/man/groff.7.man
index 43fdea99e..68a2c071f 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3255,8 +3255,14 @@ Set indentation to
 .scaleindicator m ).
 .
 .TPx
+.REQ .it
+Cancel any pending input line trap.
+.
+.TPx
 .REQ .it "npl name"
-Set an input trap,
+Set
+(or replace)
+an input line trap in the environment,
 calling macro
 .IR name ,
 after the next
@@ -3268,13 +3274,16 @@ Lines interrupted with the
 escape sequence are counted separately.
 .
 .TPx
+.REQ .itc
+Cancel any pending input line trap.
+.
+.TPx
 .REQ .itc "npl name"
-Set an input trap,
-calling macro
-.IR name ,
-after the next
-.I npl
-productive input lines have been read.
+As
+.request .it ,
+except that input lines interrupted with the
+.B \[rs]c
+escape sequence are not counted.
 .
 .TPx
 .REQ .kern