.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HOOLA 1"
.TH HOOLA 1 "2018-12-25" "EN Tools" "EN Tools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ipp \- Include Pre\-Processor
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBipp\fR
[\fB\-D\fR \fIname\fR\fB=\fR\fIvalue\fR]
[\fB\-S\fR \fIincludedir\fR]
[\fB\-I\fR \fIincludedir\fR]
[\fB\-s\fR \fIincludefile\fR]
[\fB\-i\fR \fIincludefile\fR]
[\fB\-M\fR \fIoptions\fR]
[\fB\-P\fR \fIpath\fR]
[\fB\-m\fR \fImapfile\fR]
[\fB\-N\fR \fInosynclines\fR]
[\fB\-o\fR \fIoutputfile\fR]
[\fB\-v\fR]
\&\fIinputfile\fR ...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fIipp\fR program reads all \fIinputfile\fRs and recursively expands all
.PP
.Vb 3
\&  #include \*(Aqfile\*(Aq
\&  #include "file"
\&  #include <file>
.Ve
.PP
directives by substituting the directive with the contents of the file.  The
output is send to \fIstdout\fR or to \fIoutputfile\fR. The files are searched
according to the following scheme:
.IP "\fB#include 'file'\fR" 4
.IX Item "#include 'file'"
The file is searched in the current working directory \fBonly\fR. Use
this to force the loading of a local file.
.ie n .IP "\fB#include ""file""\fR" 4
.el .IP "\fB#include ``file''\fR" 4
.IX Item "#include file"
The file is searched in all directories given by the \fB\-I\fR option in the
right-to-left order they are specified on the command line.  Note that
a \fB\-I .\fR implicit option is automatically appended to command-line
options, then files are first searched in current directory.
.IP "\fB#include <file>\fR" 4
.IX Item "#include <file>"
First the file is searched in the system wide \f(CW\*(C`ipp\*(C'\fR include directory
specified with the \fB\-S\fR option. Second if it was not not found there it is
searched for in all directories given by the \fB\-I\fR option.
.PP
And it provides eight additional features:
.SS "\fBUsing Wildcards\fP"
.IX Subsection "Using Wildcards"
These characters have a special meaning in filenames:
.ie n .IP """*""   Matches any string, including the null string." 4
.el .IP "\f(CW*\fR   Matches any string, including the null string." 4
.IX Item "* Matches any string, including the null string."
.PD 0
.ie n .IP """?""   Matches any single character." 4
.el .IP "\f(CW?\fR   Matches any single character." 4
.IX Item "? Matches any single character."
.ie n .IP """[...]""  Like bracketed expressions in regexps, matches any of the enclosed characters." 4
.el .IP "\f(CW[...]\fR  Like bracketed expressions in regexps, matches any of the enclosed characters." 4
.IX Item "[...] Like bracketed expressions in regexps, matches any of the enclosed characters."
.PD
.PP
If you want to include all your templates, you may write
.PP
.Vb 1
\&  #include "*.tmpl"
.Ve
.PP
With the following parameters you can control the order and the number
of included files using the \fB#include 'pattern'\fR directive:
.ie n .IP """IPP_SORT=\fIscheme\fP""     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)." 4
.el .IP "\f(CWIPP_SORT=\f(CIscheme\f(CW\fR     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)." 4
.IX Item "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)."
.PD 0
.ie n .IP """IPP_REVERSE=\fIscheme\fP""  As above, but resulting list of filenames is sorted in reverse order." 4
.el .IP "\f(CWIPP_REVERSE=\f(CIscheme\f(CW\fR  As above, but resulting list of filenames is sorted in reverse order." 4
.IX Item "IPP_REVERSE=scheme As above, but resulting list of filenames is sorted in reverse order."
.ie n .IP """IPP_MAX=\fInmax\fP""        Only \fInmax\fR files are included." 4
.el .IP "\f(CWIPP_MAX=\f(CInmax\f(CW\fR        Only \fInmax\fR files are included." 4
.IX Item "IPP_MAX=nmax Only nmax files are included."
.PD
.PP
If you want to include the 5 newest include files of the news directory
with file names like \f(CW\*(C`20000131.inc\*(C'\fR, you may write:
.PP
.Vb 1
\&  #include \*(Aqnews/*.inc\*(Aq IPP_REVERSE IPP_MAX=5
.Ve
.PP
In the files included with the \f(CW\*(C`#include \*(Aqpattern\*(Aq\*(C'\fR directive, the
following variables are set and can be read using \f(CW\*(C`$(name)\*(C'\fR:
.ie n .IP """IPP_THIS""  the full name of the included source file including path and extension" 4
.el .IP "\f(CWIPP_THIS\fR  the full name of the included source file including path and extension" 4
.IX Item "IPP_THIS the full name of the included source file including path and extension"
.PD 0
.ie n .IP """IPP_PREV""  the full name of the previous included file, unset in the first file" 4
.el .IP "\f(CWIPP_PREV\fR  the full name of the previous included file, unset in the first file" 4
.IX Item "IPP_PREV the full name of the previous included file, unset in the first file"
.ie n .IP """IPP_NEXT""  the full name of the next included file, unset in the last file" 4
.el .IP "\f(CWIPP_NEXT\fR  the full name of the next included file, unset in the last file" 4
.IX Item "IPP_NEXT the full name of the next included file, unset in the last file"
.PD
.PP
Keep in mind that a directive without wildcards does not set these
variables.
.SS "\fBSpecial `Use' Variant\fP"
.IX Subsection "Special `Use' Variant"
In analogon to Perl's \f(CW\*(C`use\*(C'\fR statement, \fIipp\fR provides a special variant of
\&\f(CW\*(C`#include\*(C'\fR:
.PP
.Vb 1
\&   #use type::category::file
.Ve
.PP
This internally is equivalent to the directive
.PP
.Vb 1
\&   #include <category/file.type>
.Ve
.PP
plus the special semantic that the include file is included (=used) only once,
i.e. multiple inclusion is automatically avoided. In other words
.PP
.Vb 4
\&   #include \*(Aqfile\*(Aq
\&   #include \*(Aqfile\*(Aq
\&   #use \*(Aqfile\*(Aq
\&   #use \*(Aqfile\*(Aq
.Ve
.PP
results in three inclusions of 'file'. Two from the \f(CW\*(C`#include\*(C'\fR's and only
once from the \f(CW\*(C`#use\*(C'\fR directives.
.SS "\fBSpecial `Depends' Variant\fP"
.IX Subsection "Special `Depends' Variant"
You can easily write fragments of Makefiles with the \fB\-M\fR flag (see
below) to keep tracks of which files the output file depends on, When
\&\f(CW\*(C`ipp\*(C'\fR is invoked as a piece of \f(CW\*(C`WML\*(C'\fR, the final output file may depend
on other files.  You can tell \f(CW\*(C`ipp\*(C'\fR about these hidden dependencies by
using the \f(CW\*(C`#depends\*(C'\fR variant , e.g.
.PP
.Vb 3
\&  #depends \*(Aqfoo.dat\*(Aq
\&  #depends "*/*.dat"
\&  #depends <file>
.Ve
.PP
The contents of the file is not inserted, only information about
dependencies are updated.
.SS "\fBInput Line Synchronization\fP"
.IX Subsection "Input Line Synchronization"
All include commands insert some special stuff to help \f(CW\*(C`WML\*(C'\fR keeping
track of input line numbers.  This feature may be disabled by appending
the string \f(CW\*(C`IPP_NOSYNCLINES\*(C'\fR to the \f(CW\*(C`#include\*(C'\fR (or its variants)
command.  See also the \f(CW\*(C`\-N\*(C'\fR flag.
.SS "\fBInclude Variables\fP"
.IX Subsection "Include Variables"
You can add
.PP
.Vb 1
\&   name[=value]
.Ve
.PP
pairs at the end of \f(CW\*(C`#include\*(C'\fR (and \f(CW\*(C`#use\*(C'\fR) directives to let \f(CW\*(C`$(name)\*(C'\fR
interpolate to \f(CW\*(C`value\*(C'\fR (or \f(CW1\fR if \f(CW\*(C`=value\*(C'\fR is missing) in this include file
and all its recursively included files.
.PP
There are the following forms of the \f(CW\*(C`$(name)\*(C'\fR syntax, similar to the
functionality any Bourne Shell provides:
.ie n .IP "o   \fB\f(CB""$(name)""\fB\fR" 4
.el .IP "o   \fB\f(CB$(name)\fB\fR" 4
.IX Item "o $(name)"
`Use Only Value': The standard interpolation.
.Sp
.Vb 4
\& if (exists(name))
\&     expandto(valueof(name))
\& else
\&     expandto("")
.Ve
.ie n .IP "o   \fB\f(CB""$(name=string)""\fB\fR" 4
.el .IP "o   \fB\f(CB$(name=string)\fB\fR" 4
.IX Item "o $(name=string)"
`Assign Value': Set a variable.
.Sp
.Vb 1
\& name := string
.Ve
.ie n .IP "o   \fB\f(CB""$(name:\-string)""\fB\fR" 4
.el .IP "o   \fB\f(CB$(name:\-string)\fB\fR" 4
.IX Item "o $(name:-string)"
`Use Default String': The standard interpolation
with a default value.
.Sp
.Vb 4
\& if (exists(name))
\&     expandto(valueof(name))
\& else
\&     expandto(string)
.Ve
.ie n .IP "o   \fB\f(CB""$(name:=string)""\fB\fR" 4
.el .IP "o   \fB\f(CB$(name:=string)\fB\fR" 4
.IX Item "o $(name:=string)"
`Use Default String and Assign': The standard interpolation with a default
value and additional assignment for later use.
.Sp
.Vb 5
\& if (exists(name))
\&     expandto(valueof(name))
\& else
\&     expandto(string)
\&     name := string
.Ve
.ie n .IP "o   \fB\f(CB""$(name:+string)""\fB\fR" 4
.el .IP "o   \fB\f(CB$(name:+string)\fB\fR" 4
.IX Item "o $(name:+string)"
`Use Alternate String'. The replacement interpolation.
.Sp
.Vb 4
\& if (exists(name))
\&     expandto(string)
\& else
\&     expandto("")
.Ve
.ie n .IP "o   \fB\f(CB""$(name:*string)""\fB\fR" 4
.el .IP "o   \fB\f(CB$(name:*string)\fB\fR" 4
.IX Item "o $(name:*string)"
`Use Negative Alternate String'. The replacement interpolation with negated
logic.
.Sp
.Vb 4
\& if (exists(name))
\&     expandto("")
\& else
\&     expandto(string)
.Ve
.ie n .IP "o   \fB\f(CB""$(name:?string)""\fB\fR" 4
.el .IP "o   \fB\f(CB$(name:?string)\fB\fR" 4
.IX Item "o $(name:?string)"
`Indicate Error If Unset'. The error message interpolation.  This can also be
used in conjunction with the above variants.
.Sp
.Vb 4
\& if (exists(name))
\&     expandto(valueof(name))
\& else
\&     Error(string)
.Ve
.PP
Previous constructs may be nested when variable expansion contains no
parenthesis. You may for instance need these forms:
.PP
`Set a variable if unset'.
.PP
.Vb 1
\&  $(var=$(var:\-string))
.Ve
.PP
`Redefine a variable if it is already set.'
.PP
.Vb 1
\&  $(var=$(var:+string))
.Ve
.PP
Notice that nested expressions are not handled as shells do. In shells
expressions are treated from left to right, whereas \f(CW\*(C`ipp\*(C'\fR treat inner
expressions first.  With this example below
.PP
.Vb 2
\&  $(foo=bar)
\&  $(foo:\-$(foo=quux))
.Ve
.PP
Bourne shells will show \f(CW\*(C`bar\*(C'\fR whereas \f(CW\*(C`ipp\*(C'\fR will print \f(CW\*(C`quux\*(C'\fR.
.PP
It is also possible to undefine a variable.  To do so, assign an empty
value to this variable, e.g.
.PP
.Vb 1
\&  $(foo=)
.Ve
.PP
Notice the possibility to do simple If-Then-Else constructs:
.PP
.Vb 1
\&  $(foo:+string_when_set)$(foo:*string_when_not_set)
.Ve
.PP
This is equivalent to the following pseudo-code:
.PP
.Vb 4
\&  if (exists(foo))
\&      expandto(string_when_set)
\&  else
\&      expandto(string_when_not_set)
.Ve
.SS "\fBImplicit \s-1IPP\s0 Variables\fP"
.IX Subsection "Implicit IPP Variables"
The strings \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR are always substituted by the
currently processed include file and the current line number.
.SS "\fBComments\fP"
.IX Subsection "Comments"
\&\s-1IPP\s0 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 (`\f(CW\*(C`#\*(C'\fR') 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 \f(CW\*(C`\e#\*(C'\fR, i.e. prefix it with an escaping
backslash.
.SS "\fBEnd-Of-File Stopping\fP"
.IX Subsection "End-Of-File Stopping"
It stops processing the current include file when a line containing just
.PP
.Vb 1
\&  _\|_END_\|_
.Ve
.PP
occurs. Use this to append \s-1POD\s0 documents to include files for documentation
purposes as in Perl. You can use \f(CW\*(C`_\|_END_\|_\*(C'\fR in constructs like
\&\f(CW\*(C`$(SHORTENING:+_\|_END_\|_)\*(C'\fR, so that the processing is only stopped
when the variable \s-1SHORTENING\s0 is set.
.SS "\fBEnd-Of-Line Continuation\fP"
.IX Subsection "End-Of-Line Continuation"
It removes all occurrences of the pattern
.PP
.Vb 1
\&  \e<whitespace>*<newline><whitespace>*
.Ve
.PP
Use this to let one or more lines to be concatenated.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-D\fR \fIname\fR\fB=\fR\fIvalue\fR" 4
.IX Item "-D name=value"
Defines a variable the for the initial \fIinputfile\fR the same way you define
ones with the \fB#include\fR for include files.  The variable can be interpolated
via \f(CW\*(C`$(name)\*(C'\fR in all files.
.IP "\fB\-S\fR \fIincludedir\fR" 4
.IX Item "-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.
.IP "\fB\-I\fR \fIincludedir\fR" 4
.IX Item "-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.
.IP "\fB\-s\fR \fIincludefile\fR" 4
.IX Item "-s includefile"
Pre-load a particular include file, i.e. virtually adds a
.Sp
.Vb 1
\&  #include <includefile>
.Ve
.Sp
in front of \fIinputfile\fR. Use this to automatically load default system
include files. You can also use the syntax \f(CW\*(C`type::category::file\*(C'\fR
which leads to a virtually added
.Sp
.Vb 1
\&  #include <category/file.type>
.Ve
.IP "\fB\-i\fR \fIincludefile\fR" 4
.IX Item "-i includefile"
Pre-loads a particular include file, i.e. virtually adds a
.Sp
.Vb 1
\&  #include "includefile"
.Ve
.Sp
in front of \fIinputfile\fR. Use this to automatically load default user include
files.   You can also use the syntax \f(CW\*(C`type::category::file\*(C'\fR which leads to a
virtually added
.Sp
.Vb 1
\&  #include "category/file.type"
.Ve
.IP "\fB\-M\fR \fIoptions\fR" 4
.IX Item "-M options"
Output a rule suitable for `make' describing the dependencies of each output
file, as `gcc' does. It has only sense when the \fB\-o\fR option is used.
.Sp
The \fBD\fR 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 \*(L".d\*(R".
.Sp
The \fBM\fR flag option deletes the system files from the list of dependencies.
.IP "\fB\-P\fR \fIpath\fR" 4
.IX Item "-P path"
This sets up one or more prolog program \fIpath\fR 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 \s-1STDIN\s0 and has to
produce the filtered data on \s-1STDOUT.\s0
.IP "\fB\-m\fR \fImapfile\fR" 4
.IX Item "-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:
.Sp
.Vb 3
\&   #  comment line
\&   <blank line>
\&   <oldname>[,<oldname>] <newname> \e[S|W|E: <text>\e]
.Ve
.Sp
Example:
.Sp
.Vb 1
\&   <std/headfoot.wml>,wml::std::headfoot wml::OBSOLETE::std::headfoot [S]
.Ve
.IP "\fB\-N\fR \fInosynclines\fR" 4
.IX Item "-N nosynclines"
By default, \s-1WML\s0 inserts some instructions to synchronize line numbers,
which are then interpreted in passes 2 and 3.  This option disables this
feature.
.IP "\fB\-o\fR \fIoutputfile\fR" 4
.IX Item "-o outputfile"
This redirects the output to \fIoutputfile\fR. Usually the output
will be send to \f(CW\*(C`stdout\*(C'\fR if no such option is specified or
\&\fIoutputfile\fR is "\f(CW\*(C`\-\*(C'\fR".
.IP "\fB\-v\fR" 4
.IX Item "-v"
This sets verbose mode where some processing information will be given on the
console.
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 3
\& Ralf S. Engelschall
\& rse@engelschall.com
\& www.engelschall.com
\&
\& Denis Barbier
\& barbier@engelschall.com
.Ve