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

EN Tools                                           2020-11-29                                          DIVERT(1)