File: groff.info,  Node: Page Control,  Next: Using Fonts,  Prev: Page Layout,  Up: GNU troff Reference

5.18 Page Control
=================

Discretionary page breaks can prevent the unwanted separation of
content.  A new page number takes effect during page ejection; see *note
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.  *Note Page Location Traps::.  'bp' has effect
     only if invoked within the top-level diversion.(1)  (*note Page
     Control-Footnote-1::) 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 *note 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 *note 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 *note 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 (*note 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.

     *Note Diversions::, for a comparison of 'nl' with the '.h' and '.d'
     registers.