Diverted text can be undiverted explicitly using the builtin
Undiverts the numeric diversions given by the arguments, in the order given. If no arguments are supplied, all diversions are undiverted, in numerical order.
As a GNU extension, diversions may contain non-numeric strings, which are treated as the names of files to copy into the output without expansion. A warning is issued if a file could not be opened.
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
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
but rather copied directly to the current output, and it is therefore
not an error to undivert into a diversion. Undiverting the empty string
is the same as specifying diversion 0; in either case nothing happens
since the output has already been flushed.
divert(`1')diverted text divert ⇒ undivert() ⇒ undivert(`0') ⇒ undivert ⇒diverted text ⇒ divert(`1')more divert(`2')undivert(`1')diverted text`'divert ⇒ undivert(`1') ⇒ undivert(`2') ⇒more ⇒diverted text
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. Thus, when the current diversion is not 0, the current diversion does not get rearranged among the other diversions.
divert(`1')one divert(`2')two divert(`3')three divert(`2')undivert`'dnl divert`'undivert`'dnl ⇒two ⇒one ⇒three
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 (see Include). To illustrate the difference, assume
the file foo contains:
$ cat foo bar
define(`bar', `BAR') ⇒ undivert(`foo') ⇒bar ⇒ include(`foo') ⇒BAR ⇒
If the file is not found (or cannot be read), an error message is issued, and the expansion is void. It is possible to intermix files and diversion numbers.
divert(`1')diversion one divert(`2')undivert(`foo')dnl divert(`3')diversion three divert`'dnl undivert(`1', `2', `foo', `3')dnl ⇒diversion one ⇒bar ⇒bar ⇒diversion three