7.4 Diversions

Diversions are a way of directing output to a temporary storage and inserting it (undiverting) into the main output stream again at a later time. Temporary storage used for each diversion is identified by a unique identifier assigned to it when a diversion is declared.

Directive: $$divert [name]

Begin diverting output to the diversion name. The diversion remains in effect until a subsequent $$divert directive or end of file is encountered, whichever happens first.

If name is omitted, main output stream is restored.

Several calls of divert with the same argument do not overwrite the previous diverted text, but append to it.

The diverted text remains in the temporary storage until it is discarded by $$dropdivert.

Directive: $$undivert name

Undiverts the named diversion. Undiverted text is read verbatim. Several calls to $$undivert with the same argument are allowed. This provides a way to insert same text several times.

Directive: $$dropdivert name

Discard and drop the diversion name.

M4 users should notice the following differences between diversions in xenv and m4:

1. Diversions are not implicitly undiverted at the end of input. Rather, they must be undiverted explicitly, when needed. Any diverted text that was not explicitly undiverted will be discarded.
2. Diverted text continues to exist after call to $$undivert. $$undivert can be used multiple times (even in a loop, if the need be).
3. To clear a diversion $$dropdivert should be used.

An example of using diversions:

begin text
$$divert A
this text is diverted first
$$divert B
this text is diverted after it
$$divert
main output restored
$$undivert B
some other text
$$undivert A

This will produce:

begin text
main output restored
this text is diverted after it
some other text
this text is diverted first