Next: Diversion Traps, Previous: Traps, Up: Traps [Contents][Index]
Page location traps perform an action when gtroff reaches
or passes a certain vertical location on the page. Page location traps
have a variety of purposes, including:
Enable vertical position traps if flag is non-zero, or disables
them otherwise. Vertical position traps are traps set by the wh
or dt requests. Traps set by the it request are not
vertical position traps. The parameter that controls whether vertical
position traps are enabled is global. Initially vertical position traps
are enabled. The current setting of this is available in the
.vpt read-only number register.
Note that a page can’t be ejected if vpt is set to zero.
Set a page location trap. Non-negative values for dist set the
trap relative to the top of the page; negative values set the trap
relative to the bottom of the page. Default scaling indicator is
‘v’; values of dist are always rounded to be multiples of the
vertical resolution (as given in register .V).
macro is the name of the macro to execute when the trap is sprung. If macro is missing, remove the first trap (if any) at dist.
The following is a simple example of how many macro packages set headers and footers.
.de hd \" Page header ' sp .5i . tl 'Title''date' ' sp .3i .. . .de fo \" Page footer ' sp 1v . tl ''%'' ' bp .. . .wh 0 hd \" trap at top of the page .wh -1i fo \" trap one inch from bottom
A trap at or below the bottom of the page is ignored; it can be made active by either moving it up or increasing the page length so that the trap is on the page.
Negative trap values always use the current page length; they are not converted to an absolute vertical position:
.pl 5i
.wh -1i xx
.ptr
⇒ xx -240
.pl 100i
.ptr
⇒ xx -240
It is possible to have more than one trap at the same location; to do
so, the traps must be defined at different locations, then moved
together with the ch request; otherwise the second trap would
replace the first one. Earlier defined traps hide later defined traps
if moved to the same position (the many empty lines caused by the
bp request are omitted in the following example):
.de a
. nop a
..
.de b
. nop b
..
.de c
. nop c
..
.
.wh 1i a
.wh 2i b
.wh 3i c
.bp
⇒ a b c
.ch b 1i
.ch c 1i
.bp
⇒ a
.ch a 0.5i
.bp
⇒ a b
A read-only number register holding the distance to the next trap.
If there are no traps between the current position and the bottom of the
page, it contains the distance to the page bottom. In a diversion, the
distance to the page bottom is infinite (the returned value is the
biggest integer that can be represented in groff) if there are
no diversion traps.
Change the location of a trap. The first argument is the name of the
macro to be invoked at the trap, and the second argument is the new
location for the trap (note that the parameters are specified in
opposite order as in the wh request). This is useful for
building up footnotes in a diversion to allow more space at the bottom
of the page for them.
Default scaling indicator for dist is ‘v’. If dist is missing, the trap is removed.
The read-only number register .ne contains the amount of space
that was needed in the last ne request that caused a trap to be
sprung. Useful in conjunction with the .trunc register.
See Page Control, for more information.
Since the .ne register is only set by traps it doesn’t make much
sense to use it outside of trap macros.
A read-only register containing the amount of vertical space truncated
from an sp request by the most recently sprung vertical
position trap, or, if the trap was sprung by an ne request,
minus the amount of vertical motion produced by the ne
request. In other words, at the point a trap is sprung, it
represents the difference of what the vertical position would have
been but for the trap, and what the vertical position actually is.
Since the .trunc register is only set by traps it doesn’t make
much sense to use it outside of trap macros.
A read-only register that is set to 1 while a page is ejected with
the bp request (or by the end of input).
Outside of traps this register is always zero. In the following
example, only the second call to x is caused by bp.
.de x
\&.pe=\\n[.pe]
.br
..
.wh 1v x
.wh 4v x
A line.
.br
Another line.
.br
⇒ A line.
.pe=0
Another line.
.pe=1
An important fact to consider while designing macros is that diversions
and traps do not interact normally. For example, if a trap invokes a
header macro (while outputting a diversion) that tries to change the
font on the current page, the effect is not visible before the diversion
has completely been printed (except for input protected with \!
or \?) since the data in the diversion is already formatted. In
most cases, this is not the expected behaviour.
Next: Diversion Traps, Previous: Traps, Up: Traps [Contents][Index]