ms keeps and displays (The GNU Troff Manual)

#### 4.6.5.8 Keeps, boxed keeps, and displays

On occasion, you may want to keep several lines of text, or a region of a document, together on a single page, preventing an automatic page break within certain boundaries. This can cause a page break to occur earlier than it normally would. For example, you may want to keep two paragraphs together, or a paragraph that refers to a table, list, or figure adjacent to the item it discusses. `ms` provides the `KS` and `KE` macros for this purpose.

You can alternatively specify a floating keep: if a keep cannot fit on the current page, `ms` holds its contents and allows material following the keep (in the source document) to fill the remainder of the current page. When the page breaks, whether by reaching the end or `bp` request, `ms` puts the floating keep at the beginning of the next page. This is useful for placing large graphics or tables that do not need to appear exactly where they occur in the source document.

Macro: `.KS` ¶
Macro: `.KF` ¶
Macro: `.KE` ¶

  `KS` begins a keep, `KF` a floating keep, and `KE` ends a keep of either kind.

As an alternative to the keep mechanism, the `ne` request forces a page break if there is not at least the amount of vertical space specified in its argument remaining on the page (see Page Control). One application of `ne` is to reserve space on the page for a figure or illustration to be included later.

A boxed keep has a frame drawn around it.

Macro: `.B1` ¶
Macro: `.B2` ¶

  `B1` begins a keep with a box drawn around it. `B2` ends a boxed keep.

Boxed keep macros cause breaks; if you need to box a word or phrase within a line, see the `BX` macro in Typeface and decoration. Box lines are drawn as close as possible to the text they enclose so that they are usable within paragraphs. If you wish to box one or more paragraphs, you may improve the appearance by calling `B1` after the first paragraphing macro, and by adding a small amount of vertical space before calling `B2`.

    .LP
    .B1
    .I Warning:
    Happy Fun Ball may suddenly accelerate to dangerous
    speeds.
    .sp \n[PD]/2 \" space by half the inter-paragraph distance
    .B2

If you want a boxed keep to float, you will need to enclose the `B1` and `B2` calls within a pair of `KF` and `KE` calls.

Displays turn off filling; lines of verse or program code are shown with their lines broken as in the source document without requiring `br` requests between lines. Displays can be kept on a single page or allowed to break across pages. The `DS` macro begins a kept display of the layout specified in its first argument; non-kept displays are begun with dedicated macros corresponding to their layout.

Macro: `.DS` `L` ¶
Macro: `.LD` ¶

  Begin (`DS`: kept) left-aligned display.

Macro: `.DS` [`I` [indent]] ¶
Macro: `.ID` [indent] ¶

  Begin (`DS`: kept) display indented by indent if specified, and by the amount of the `DI` register otherwise.

Macro: `.DS` `B` ¶
Macro: `.BD` ¶

  Begin a (`DS`: kept) a block display: the entire display is left-aligned, but indented such that the longest line in the display is centered on the page.

Macro: `.DS` `C` ¶
Macro: `.CD` ¶

  Begin a (`DS`: kept) centered display: each line in the display is centered.

Macro: `.DS` `R` ¶
Macro: `.RD` ¶

  Begin a (`DS`: kept) right-aligned display. This is a GNU extension.

Macro: `.DE` ¶

  End any display.

The distance stored in the `DD` register is inserted before and after each pair of display macros; this is a Berkeley extension. In `groff` `ms`, this distance replaces any adjacent inter-paragraph distance or subsequent spacing prior to a section heading. The `DI` register is a GNU extension; its value is an indentation applied to displays created with ‘`.DS`’ and ‘`.ID`’ without arguments, to ‘`.DS I`’ without an indentation argument, and to indented equations set with ‘`.EQ`’. Changes to either register take effect at the next display boundary.