[groff] 11/15: [docs]: Update discussion of `itc` request.

[G. Branden Robinson]

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