path: root/doc/pies.texi
diff options
Diffstat (limited to 'doc/pies.texi')
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
@@ -41,7 +41,7 @@ Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301 USA
-Copyright @copyright{} 2005-2013 Sergey Poznyakoff
+Copyright @copyright{} 2005-2014 Sergey Poznyakoff
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -349,6 +349,11 @@ with @samp{#} or @samp{//} and continue to the end of the line:
// This too is a comment
@end smallexample
+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
@dfn{Multi-line} or @dfn{C-style} comments start with the two
characters @samp{/*} (slash, star) and continue until the first
@@ -538,9 +543,66 @@ this is not required.
@node Preprocessor
@subsection Using Preprocessor to Improve the Configuration.
@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
+@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
+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
@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
@@ -557,8 +619,7 @@ it to include line synchronization information in its output. This
information is then used by the parser to display meaningful
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.
The default @file{pp-setup} file renames all @command{m4} built-in
macro names so they all start with the prefix @samp{m4_}. This
@@ -566,8 +627,10 @@ is similar to GNU m4 @option{--prefix-builtin} options, but has an
advantage that it works with non-GNU @command{m4} implementations as
-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:
@table @option
@xopindex{define, described}
@@ -584,6 +647,24 @@ the @var{value} is not given.
Undefine symbol @var{sym}.
@end table
+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
@section Component Statement
@kwindex component
@@ -2493,6 +2574,12 @@ Run in @command{inetd}-compatibility mode. It is roughly
equivalent to @command{pies --instance=inetd --syntax=inetd}.
+@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}.
@item --instance=@var{name}
Define the name of the @command{pies} instance. @xref{instances}.

Return to:

Send suggestions and report system problems to the System administrator.