Whole document tree
Diversions are a way of temporarily saving output. The output of
Numbered diversions are counted from 0 upwards, diversion number 0
being the normal output stream. The number of simultaneous diversions
is limited mainly by the memory used to describe them, because GNU
where number is the diversion to be used. If number is left out, it is assumed to be zero.
The expansion of
When all the
divert(1) This text is diverted. divert => This text is not diverted. =>This text is not diverted. ^D => =>This text is diverted.
Several calls of
If output is diverted to a non-existent diversion, it is simply discarded. This can be used to suppress unwanted output. A common example of unwanted output is the trailing newlines after macro definitions. Here is how to avoid them.
divert(-1) define(`foo', `Macro `foo'.') define(`bar', `Macro `bar'.') divert =>
This is a common programming idiom in
undivert(opt number, ...)
which undiverts the diversions given by the arguments, in the order given. If no arguments are supplied, all diversions are undiverted, in numerical order.
The expansion of
divert(1) This text is diverted. divert => This text is not diverted. =>This text is not diverted. undivert(1) => =>This text is diverted. =>
Notice the last two blank lines. One of them comes from the newline
When diverted text is undiverted, it is not reread by
When a diversion has been undiverted, the diverted text is discarded, and it is not possible to bring back diverted text more than once.
divert(1) This text is diverted first. divert(0)undivert(1)dnl => =>This text is diverted first. undivert(1) => divert(1) This text is also diverted but not appended. divert(0)undivert(1)dnl => =>This text is also diverted but not appended.
Attempts to undivert the current diversion are silently ignored.
define(`bar', `BAR') => undivert(`foo') =>bar => include(`foo') =>BAR =>
expands to the number of the current diversion.
Initial divnum =>Initial 0 divert(1) Diversion one: divnum divert(2) Diversion two: divnum divert => ^D => =>Diversion one: 1 => =>Diversion two: 2
The last call of
Often it is not known, when output is diverted, whether the diverted
text is actually needed. Since all non-empty diversion are brought back
on the main output stream when the end of input is seen, a method of
discarding a diversion is needed. If all diversions should be
discarded, the easiest is to end the input to
divert(1) Diversion one: divnum divert(2) Diversion two: divnum divert(-1) undivert ^D
No output is produced at all.
Clearing selected diversions can be done with the following macro:
define(`cleardivert', `pushdef(`_num', divnum)divert(-1)undivert($@)divert(_num)popdef(`_num')') =>
It is called just like