DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(m4.info.gz) Undivert

Info Catalog (m4.info.gz) Divert (m4.info.gz) Diversions (m4.info.gz) Divnum
 
 9.2 Undiverting output
 ======================
 
 Diverted text can be undiverted explicitly using the builtin `undivert':
 
  -- Builtin: undivert ([NUMBER]...)
      Undiverts the 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, if NUMBER is
      not numeric, treat it as a file name instead.
 
      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
 following `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 `m4', 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
      =>
 
    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
 
    GNU `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' (
 Include).  To illustrate the difference, the file `examples/foo'
 contains the word `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.
 
Info Catalog (m4.info.gz) Divert (m4.info.gz) Diversions (m4.info.gz) Divnum
automatically generated byinfo2html