Provided by: wml_2.0.11ds1-0.4_i386 bug

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