Page location traps perform an action when
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
dtrequests. Traps set by the
itrequest 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
.vptread-only number register.
Note that a page can't be ejected if
vptis 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
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..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
chrequest; 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
bprequest 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
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 which 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
whrequest). 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
.necontains the amount of space that was needed in the last
nerequest that caused a trap to be sprung. Useful in conjunction with the
.truncregister. See Page Control, for more information.
.neregister 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 by the most recently sprung vertical position trap, or, if the trap was sprung by an
nerequest, minus the amount of vertical motion produced by the
nerequest. 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.
.truncregister is only set by traps it doesn't make much sense to use it outside of trap macros.
Outside of traps this register is always zero. In the following example, only the second call to
xis 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) which 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
\?) since the data in the diversion is already formatted. In
most cases, this is not the expected behaviour.