groff-commit
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[groff] 28/50: [docs]: Expand discussion of input line traps.


From: G. Branden Robinson
Subject: [groff] 28/50: [docs]: Expand discussion of input line traps.
Date: Sat, 21 May 2022 12:17:27 -0400 (EDT)

gbranden pushed a commit to branch master
in repository groff.

commit ada4fb3266213801bd91db915c75eeffa64387ee
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu May 19 02:06:44 2022 -0500

    [docs]: Expand discussion of input line traps.
    
    * doc/groff.texi (Input Line Traps):  Expand discussion.  The `it` and
      `itc` requests count neither input lines (strictly) nor text lines.
      Instead, they count input lines that _directly produce fotmatted
      output_ (and, in the case of `itc`, are not "interrupted" or continued
      with the `\c` escape sequence).  This is useful--empty requests and
      requests that don't put nodes on the output don't break things--but
      does demand some explanation.  Clarify and provide example.
    
    * man/groff.7.man (Escape sequence short reference) <it>: Sync.
---
 ChangeLog       | 12 ++++++++++++
 doc/groff.texi  | 43 +++++++++++++++++++++++++++++++++++++++----
 man/groff.7.man |  4 ++--
 3 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 62c25852..4c07e63a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2022-05-19  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (Input Line Traps):  Expand discussion.  The
+       `it` and `itc` requests count neither input lines (strictly) nor
+       text lines.  Instead, they count input lines that _directly
+       produce fotmatted output_ (and, in the case of `itc`, are not
+       "interrupted" or continued with the `\c` escape sequence).  This
+       is useful--empty requests and requests that don't put nodes on
+       the output don't break things--but does demand some explanation.
+       Clarify and provide example.
+       * man/groff.7.man (Escape sequence short reference) <it>: Sync.
+
 2022-05-18  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/roff/troff/env.cpp (environment::choose_breakpoint): Tweak
diff --git a/doc/groff.texi b/doc/groff.texi
index 9894c01f..d966b7c4 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14222,8 +14222,10 @@ error to invoke @code{dt} in the top-level diversion.
 @cindex setting input line trap (@code{it})
 @cindex input line trap, setting (@code{it})
 @cindex trap, input line, setting (@code{it})
-Set an input line trap, calling macro @var{name} after the next
-@var{n}@tie{}lines of input have been read.
+Set an input line trap, calling macro @var{name} after processing the
+next @var{n}@tie{}lines of input that directly produce formatted output.
+Only text lines and (some) requests produce output directly; macro calls
+do not.
 
 Consider a macro @samp{.ST @var{s n}} which sets the next
 @var{n}@tie{}input lines in the font style@tie{}@var{s}.
@@ -14242,8 +14244,8 @@ Consider a macro @samp{.ST @var{s n}} which sets the 
next
 @cindex interrupted lines and input line traps (@code{itc})
 @cindex traps, input line, and interrupted lines (@code{itc})
 @cindex lines, interrupted, and input line traps (@code{itc})
-With @code{itc}, text lines interrupted with the @code{\c} escape are
-not applied to the line count.
+With @code{itc}, text lines interrupted with the @code{\c} escape
+sequence are not applied to the line count.
 
 @Example
 .de Monospace
@@ -14267,6 +14269,39 @@ In the above, the Courier font family is used to 
render input on the
 next four text lines because all but the last are interrupted with
 @code{\c}, while the style macros apply only to the next input line.
 @xref{Line Continuation}.
+
+Text lines are easily understood as input lines that produce formatted
+output, but spacing requests and escape sequences like @code{\D},
+@code{\h}, @code{\l}, @code{\L}, and @code{\v} do as well; they thus
+increment the internal line counter tested for fulfillment of the input
+trap line count.
+
+@Example
+.de Trap
+TRAP SPRUNG
+..
+.de Mac
+.if r a \l'5n'
+..
+.it 2 Trap
+.
+foo
+.Mac
+bar
+baz
+@endExample
+
+@noindent
+The timing of the input trap call above is dependent on whether the
+@samp{a} register is defined; the control line with the @code{if}
+request may or may not produce formatted output.
+
+@Example
+$ groff -Tascii input-trap-example.groff
+    @result{} foo bar TRAP SPRUNG baz
+$ groff -Tascii -ra1 input-trap-example.groff
+    @result{} foo _____ TRAP SPRUNG bar baz
+@endExample
 @endDefreq
 
 Input traps are associated with the environment (@pxref{Environments});
diff --git a/man/groff.7.man b/man/groff.7.man
index 331fabbd..47ec2b49 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2483,12 +2483,12 @@ Change indentation according to
 .
 .TPx
 .REQ .it "n name"
-Set an input line trap,
+Set an input trap,
 calling macro
 .IR name ,
 after the next
 .IR n\~ lines
-lines of input have been read.
+lines of input that directly produce formatted output have been read.
 .
 .
 .TPx



reply via email to

[Prev in Thread] Current Thread [Next in Thread]