[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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 28/50: [docs]: Expand discussion of input line traps.,
G. Branden Robinson <=