Diversions (The GNU troff Manual)

5.30 Diversions

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 formatter uses the same name space for such diversions as for strings and macros; recall 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 footnotes, tables of contents, indices, and “keeps” (preventing a page break from occurring at an inconvenient place by forcing a set of output lines to be set as a group). For orthogonality it is said that GNU troff populates the top-level diversion if no diversion is active (that is, formatted output is being “diverted” directly to the output device). The top-level diversion has no name.

Dereferencing an undefined diversion creates an empty one of that name.¹⁶⁹ A diversion does not exist for the purpose of testing with the d conditional expression operator until its initial definition ends; recall Operators in Conditionals. The following requests create and alter diversions.

Request: .di [name]

Request: .da [name]

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.¹⁷⁰

Invoking di or da without an argument stops diverting output to the diversion named by the most recent corresponding request. Invoking di or da without an argument when no diversion is being populated does nothing.¹⁷¹

.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.

Request: .box [name]

Request: .boxa [name]

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.¹⁷²

.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 output to a (named) diversion stops, the formatter stores its vertical and horizontal sizes, to the writable registers dn and dl, 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

Escape sequence: \!character-sequence

Escape sequence: \?character-sequence\?

Transparently embed character-sequence into the current diversion, preventing the formatter from interpreting requests, macro calls, and escape sequences when reading them into a diversion. Doing so prevents 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, up to its own next occurrence on the input line. Use \! by itself to embed newlines in a diversion. The two escape sequences differ in that GNU troff interprets \? even in copy mode; recall Copy Mode. Consequently, comparands protected with \? need not be valid GNU troff syntax.

.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.

Request: .output ["]character-sequence

Emit character-sequence directly to GNU troff’s output; this usage is similar to that of \! when it occurs in the top-level diversion.

GNU troff removes a leading neutral double quote ‘"’ from character-sequence, permitting initial embedded spaces in it, and reads it to the end of the input line in copy mode. Recall Copy Mode.

Caution: Use of these features can put syntactically invalid content into the formatter’s output, which groff’s output drivers then fail to process. One application of output and of \! from the top-level diversion is to pass instructions to a postprocessor that interprets character-sequence and filters it out before sending it to the output driver.

Request: .asciify div

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.

When transforming a glyph node back into an input sequence that demands expression as a special character escape sequence, GNU troff uses the default escape character.

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 nodes in a diversion to their source equivalents: those produced by indexed characters (\N), for example, remain nodes, so the result cannot be guaranteed to be a character sequence as a macro or string is. Give the diversion name as an argument to the pm request to inspect its contents and node list. Glyph parameters such as the type face and size are not preserved; use unformat to achieve that.

Request: .unformat div: 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.