AutoGen provides a means for redirecting the template output to different
files or, in M4 parlance, to various diversions. It is accomplished
by providing a set of Scheme functions named out-*
(see AutoGen Functions).
This allows you to logically "push" output files onto a stack.
If you supply a string name, then a file by that name is created
to hold the output. If you do not supply a name, then the text is
written to a scratch pad and retrieved by passing a #t argument
to the out-pop (see SCM out-pop) function.
This function closes the current output file and resumes output to the next
one in the stack. At least one output must have been pushed onto the output
stack with the out-push-new (see SCM out-push-new) function. If
#t is passed in as an argument, then the entire contents of the
diversion (or file) is returned.
This function does not close the current output, but instead sets it aside
for resumption by the given name with out-resume. The current output
must have been pushed on the output queue with out-push-new
(see SCM out-push-new).
This closes the current output and creates a new file,
purging any preexisting one. This is a shortcut for "pop"
followed by "push", but this can also be done at the base level.