[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 11/15: [docs]: Update discussion of `itc` request.
From: |
G. Branden Robinson |
Subject: |
[groff] 11/15: [docs]: Update discussion of `itc` request. |
Date: |
Mon, 6 Jun 2022 22:26:13 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 7435ddb594a2ed973e80865c794fb04c9c4ab703
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jun 6 19:09:37 2022 -0500
[docs]: Update discussion of `itc` request.
* Say "written (or drawn) output" instead of "formatted output", to
avoid the question of whether horizontal and vertical motions
constitute formatting operations. (Input traps ignore them.)
* Update first `it` example to extend, use `\c`, and include output.
* Regarding `itc`, say simply "lines", instead of "text lines", since
control lines like ".if 1 foo" certainly produce written output.
* Replace `itc` example with slight modification of first `it` example
to illustrate how `\c` is handled differently.
* Drop incorrect claim (introduced by me in commit ada4fb3266, 19 May)
that `\h` and `\v` "count" for `it`/`itc` purposes; they don't.
* Add demonstration of (non-)impact of `sp` request and horizontal
motion escape sequence on `it` line count in spite of obvious effects
on output.
Also synchronize groff(7) and groff_diff(7) summaries of `itc` request.
Prompted by
<https://lists.gnu.org/archive/html/groff/2022-06/msg00026.html>.
---
doc/groff.texi | 81 +++++++++++++++++++++++++++++-----------------------
man/groff.7.man | 5 ++--
man/groff_diff.7.man | 4 +--
3 files changed, 51 insertions(+), 39 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 384b4531..928d8f3d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14146,9 +14146,10 @@ error to invoke @code{dt} in the top-level diversion.
@cindex input line trap, setting (@code{it})
@cindex trap, input line, setting (@code{it})
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.
+next @var{n}@tie{}lines of input that directly produce written output.
+Only text lines and (some) requests produce output directly. Macro
+calls of themselves do not---requests or text lines they interpolate
+can.
Consider a macro @samp{.ST @var{s n}} which sets the next
@var{n}@tie{}input lines in the font style@tie{}@var{s}.
@@ -14161,43 +14162,37 @@ Consider a macro @samp{.ST @var{s n}} which sets the
next
.de ES \" end ST
. ft R
..
+.ST I 1
+oblique
+face
+.ST I 1
+oblique\c
+face
+ @result{} @i{oblique} face @i{oblique}face @
+@r{(second ``face'' upright)}
@endExample
@cindex input line traps and interrupted lines (@code{itc})
@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
-sequence are not applied to the line count.
+The @code{itc} request is similar, except that lines interrupted with
+the @code{\c} escape sequence are not applied to the line count.
+@xref{Line Continuation}. To see the difference, let's change the
+previous example to use @code{itc} instead.
@Example
-.de Monospace
-. itc \\$1 End-Monospace
-. fam C
-..
-.de End-Monospace
-. fam T
-..
-Syntax:
-.Monospace 1
-.ST B 1 \" from previous example
-mycommand \c
-[\c
-.ST I 1
-operand\c
-]
+@r{@dots{}}
+. itc \\$2 ES
+@r{@dots{}}
+ @result{} @i{oblique} face @i{obliqueface} @
+@r{(second ``face'' oblique)}
@endExample
-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.
+Text lines are easily understood as input lines that produce written
+output, but escape sequences like @code{\D}, @code{\l}, and @code{\L},
+do as well; they thus increment the internal line counter tested for
+fulfillment of the input trap line count. @xref{Drawing Requests}.
@Example
.de Trap
@@ -14212,25 +14207,41 @@ foo
.Mac
bar
baz
+.it 1 Trap
+.sp \" moves, but does not write or draw
+qux
+.itc 1 Trap
+\h'5n'\c \" moves, but does not write or draw
+jat
@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.
+When @samp{Trap} gets called depends on whether the @samp{a} register is
+defined; the control line with the @code{if} request may or may not
+produce written output. We also see that the spacing request @code{sp},
+while certainly affecting the output, does not spring the input trap.
+Similarly, the horizontal motion escape sequence @code{\h} also affected
+the output, but was not ``written''. Observe that we had to follow it
+with @code{\c} and use @code{itc} to prevent the newline at the end of
+the text line from causing a word break, which, like an ordinary space
+character, counts as written output.
@Example
$ groff -Tascii input-trap-example.groff
@result{} foo bar TRAP SPRUNG baz
+ @result{}
+ @result{} qux TRAP SPRUNG jat TRAP SPRUNG
$ groff -Tascii -ra1 input-trap-example.groff
@result{} foo _____ TRAP SPRUNG bar baz
+ @result{}
+ @result{} qux TRAP SPRUNG jat TRAP SPRUNG
@endExample
@endDefreq
Input traps are associated with the environment (@pxref{Environments});
switching to another environment disables the current input trap, and
-going back reactivates it, restoring the count of lines already
-processed.
+going back reactivates it, restoring the count of qualifying lines
+enumerated in that environment.
@c ---------------------------------------------------------------------
diff --git a/man/groff.7.man b/man/groff.7.man
index e067ca52..7078d0f9 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2500,8 +2500,9 @@ lines of input that directly produce formatted output
have been read.
.REQ .itc "n name"
As
.request .it ,
-but don't count lines interrupted with
-.esc c .
+but lines interrupted with the
+.B \[rs]c
+escape sequence are not applied to the line count.
.
.
.TPx
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 743a506b..0efac0d7 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2668,9 +2668,9 @@ zero, emitting a warning in category \[lq]range\[rq].
.BI .itc\~ n\~name
As
.BR .it ,
-but text lines interrupted with the
+but lines interrupted with the
.B \[rs]c
-escape are not applied to the line count.
+escape sequence are not applied to the line count.
.
.
.TP
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 11/15: [docs]: Update discussion of `itc` request.,
G. Branden Robinson <=