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 current page number.

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

Request: .ne [space]

Force a page break if insufficient vertical space is available (assert “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 widowed 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,

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

Require vertical space as ne does, but also save 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 or sets the vertical drawing position. When the formatter starts, the first page transition hasn’t happened yet, and nl is negative. If a header trap has been planted on the page (typically at vertical position 0), you can assign a negative value to nl to spring it if that 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.