[groff] 29/34: [sboxes]: Editorially revise msboxes.ms.in.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0c1db8b2effa9e7d5019fef1cefa07d7079a672f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Oct 17 12:08:05 2021 +1100

    [sboxes]: Editorially revise msboxes.ms.in.
    
    * contrib/sboxes/msboxes.ms.in: Revise.
      - Define and use `Qq` and `Lt` macros for quotation and code literals.
      - Use \[rs] instead of \e.
      - Set metasyntactic variables in italics.
      - Capitalize "PDF" when referring to the file format.
      - Use a paragraph distance of zero in uninterrupted list of paragraph
        tags (like using `TP`/`TQ` in man(7)).
      - Escape hyphen-minus used as example of input.
      - Pull the caveat about the spacing of boxes interrupted by page
        breaks into a footnote.  Ironically for me, this arguably obviates
        the need for the "Schrödinger's footnote" used later, but I'm
        leaving the latter intact in the event future revisions eliminate
        this footnote or move it prior to the code box.
      - Make usage and validity clarifications.
---
 contrib/sboxes/msboxes.ms.in | 222 +++++++++++++++++++++++++++++--------------
 1 file changed, 152 insertions(+), 70 deletions(-)

diff --git a/contrib/sboxes/msboxes.ms.in b/contrib/sboxes/msboxes.ms.in
index 1377316..1aa785a 100644
--- a/contrib/sboxes/msboxes.ms.in
+++ b/contrib/sboxes/msboxes.ms.in
@@ -12,6 +12,19 @@
 .EF ''''
 .OH 'Using PDF boxes with the \f[I]ms\f[] macros''%'
 .OF ''''
+.\" Define a quotation macro.
+.de Qq
+.  nop \[lq]\\$1\[rq]\\$2
+..
+.\" Define a macro for code literals; use bold and disable hyphenation.
+.de Lt
+.  ft B
+.  nh
+.  nop \&\\$1\c
+.  hy \\n[HY]
+.  ft
+.  nop \&\\$2
+..
 .ds FAM H
 .TL
 Using PDF boxes with the
@@ -30,9 +43,9 @@ document formatting system,
 allows coloured rectangles to be created beneath any output created by
 .I groff .
 The extension can be accessed via a device control escape sequence
-.B \eX\[aq]pdf:\[aq]
+.Lt \[rs]X\[aq]pdf:\[aq]
 (with a convenience command
-.B pdfbackground
+.Lt pdfbackground
 supporting the same parameters).
 .QS
 .BoxStart SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
@@ -40,120 +53,189 @@ supporting the same parameters).
 .pdfbackground pagefill
 \M[]\c
 .B
-\eX\[aq]pdf: background
+\[rs]X\[aq]pdf: background
 .BI
 cmd left top right bottom weight\[aq]
 .br
-.B .pdfbackground
+.Lt .pdfbackground
 .BI
 cmd left top right bottom weight
 .LP
-Where:-
-.IP cmd 7n
-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]".
+where
+.IP \f[I]cmd 7n
+can be any of
+.Qq page|fill|box
+in combination.
+So
+.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
+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
+.Lt \[rs]M[] )
+and including
+.Qq box
+will give the rectangle a border in the current stroke colour
+(as with
+.Lt \[rs]m[] ).
 .sp \n[PD]u
-The "cmd" may also be "off", on its own, which will terminate drawing
-the current box.
+.I cmd
+may also be
+.Qq off ,
+on its own, which will terminate drawing the current box.
 If you have specified a page colour with
-.B ".pdfbackground pagefill"
-it is always the first box in the stack, and if you specify it again it
+.Lt ".pdfbackground 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 which
-"watermark" pdf pages are unlikely to be successful.
-To return the background to transparent do a
-.B ".pdfbackground off"
+Be aware that the 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.
 .sp \n[PD]u
-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.\m[red]\**\m[]\" FOOTNOTE
+Finally, the command 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.
+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
 .FS
-If the value is negative it is used as an offset from the bottom of the
+If the value is negative, it is used as an offset from the bottom of the
 page.
 .FE
