Using PDF bo
xes with
groff
and
the
ms
macr
os
Deri James
deri@chuzzlewit.m
yzen.co
.uk
An
e
xtension
in
v
ersion
1.23.0
of
gropdf
,
the
PDF
output
driver
f
or
the
groff
document
f
or
matting
system,
allows
coloured
rectangles
to
be
placed
beneath
any
output
created
b
y
groff
.
The
e
xten-
sion
can
be
accessed
via
a
de
vice
e
xtension
escape
sequence
\X'pdf:
bac
kgr
ound
.
.
.
'
or
a
con-
v
enience macro
pdfbac
kgr
ound
suppor
ting the same parameters
.
\X'pdf: bac
kgr
ound
cmd left top right bottom weight'
.pdfbac
kgr
ound
cmd left top right bottom weight
Produce a bac
kground rectangle on the page
.
cmd
is
the
command,
which
can
be
any
of
“page|fill|bo
x”
in
combination.
Thus,
“pagefill”
would
dra
w
a
rectangle
that
cov
ers
the
whole
current
page
size
(in
which
case
the
rest
of
the
parameters
can
be
omitted
because
the
bo
x
di-
mensions
are
tak
en
from
the
current
media
size).
“bo
xfill”,
on
the
other
hand,
requires
the
giv
en
dimensions
to
place
the
bo
x.
Including
“fill”
in
the
command
will
paint
the
rectangle
with
the
current
fill
colour
(as
with
\M[
]
)
and
including
“bo
x”
will
giv
e
the
rectangle
a
border
in
the
current
strok
e
colour (as with
\m[
]
).
cmd
ma
y
also
be
“off
”
on
its
own,
which
will
ter
minate
dra
wing
the
current
bo
x.
If
y
ou
ha
v
e
specified
a
page
colour
with
“pagefill”,
it
is
alwa
ys
the
first
bo
x
in
the
stac
k,
and
if
y
ou
specify
it
again,
it
will
replace
the
first
entr
y
.
Be
a
ware
that
the
“pagefill”
bo
x
renders
the
page
opaque,
so
tools
that
“water-
mark”
PDF
pages
are
unlik
ely
to
be
successful.
T
o
retur
n
the
bac
kground
to
transparent, issue an “off
”
command with no other bo
x
es open.
Finally
,
cmd
ma
y
be
“f
ootnote”
f
ollow
ed
b
y
a
ne
w
v
alue
f
or
bottom
,
which
will be used
f
or all open
bo
x
es on the
current page. This is
to allow room f
or
f
ootnote
areas
that
gro
w
while
a
page
is
processed
(to
accommodate
multi-
ple f
ootnotes, f
or instance).
1
left
top
right
bottom
are
the
coordinates
of
the
bo
x.
The
top
and
bottom
coordinates
are
the
minimum
and
maximum
f
or
the
bo
x,
since
the
actual
star
t
of
the
bo
x
is
groff
’
s
dra
wing
position
when
y
ou
issue
the
command,
and
the
bottom
of
the
bo
x
is
the
point
where
y
ou
tur
n
the
bo
x
“off
”.
The
top
and
bottom
coor-
dinates
are
used
only
if
the
bo
x
dra
wing
e
xtends
onto
the
ne
xt
page;
ordi-
narily
, the
y would be set to the header and f
ooter margins.
weight
provides the line width f
or the border if “bo
x”
is included in the command.
F
or
an
e
v
en
more
con
v
enient
interf
ace,
include
-msbo
xes
on
the
groff
command
line;
the
sbo
x
es
pac
kage defines the macros
BO
XST
AR
T
and
BO
XST
OP
.
1
If the v
alue is negativ
e, it is used as an offset from the bottom of the page
.
2
March 2021
.BO
XST
AR
T SHADED
colour
OUTLINED
colour
INDENT
size
WEIGHT
size
begins
a
bo
x,
where
the
argument
after
SHADED
giv
es
the
fill
colour
and
that
after
OUTLINED
the
border
colour
.
Omit
the
f
or
mer
to
get
a
borderless
filled
bo
x
and
the
latter
f
or
a
border
with
no
fill.
The
specified
WEIGHT
is
used
if
the
bo
x
is
OUT
-
LINED
.
INDENT
precedes a value that lea
v
es a gap between the border and
the contents in-
side the bo
x.
Each
colour
must
be
a
defined
groff
colour
name,
and
each
size
a
v
alid
groff
nu-
meric expression. The k
e
yword/v
alue pairs can be specified in any order
.
Bo
x
es
can
be
stac
k
ed,
so
y
ou
can
star
t
a
bo
x
within
another
bo
x;
usually
the
later
bo
x
es
would
be
smaller
than
the
containing
bo
x,
b
ut
this
is
not
enf
orced.
When
using
BO
XST
AR
T
,
the
left
position
is
the
current
indent
minus
the
INDENT
in
the
command,
and
the
right
position
is
the
left
position
(calculated
abov
e)
plus
the
current
line
length
and
twice
the
indent.
The
synopsis
of
BO
XST
AR
T
abov
e itself uses a
BO
XST
AR
T
call without borders and with a
2p
(two point) indent.
.BO
XST
OP
tak
es
no
parameters
.
It
closes
the
most
recently
star
ted
bo
x
at
the
current
v
er
tical
position after adding its
INDENT
spacing.
Y
our
groff
documents
can
conditionally
e
x
ercise
the
sbo
x
es
macros.
The
register
GSBO
X
is
de-
fined if the pac
kage is loaded, and inter
polates a true value if the
pdf
output de
vice is in use.
sbo
x
es
fur
ther
more
hooks
into
the
groff
ms
pac
kage
to
receiv
e
notifications
when
f
ootnotes
are
gro
wing, so
that it
can close
bo
x
es on
a page
bef
ore footnotes are pr
inted. When
that condition
ob-
tains,
sbo
x
es
will
close
open
bo
x
es
two
points
2
abov
e
the
f
ootnote
separator
and
re-open
them
on
the ne
xt page.
This document was produced using the f
ollowing code
.
.\" 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
2
This amount probably will not match the bo
x’
s
INDENT
.
Using PDF bo
x
es with
groff
and the
ms
macros
3
.\" 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
.ie '\*[.T]'pdf'
.ds pgbkgd floralwhite
.el
.ds
pgbkgd
default
.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,
4
March 2021
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[\*[pgbkgd]]\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.
Using PDF bo
x
es with
groff
and the
ms
macros
5
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[]
3
.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
3
This
is
a
long
f
ootnote
occup
ying
multiple
output
lines.
Its
only
pur
pose
is
to
v
erify
that
the
bottom
of
the
bo
x on this page has been adjusted upward to accommodate it.
6
March 2021
.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
Using PDF bo
x
es with
groff
and the
ms
macros
7
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 .
8
March 2021
.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
\# (replaced by source of this document)
.BOXSTOP
.\" Local Variables:
.\" mode: nroff
.\" fill-column: 72
.\" End:
.\" vim: set filetype=groff textwidth=72: