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
Although the following requests can be used to create diversions, simply using an undefined diversion will cause it to be defined as empty. See Identifiers.
dawithout an argument ends the diversion.
The current partially-filled line is included into the diversion. See the
boxrequest below for an example. Note that switching to another (empty) environment (with the
evrequest) avoids the inclusion of the current partially-filled line.
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.
boxawithout an argument ends the diversion.
.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
After completing a diversion, the read-write number registers
dlcontain the vertical and horizontal size of the diversion. Note that only the just processed lines are counted: For the computation of
dl, the requests
boxaare handled as if
boxhad been used – lines which 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
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 which shouldn't be invoked until the diverted text is actually output.
\!escape transparently embeds text up to and including the end of the line. The
\?escape transparently embeds text until the next occurrence of the
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.
\!is used in the top-level diversion, its argument is directly embedded into the
gtroffintermediate output. This can be used for example to control a postprocessor which processes the data before it is sent to the device driver.
Emit string directly to the
gtroffintermediate 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
Use with caution! It is normally only needed for mark-up used by a postprocessor which does something with the output before sending it to the output device, filtering out string again.
Unformat the diversion specified by div in such a way that ASCII characters, characters translated with the
trinrequest, 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
nto 1..tr @. .di x @nr n 1 .br .di .tr @@ .asciify x .x
asciifycannot 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.
See Copy-in Mode.
The vertical size of lines is not preserved; glyph information (font, font size, space width, etc.) is retained.