[groff] 12/12: [ms]: Improve documentation of .B1/.B2.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2f832ab366a82cbc807bb40728d12190238128a0
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu May 6 18:49:14 2021 +1000

    [ms]: Improve documentation of .B1/.B2.
    
    * doc/ms.ms (Displays and keeps):
    * tmac/groff_ms.7.man (Displays and keeps): Document the .B1 and .B2
      macros on par with other macros.  Mention that they cause breaks.
    
    * doc/groff.texi (ms Displays and Keeps):
    * doc/ms.ms (Displays and keeps): Elaborate usage of .ne request.  Add
      example of paragraph boxed with .B1 and .B2.
---
 doc/groff.texi      | 25 ++++++++++++++++++----
 doc/ms.ms           | 60 +++++++++++++++++++++++++++++++++++++++++++++++++----
 tmac/groff_ms.7.man | 32 +++++++++++++++++-----------
 3 files changed, 97 insertions(+), 20 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 5c02b1a..16857bd 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3597,17 +3597,34 @@ large graphics or tables that do not need to appear 
exactly where
 specified.
 @endDefmac
 
-You can also use the @code{ne} request to force a page break if there is
-not enough vertical space remaining on the page.
+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}).
 
-Use the following macros to draw a box around a region of text (such as
-a display).
+Use the following macros to draw a box around a region of the page.
 
 @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}.
+
+@CartoucheExample
+.LP
+.B1
+.I Warning:
+Happy Fun Ball may suddenly accelerate to lethal speeds.
+.sp \n[PD]/2
+.B2
+@endCartoucheExample
 @endDefmac
 
 @c ---------------------------------------------------------------------
diff --git a/doc/ms.ms b/doc/ms.ms
index bdf4b16..8f1a860 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -1735,11 +1735,63 @@ Use the
 and
 .CW .KE
 macros to specify a floating keep.
+.
+.
+.PP
+As an alternative to the keep mechanism,
+the
+.CW 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
-You can also use the
-.CW .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 region of the page.
+.
+.
+.TS
+box;
+cb cb
+lf(CR) lx .
+Macro  Description
+_
+\&.B1  Begin a keep with a box drawn around it.
+\&.B2  End boxed keep.
+.TE
+.
+.
+.LP
+These macros cause line breaks;
+if you need to box a word or phrase within a line,
+see the
+.CW 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
+.CW .B1
+after the first paragraphing macro,
+and by adding a small amount of vertical space before calling
+.CW .B2 .
+.
+.
+.TS
+box center;
+lf(CR).
+\&.LP
+\&.B1
+\&.I Warning:
+Happy Fun Ball may suddenly accelerate to lethal speeds.
+\&.sp \[rs]n[PD]/2
+\&.B2
+.TE
+.
+.
 .\" ----------------------------
 .KS
 .NH 2
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 8fe90e0..00b5166 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1097,18 +1097,26 @@ that do not need to appear exactly where specified.
 .
 .
 .PP
-The macros
-.B B1
-and
-.B B2
-can be used to enclose a text within a box;
-.B .B1
-begins the box, and
-.B .B2
-ends it.
-.
-Text in the box is automatically placed in a diversion
-(keep).
+Use the following macros to draw a box around a region of the page.
+.
+.
+.TS
+box;
+cb cb
+lf(CR) lx .
+Macro  Description
+_
+\&.B1  Begin a keep with a box drawn around it.
+\&.B2  End boxed keep.
+.TE
+.
+.
+.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.
 .
 .
 .\" ====================================================================