File: groff.info,  Node: Input Line Traps,  Next: Traps.php">Blank Line Traps,  Prev: Traps.php">Diversion Traps,  Up: Traps

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 *note 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 (*note 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 (*note
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.