Provided by: wml_2.0.11ds2-1build1_i386 bug

NAME

       ipp - Include Pre-Processor

SYNOPSIS

       ipp [-D name=value] [-S includedir] [-I includedir] [-s includefile]
       [-i includefile] [-M options] [-P path] [-m mapfile] [-N nosynclines]
       [-o outputfile] [-v] inputfile ...

DESCRIPTION

       The ipp program reads all inputfiles and recursively expands all

         #include 'file'
         #include "file"
         #include <file>

       directives by substituting the directive with the contents of the file.
       The output is send to stdout or to outputfile. The files are searched
       according to the following scheme:

       #include 'file'
           The file is searched in the current working directory only. Use
           this to force the loading of a local file.

       #include "file"
           The file is searched in all directories given by the -I option in
           the right-to-left order they are specified on the command line.
           Note that a -I . implicit option is automatically appended to
           command-line options, then files are first searched in current
           directory.

       #include <file>
           First the file is searched in the system wide "ipp" include
           directory specified with the -S option. Second if it was not not
           found there it is searched for in all directories given by the -I
           option.

       And it provides eight additional features:

   Using Wildcards
       These characters have a special meaning in filenames:

       "*"   Matches any string, including the null string.
       "?"   Matches any single character.
       "[...]"  Like bracketed expressions in regexps, matches any of the
       enclosed characters.

       If you want to include all your templates, you may write

         #include "*.tmpl"

       With the following parameters you can control the order and the number
       of included files using the #include 'pattern' directive:

       "IPP_SORT=scheme"     Specify a sort criterion to include files. There
       are actually 3 different criteria : date (files are sorted according to
       their last modification time), name (this is the default) and numeric
       (filenames are sorted numerically).
       "IPP_REVERSE=scheme"  As above, but resulting list of filenames is
       sorted in reverse order.
       "IPP_MAX=nmax"        Only nmax files are included.

       If you want to include the 5 newest include files of the news directory
       with file names like "20000131.inc", you may write:

         #include 'news/*.inc' IPP_REVERSE IPP_MAX=5

       In the files included with the "#include 'pattern'" directive, the
       following variables are set and can be read using "$(name)":

       "IPP_THIS"  the full name of the included source file including path
       and extension
       "IPP_PREV"  the full name of the previous included file, unset in the
       first file
       "IPP_NEXT"  the full name of the next included file, unset in the last
       file

       Keep in mind that a directive without wildcards does not set these
       variables.

   Special `Use' Variant
       In analogon to Perl's "use" statement, ipp provides a special variant
       of "#include":

          #use type::category::file

       This internally is equivalent to the directive

          #include <category/file.type>

       plus the special semantic that the include file is included (=used)
       only once, i.e. multiple inclusion is automatically avoided. In other
       words

          #include 'file'
          #include 'file'
          #use 'file'
          #use 'file'

       results in three inclusions of 'file'. Two from the "#include"'s and
       only once from the "#use" directives.

   Special `Depends' Variant
       You can easily write fragments of Makefiles with the -M flag (see
       below) to keep tracks of which files the output file depends on, When
       "ipp" is invoked as a piece of "WML", the final output file may depend
       on other files.  You can tell "ipp" about these hidden dependencies by
       using the "#depends" variant , e.g.

         #depends 'foo.dat'
         #depends "*/*.dat"
         #depends <file>

       The contents of the file is not inserted, only information about
       dependencies are updated.

   Input Line Synchronization
       All include commands insert some special stuff to help "WML" keeping
       track of input line numbers.  This feature may be disabled by appending
       the string "IPP_NOSYNCLINES" to the "#include" (or its variants)
       command.  See also the "-N" flag.

   Include Variables
       You can add

          name[=value]

       pairs at the end of "#include" (and "#use") directives to let "$(name)"
       interpolate to "value" (or 1 if "=value" is missing) in this include
       file and all its recursively included files.

       There are the following forms of the "$(name)" syntax, similar to the
       functionality any Bourne Shell provides:

       o   "$(name)"
           `Use Only Value': The standard interpolation.

            if (exists(name))
                expandto(valueof(name))
            else
                expandto("")

       o   "$(name=string)"
           `Assign Value': Set a variable.

            name := string

       o   "$(name:-string)"
           `Use Default String': The standard interpolation with a default
           value.

            if (exists(name))
                expandto(valueof(name))
            else
                expandto(string)

       o   "$(name:=string)"
           `Use Default String and Assign': The standard interpolation with a
           default value and additional assignment for later use.

            if (exists(name))
                expandto(valueof(name))
            else
                expandto(string)
                name := string

       o   "$(name:+string)"
           `Use Alternate String'. The replacement interpolation.

            if (exists(name))
                expandto(string)
            else
                expandto("")

       o   "$(name:*string)"
           `Use Negative Alternate String'. The replacement interpolation with
           negated logic.

            if (exists(name))
                expandto("")
            else
                expandto(string)

       o   "$(name:?string)"
           `Indicate Error If Unset'. The error message interpolation.  This
           can also be used in conjunction with the above variants.

            if (exists(name))
                expandto(valueof(name))
            else
                Error(string)

       Previous constructs may be nested when variable expansion contains no
       parenthesis. You may for instance need these forms:

       `Set a variable if unset'.

         $(var=$(var:-string))

       `Redefine a variable if it is already set.'

         $(var=$(var:+string))

       Notice that nested expressions are not handled as shells do. In shells
       expressions are treated from left to right, whereas "ipp" treat inner
       expressions first.  With this example below

         $(foo=bar)
         $(foo:-$(foo=quux))

       Bourne shells will show "bar" whereas "ipp" will print "quux".

       It is also possible to undefine a variable.  To do so, assign an empty
       value to this variable, e.g.

         $(foo=)

       Notice the possibility to do simple If-Then-Else constructs:

         $(foo:+string_when_set)$(foo:*string_when_not_set)

       This is equivalent to the following pseudo-code:

         if (exists(foo))
             expandto(string_when_set)
         else
             expandto(string_when_not_set)

   Implicit IPP Variables
       The strings "__FILE__" and "__LINE__" are always substituted by the
       currently processed include file and the current line number.

   Comments
       IPP provides support for up-to-end-of-line comments.  This type of
       comment is like the one found in Bourne-Shell or Perl, i.e. any line
       which starts with a sharp symbol (`"#"') is entirely (i.e. including
       the newline at the end) removed from the input. Additionally these
       lines can have whitespaces in front of the sharp symbol. When you
       really need a sharp symbol at the start of a line you can use "\#",
       i.e. prefix it with an escaping backslash.

   End-Of-File Stopping
       It stops processing the current include file when a line containing
       just

         __END__

       occurs. Use this to append POD documents to include files for
       documentation purposes as in Perl. You can use "__END__" in constructs
       like "$(SHORTENING:+__END__)", so that the processing is only stopped
       when the variable SHORTENING is set.

   End-Of-Line Continuation
       It removes all occurences of the pattern

         \<whitespace>*<newline><whitespace>*

       Use this to let one or more lines to be concatenated.

