m4: Diversions

1 
1 10 Diverting and undiverting output
1 ***********************************
1 
1 Diversions are a way of temporarily saving output.  The output of 'm4'
1 can at any time be diverted to a temporary file, and be reinserted into
1 the output stream, "undiverted", again at a later time.
1 
1    Numbered diversions are counted from 0 upwards, diversion number 0
1 being the normal output stream.  GNU 'm4' tries to keep diversions in
1 memory.  However, there is a limit to the overall memory usable by all
1 diversions taken together (512K, currently).  When this maximum is about
1 to be exceeded, a temporary file is opened to receive the contents of
1 the biggest diversion still in memory, freeing this memory for other
1 diversions.  When creating the temporary file, 'm4' honors the value of
1 the environment variable 'TMPDIR', and falls back to '/tmp'.  Thus, the
1 amount of available disk space provides the only real limit on the
1 number and aggregate size of diversions.
1 
1    Diversions make it possible to generate output in a different order
1 than the input was read.  It is possible to implement topological
1 sorting dependencies.  For example, GNU Autoconf makes use of diversions
1 under the hood to ensure that the expansion of a prerequisite macro
1 appears in the output prior to the expansion of a dependent macro,
1 regardless of which order the two macros were invoked in the user's
1 input file.
1 

Menu