[groff] 12/14: [sboxes]: Tighten and integrate documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 9ac276e875744f17aab58827425ab45db14491e8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jan 24 18:33:59 2022 +1100

    [sboxes]: Tighten and integrate documentation.
    
    Adapt Deri's ms(7) article into man(7) content.
    
    * contrib/sboxes/msboxes.ms.in: Fix style nits.  Tighten wording.
    
    * man/groff_tmac.5.man (Auxiliary packages) <sboxes>: Add documentation
      of macro interface (macros BOXSTART and BOXSTOP, and register GSBOX).
    
    * src/devices/gropdf/gropdf.1.man (Usage): Revise style to more closely
      follow our man page conventions.  Add cross reference to
      groff_tmac(5).
    
      (See also): Add cross reference to Deri's article.
---
 contrib/sboxes/msboxes.ms.in    |  51 +++++++------
 man/groff_tmac.5.man            | 114 ++++++++++++++++++++++++++++-
 src/devices/gropdf/gropdf.1.man | 157 +++++++++++++++++++++++++++++++---------
 3 files changed, 263 insertions(+), 59 deletions(-)

diff --git a/contrib/sboxes/msboxes.ms.in b/contrib/sboxes/msboxes.ms.in
index e827fbdb..34487a13 100644
--- a/contrib/sboxes/msboxes.ms.in
+++ b/contrib/sboxes/msboxes.ms.in
@@ -70,17 +70,17 @@ each produce a background rectangle on the page, where
 is the command, which can be any of
 .Qq page|fill|box
 in combination.
-So
+Thus,
 .Qq pagefill