-.LP
-.IP left
-.IP top
-.IP right
-.IP bottom 7n
-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
+.nr oldPD \n[PD]
+.nr PD 0
+.IP \f[I]left
+.IP \f[I]top
+.IP \f[I]right
+.IP \f[I]bottom 7n
+.nr PD \n[oldPD]
+are the coordinates of the box.
+The
+.Qq top
+and
+.Qq 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 "off".
+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
 footer margins.
-.IP weight 7n
-If "box" is included in the command then this parameter provides the
-line width for the box border.
+.IP \f[I]weight 7n
+If
+.Qq box
+is included in the command, then this parameter provides the line width
+for the box border.
 .BoxStop
 .QE
-More convenience can be gained by including -msboxes on the
+For a more convenient interface, include
+.Lt \-msboxes
+on the
 .I groff
-command line which includes the macros "BoxStart" and "BoxStop".
+command line; the
+.I sboxes
+package defines the macros
+.Lt BoxStart
+and
+.Lt BoxStop .
 .QS
 .BoxStart SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
 .BoxStart SHADED cornsilk3 INDENT 2p
-.B .BoxStart
-.R SHADED
+.Lt .BoxStart
+.Lt SHADED
 .I colour
-.R OUTLINED
+.Lt OUTLINED
 .I colour
-.R INDENT
+.Lt INDENT
 .I size
-.R WEIGHT
+.Lt WEIGHT
 .I size
 .BoxStop
 .LP
-Where SHADED gives the fill colour and OUTLINED the border colour.
-Omit either to get a borderless filled box, or just a border with no
-fill.
-WEIGHT is used if the box is OUTLINED.
+where the argument after
+.Lt SHADED
+gives the fill colour and that after
+.Lt OUTLINED
+the border colour.
+Omit the former to get a borderless filled box and the latter for a
+border with no fill.
+The specified
+.Lt WEIGHT
+is used if the box is
+.Lt OUTLINED .
 .LP
-INDENT is a value which leaves a gap between the border and the contents
+.Lt INDENT
+precedes a value which leaves a gap between the border and the contents
 inside the box.
+.LP
+Each
+.I colour
+must be a defined
+.I groff
+colour name,
+and each
+.I size
+a valid
+.I groff
+numeric expression.
 .BoxStop
 .QE
-Boxes can stacked, so you can start a box within another box, usually
+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.
-If using the BoxStart macro the left position is the current indent
-minus the INDENT in the command, and the right position is the left
-position (calculated above) plus the current line length and twice the
-indent.
-The macro definition of .BoxStart above has been given a box without
-borders and a 2p indent.
+When using
+.Lt BoxStart ,
+the left position is the current indent minus the
+.Lt INDENT
+in the command,
+and the right position is the left position (calculated above) plus the
+current line length and twice the indent.
+The synopsis of
+.Lt BoxStart
+above itself uses a
+.Lt BoxStart
+call without borders and with a
+.Lt 2p
+(two point) indent.
 .QS
 .BoxStart SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
 .BoxStart SHADED cornsilk3 INDENT 2p
-.B .BoxStop
+.Lt .BoxStop
 .BoxStop
 .LP
-There are no parameters, it closes the last box at the current vertical
-position, after adding the Indent spacing.
+This macro takes no parameters.
+It closes the most recently started box at the current vertical position
+after adding its
+.Lt INDENT
+spacing.
 .BoxStop
 .QE
-This macro package has one further feature, it attempts to hook into the
-.I ms
+.I sboxes
+has one further feature: it hooks into the
+.I "groff ms"
 package to receive notifications when footnotes are growing, so that it
-can close boxes before the footnotes are printed.
-If there are footnotes on a page it will close current boxes 2p above
-the footnote separator, this probably will not match the indent amount
-requested.
+can close boxes on a page before footnotes are printed.
+When that condition obtains,
+.I sboxes
+will close open boxes two points\**
+.FS
+This amount probably will not match the box's
+.Lt INDENT .
+.FE
+above the footnote separator and re-open them on the next page.
 .LP
-The above was produced by the following code.
+This document was produced using the following code.
 .ds FAM C
 .nr PS 11
 .nr VS 13