groff: ms Displays and Keeps
4.3.5.7 Displays and keeps
..........................
Use displays to show text-based examples or figures (such as code
listings).
Displays turn off filling, so lines of code are displayed as-is
without inserting 'br' requests in between each line. Displays can be
"kept" on a single page, or allowed to break across pages.
-- Macro: .DS L
-- Macro: .LD
-- Macro: .DE
Left-justified display. The '.DS L' call generates a page break,
if necessary, to keep the entire display on one page. The 'LD'
macro allows the display to break across pages. The 'DE' macro
ends the display.
-- Macro: .DS I
-- Macro: .ID
-- Macro: .DE
Indents the display as defined by the 'DI' register. The '.DS I'
call generates a page break, if necessary, to keep the entire
display on one page. The 'ID' macro allows the display to break
across pages. The 'DE' macro ends the display.
-- Macro: .DS B
-- Macro: .BD
-- Macro: .DE
Sets a block-centered display: the entire display is
left-justified, but indented so that the longest line in the
display is centered on the page. The '.DS B' call generates a page
break, if necessary, to keep the entire display on one page. The
'BD' macro allows the display to break across pages. The 'DE'
macro ends the display.
-- Macro: .DS C
-- Macro: .CD
-- Macro: .DE
Sets a centered display: each line in the display is centered. The
'.DS C' call generates a page break, if necessary, to keep the
entire display on one page. The 'CD' macro allows the display to
break across pages. The 'DE' macro ends the display.
-- Macro: .DS R
-- Macro: .RD
-- Macro: .DE
Right-justifies each line in the display. The '.DS R' call
generates a page break, if necessary, to keep the entire display on
one page. The 'RD' macro allows the display to break across pages.
The 'DE' macro ends the display.
-- Macro: .Ds
-- Macro: .De
These two macros were formerly provided as aliases for 'DS' and
'DE', respectively. They have been removed, and should no longer
be used. The original implementations of 'DS' and 'DE' are
retained, and should be used instead. X11 documents that actually
use 'Ds' and 'De' always load a specific macro file from the X11
distribution ('macros.t') that provides proper definitions for the
two macros.
On occasion, you may want to "keep" other text together on a page.
For example, you may want to keep two paragraphs together, or a
paragraph that refers to a table (or list, or other item) immediately
following. The 'ms' macros provide the 'KS' and 'KE' macros for this
purpose.
-- Macro: .KS
-- Macro: .KE
The 'KS' macro begins a block of text to be kept on a single page,
and the 'KE' macro ends the block.
-- Macro: .KF
-- Macro: .KE
Specifies a "floating keep"; if the keep cannot fit on the current
page, 'groff' holds the contents of the keep and allows text
following the keep (in the source file) to fill in the remainder of
the current page. When the page breaks, whether by an explicit
'bp' request or by reaching the end of the page, 'groff' prints the
floating keep at the top of the new page. This is useful for
printing large graphics or tables that do not need to appear
exactly where specified.
You can also use the 'ne' request to force a page break if there is
not enough vertical space remaining on the page.
Use the following macros to draw a box around a section of text (such
as a display).
-- Macro: .B1
-- Macro: .B2
Marks the beginning and ending of text that is to have a box drawn
around it. The 'B1' macro begins the box; the 'B2' macro ends it.
Text in the box is automatically placed in a diversion (keep).