Undiverting output
==================
Diverted text can be undiverted explicitly using the builtin
`undivert':
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 `undivert' is void.
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
following `undivert', the other from the newline that followed the
`divert'! A diversion often starts with a blank line like this.
When diverted text is undiverted, it is _not_ reread by `m4', but
rather copied directly to the current output, and it is therefore not
an error to undivert into a diversion.
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.
GNU `m4' allows named files to be undiverted. Given a non-numeric
argument, the contents of the file named will be copied, uninterpreted,
to the current output. This complements the builtin `include' (Note:Include). To illustrate the difference, assume the file `foo'
contains the word `bar':
define(`bar', `BAR')
=>
undivert(`foo')
=>bar
=>
include(`foo')
=>BAR
=>