5.18 Page Control

Request: .bp [page]
Request: .bp +page
Request: .bp -page
Register: \n[%]

Stop processing the current page and move to the next page. This request causes a break. It can also take an argument to set (increase, decrease) the page number of the next page (which becomes the current page after bp has finished). The difference between bp and pn is that pn does not cause a break or actually eject a page. See Page Layout. This request is incorrectly documented in the AT&T troff manual as having a default scaling indicator of ‘v’.

.de newpage                         \" define macro
'bp                                 \" begin page
'sp .5i                             \" vertical space
.tl 'left top'center top'right top' \" title
'sp .3i                             \" vertical space
..                                  \" end macro

bp has no effect if not called within the top-level diversion (see Diversions).

The writable register % holds the current page number.

The register .pe is set to 1 while bp is active. See Page Location Traps.

Request: .ne [space]

Your text may need a certain amount of vertical space before a page break occurs. For instance, you may wish to ensure that the first output line of a paragraph is not orphaned at the bottom of a page. The ne request tests the amount of distance to the next page location trap (or the page bottom if none is planted earlier; see Page Location Traps), and breaks the page if less than space is available. The default scaling unit is ‘v’. If space is not specified, ‘1v’ is assumed.

For example, to require room for at least the first two output lines of a paragraph, you can do the following.

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

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

The sv request is similar to ne, but saves the specified vertical space. If space is available before the next page location trap (or the page bottom if none is planted earlier; see Page Location Traps), the space is output immediately. Any partially collected line is ignored. Otherwise, the vertical space is saved. Output the space on demand with os. Both 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 and first page transition hasn’t happened yet, 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 header
.  sp
.  tl ''Goldbach Solution''
.  sp
..
.
First page.

.bp
.wh 0 header \" plant header trap at top of page
.nr nl (-1)
Second page.

    ⇒ First page.
    ⇒
    ⇒ 
    ⇒
    ⇒                   Goldbach Solution
    ⇒
    ⇒ 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.