Diversions (The GNU Troff Manual)

+Next: Punning Names, Previous: Traps, Up: GNU troff Reference [Contents][Index]

5.29 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 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). +

Dereferencing an undefined diversion will create an empty one of that +name and cause a warning in category ‘mac’ to be emitted. +See Warnings, for information about 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. +

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; 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, for information about the enablement and suppression +of warnings. +

Before the diversion.
+.di yyy
+In the diversion.
+.br
+.di
+After the diversion.
+.br
+    ⇒ After the diversion.
+.yyy
+    ⇒ Before the diversion.  In the diversion.
+

+ + +

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

Before the box.
+.box xxx
+In the box.
+.br
+Hidden treasure.
+.box
+After the box.
+.br
+    ⇒ Before the box.  After the box.
+.xxx
+    ⇒ In the box.
+

+ +

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

Register: \n[.z] ¶: +
Register: \n[.d] ¶: + + + + + + + +
Diversions may be nested. The read-only string-valued register +.z contains the name of the current diversion. The read-only +register .d contains the current vertical place in the diversion. +If the input text is not being diverted, .d reports the same +location as the register nl. +

+ +

+ + + + +

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 completing a diversion, the writable registers dn and +dl contain its vertical and horizontal sizes. 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: \!anything ¶

Escape sequence: \?anything\? ¶

+ + +

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 until its own next occurrence. +

+ + + + + + +

anything may not contain newlines; use \! by itself 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 escape sequences read the data in copy mode. +

+ + + +

If \! is used in the top-level diversion, its argument is +directly embedded into GNU troff’s intermediate output. This can +be used, for example, to control a postprocessor that processes the data +before it is sent to an output driver. +

+ + + +

The \? escape used in the top-level diversion produces no output +at all; its argument is simply ignored. +

+ + + + + + +

Request: .output contents ¶

Emit contents directly to GNU troff’s intermediate output +(subject to copy mode interpretation); this is similar to \! used +at the top level. An initial neutral double quote in contents is +stripped to allow embedding of leading spaces. +

This request can’t be used before the first page has started—if you +get an error, simply insert .br before the output request. +

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 contents again. +

+ +

Request: .asciify div ¶

+ + + +

Unformat the diversion div in a way such that Unicode basic +Latin (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 reread. 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. +

+ +

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

+ + + +