Page Control (The GNU Troff Manual)

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