m4: Cleardivert

1 
1 10.4 Discarding diverted text
1 =============================
1 
1 Often it is not known, when output is diverted, whether the diverted
1 text is actually needed.  Since all non-empty diversion are brought back
1 on the main output stream when the end of input is seen, a method of
1 discarding a diversion is needed.  If all diversions should be
1 discarded, the easiest is to end the input to 'm4' with 'divert(`-1')'
1 followed by an explicit 'undivert':
1 
1      divert(`1')
1      Diversion one: divnum
1      divert(`2')
1      Diversion two: divnum
1      divert(`-1')
1      undivert
1      ^D
1 
1 No output is produced at all.
1 
1    Clearing selected diversions can be done with the following macro:
1 
1  -- Composite: cleardivert ([DIVERSIONS...])
1      Discard the contents of each of the listed numeric DIVERSIONS.
1 
1      define(`cleardivert',
1      `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
1      =>
1 
1    It is called just like 'undivert', but the effect is to clear the
1 diversions, given by the arguments.  (This macro has a nasty bug!  You
11 should try to see if you can find it and correct it; or ⇒Answers
 Improved cleardivert.).
1