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.¹¹¹

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,¹¹² 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.