NAME

       Divert - Text Diversion Filter

SYNOPSIS

       divert [-o outputfile] [-q] [-v] [inputfile]

DESCRIPTION

       The divert program reads inputfile or from "stdin" and applies a 2-pass diversion filter
       to its contents. In pass 1 all diversion locations are accumulated and in pass 2 these
       locations are recursively expanded at their dump positions.  The diversion filter is
       controlled by directives found in the input data:

       {#NAME#} (or <<NAME>>)
           This defines the dump position of the location NAME. All accumulated data which
           finally has to been diverted to NAME is inserted at this data position.  Notice: the
           final data of a location NAME has not to be known at this point, because the expansion
           of such location dumps are done in pass 2.  You can also dump a location more than
           once, but the contents is always the same, independent of the data position where the
           location dump tag stays.  The NAME can be any symbolic name matching
           "[a-zA-Z][a-zA-Z0-9_]*".

       {#[!]NAME[!]#: (or ..[!]NAME[!]>>)
           This enters the location NAME (or diverts the data flow to it, hence the name for this
           filter).  In other words: the data flow now goes on at location NAME. All following
           data (up to end of file or the next location leave tag) gets appended to location
           NAME. You can nest diversions by entering other locations at any point, because the
           locations are remembered on a stack. The default entered location is named ``"main"''.
           The top most location is named ``"null"'' which neither can be entered nor leaved
           explicitly. But of course the ``"null"'' diversion can be manually dumped, for
           instance when using it for error messages.

           There are two special features for diverting data which are controlled by the ""!""
           characters preceding or following the NAME identifier:

           !NAME
               This sets the data flow position to the begin of location NAME, i.e. it actually
               discards the current (already diverted) contents of location NAME before entering
               it. Use this to overwrite a locations contents.

           NAME!
               This marks this location entry as overwritable, i.e. it enters location NAME but
               when the corresponding leave tag is found, the data-flow position for NAME gets
               automatically reset to its begin. Use this if you want to set the default contents
               for a location which only gets used if no other diversions occur to it (because
               any following diversions to this location will be overwrite the contents). This
               feature is usually used for a template scheme.

           !NAME!
               Just the combination of the above two features. Use this to both discard the
               current contents of location NAME and set a new default for it.

       :#[NAME]#} (or <<[NAME]..)
           This leaves the current location, i.e. enters again the location which was active when
           this location was entered.  There is no need to leave all locations at the end of the
           input data. All still entered locations are automatically left at end of file because
           this is essential for a template scheme.

       Notice that there are two ways of using (and thinking) about the filtering mechanism this
       program provides:

       Macro Mechanism
           This is the "predefined" way of thinking here. Use it like this:

             FOO
             {#BAR#}
             QUUX
             {#BAR#:
             BAZ
             :##}

           Here you are thinking of the mechanism as a macro mechanism where you expand a macro
           at one data position while you define it via begin and end tags.

       Diversion Mechanism
           This is the alternative way of thinking. Use it like this:

             FOO
             <<BAR>>
             QUUX
             ..BAR>>
             BAZ
             <<..

           In other words: You are thinking of the mechanism as a diversion mechanism where you
           dump a location at one data position while you divert to it by entering end leaving
           the location (here BAR) at other positions.

       You can even intermix both ways because both are just alternative syntax variants which
       are treated the same.

EXAMPLE

         {#HEAD#}
         {#BODY#}
         {#FOOT#}

         {#FOOT#:
         Quux
         :##}

         {#BODY#:
         Bar
         :##}

         {#HEAD#:
         Foo
         :##}

OPTIONS

       -o outputfile
           This redirects the output to outputfile. Usually the output will be send to stdout if
           no such option is specified or outputfile is ``"-"''.

       -q  This sets quiet mode where warnings are suppressed.

       -v  This sets verbose mode where some processing information will be given on stderr.

AUTHORS

        Ralf S. Engelschall
        rse@engelschall.com
        www.engelschall.com

        Denis Barbier
        barbier@engelschall.com