groff: Diversions
5.25 Diversions
===============
In 'gtroff' it is possible to "divert" text into a named storage area.
Due to the similarity to defining macros it is sometimes said to be
stored in a macro. This is used for saving text for output at a later
time, which is useful for keeping blocks of text on the same page,
footnotes, tables of contents, and indices.
For orthogonality it is said that 'gtroff' is in the "top-level
diversion" if no diversion is active (i.e., the data is diverted to the
output device).
Although the following requests can be used to create diversions,
simply using an undefined diversion will cause it to be defined as
empty. 
Identifiers.
-- Request: .di macro
-- Request: .da macro
Begin a diversion. Like the 'de' request, it takes an argument of
a macro name to divert subsequent text into. The 'da' macro
appends to an existing diversion.
'di' or 'da' without an argument ends the diversion.
The current partially-filled line is included into the diversion.
See the 'box' request below for an example. Note that switching to
another (empty) environment (with the 'ev' request) avoids the
inclusion of the current partially-filled line.
-- Request: .box macro
-- Request: .boxa macro
Begin (or append to) a diversion like the 'di' and 'da' requests.
The difference is that 'box' and 'boxa' do not include a
partially-filled line in the diversion.
Compare this:
Before the box.
.box xxx
In the box.
.br
.box
After the box.
.br
=> Before the box. After the box.
.xxx
=> In the box.
with this:
Before the diversion.
.di yyy
In the diversion.
.br
.di
After the diversion.
.br
=> After the diversion.
.yyy
=> Before the diversion. In the diversion.
'box' or 'boxa' without an argument ends the diversion.
-- Register: \n[.z]
-- Register: \n[.d]
Diversions may be nested. The read-only number register '.z'
contains the name of the current diversion (this is a string-valued
register). The read-only number register '.d' contains the current
vertical place in the diversion. If not in a diversion it is the
same as register 'nl'.
-- Register: \n[.h]
The "high-water mark" on the current page. It corresponds to the
text baseline of the lowest line on the page. This is a read-only
register.
.tm .h==\n[.h], nl==\n[nl]
=> .h==0, nl==-1
This is a test.
.br
.sp 2
.tm .h==\n[.h], nl==\n[nl]
=> .h==40, nl==120
As can be seen in the previous example, empty lines are not
considered in the return value of the '.h' register.
-- Register: \n[dn]
-- Register: \n[dl]
After completing a diversion, the read-write number registers 'dn'
and 'dl' contain the vertical and horizontal size of the diversion.
Note that only the just processed lines are counted: For the
computation of 'dn' and 'dl', the requests 'da' and 'boxa' are
handled as if 'di' and 'box' had been used - lines that have been
already stored in a macro are not taken into account.
.\" Center text both horizontally & vertically
.
.\" Enclose macro definitions in .eo and .ec
.\" to avoid the doubling of the backslash
.eo
.\" macro .(c starts centering mode
.de (c
. br
. ev (c
. evc 0
. in 0
. nf
. di @c
..
.\" macro .)c terminates centering mode
.de )c
. br
. ev
. di
. nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
. sp \n[@s]u
. ce 1000
. @c
. ce 0
. sp \n[@s]u
. br
. fi
. rr @s
. rm @s
. rm @c
..
.\" End of macro definitions, restore escape mechanism
.ec
-- Escape: \!
-- Escape: \?anything\?
Prevent requests, macros, and escapes from being interpreted when
read into a diversion. Both escapes take the given text and
"transparently" embed it into the diversion. This is useful for
macros that shouldn't be invoked until the diverted text is
actually output.
The '\!' escape transparently embeds text up to and including the
end of the line. The '\?' escape transparently embeds text until
the next occurrence of the '\?' escape. Example:
\?ANYTHING\?
ANYTHING may not contain newlines; use '\!' to embed newlines in a
diversion. The escape sequence '\?' is also recognized in copy
mode and turned into a single internal code; it is this code that
terminates ANYTHING. Thus the following example prints 4.
.nr x 1
.nf
.di d
\?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
.di
.nr x 2
.di e
.d
.di
.nr x 3
.di f
.e
.di
.nr x 4
.f
Both escapes read the data in copy mode.
If '\!' is used in the top-level diversion, its argument is
directly embedded into the 'gtroff' intermediate output. This can
be used for example to control a postprocessor that processes the
data before it is sent to the device driver.
The '\?' escape used in the top-level diversion produces no output
at all; its argument is simply ignored.
-- Request: .output string
Emit STRING directly to the 'gtroff' intermediate output (subject
to copy mode interpretation); this is similar to '\!' used at the
top level. An initial double quote in STRING is stripped off to
allow initial blanks.
This request can't be used before the first page has started - if
you get an error, simply insert '.br' before the 'output' request.
Without argument, 'output' is ignored.
Use with caution! It is normally only needed for mark-up used by a
postprocessor that does something with the output before sending it
to the output device, filtering out STRING again.
-- Request: .asciify div
"Unformat" the diversion specified by DIV in such a way that ASCII
characters, characters translated with the 'trin' request, space
characters, and some escape sequences that were formatted and
diverted are treated like ordinary input characters when the
diversion is reread. It can be also used for gross hacks; for
example, the following sets register 'n' to 1.
.tr @.
.di x
@nr n 1
.br
.di
.tr @@
.asciify x
.x
Note that 'asciify' cannot return all items in a diversion back to
their source equivalent, nodes such as '\N[...]' will still remain
as nodes, so the result cannot be guaranteed to be a pure string.
Copy-in Mode.
-- Request: .unformat div
Like 'asciify', unformat the specified diversion. However,
'unformat' only unformats spaces and tabs between words.
Unformatted tabs are treated as input tokens, and spaces are
stretchable again.
The vertical size of lines is not preserved; glyph information
(font, font size, space width, etc.) is retained.
Info Catalog
groff: Traps
groff: gtroff Reference
groff: Environments