OPTIONS

       -D name=value
           Defines a variable the for the initial inputfile the same way you
           define ones with the #include for include files.  The variable can
           be interpolated via "$(name)" in all files.

       -S includedir
           Adds a system wide include directory.  You can use this option more
           than once.  The files are searched in right-to-left order.

       -I includedir
           This adds an entry to the include path where include files are
           searched for.  You can use this option more than once. The files
           are searched in right-to-left order. The current working directory
           is always appended as the last directory to this list, and so is
           searched first.

       -s includefile
           Pre-load a particular include file, i.e. virtually adds a

             #include <includefile>

           in front of inputfile. Use this to automatically load default
           system include files. You can also use the syntax
           "type::category::file" which leads to a virtually added

             #include <category/file.type>

       -i includefile
           Pre-loads a particular include file, i.e. virtually adds a

             #include "includefile"

           in front of inputfile. Use this to automatically load default user
           include files.   You can also use the syntax "type::category::file"
           which leads to a virtually added

             #include "category/file.type"

       -M options
           Output a rule suitable for `make' describing the dependencies of
           each output file, as `gcc' does. It has only sense when the -o
           option is used.

           The D flag option writes the rule to a dependency file. The name of
           this file is obtained by replacing the suffix of the output file by
           ".d".

           The M flag option deletes the system files from the list of
           dependencies.

       -P path
           This sets up one or more prolog program path which are applied to
           each single input file just before real processing starts. Use this
           to pre-process the data.  Each program receives the data to act on
           as STDIN and has to produce the filtered data on STDOUT.

       -m mapfile
           This adds an entry to the list of mapfiles where a mapping between
           obsolete include file names and current ones can be found.  You can
           use this option more than once. The mapfiles can contain the
           following lines:

              #  comment line
              <blank line>
              <oldname>[,<oldname>] <newname> \[S|W|E: <text>\]

           Example:

              <std/headfoot.wml>,wml::std::headfoot wml::OBSOLETE::std::headfoot [S]

       -N nosynclines
           By default, WML inserts some instructions to synchronize line
           numbers, which are then interpreted in passes 2 and 3.  This option
           disables this feature.

       -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
           ""-"".

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

AUTHORS

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

        Denis Barbier
        barbier@engelschall.com