m4: Cleardivert
10.4 Discarding diverted text
=============================
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 'm4' with 'divert(`-1')'
followed by an explicit 'undivert':
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:
-- Composite: cleardivert ([DIVERSIONS...])
Discard the contents of each of the listed numeric DIVERSIONS.
define(`cleardivert',
`pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
=>
It is called just like 'undivert', but the effect is to clear the
diversions, given by the arguments. (This macro has a nasty bug! You
should try to see if you can find it and correct it; or ⇒Answers
Improved cleardivert.).