-would draw a rectangle which covers whole current page size (in which
-case the rest of the parameters can be omitted because the box
+would draw a rectangle which covers the whole current page size (in
+which case the rest of the parameters can be omitted because the box
 dimensions are taken from the current media size).
 .Qq boxfill ,
 on the other hand, requires the given dimensions to place the box.
 Including
 .Qq fill
-in the command will fill the rectangle with the current background
-colour (as with
+in the command will paint the rectangle with the current fill colour (as
+with
 .Lt \[rs]M[] )
 and including
 .Qq box
@@ -90,24 +90,28 @@ will give the rectangle a border in the current stroke 
colour
 .sp \n[PD]u
 .I cmd
 may also be
-.Qq off ,
+.Qq off
 on its own, which will terminate drawing the current box.
 If you have specified a page colour with
-.Lt ".pdfbackground pagefill"
+.Qq pagefill ,
 it is always the first box in the stack, and if you specify it again, it
 will replace the first entry.
-Be aware that the pagefill box renders the page opaque, so tools that
+Be aware that the
+.Qq pagefill
+box renders the page opaque, so tools that
 .Qq watermark
 PDF pages are unlikely to be successful.
-To return the background to transparent, do a
-.Lt ".pdfbackground off"
-with no other boxes open.
+To return the background to transparent, issue an
+.Qq off
+command with no other boxes open.
 .sp \n[PD]u
-Finally, the command may be
+Finally,
+.I cmd
+may be
 .Qq footnote
 followed by a new value for
-.I bottom
-which will be used for all current boxes, just for the current page.
+.I bottom ,
+which will be used for all open boxes on the current page.
 This is to allow room for footnote areas that grow while a page is
 processed (to accommodate multiple footnotes,
 for instance).\m[red]\**\m[]\" FOOTNOTE
@@ -124,17 +128,17 @@ page.
 .nr PD \n[oldPD]
 are the coordinates of the box.
 The
-.Qq top
+.I top
 and
-.Qq bottom
+.I bottom
 coordinates are the minimum and maximum for the box, since the actual
-start of the box is the vertical position of
-.I groff
-when you issue the command and the bottom of the box is the point where
-you turn the box
+start of the box is
+.I groff 's
+drawing position when you issue the command, and the bottom of the box
+is the point where you turn the box
 .Qq off .
-The top and bottom coordinates are only used if the box drawing extends
-onto the next page, so, ordinarily they would be set to the header and
+The top and bottom coordinates are used only if the box drawing extends
+onto the next page; ordinarily, they would be set to the header and
 footer margins.
 .IP \f[I]weight
 provides the line width for the border if
@@ -166,6 +170,7 @@ and
 .I size
 .BOXSTOP
 .LP
+begins a box,
 where the argument after
 .Lt SHADED
 gives the fill colour and that after
@@ -218,7 +223,7 @@ call without borders and with a
 .Lt .BOXSTOP
 .BOXSTOP
 .LP
-This macro takes no parameters.
+takes no parameters.
 It closes the most recently started box at the current vertical position
 after adding its
 .Lt INDENT
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index a9bbe75d..6f2ce89b 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -7,7 +7,7 @@ groff_tmac \- macro files in the GNU roff typesetting system
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 2000-2021 Free Software Foundation, Inc.
+.\" Copyright (C) 2000-2022 Free Software Foundation, Inc.
 .\"
 .\" This file is part of groff, the GNU roff typesetting system.
 .\"
@@ -716,6 +716,116 @@ documents can draw colored rectangles beneath any output;
 it further includes special support for
 .IR "groff ms" .
 .
+.RS
+.TP
+.B .BOXSTART \c
+.B SHADED \c
+.I colour \c
+.B OUTLINED \c
+.I colour \c
+.B INDENT \c
+.I size \c
+.B WEIGHT \c
+.I size
+begins a box,
+where the argument after
+.B SHADED
+gives the fill colour and that after
+.B OUTLINED
+the border colour.
+.
+Omit the former to get a borderless filled box and the latter for a
+border with no fill.
+.
+The specified
+.B WEIGHT
+is used if the box is
+.BR OUTLINED .
+.
+.
+.IP
+.B INDENT
+precedes a value which leaves a gap between the border and the contents
+inside the box.
+.
+.
+.IP
+Each
+.I colour
+must be a defined
+.I groff
+colour name,
+and each
+.I size
+a valid
+.I groff
+numeric expression.
+.
+The keyword/value pairs can be specified in any order.
+.RE
+.
+.
+.IP
+Boxes can be stacked,
+so you can start a box within another box;
+usually the later boxes would be smaller than the containing box,
+but this is not enforced.
+.
+When using
+.BR BOXSTART ,
+the left position is the current indent minus the
+.B INDENT
+in the command,
+and the right position is the left position
+(calculated above)
+plus the current line length and twice the indent.
+.
+.
+.RS
+.TP
+.B .BOXSTOP
+takes no parameters.
+.
+It closes the most recently started box at the current vertical position
+after adding its
+.B INDENT
+spacing.
+.RE
+.
+.
+.IP
+Your
+.I groff
+documents can conditionally exercise the
+.I sboxes
+.
+macros.
+The register
+.B GSBOX
+is defined if the package is loaded,
+and interpolates a true value if the
+.B pdf
+output device is in use.
+.
+.
+.IP
+.I sboxes
+has one further feature:
+it hooks into the
+.MR groff_ms @MAN7EXT@
+package to receive notifications when footnotes are growing,
+so that it can close boxes on a page before footnotes are printed.
+.
+When that condition obtains,
+.I sboxes
+will close open boxes two points
+above the footnote separator and re-open them on the next page.
+.
+(This amount probably will not match the box's
+.BR INDENT .)
+.
+.
+.IP
 See
 .UR file://\%@DOCDIR@/\:msboxes\:.pdf
 \[lq]Using PDF boxes with
@@ -724,7 +834,7 @@ and the
 .I ms
 macros\[rq]
 .UE
-for instructions and a demonstration.
+for a demonstration.
 .
 .
 .TP
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index 633568a7..ca35c3a9 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -7,7 +7,7 @@ gropdf \- groff output driver for Portable Document Format
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 2011-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 2011-2022 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -1149,27 +1149,85 @@ not all PDF Readers support any or all these 
transitions.
 .
 .
 .TP
-.BI "\eX'pdf: background " "cmd left top right bottom weight" \[aq]
-Where:-
+.BI "\eX\[aq]pdf: background\~" "cmd left top right bottom weight" \[aq]
+.TQ
+.B "\eX\[aq]pdf: background off\[aq]"
+.TQ
+.BI "\eX\[aq]pdf: background footnote\~" bottom \[aq]
+produces a background rectangle on the page,
+where
 .RS
 .TP
 .I cmd
-Can be any of "page|fill|box" in combination. So "pagefill" would draw a
-rectangle which covers whole current page size (in which case the rest of the
-parameters can be omitted because the box dimensions are taken from the
-current media size). "boxfill", on the other hand, requires the given
-dimensions to place the box. Including "fill" in the command will make the
-rectangle filled with the current background colour "\eM[colour]" and including
-"box" will give the rectangle a border in the current stroke colour
-"\em[colour]".
-.sp .5v
-The "cmd" may also be "off", on its own, which will terminate drawing the
-current box.
-.sp .5v
-Finally the command may be "footnote" followed by a new value for "bottom"
-which will be used for all current boxes, just for the current page. This is
-to allow room for footnotes which grow during the page.
-.LP
+is the command,
+which can be any of
+.RB \[lq] page | fill | box \[rq]
+in combination.
+.
+Thus,
+.RB \[lq] pagefill \[rq]
+would draw a rectangle which covers the whole current page size
+(in which case the rest of the parameters can be omitted because the box
+dimensions are taken from the current media size).
+.
+.RB \[lq] boxfill \[rq],
+on the other hand,
+requires the given dimensions to place the box.
+.
+Including
+.RB \[lq] fill \[rq]
+in the command will paint the rectangle with the current fill colour
+(as with
+.BR \[rs]M[] )
+and including
+.RB \[lq] box \[rq]
+will give the rectangle a border in the current stroke colour
+(as with
+.BR \[rs]m[] ).
+.
+.
+.IP
+.I cmd
+may also be
+.RB \[lq] off \[rq]
+on its own,
+which will terminate drawing the current box.
+.
+If you have specified a page colour with
+.RB \[lq] pagefill \[rq],
+it is always the first box in the stack,
+and if you specify it again,
+it will replace the first entry.
+.
+Be aware that the
+.RB \[lq]  pagefill \[rq]
+box renders the page opaque,
+so tools that \[lq]watermark\[rq] PDF pages are unlikely to be
+successful.
+.
+To return the background to transparent,
+issue an
+.RB \[lq] off \[rq]
+command with no other boxes open.
+.
+.
+.IP
+Finally,
+.I cmd
+may be
+.RB \[lq] footnote \[rq]
+followed by a new value for
+.IR bottom ,
+which will be used for all open boxes on the current page.
+This is to allow room for footnote areas that grow while a page is
+processed
+(to accommodate multiple footnotes,
+for instance).
+.
+(If the value is negative,
+it is used as an offset from the bottom of the page.)
+.
+.
 .TP
 .I left
 .TQ
@@ -1178,24 +1236,43 @@ to allow room for footnotes which grow during the page.
 .I right
 .TQ
 .I bottom
-Are the coordinates of the box. The "top" and "bottom" coordinates are
-the minimum and maximum for the box, since the actual start of the
-box is the vertical position of groff when you issue the command and the 
bottom of
-the box is the point where you turn the box "off". The top and bottom
-coordinates are only used if the box drawing extends onto the next page, so,
-ordinarily they would be set to the header and footer margins.
+are the coordinates of the box.
+.
+The
+.I top
+and
+.I bottom
+coordinates are the minimum and maximum for the box,
+since the actual start of the box is
+.IR groff 's
+drawing position when you issue the command,
+and the bottom of the box is the point where you turn the box
+.RB \[lq] off \[rq].
+.
+The top and bottom coordinates are used only if the box drawing extends
+onto the next page;
+ordinarily,
+they would be set to the header and footer margins.
+.
+.
 .TP
 .I weight
-If "box" is included in the command then this parameter provides the line width
-for the box border.
-.RE
-The convenience macro for this escape is
+provides the line width for the border if
+.RB \[lq] box \[rq]
+is included in the command.
+.
+.
+.P
+The convenience macro for this escape sequence is
 .BR .pdfbackground .
-.LP
-There is also a macro file which can be included if you are using the ms macro
-package which can be incorporated by placing -msboxes on the
-.B groff
-command line.
+.
+An
+.I sboxes
+macro file is also available;
+see
+.MR groff_tmac @MAN5EXT@.
+.RE
+.
 .
 .\" ====================================================================
 .SS "Importing graphics"
@@ -1467,6 +1544,18 @@ automatically loaded by
 .SH "See also"
 .\" ====================================================================
 .
+.TP
+.I \%@DOCDIR@/\:sboxes/\:msboxes\:.ms
+.TQ
+.I \%@DOCDIR@/\:sboxes/\:msboxes\:.pdf
+\[lq]Using PDF boxes with
+.I groff
+and the
+.I ms
+macros\[rq],
+by Deri James.
+.
+.
 .MR afmtodit @MAN1EXT@ ,
 .MR groff @MAN1EXT@ ,
 .MR @g@troff @MAN1EXT@ ,