---

5.18 Page Control

The formatter permits manipulation of page breaks to prevent the unwanted separation of content, or to force separation where desired, as at a major division of a document. 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. Omitting page-number implies ‘+1’. 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; the request asserts that the document “needs” vertical space for forthcoming material on the page, like a table, figure, or the start of a paragraph. 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’. space must be nonnegative. Omitting space implies ‘1v’.

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.

Occasionally, when vertically spacing with sp, you may wish to exactly preserve the amount of space you requested, and not let the formatter discard any excess as it does when breaking a page. The sv request works like sp if it has room to vertically space, but instead saves vertical space if the requested amount would move the vertical drawing position beyond the next page location trap.¹⁶³ The os request outputs the saved vertical space as if with the sp request.

Request: .sv [space] ¶

Request: .os ¶

sv requires vertical space as ne does, but if that amount is not available, saves it for later output by the os request. If space is available before the next page location trap, the formatter outputs it immediately. Both requests ignore a partially collected line, taking effect at the next break. sv and os ignore no-space mode (recall Manipulating Spacing). The default scaling unit is ‘v’. If space is not specified, the formatter assumes ‘1v’. There is only one, global, saved space amount.

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

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