diff options
Diffstat (limited to 'doc/pies.texi')
-rw-r--r-- | doc/pies.texi | 101 |
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} |