[groff] 34/39: [docs]: Recast description of \b escape sequence.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 566260a62967fe43af385f09c7d1104b4ccfae61
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 31 16:25:56 2022 -0500

    [docs]: Recast description of \b escape sequence.
    
    Also reorganize to gather the formal description before the example.
    
    Move Texinfo @codequote* commands to mark this chunk of text as reviewed
    for correct glyph usage.
---
 doc/groff.texi  | 43 +++++++++++++++++++++++--------------------
 man/groff.7.man | 13 +++++--------
 2 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 1f0fbd19..c496c778 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -13706,39 +13706,42 @@ Examples:
 
 @xref{Graphics Commands}.
 
+@codequotebacktick on
+@codequoteundirected on
+
 @Defesc {\\b, @code{'}, string, @code{'}}
 @cindex pile, glyph (@code{\b})
 @cindex glyph pile (@code{\b})
 @cindex stacking glyphs (@code{\b})
-@dfn{Pile} a sequence of glyphs vertically, and center it vertically on
-the current line.  Use it to build large brackets and braces.
-
-Here is an example of how to create a large opening brace:
+Pile and center a sequence of glyphs vertically on the output line.
+@dfn{Piling} vertically stacks glyphs corresponding to each character in
+the argument @var{string}, read from left to right, and placed from top
+to bottom.  GNU @code{troff} separates the glyphs vertically by
+1@dmn{m}, and the pile itself is centered 0.5@dmn{m} above the text
+baseline.  The horizontal drawing position is then advanced by the width
+of the widest glyph in the pile.
+
+@cindex @code{\b}, limitations of
+@cindex limitations of @code{\b} escape sequence
+This rather inflexible positioning algorithm doesn't work with the
+@code{dvi} output device since its bracket pieces vary in height.
+Instead, use the @code{geqn} preprocessor.
+
+@xref{Manipulating Spacing}, to see how to adjust the vertical spacing
+of the output line with the @code{\x} escape sequence.
+
+The idiomatic use of @code{\b} is for building large brackets and
+braces, hence its name.  We might construct a large opening brace as
+follows.
 
 @Example
 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
 @endExample
-
-@cindex @code{\b}, limitations
-@cindex limitations of @code{\b} escape
-The first glyph is on the top, the last glyph in @var{string} is at the
-bottom.  GNU @code{troff} separates the glyphs vertically by 1@dmn{m},
-and the whole object is centered 0.5@dmn{m} above the current baseline;
-the largest glyph width is used as the width for the whole object.
-This rather inflexible positioning algorithm doesn't work with
-@option{-Tdvi} since the bracket pieces vary in height for this device.
-Instead, use the @code{eqn} preprocessor.
-
-@xref{Manipulating Spacing}, how to adjust the vertical spacing with the
-@code{\x} escape sequence.
 @endDefesc
 
 
 @c =====================================================================
 
-@codequotebacktick on
-@codequoteundirected on
-
 @node Deferring Output, Traps, Drawing Requests, gtroff Reference
 @section Deferring Output
 @cindex deferred output
diff --git a/man/groff.7.man b/man/groff.7.man
index 423d288c..d8478ef1 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3886,16 +3886,13 @@ environment,
 or font,
 and\~0 otherwise.
 .
-.
 .TP
-.ESCq b abc\fR\&.\|.\|.\&\fP
+.ESCq b string
 Build bracket:
-stack glyphs
-.IR a ,
-.IR b ,
-.IR c .\|.\|.\&
-vertically.
-.
+pile a sequence of glyphs corresponding to each character in
+.I string
+vertically,
+and center it vertically on the output line.
 .
 .TP
 .ESCq B anything