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 see Answers).