598 lines
14 KiB
Text
598 lines
14 KiB
Text
.\" groff -ms -msboxes -Tpdf
|
|
.
|
|
.\" Copyright 2021 Free Software Foundation, Inc.
|
|
.\" 2021 G. Branden Robinson
|
|
.\"
|
|
.\" Written by Deri James <deri@chuzzlewit.myzen.co.uk>
|
|
.\"
|
|
.\" This file is part of sboxes.
|
|
.\"
|
|
.\" sboxes is distributed with groff, the GNU roff typesetting system.
|
|
.\"
|
|
.\" groff is free software; you can redistribute it and/or modify it
|
|
.\" under the terms of the GNU General Public License as published by
|
|
.\" the Free Software Foundation, either version 3 of the License, or
|
|
.\" (at your option) any later version.
|
|
.\"
|
|
.\" groff is distributed in the hope that it will be useful, but WITHOUT
|
|
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
|
|
.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
|
|
.\" License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License
|
|
.\" along with this program. If not, see
|
|
.\" <http://www.gnu.org/licenses/>.
|
|
.
|
|
.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 extension 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
|
|
Produce a background rectangle on the page.
|
|
.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 that 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 that 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
|
|
\&.\[rs]" groff \-ms \-msboxes \-Tpdf
|
|
\&.
|
|
\&.\[rs]" Copyright 2021 Free Software Foundation, Inc.
|
|
\&.\[rs]" 2021 G. Branden Robinson
|
|
\&.\[rs]"
|
|
\&.\[rs]" Written by Deri James <deri@chuzzlewit.myzen.co.uk>
|
|
\&.\[rs]"
|
|
\&.\[rs]" This file is part of sboxes.
|
|
\&.\[rs]"
|
|
\&.\[rs]" sboxes is distributed with groff, the GNU roff typesetting system.
|
|
\&.\[rs]"
|
|
\&.\[rs]" groff is free software; you can redistribute it and/or modify it
|
|
\&.\[rs]" under the terms of the GNU General Public License as published by
|
|
\&.\[rs]" the Free Software Foundation, either version 3 of the License, or
|
|
\&.\[rs]" (at your option) any later version.
|
|
\&.\[rs]"
|
|
\&.\[rs]" groff is distributed in the hope that it will be useful, but WITHOUT
|
|
\&.\[rs]" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
|
|
\&.\[rs]" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
|
|
\&.\[rs]" License for more details.
|
|
\&.\[rs]"
|
|
\&.\[rs]" You should have received a copy of the GNU General Public License
|
|
\&.\[rs]" along with this program. If not, see
|
|
\&.\[rs]" <http://www.gnu.org/licenses/>.
|
|
\&.
|
|
\&.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 \[aq]%\[aq]\[aq]March 2021\[aq]
|
|
\&.EF \[aq]\[aq]\[aq]\[aq]
|
|
\&.OH \[aq]Using PDF boxes with \[rs]f[I]groff\[rs]f[] and the \[rs]f[I]ms\[rs]f[] macros\[aq]\[aq]%\[aq]
|
|
\&.OF \[aq]\[aq]\[aq]\[aq]
|
|
\&.\[rs]" Define a quotation macro.
|
|
\&.de Qq
|
|
\&. nop \[rs][lq]\[rs]\[rs]$1\[rs][rq]\[rs]\[rs]$2
|
|
\&..
|
|
\&.\[rs]" Define a macro for code literals; use bold and disable hyphenation.
|
|
\&.de Lt
|
|
\&. ft B
|
|
\&. nh
|
|
\&. nop \[rs]&\[rs]\[rs]$1\[rs]c
|
|
\&. hy \[rs]\[rs]n[HY]
|
|
\&. ft
|
|
\&. nop \[rs]&\[rs]\[rs]$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 extension escape sequence
|
|
\&.Lt "\[rs][rs]X\[rs][aq]pdf: background" \[rs]\[ti].\[rs]|.\[rs]|.\[rs]|\[rs]c
|
|
\&.Lt \[rs][aq]
|
|
or a convenience macro
|
|
\&.Lt pdfbackground
|
|
supporting the same parameters.
|
|
\&.QS
|
|
\&.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
|
|
\[rs]M[floralwhite]\[rs]c
|
|
\&.pdfbackground pagefill
|
|
\[rs]M[]\[rs]c
|
|
\&.B
|
|
\[rs][rs]X\[rs][aq]pdf: background
|
|
\&.BI
|
|
cmd left top right bottom weight\[rs][aq]
|
|
\&.br
|
|
\&.Lt .pdfbackground
|
|
\&.BI
|
|
cmd left top right bottom weight
|
|
\&.LP
|
|
Produce a background rectangle on the page.
|
|
\&.IP \[rs]f[I]cmd 8n \[rs]" 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 that 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][rs]M[\[rs]|] )
|
|
and including
|
|
\&.Qq box
|
|
will give the rectangle a border in the current stroke colour
|
|
(as with
|
|
\&.Lt \[rs][rs]m[\[rs]|] ).
|
|
\&.sp \[rs]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 \[rs]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).\[rs]m[red]\[rs]**\[rs]m[]\m[red]\**\m[]
|
|
.FS
|
|
This is a long footnote occupying multiple output lines.
|
|
Its only purpose is to verify that the bottom of the box on this page
|
|
has been adjusted upward to accommodate it.
|
|
.FE
|
|
\&.FS
|
|
If the value is negative, it is used as an offset from the bottom of the
|
|
page.
|
|
\&.FE
|
|
\&.nr oldPD \[rs]n[PD]
|
|
\&.nr PD 0
|
|
\&.IP \[rs]f[I]left
|
|
\&.IP \[rs]f[I]top
|
|
\&.IP \[rs]f[I]right
|
|
\&.IP \[rs]f[I]bottom
|
|
\&.nr PD \[rs]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 \[aq]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 \[rs]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 \[rs]\-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 that 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\[rs]**
|
|
\&.FS
|
|
This amount probably will not match the box\[aq]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
|
|
\[rs]# (replaced by source of this document)
|
|
\&.BOXSTOP
|
|
\&.\[rs]" Local Variables:
|
|
\&.\[rs]" mode: nroff
|
|
\&.\[rs]" fill\-column: 72
|
|
\&.\[rs]" End:
|
|
\&.\[rs]" vim: set filetype=groff textwidth=72:
|
|
\# REPLACEME
|
|
.BOXSTOP
|
|
.\" Local Variables:
|
|
.\" mode: nroff
|
|
.\" fill-column: 72
|
|
.\" End:
|
|
.\" vim: set filetype=groff textwidth=72:
|