[groff] 07/28: [ms]: Revise indented region, keep, display stuff.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a0b17d6e478d5126d96e306c30edadb4a0e8c0bb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jun 19 10:36:04 2021 +1000

    [ms]: Revise indented region, keep, display stuff.
    
    * Do minor recast of .RS/.RE discussion.
    * Revise order of presentation; present keeps before displays, since
      much understanding of the latter requires knowledge of the former.
    * Be more clear about what keep is for and the effect it has.
    * Describe (except in groff_ms(7)) more useful keep scenarios.
    * Discuss box macros more thoroughly; explain how to get a floating box.
    * Exercise more imagination in application of examples; not everyone is
      a programmer.
---
 doc/groff.texi      | 205 ++++++++++++++++++-------------------
 doc/ms.ms           | 278 ++++++++++++++++++++++++++++++--------------------
 tmac/groff_ms.7.man | 287 +++++++++++++++++++++++++++++++---------------------
 3 files changed, 440 insertions(+), 330 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 0e5bdc6..30f2e79 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3015,7 +3015,7 @@ footnotes, and inclusions of material such as tables and 
figures.
 * Highlighting in ms::
 * Lists in ms::
 * Indented regions in ms::
-* ms Displays and Keeps::
+* ms keeps and displays::
 * ms Insertions::
 * Example multi-page table::
 * ms Footnotes::
@@ -3497,26 +3497,26 @@ money
 
 @c ---------------------------------------------------------------------
 
-@node Indented regions in ms, ms Displays and Keeps, Lists in ms, ms Body Text
+@node Indented regions in ms, ms keeps and displays, Lists in ms, ms Body Text
 @subsubsection Indented regions
 
-You may need to indent a region of text while still wrapping and
-filling.
+You may need to indent a region of text while still letting @code{groff}
+automatically break lines and fill the text.
 
 @Defmac {RS, , ms}
-Begin a region indented by the amount stored in the @code{PI} register,
-affecting the placement of headings, paragraphs, and displays.
+Begin a region where headings, paragraphs, and displays are indented by
+the amount stored in the @code{PI} register.
 @endDefmac
 
 @Defmac {RE, , ms}
 End the most recent indented region.
 @endDefmac
 
-You can use @code{RS}/@code{RE} regions to line up text under hanging
-and indented paragraphs.
+You can use indented regions to line up text under hanging and indented
+paragraphs.
 @cindex @code{ms} macros, nested lists
 @cindex nested lists [@code{ms}]
-For example, you may wish to nest lists; the input
+For example, you may wish to nest lists.
 
 @CartoucheExample
 .IP \[bu] 2
@@ -3552,129 +3552,130 @@ produces
 @noindent
 as output.
 
-@xref{ms Displays and Keeps}, for macros to indent regions with filling
-disabled.
-
 @c ---------------------------------------------------------------------
 
-@node ms Displays and Keeps, ms Insertions, Indented regions in ms, ms Body 
Text
-@subsubsection Displays and keeps
+@node ms keeps and displays, ms Insertions, Indented regions in ms, ms Body 
Text
+@subsubsection Keeps and displays
 @cindex @code{ms} macros, displays
 @cindex @code{ms} macros, keeps
 @cindex keeps [@code{ms}]
