Next: Punning Names, Previous: Traps, Up: GNU troff Reference [Contents][Index]
In roff
systems it is possible to format text as if for output,
but instead of writing it immediately, one can divert the
formatted text into a named storage area. It is retrieved later by
specifying its name after a control character. The same name space is
used for such diversions as for strings and macros; see
Identifiers. Such text is sometimes said to be “stored in a
macro”, but this coinage obscures the important distinction between
macros and strings on one hand and diversions on the other; the former
store unformatted input text, and the latter capture
formatted output. Diversions also do not interpret arguments.
Applications of diversions include “keeps” (preventing a page break
from occurring at an inconvenient place by forcing a set of output lines
to be set as a group), footnotes, tables of contents, and indices.
For orthogonality it is said that GNU troff
is in the
top-level diversion if no diversion is active (that is, formatted
output is being “diverted” immediately to the output device). The
top-level diversion has no name.
Dereferencing an undefined diversion creates an empty one of that
name and emits a warning in category ‘mac’.
See Warnings, regarding the enablement and suppression of warnings.
A diversion does not exist for the purpose of testing with the d
conditional operator until its initial definition ends (see Operators in Conditionals). The following requests are used to create and alter
diversions.
Start collecting formatted output in a diversion called name. The
da
request appends to a diversion called name, creating it
if necessary. If name already exists as an alias, the target of
the alias is replaced or appended to; recall Strings. The pending
output line is diverted as well. Switching to another environment (with
the ev
request) before invoking di
or da
avoids
including any pending output line in the diversion; see
Environments.
Invoking di
or da
without an argument stops diverting
output to the diversion named by the most recent corresponding request.
If di
or da
is called without an argument when there is no
current diversion, a warning in category ‘di’ is produced.
See Warnings, regarding the enablement and suppression of warnings.
.ll 56n Ahoy, me hearties, I traveled unto a distant isle, .br .di HT and thereupon I lay a vast treasure, .br .di .HT .br which none o' ye shall ever see. ⇒ Ahoy, mateys, I traveled unto a distant isle, ⇒ and thereupon I lay a vast treasure, ⇒ which none o’ ye shall ever see.
GNU troff
supports box requests to exclude a partially
collected line from a diversion, as this is often desirable.
Divert (or append) output to name, similarly to the di
and
da
requests, respectively. Any pending output line is not
included in the diversion. Without an argument, stop diverting output;
any pending output line inside the diversion is discarded.
.ll 56n Ahoy, mateys, I traveled unto a distant isle, .br .box SECRET and thereupon I lay a vast treasure, .br accurst wi' neutron activation, .box .SECRET .br which none o' ye shall ever see. ⇒ Ahoy, mateys, I traveled unto a distant isle, ⇒ and thereupon I lay a vast treasure, ⇒ which none o’ ye shall ever see.
Apart from pending output line inclusion and the request names that
populate them, boxes are handled exactly as diversions are. All of the
following groff
language elements can be used with them
interchangeably.
Diversion requests may be nested. The read-only string-valued register
.z
contains the name of the current diversion. The read-only
register .d
contains the vertical drawing position in the
diversion. If the input text is not being diverted, .d
reports
the same location as the register nl
.
.nf .di A alpha .di B beta .di gamma \*B .di delta \*A epsilon ⇒ delta ⇒ alpha ⇒ gamma ⇒ beta ⇒ ⇒ ⇒ epsilon
The read-only register .h
stores the high-water mark on the
current page or in the current diversion. It corresponds to the text
baseline of the lowest line on the page.133
.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 implied by the example, vertical motion does not produce text baselines and thus does not increase the value interpolated by ‘\n[.h]’.
After completing a diversion, the writable registers dn
and
dl
contain its vertical and horizontal sizes, respectively.
Only the lines just processed are counted: for the computation of
dn
and dl
, the requests da
and boxa
are
handled as if di
and box
had been used,
respectively—lines that have been already stored in the diversion
(box) are not taken into account.
.\" Center text both horizontally and vertically. .\" Macro .(c starts centering mode; .)c terminates it. . .\" Disable the escape character with .eo so that we .\" don't have to double backslashes on the "\n"s. .eo .de (c . br . ev (c . evc 0 . in 0 . nf . di @c ..
.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 @c .. .ec
Transparently embed anything into the current diversion,
preventing requests, macro calls, and escape sequences from being
interpreted when read into a diversion. This is useful for preventing
them from taking effect until the diverted text is actually output. The
\!
escape sequence transparently embeds input up to and including
the end of the line. The \?
escape sequence transparently embeds
input, read in copy mode, until its own next occurrence on the input
line.
Use \!
by itself to embed newlines in a diversion.
Unlike \!
, \?
is interpreted even in copy mode
(see Copy Mode).
.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 ⇒ 4
Both escape sequences read the data in copy mode.
If \!
is used in the top-level diversion, its argument is
embedded into GNU troff
’s device-independent output. One of
its applications is control of a postprocessor that transforms the data
that are subsequently read by an output driver.
Using the \?
escape sequence in the top-level diversion produces
no output at all; its argument is simply ignored.
"
]contentsEmit contents directly to GNU troff
’s output; this usage
is similar to that of \!
in the top-level diversion.
A leading neutral double quote in the argument to output
is
stripped from it, allowing embedded leading spaces in contents,
which is read to the end of the input line in copy mode.
Caution: Use of these features can put syntactically invalid
content into GNU troff
’s output, which groff
’s output
drivers then fail to process. output
and use of \!
from
the top-level diversion are normally needed only for instructions to a
postprocessor that does something with the output before sending it to
the output device, filtering out contents again.
Unformat the diversion div in a way such that Unicode basic
Latin (US-ASCII) characters, characters translated with the
trin
request, space characters, and some escape sequences that
were formatted and diverted into div are treated like ordinary
input characters when div is interpolated. Doing so can be useful
in conjunction with the writem
request.
asciify
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
asciify
cannot return all items in a diversion to their source
equivalent: nodes such as those produced by the \N
escape
sequence will remain nodes, so the result cannot be guaranteed to be a
pure string. See Copy Mode. Glyph parameters such as the type face
and size are not preserved; use unformat
to achieve that.
Like asciify
, unformat the diversion div. However,
unformat
handles only tabs and spaces between words, the latter
usually arising from spaces or newlines in the input. Tabs are treated
as tokens, and spaces become adjustable again. The vertical sizes of
lines are not preserved, but glyph information (font, type size, space
width, and so on) is retained.
Next: Punning Names, Previous: Traps, Up: GNU troff Reference [Contents][Index]