diff options
Diffstat (limited to 'contrib/sboxes/msboxes.ms.in')
| -rw-r--r-- | contrib/sboxes/msboxes.ms.in | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/contrib/sboxes/msboxes.ms.in b/contrib/sboxes/msboxes.ms.in new file mode 100644 index 0000000..a1700df --- /dev/null +++ b/contrib/sboxes/msboxes.ms.in @@ -0,0 +1,272 @@ +.\" groff -ms -msboxes -Tpdf +.nr LL 17c +.nr PO 2c +.nr PS 11 +.nr VS 13 +.nr PI 3.5n +.nr HM 2c +.nr FM 2c +.nr QI 7n +.ss 12 0 +.ND March 2021 +.EH '%''March 2021' +.EF '''' +.OH 'Using PDF boxes with \f[I]groff\f[] and 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 +.BI groff +and the +.BI ms +macros +.AU +Deri James +.AI +deri@chuzzlewit.myzen.co.uk +.LP +An extension in version 1.23.0 of +.I gropdf , +the PDF output driver for the +.I groff +document formatting system, +allows coloured rectangles to be placed beneath any output created by +.I groff . +The extension can be accessed via a device control escape sequence +.Lt "\[rs]X\[aq]pdf: background" \~.\|.\|.\|\c +.Lt \[aq] +or a convenience macro +.Lt pdfbackground +supporting the same parameters. +.QS +.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p +\M[floralwhite]\c +.pdfbackground pagefill +\M[]\c +.B +\[rs]X\[aq]pdf: background +.BI +cmd left top right bottom weight\[aq] +.br +.Lt .pdfbackground +.BI +cmd left top right bottom weight +.LP +each produce a background rectangle on the page, where +.IP \f[I]cmd 8n \" indent enough to fit "bottom" tag +is the command, which can be any of +.Qq page|fill|box +in combination. +Thus, +.Qq pagefill +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 paint the rectangle with the current fill 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 +.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 +.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 +.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, issue an +.Qq off +command with no other boxes open. +.sp \n[PD]u +Finally, +.I cmd +may be +.Qq footnote +followed by a new value for +.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 +.FS +If the value is negative, it is used as an offset from the bottom of the +page. +.FE +.nr oldPD \n[PD] +.nr PD 0 +.IP \f[I]left +.IP \f[I]top +.IP \f[I]right +.IP \f[I]bottom +.nr PD \n[oldPD] +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 +.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 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 +.Qq box +is included in the command. +.BOXSTOP +.QE +For an even more convenient interface, include +.Lt \-msboxes +on the +.I groff +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 +.Lt .BOXSTART +.Lt SHADED +.I colour +.Lt OUTLINED +.I colour +.Lt INDENT +.I size +.Lt WEIGHT +.I size +.BOXSTOP +.LP +begins a box, +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 +.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. +The keyword/value pairs can be specified in any order. +.BOXSTOP +.QE +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 +.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 +.Lt .BOXSTOP +.BOXSTOP +.LP +takes no parameters. +It closes the most recently started box at the current vertical position +after adding its +.Lt INDENT +spacing. +.BOXSTOP +.QE +Your +.I groff +documents can conditionally exercise the +.I sboxes +macros. +The register +.Lt GSBOX +is defined if the package is loaded, and interpolates a true value if +the +.Lt pdf +output device is in use. +.LP +.I sboxes +furthermore hooks into the +.I "groff ms" +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\** +.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 +This document was produced using the following code. +.ds FAM C +.nr PS 11 +.nr VS 13 +.LP +.BOXSTART SHADED white OUTLINED brown INDENT 2n WEIGHT 1p +.nf +\# REPLACEME +.BOXSTOP +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 72 +.\" End: +.\" vim: set filetype=groff textwidth=72: |