-@cindex displays [@code{ms}]
-
-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 @code{br} requests in between each line.  Displays can be
-@dfn{kept} on a single page, or allowed to break across pages.
-
-@DefmacList {DS, @t{L}, ms}
-@DefmacItemx {LD, , ms}
-@DefmacListEndx {DE, , ms}
-Left-justified display.  The @samp{.DS L} call generates a page break,
-if necessary, to keep the entire display on one page.  The @code{LD}
-macro allows the display to break across pages.  The @code{DE} macro
-ends the display.
-@endDefmac
-
-@DefmacList {DS, @t{I} [@Var{indent}], ms}
-@DefmacItemx {ID, [@Var{indent}], ms}
-@DefmacListEndx {DE, , ms}
-Indents the display by @var{indent} if specified (and by the amount of
-the @code{DI} register otherwise).  The @samp{.DS I} call generates a
-page break, if necessary, to keep the entire display on one page.  The
-@code{ID} macro allows the display to break across pages.  The @code{DE}
-macro ends the display.
-@endDefmac
-
-@DefmacList {DS, @t{B}, ms}
-@DefmacItemx {BD, , ms}
-@DefmacListEndx {DE, , ms}
-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 @samp{.DS B} call generates a page break, if necessary, to
-keep the entire display on one page.  The @code{BD} macro allows the
-display to break across pages.  The @code{DE} macro ends the display.
-@endDefmac
-
-@DefmacList {DS, @t{C}, ms}
-@DefmacItemx {CD, , ms}
-@DefmacListEndx {DE, , ms}
-Sets a centered display: each line in the display is centered.  The
-@samp{.DS C} call generates a page break, if necessary, to keep the
-entire display on one page.  The @code{CD} macro allows the display to
-break across pages.  The @code{DE} macro ends the display.
-@endDefmac
-
-@DefmacList {DS, @t{R}, ms}
-@DefmacItemx {RD, , ms}
-@DefmacListEndx {DE, , ms}
-Right-justifies each line in the display.  The @samp{.DS R} call
-generates a page break, if necessary, to keep the entire display on one
-page.  The @code{RD} macro allows the display to break across pages.
-The @code{DE} macro ends the display.
-@endDefmac
 
