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

.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 read-write register % holds the current page number.

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

Request: .ne [space]

It is often necessary to force a certain amount of space before a new page occurs. This is most useful to make sure that there is not a single orphan line left at the bottom of a page. The ne request ensures that there is a certain distance, specified by the first argument, before the next page is triggered (see Traps, for further information). The default scaling indicator for ne is ‘v’; the default value of space is 1v if no argument is given.

For example, to make sure that no fewer than 2 lines get orphaned, do the following before each paragraph:

.ne 2
text text text

ne then automatically causes a page break if there is space for one line only.

Request: .sv [space]

Request: .os

sv is similar to the ne request; it reserves the specified amount of vertical space. If the desired amount of space exists before the next trap (or the bottom page boundary if no trap is set), the space is output immediately (ignoring a partially filled line, which stays untouched). If there is not enough space, it is stored for later output via the os request. The default value is 1v if no argument is given; the default scaling indicator is ‘v’.

Both sv and os ignore no-space mode. While the sv request allows negative values for space, os ignores them.

Register: \n[nl]

This register contains the current vertical position. If the vertical position is zero and the top of page transition hasn’t happened yet, nl is set to negative value. gtroff itself does this at the very beginning of a document before anything has been printed, but the main usage is to plant a header trap on a page if this page has already started.

Consider the following:

.de xxx
.  sp
.  tl ''Header''
.  sp
..
.
First page.
.bp
.wh 0 xxx
.nr nl (-1)
Second page.

Result:

First page.

...

                             Header

Second page.

...

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

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