5.18 Page Control

Discretionary page breaks can prevent the unwanted separation of content. A new page number takes effect during page ejection; see The Implicit Page Trap.

Request: .bp [page-number]

Request: .bp +page-number

Request: .bp -page-number

Register: \n[%]

Break the page and change (increase or decrease) the next page number per the numeric expression page-number. If page-number is invalid, GNU troff emits a warning in category ‘number’ and ignores the argument. This request causes a break. A page break advances the vertical drawing position to the bottom of the page, springing traps. See Page Location Traps. bp has effect only if invoked within the top-level diversion.¹⁰⁹ This request is incorrectly documented in the AT&T troff manual as having a default scaling unit of ‘v’.

The register % interpolates the page number.

.de BP
'  bp \" schedule page break once current line is output
..

Caution: Interpolations occur before formatting operations. The process of filling, breaking, and adjusting a line can change the page number. % is a register like any other, not a placeholder that is rewritten after the line it appears on is formatted. Consider, for example, an extremely long page number at the end of the last line on the page; numbers aren’t hyphenated, so the word containing the page number might break the line and the page, causing the reported page number to lag by one. This sequencing also means that interpolating the % register inside a diversion (such as a footnote) records the page number at the time the diversion is populated, not when it is output.

Request: .ne [space]

Force a page break if insufficient vertical space is available (it asserts “needed” space). ne tests the distance to the next page location trap; see Page Location Traps, and breaks the page if that amount is less than space. The default scaling unit is ‘v’. If space is invalid, GNU troff emits a warning in category ‘number’ and ignores the argument. If space is not specified, ‘1v’ is assumed.

We can require space for at least the first two output lines of a paragraph, preventing its first line from being isolated at the page bottom.

.ne 2v
Considering how common illness is,
how tremendous the spiritual change that it brings,
how astonishing,
when the lights of health go down,
the undiscovered countries that are then disclosed,
what wastes and deserts of the soul a slight attack
of influenza brings to view,
what precipices and lawns sprinkled with bright flowers
a little rise of temperature reveals,
what ancient and obdurate oaks are uprooted in us
in the act of sickness,
how we go down into the pit of death
and feel the waters of annihilation
close above our heads.\|.\|.
.sp
Virgina Woolf, \[lq]On Being Ill\[rq], 1926

This method is reliable only if no output line is pending when ne is invoked. When macro packages are used, this is often not the case: their paragraphing macros perform the break. You may need to experiment with placing the ne after the paragraphing macro, or br and ne before it.

ne is also useful to force grouping of section headings with their subsequent paragraphs, or tables with their captions and/or explanations. Macro packages often use ne with diversions to implement keeps and displays; see Diversions. They may also offer parameters for widow and orphan management.

Request: .sv [space]

Request: .os

sv requires vertical space as ne does, but also saves it for later output by the os request. If space is available before the next page location trap, it is output immediately. Both requests ignore a partially collected line, taking effect at the next break. sv and os ignore no-space mode (recall Manipulating Spacing). While the sv request allows negative values for space, os ignores them. The default scaling unit is ‘v’. If space is not specified, ‘1v’ is assumed.

Register: \n[nl]

nl interpolates the vertical drawing position as of the most recently typeset output line. It does not necessarily (and often does not) represent that of the pending output line, because the formatter does not determine the position of its baseline until it is output; recall Manipulating Spacing. Assigning a value to nl sets the vertical drawing position in advance of further modifications to baseline positioning arising from alterations to type size, changes to vertical spacing, or application of extra pre- or post-vertical spacing.

When the formatter starts, the transition to the first page has not yet happened—nl is negative. If you plant a page location trap at vertical position ‘0’ (idiomatically to format a header), you can assign a negative value to nl to spring that trap even if the page has already started (see Page Location Traps).

.de HD
.  sp
.  tl ''Goldbach Solution''
.  sp
..
.
First page.
.bp
.wh 0 HD \" plant header trap at top of page
.nr nl (-1)
Second page.
    ⇒ First page.
    ⇒
    ⇒ (blank lines elided)
    ⇒
    ⇒                         Goldbach Solution
    ⇒
    ⇒ (blank lines elided)
    ⇒
    ⇒ Second page.

Without resetting nl to a negative value, the trap just planted would be active beginning with the next page, not the current one.

See Diversions, for a comparison of nl with the .h and .d registers.