-On occasion, you may want to @dfn{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 @file{ms} macros provide the @code{KS} and @code{KE}
-macros for this purpose.
+On occasion, you may want to @dfn{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.  The @file{ms} macros provide
+the @code{KS} and @code{KE} macros for this purpose.
+
+You can alternatively specify a @dfn{floating keep}; if a keep cannot
+fit on the current page, @file{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 an
+explicit @code{bp} request or by reaching the end of the page, @file{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.
 
 @DefmacList {KS, , ms}
+@DefmacItemx {KF, , ms}
 @DefmacListEndx {KE, , ms}
-The @code{KS} macro begins a block of text to be kept on a single page,
-and the @code{KE} macro ends the block.
-@endDefmac
-
-@DefmacList {KF, , ms}
-@DefmacListEndx {KE, , ms}
-Specifies a @dfn{floating keep}; if the keep cannot fit on the current
-page, @code{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 @code{bp}
-request or by reaching the end of the page, @code{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.
+@code{KS} begins a keep, @code{KF} a floating keep, and @code{KE} ends a
+keep of either kind.
 @endDefmac
 
 As an alternative to the keep mechanism, the @code{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 (@pxref{Page Control}).
+One application of @code{ne} is to reserve space on the page for a
+figure or illustration to be included later.
 
-Use the following macros to draw a box around a region of the page.
+@cindex boxes [@code{ms}]
+A keep can also be @dfn{boxed}.  Text in a box is automatically placed
+in a diversion (keep).
 
 @DefmacList {B1, , ms}
 @DefmacListEndx {B2, , ms}
-Marks the beginning and ending of text that is to have a box drawn
-around it.  The @code{B1} macro begins the box; the @code{B2} macro ends
-it.  Text in the box is automatically placed in a diversion (keep).
-
-These macros cause line breaks; if you need to box a word or phrase
-within a line, see the @code{BX} macro in @ref{Highlighting in ms}.  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 @code{B1} after
-the first paragraphing macro, and by adding a small amount of vertical
-space before calling @code{B2}.
+@code{B1} begins a keep with a box drawn around it.  @code{B2} ends a
+boxed keep.
+@endDefmac
+
+Box macros cause line breaks; if you need to box a word or phrase within
+a line, see the @code{BX} macro in @ref{Highlighting in ms}.  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 @code{B1} after the first
+paragraphing macro, and by adding a small amount of vertical space
+before calling @code{B2}.
 
+@c Wrap example at 56 columns.
 @CartoucheExample
 .LP
 .B1
 .I Warning:
-Happy Fun Ball may suddenly accelerate to lethal speeds.
+Happy Fun Ball may suddenly accelerate to dangerous
+speeds.
 .sp \n[PD]/2
 .B2
 @endCartoucheExample
+
+If you want a box to float, you will need to enclose the @code{B1} and
+@code{B2} calls within a pair of @code{KF} and @code{KE} calls.
+
+@cindex displays [@code{ms}]
+@dfn{Displays} turn off filling; lines of verse or program code are
+shown with their lines broken as in the source document without
+requiring @code{br} requests between lines.  Displays can be kept on a
+single page or allowed to break across pages.  The @code{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.
+
+@DefmacList {DS, @t{L}, ms}
+@DefmacListEndx {LD, , ms}
+Begin (@code{DS}:@: kept) left-aligned display.
+@endDefmac
+
+@DefmacList {DS, @t{I} [@Var{indent}], ms}
+@DefmacListEndx {ID, [@Var{indent}], ms}
+Begin (@code{DS}:@: kept) display indented by @var{indent} if specified,
+and by the amount of the @code{DI} register otherwise.
+@endDefmac
+
+@DefmacList {DS, @t{B}, ms}
+@DefmacListEndx {BD, , ms}
+Begin a (@code{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.
+@endDefmac
+
+@DefmacList {DS, @t{C}, ms}
+@DefmacListEndx {CD, , ms}
+Begin a (@code{DS}:@: kept) centered display:@: each line in the display
+is centered.
+ @endDefmac
+
+@DefmacList {DS, @t{R}, ms}
+@DefmacListEndx {RD, , ms}
+Begin a (@code{DS}:@: kept) right-aligned display.
 @endDefmac
 
+@Defmac {ED, , ms}
+End any display.
+@endDefmac
+
+The distance stored in the @code{DD} register is inserted before and
+after each pair of display macros.  This is a Berkeley extension.
+
+The identation amount stored in the @code{DI} register is applied only
+to displays created with @samp{.DS I} and @code{ID}.  This is a GNU
+extension.
+
+Changes to either register take effect at the next display boundary.
+
 @c ---------------------------------------------------------------------
 
-@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body 
Text
+@node ms Insertions, Example multi-page table, ms keeps and displays, ms Body 
Text
 @subsubsection Tables, figures, equations, and references
 @cindex @code{ms} macros, tables
 @cindex @code{ms} macros, figures
diff --git a/doc/ms.ms b/doc/ms.ms
index d87d504..b41bb8e 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -1557,8 +1557,9 @@ Indented regions
 .
 .
 .LP
-You may need to indent a region of text while still wrapping and
-filling.
+You may need to indent a region of text while still letting
+.I groff
+automatically break lines and fill the text.
 .
 .
 .TS
@@ -1568,11 +1569,10 @@ lf(CR) lx .
 Macro  Description
 _
 \&.RS  T{
-Begin a region indented by
-.CW \[rs]n[PI] ,
-affecting the placement of headings,
+Begin a region where headings,
 paragraphs,
-and displays.
+and displays are indented by
+.CW \[rs]n[PI] .
 T}
 \&.RE  T{
 End the most recent indented region.
@@ -1581,10 +1581,8 @@ T}
 .
 .
 .PP
-You can use
-.CW .RS /
-.CW .RE
-regions to line up text under hanging and indented paragraphs.
+You can use indented regions to line up text under hanging and indented
+paragraphs.
 .
 For example,
 you may wish to nest lists.
@@ -1635,122 +1633,69 @@ T}
 .
 .
 .NH 2
-Displays and keeps
+Keeps, boxed keeps, and displays
 .XS
-       Displays and keeps
+       Keeps, boxed keeps, and displays
 .XE
-.LP
-Use displays to show text-based examples or figures
-(such as code listings).
-This document shows
-.I groff
-code examples inside displays, for example.
-.PP
-Displays turn off filling, so lines of code can be
-displayed as-is without inserting
-.CW .br
-requests in between each line.
-Displays can be 
-.I kept
-on a single page, or allowed to break across pages.
-The following table shows the display types available.
-.
-.
-.TS
-box;
-cb s | cb
-cb cb | ^
-lf(CR) lf(CR) | lx .
-Display macro  Description
-With keep      No keep
-_
-\&.DS L        \&.LD   Left-aligns display.
-\&.DS I \f[R][\,\f[I]indent\/\f[]]     \
-\&.ID \f[R][\,\f[I]indent\/\f[]]       T{
-Indents display
-(by
-.I indent
-if given,
-otherwise the value of
-.CW \[rs]n[DI] ).
-T}
-\&.DS B        \&.BD   T{
-Block-centers display
-(left-aligns with the longest line centered).
-T}
-\&.DS C        \&.CD   Centers all lines in the display.
-\&.DS R        \&.RD   Right-aligns all lines in the display.
-.TE
 .
 .
 .LP
-Use the
-.CW .DE
-macro to end any display type.
-.
-.
-.PP
-The distance stored in
-.CW \[rs]n[DD]
-is inserted before and after each pair of display macros.
-.
-This is a Berkeley extension.
-.
-.
-.PP
-The
-.CW \[rs]n[DI]
-indentation is applied to only to displays created with
-.CW ".DS I" \[rq] \[lq]
-and
-.CW .ID .
-.
-Changes take effect at the next display boundary.
+On occasion,
+you may want to
+.I 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 is a GNU extension.
+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.
 .
-.PP
-On occasion, you may want to
-.I 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
 .I ms
 macros provide the
-.CW .KS
+.CW KS
 and
-.CW .KE
+.CW KE
 macros for this purpose.
-The
-.CW .KS
-macro begins a block of text to be kept on a single page,
-and the
-.CW .KE
-macro ends the block.
+.
+.
 .PP
-You can specify a
+You can alternatively specify a
 .I "floating keep" ;
-if the keep cannot fit on the current page,
-.I 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.
+if a keep cannot fit on the current page,
+.I 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 an explicit
-.CW .bp
+.CW bp
 request or by reaching the end of the page,
-.I 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.
-Use the
-.CW .KF
-and
-.CW .KE
-macros to specify a floating keep.
+.I 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.
+.
+.
+.TS
+box;
+cb cb
+lf(CR) lx .
+Macro  Description
+_
+\&.KS  Begin a keep.
+\&.KF  Begin a floating keep.
+_
+\&.KE  End (floating) keep.
+.TE
 .
 .
 .PP
@@ -1760,9 +1705,17 @@ the
 request forces a page break if there is not at least the amount of
 vertical space specified in its argument remaining on the page.
 .
+One application of
+.CW ne
+is to reserve space on the page for a figure or illustration to be
+included later.
+.
 .
 .PP
-Use the following macros to draw a box around a region of the page.
+A keep can also be
+.I boxed .
+.
+Text in a box is automatically placed in a diversion (keep).
 .
 .
 .TS
@@ -1777,7 +1730,7 @@ _
 .
 .
 .LP
-These macros cause line breaks;
+Box macros cause line breaks;
 if you need to box a word or phrase within a line,
 see the
 .CW BX
@@ -1800,12 +1753,96 @@ lf(CR).
 \&.LP
 \&.B1
 \&.I Warning:
-Happy Fun Ball may suddenly accelerate to lethal speeds.
+Happy Fun Ball may suddenly accelerate to dangerous speeds.
 \&.sp \[rs]n[PD]/2
 \&.B2
 .TE
 .
 .
+.LP
+If you want a box to float,
+you will need to enclose the
+.CW .B1
+and
+.CW .B2
+calls within a pair of
+.CW .KF
+and
+.CW .KE
+calls.
+.
+.
+.PP
+.I Displays
+turn off filling;
+lines of verse or program code are shown with their lines broken as in
+the source document without requiring
+.CW br
+requests between lines.
+.
+Displays can be kept on a single page or allowed to break across pages.
+.
+The
+.CW 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.
+.
+.
+.TS
+box;
+cb s | cb
+cb cb | ^
+lf(CR) lf(CR) | lx .
+Display macro  Description
+With keep      Without keep
+_
+\&.DS L        \&.LD   Begin left-aligned display.
+\&.DS I \f[R][\,\f[I]indent\/\f[]]     \
+\&.ID \f[R][\,\f[I]indent\/\f[]]       T{
+Begin display indented by
+.I indent
+if given,
+.CW \[rs]n[DI]
+otherwise.
+T}
+\&.DS B        \&.BD   T{
+Begin block display
+(left-aligned with longest line centered).
+T}
+\&.DS C        \&.CD   Begin centered display.
+\&.DS R        \&.RD   Begin right-aligned display.
+_
+.T&
+cf(CR) s | lx .
+\&.ED  End any display.
+.TE
+.
+.
+.PP
+The distance stored in
+.CW \[rs]n[DD]
+is inserted before and after each pair of display macros.
+.
+This is a Berkeley extension.
+.
+.
+.PP
+The
+.CW \[rs]n[DI]
+indentation is applied to only to displays created with
+.CW ".DS I" \[rq] \[lq]
+and
+.CW .ID .
+.
+This is a GNU extension.
+.
+.
+.PP
+Changes to either register take effect at the next display boundary.
+.
+.
 .\" ----------------------------
 .KS
 .NH 2
@@ -2327,6 +2364,25 @@ You can replace the neutral apostrophes (\[aq]) with any 
character not
 appearing in the header or footer text.
 .
 .
+.PP
+You can redefine the
+.CW PT
+and
+.CW BT
+macros to change the behavior of
+the header and footer,
+respectively.
+.
+The header process also calls the (undefined)
+.CW HD
+macro after
+.CW .PT ;
+you can define this macro if you need additional processing after
+printing the header
+(for example,
+to draw a line below the header).
+.
+.
 .TS
 box;
 lb lb
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 8986516..2fb7753 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -975,17 +975,17 @@ as a subscript.
 .SS "Indented regions"
 .\" ====================================================================
 .
-You may need to indent a region of text while still wrapping and
-filling.
+You may need to indent a region of text while still letting
+.I groff
+automatically break lines and fill the text.
 .
 .
 .TP
 .B .RS
-Begin a region indented by
-.BR \[rs]n[PI] ,
-affecting the placement of headings,
+Begin a region where headings,
 paragraphs,
-and displays.
+and displays are indented by
+.BR \[rs]n[PI] .
 .
 .
 .TP
@@ -993,154 +993,207 @@ and displays.
 End the most recent indented region.
 .
 .
-.PP
-You can use
-.BR .RS / .RE
-regions to line up text under hanging and indented paragraphs.
+.\" ====================================================================
+.SS "Keeps, boxed keeps, and displays"
+.\" ====================================================================
 .
-For example,
-you may wish to nest lists.
+On occasion,
+you may want to
+.I 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.
 .
-.\" ====================================================================
-.SS "Displays and keeps"
-.\" ====================================================================
 .
-Use displays to show text-based examples or figures
-(such as code listings).
+.P
+You can alternatively specify a
+.IR "floating keep" ;
+if a keep cannot fit on the current page,
+.I ms
+holds its contents and allows text following the keep
+(in the source document)
+to fill in the remainder of the current page.
 .
-Displays turn off filling, so lines of code can be displayed as-is
-without inserting
-.B br
-requests in between each line.
+When the page breaks,
+whether by an explicit
+.B bp
+request or by reaching the end of the page,
+.I ms
+puts the floating keep at the beginning of the next page.
 .
-Displays can be
-.I kept
-on a single page, or allowed to break across pages.
 .
-The following table shows the display types available.
+.TP
+.B .KS
+Begin a keep.
 .
-.RS
-.ne 11v
-.TS
-cb   s    cbt
-cb   cb   ^
-lfCR lfCR lx.
-Display macro  Type of display
-With keep      No keep
-_
-\&.DS L        \&.LD   Left-justified.
-\&.DS I \f[R][\,\f[I]indent\/\f[]]     \
-\&.ID \f[R][\,\f[I]indent\/\f[]]       T{
-Indented
-(by
-.I indent
-if given,
-otherwise the value of
-.BR \[rs]n[DI] ).
-T}
-\&.DS B        \&.BD   T{
-Block-centered (left-justified, longest line centered).
-T}
-\&.DS C        \&.CD   Centered.
-\&.DS R        \&.RD   Right-justified.
-_
-.TE
-.RE
 .
-.LP
-Use the
-.B DE
-macro to end any display type.
+.TP
+.B .KF
+Begin a floating keep.
 .
 .
-.PP
-The distance stored in
-.B \[rs]n[DD]
-is inserted before and after each pair of display macros.
+.TP
+.B .KE
+End (floating) keep.
 .
-This is a Berkeley extension.
+.
+.P
+As an alternative to the keep mechanism,
+the
+.B 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.
 .
 .
 .PP
-The
-.B \[rs]n[DI]
-indentation is applied to only to displays created with
-.RB \[lq] ".DS I" \[rq]
-and
-.BR .ID .
+A keep can also be boxed.
 .
-Changes take effect at the next display boundary.
+Text in a box is automatically placed in a diversion (keep).
 .
-This is a GNU extension.
 .
+.TP
+.B .B1
+Begin a keep with a box drawn around it.
 .
-.PP
-To
-.I keep
-text together on a page,
-such as
-a paragraph that refers to a table (or list, or other item)
-immediately following, use the
-.B KS
+.
+.TP
+.B .B2
+End boxed keep.
+.
+.
+.P
+Box macros cause line breaks;
+if you need to box a word or phrase within a line,
+see the
+.B BX
+macro in section \[lq]Highlighting\[rq] above.
+.
+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
+.B .B1
+after the first paragraphing macro,
+and by adding a small amount of vertical space before calling
+.B .B2 .
+.
+.
+.P
+If you want a box to float,
+you will need to enclose the
+.B .B1
 and
-.B KE
-macros.
+.B .B2
+calls within a pair of
+.B .KF
+and
+.B .KE
+calls.
+.
+.
+.P
+.I Displays
+turn off filling;
+lines of verse or program code are shown with their lines broken as in
+the source document without requiring
+.B br
+requests between lines.
+.
+Displays can be kept on a single page or allowed to break across pages.
 .
 The
-.B KS
-macro begins a block of text to be kept on a single page,
-and the
-.B KE
-macro ends the block.
+.B 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.
 .
 .
-.PP
-You can specify a
-.I floating keep
-using the
-.B KF
-and
-.B KE
-macros.
+.TP
+.B .DS L
+.TQ
+.B .LD
+Begin
+.RB ( DS ": kept)"
+left-aligned display.
 .
-If the keep cannot fit on the current page,
-.I 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
-.B bp
-request or by reaching the end of the page,
-.I groff
-prints the floating keep at the top of the new page.
+.TP
+.B .DS I \c
+.RI [ indent ]
+.TQ
+.B ID \c
+.RI [ indent ]
+Begin
+.RB ( DS ": kept)"
+display indented by
+.I indent
+if specified,
+.B \[rs]n[DI]
+otherwise.
 .
-This is useful for printing large graphics or tables
-that do not need to appear exactly where specified.
 .
+.TP
+.B .DS B
+.TQ
+.B .BD
+Begin
+.RB ( DS ": kept)"
+block display:
+the entire display is left-aligned,
+but indented such that the longest line in the display is centered on
+the page.
 .
-.PP
-Use the following macros to draw a box around a region of the page.
+.
+.TP
+.B .DS C
+.TQ
+.B .CD
+Begin
+.RB ( DS ": kept)"
+centered display:
+each line in the display is centered.
 .
 .
 .TP
-.B .B1
-Begin a keep with a box drawn around it.
+.B .DS R
+.TQ
+.B .RD
+Begin
+.RB ( DS ": kept)"
+right-aligned display.
 .
 .
 .TP
-.B .B2
-End boxed keep.
+.B .ED
+End any display.
 .
 .
-.PP
-These macros cause line breaks;
-if you need to box a word or phrase within a line,
-see the
-.B BX
-macro in section \[lq]Highlighting\[rq] above.
+.P
+The distance stored in
+.B \[rs]n[DD]
+is inserted before and after each pair of display macros.
+.
+This is a Berkeley extension.
+.
+.
+.P
+The
+.B \[rs]n[DI]
+indentation is applied only to displays created with
+.RB \[lq] ".DS I" \[rq]
+and
+.B .ID .
+.
+This is a GNU extension.
+.
+.
+.P
+Changes to either register take effect at the next display boundary.
 .
 .
 .\" ====================================================================