Contents | < Browse | Browse >
Diverting output
================

   Output is diverted using `divert':

     divert(opt NUMBER)

where NUMBER is the diversion to be used.  If NUMBER is left out, it is
assumed to be zero.

   The expansion of `divert' is void.

   Diverted output, that hasn't been explicitly undiverted, will be
undiverted when all the input has been processed.

     divert(1)
     This text is diverted.
     divert
     =>
     This text is not diverted.
     =>This text is not diverted.
     ^D
     =>
     =>This text is diverted.

   Several calls of `divert' with the same argument do not overwrite
the previous diverted text, but append to it.

   If output is diverted to an non-existent diversion, it is simply
discarded.  This can be used to suppress unwanted output.  A common
example of unwanted output is the trailing newlines after macro
definitions.  Here is how to avoid them.

     divert(-1)
     define(`foo', `Macro `foo'.')
     define(`bar', `Macro `bar'.')
     divert
     =>

   This is a common programming idiom in `m4'.