aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/pies.texi101
1 files changed, 94 insertions, 7 deletions
diff --git a/doc/pies.texi b/doc/pies.texi
index b45a164..37ade1b 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -43,3 +43,3 @@ Boston, MA 02110-1301 USA
-Copyright @copyright{} 2005-2013 Sergey Poznyakoff
+Copyright @copyright{} 2005-2014 Sergey Poznyakoff
@@ -351,2 +351,7 @@ with @samp{#} or @samp{//} and continue to the end of the line:
+The following constructs, appearing at the start of a line are
+treated specially: @samp{#include}, @samp{#include_once},
+@samp{#line}, @samp{# @var{num}} (where @var{num} is a decimal number).
+These are described in detail in @ref{Preprocessor}.
+
@cindex multi-line comments
@@ -540,5 +545,62 @@ this is not required.
@cindex preprocessor
+Before parsing, configuration file is preprocessed. This goes in
+three stages. First, include directives are expanded. An
+@dfn{include directive} begins with a @samp{#} sign at the beginning
+of a line, followed by the word @samp{include} or @samp{include_once}.
+Any amount of whitespace is allowed between the @samp{#} and the
+word. The entire text up to the end of the line is removed and
+replaced using the following rules:
+
+@table @code
+@kwindex #include
+@item #include <@var{file}>
+@itemx #include @var{file}
+The contents of the file @var{file} is included. There are three possible
+use cases.
+
+If @var{file} is an absolute file name, the named file is included.
+An error message will be issued if it does not exist.
+
+If @var{file} contains wildcard characters (@samp{*}, @samp{[},
+@samp{]} or @samp{?}), it is interpreted as shell globbing pattern and
+all files matching that pattern are included, in lexicographical
+order. If no matching files are found, the directive is replaced with
+an empty line.
+
+Otherwise, the form with angle brackets searches for file in the
+@dfn{include search path}, while the second one looks for it in the
+current working directory first, and, if not found there, in the
+include search path. If the file is not found, an error message will
+be issued.
+
+@cindex include search path, preprocessor
+@cindex include directories, preprocessor
+@cindex preprocessor include search path
+@anchor{include search path}
+The include search path is:
+
+@enumerate 1
+@item
+@xopindex{include-directory, described}
+Any directories supplied with the @option{-I} (@option{--include-directory})
+command line option. These directories are scanned in the same order
+as they appear in the command line.
+
+@item @file{@var{prefix}/share/pies/@value{VERSION}/include}
+@item @file{@var{prefix}/share/pies/include}
+@end enumerate
+
+@noindent
+where @var{prefix} is the installation prefix.
+
+@kwindex #include_once
+@item #include_once <@var{file}>
+@itemx #include_once @var{file}
+ Same as @code{#include}, except that, if the @var{file} has already
+been included, it will not be included again.
+@end table
+
@cindex m4
- Before parsing, the configuration file is @dfn{preprocessed} using
-external preprocessor @command{m4}. For a complete user manual, refer
+ The obtained material is then passed to @command{m4} for
+preprocessing. For a complete user manual, refer
to
@@ -559,4 +621,3 @@ diagnostic. An initial set of macro definitions is supplied by the
@file{pp-setup} file, located in
-@file{@var{$prefix}/share/pies/@var{version}/include} directory (where
-@var{version} means the version of the package).
+@file{@var{$prefix}/share/pies/@value{VERSION}/include} directory.
@@ -568,4 +629,6 @@ well.
-Additional preprocessor symbols may be defined and the existing
-symbols may be undefined using the following command line options:
+The include path for @command{m4} is set as described above.
+
+Additional preprocessor symbols may be defined and existing
+definitions cancelled using the following command line options:
@@ -586,2 +649,20 @@ Undefine symbol @var{sym}.
+Finally, the @command{m4} output is passed to the configuration
+parser. When parsing, the following constructs appearing at the
+beginning of a line are handled specially:
+
+@table @code
+@kwindex #line
+@item #line @var{num}
+@itemx #line @var{num} "@var{file}"
+ This line causes the parser to believe, for purposes of error
+diagnostics, that the line number of the next source line is given by
+@var{num} and the current input file is named by @var{file}.
+If the latter is absent, the remembered file name does not change.
+
+@item # @var{num} "@var{file}"
+ This is a special form of @code{#line} statement, understood for
+compatibility with the @sc{c} preprocessor.
+@end table
+
@node Component Statement
@@ -2495,2 +2576,8 @@ equivalent to @command{pies --instance=inetd --syntax=inetd}.
+@opsummary{include-directory}
+@item --include-directory=@var{dir}
+@itemx -I @var{dir}
+Add directory @var{dir} to the list of directories to be scanned for
+include files. @xref{include search path}.
+
@opsummary{instance}

Return to:

Send suggestions and report system problems to the System administrator.