diff options
Diffstat (limited to 'doc')
| -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 @@ -38,13 +38,13 @@ @copying 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 any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``GNU Pies Manual'', and with the Back-Cover Texts as in (a) below. A copy of the license @@ -346,12 +346,17 @@ with @samp{#} or @samp{//} and continue to the end of the line: @smallexample # This is a comment // 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 occurrence of @samp{*/} (star, slash). Multi-line comments cannot be nested. @@ -535,15 +540,72 @@ component multiplexor @{ The closing curly brace may be followed by a semicolon, although 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 +@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 @ifnothtml @ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}. @end ifnothtml @ifhtml @uref{http://www.gnu.org/software/m4/manual}. @@ -554,23 +616,24 @@ acquainted with @command{m4} macro processor. @flindex pp-setup The external preprocessor is invoked with @option{-s} flag, instructing 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 is similar to GNU m4 @option{--prefix-builtin} options, but has an advantage that it works with non-GNU @command{m4} implementations as 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: @table @option @xopindex{define, described} @cindex @option{-D} @item --define=@var{sym}[=@var{value}] @itemx -D @var{symbol}[=@var{value}] @@ -581,12 +644,30 @@ the @var{value} is not given. @cindex @option{-U} @item --undefine=@var{sym} @itemx -U @var{sym} 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 @deffn {Config} component The @code{component} statement defines a new component: @@ -2490,12 +2571,18 @@ Display a short usage summary and exit. @item --inetd @itemx -i Run in @command{inetd}-compatibility mode. It is roughly equivalent to @command{pies --instance=inetd --syntax=inetd}. @xref{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} @item --instance=@var{name} Define the name of the @command{pies} instance. @xref{instances}. @opsummary{lint} @item --lint |