File: groff.info,  Node: End-of-input Traps,  Prev: Traps.php">Leading Space Traps,  Up: Traps

5.28.5 End-of-input Traps
-------------------------

 -- Request: .em [name]
     Set a trap at the end of input, calling macro NAME after the last
     line of the last input file has been processed.  If no argument is
     given, any existing end-of-input trap is removed.

     For example, if the document had to have a section at the bottom of
     the last page for someone to approve it, the 'em' request could be
     used.

          .de approval
          \c
          .  ne 3v
          .  sp (\\n[.t]u - 3v)
          .  in +4i
          .  lc _
          .  br
          Approved:\t\a
          .  sp
          Date:\t\t\a
          ..
          .
          .em approval

     The '\c' in the above example needs explanation.  For historical
     reasons (compatibility with AT&T 'troff'), the end-of-input macro
     exits as soon as it causes a page break if no partially collected
     line remains.(1)  (*note End-of-input Traps-Footnote-1::)

     Let us assume that there is no '\c' in the above 'approval' macro,
     that the page is full, and last output line has been broken with,
     say, a 'br' request.  Because there is no more room, a 'ne' request
     at this point causes a page ejection, which in turn makes 'troff'
     exit immediately as just described.  In most situations, this is
     not desired; people generally want to format the input after 'ne'.

     To force processing of the whole end-of-input macro independently
     of this behavior, it is thus advisable to (invisibly) ensure the
     existence of a partially collected line ('\c') whenever there is a
     chance that a page break can happen.  In the above example,
     invoking the 'ne' request ensures that there is room for the
     subsequent formatted output on the same page, so we need insert
     '\c' only once.

     The next example shows how to append three lines, then start a new
     page unconditionally.  Since '.ne 1' doesn't give the desired
     effect--there is always one line available or we are already at the
     beginning of the next page--we temporarily increase the page length
     by one line so that we can use '.ne 2'.

          .de EM
          .pl +1v
          \c
          .ne 2
          line one
          .br
          \c
          .ne 2
          line two
          .br
          \c
          .ne 2
          line three
          .br
          .pl -1v
          \c
          'bp
          ..
          .em EM

     This specific feature affects only the first potential page break
     caused by the end-of-input macro; further page breaks emitted by
     the macro are handled normally.

     Another possible use of the 'em' request is to make GNU 'troff'
     emit a single large page instead of multiple pages.  For example,
     one may want to produce a long plain text file for reading in a
     terminal or emulator without page footers and headers interrupting
     the body of the document.  One approach is to set the page length
     at the beginning of the document to a very large value to hold all
     the text,(2) (*note End-of-input Traps-Footnote-2::) and
     automatically adjust it to the exact height of the document after
     the text has been output.

          .de adjust-page-length
          .  br
          .  pl \\n[nl]u \" \n[nl]: current vertical position
          ..
          .
          .de single-page-mode
          .  pl 99999
          .  em adjust-page-length
          ..
          .
          .\" Activate the above code if configured.
          .if \n[do-continuous-rendering] \
          .  single-page-mode

     Since only one end-of-input trap exists and another macro package
     may already use it, care must be taken not to break the mechanism.
     A simple solution would be to append the above macro to the macro
     package's end-of-input macro using the 'am' request.