5.28.2 Input Line Traps

Request: .it [n name]

Request: .itc [n name]

Set an input line trap, calling macro name after processing the next n productive input lines (recall Manipulating Filling and Adjustment). Any existing input line trap in the environment is replaced. Without arguments, it and itc clear any input line trap that has not yet sprung.

Consider a macro ‘.ST s n’ which sets the next n input lines in the font style s.

.de ST \" Use style $1 for next $2 text lines.
.  it \\$2 ES
.  ft \\$1
..
.de ES \" end ST
.  ft R
..
.ST I 1
oblique
face
.ST I 1
oblique\c
face
    ⇒ oblique face obliqueface  (second “face” upright)

Unlike the ce and rj requests, it counts lines interrupted with the \c escape sequence separately (see Line Continuation); itc does not. To see the difference, let’s change the previous example to use itc instead.

…
.  itc \\$2 ES
…
    ⇒ oblique face obliqueface  (second “face” oblique)

You can think of the ce and rj requests as implicitly creating an input line trap with itc that schedules a break when the trap is sprung.

.de BR
.  br
.  internal: disable centering-without-filling
..
.
.de ce
.  if \\n[.br] .br
.  itc \\$1 BR
.  internal: enable centering-without-filling
..

Let us consider in more detail the sorts of input lines that are or are not “productive”.

.de Trap
TRAP SPRUNG
..
.de Mac
.if r a \l'5n'
..
.it 2 Trap
.
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

When ‘Trap’ gets called depends on whether the ‘a’ register is defined; the control line with the if request may or may not produce written output. We also see that the spacing request sp, while certainly affecting the output, does not spring the input line trap. Similarly, the horizontal motion escape sequence \h also affected the output, but was not “written”. Observe that we had to follow it with \c and use 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.

$ groff -Tascii input-trap-example.groff
    ⇒ foo bar TRAP SPRUNG baz
    ⇒
    ⇒ qux TRAP SPRUNG      jat TRAP SPRUNG
$ groff -Tascii -ra1 input-trap-example.groff
    ⇒ foo _____ TRAP SPRUNG bar baz
    ⇒
    ⇒ qux TRAP SPRUNG      jat TRAP SPRUNG

Input line traps are associated with the environment (see Environments); switching to another environment suspends the current input line trap, and going back resumes it, restoring the count of qualifying lines enumerated in that environment.