Diversions

m4 output can be diverted to temporary files during processing, and the collected material can be output on command. m4 maintains nine of these diversions, numbered 1 through 9. If the built-in macro divert(n) is used, all subsequent output is appended to a temporary file referred to as n. Diverting to this file is stopped by the divert() or divert(0) macros, which resume the normal output process.

Diverted text is normally placed at the end of processing in numerical order. Diversions can be brought back at any time by appending the new diversion to the current diversion. Output diverted to a stream other than 0 through 9 is discarded. The built-in undivert() brings back all diversions in numerical order; undivert() with arguments brings back the selected diversions in the order given. Undiverting discards the diverted text (as does diverting) into a diversion whose number is not between 0 and 9, inclusive.

The value of undivert() is not the diverted text. Furthermore, the diverted material is not rescanned for macros. The built-in divnum() returns the number of the currently active diversion. The current output stream is 0 during normal processing.