12 files changed, 398 insertions, 12 deletions

diff --git a/am/grecs.m4 b/am/grecs.m4
index 8d046f5..47c9867 100644
--- a/am/grecs.m4
+++ b/am/grecs.m4
@@ -1,5 +1,5 @@
 # This file is part of grecs - Gray's Extensible Configuration System -*- autoconf -*-
-# Copyright (C) 2007, 2009, 2010 Sergey Poznyakoff
+# Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
 #
 # Grex is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -45,7 +45,7 @@ AC_DEFUN([_GRECS_OPTION_SWITCH],
 
 # _GRECS_SET_OPTIONS(OPTIONS)
 # ----------------------------------
-# OPTIONS is a space-separated list of Gint options.
+# OPTIONS is a space-separated list of Grecs options.
 AC_DEFUN([_GRECS_SET_OPTIONS],
 [m4_foreach_w([_GRECS_Option], [$1], [_GRECS_SET_OPTION(_GRECS_Option)])])
 
diff --git a/doc/grecs-syntax.texi b/doc/grecs-syntax.texi
new file mode 100644
index 0000000..b95a0ba
--- /dev/null
+++ b/doc/grecs-syntax.texi
@@ -0,0 +1,386 @@
+@c This file is part of grecs - Gray's Extensible Configuration System
+@c Copyright (C) 2007, 2009, 2010, 2011 Sergey Poznyakoff
+@c
+@c Grecs is free software; you can redistribute it and/or modify
+@c it under the terms of the GNU General Public License as published by
+@c the Free Software Foundation; either version 3, or (at your option)
+@c any later version.
+@c
+@c Grecs is distributed in the hope that it will be useful,
+@c but WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+@c GNU General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with Grecs.  If not, see <http://www.gnu.org/licenses/>.
+
+@c TIPS: 1. You can @include this file directly into your Texinfo
+@c document.  It produces a section as its upper level sectioning
+@c command.  If it is not appropriate, use @raisesections or
+@c @lowersections:
+@c
+@c   @raisesections
+@c   @include grecs-syntax.texi
+@c   @lowersections
+@c
+@c 2. This texinfo source refers to the following values:
+@c
+@c  PACKAGE     - name of the package
+@c  PROGNAME    - name of the program, which uses Grecs (without any
+@c                Texinfo markup)
+@c
+@c 3. Some additional/optional parts of the text are commented out, and
+@c marked with `@c FIXME:' comments.
+
+@section Configuration file syntax
+
+  The configuration file consists of statements and comments.
+
+  There are three classes of lexical tokens: keywords, values, and
+separators.  Blanks, tabs, newlines and comments, collectively called
+@dfn{white space} are ignored except as they serve to separate
+tokens.  Some white space is required to separate otherwise adjacent 
+keywords and values.
+
+@menu
+* Comments::
+* Pragmatic Comments::
+* Statements::
+* Preprocessor::
+@end menu
+
+@node Comments
+@subsection Comments
+@cindex Comments in a configuration file
+@cindex single-line comments
+  @dfn{Comments} may appear anywhere where white space may appear in the
+configuration file.  There are two kinds of comments:
+single-line and multi-line comments.  @dfn{Single-line} comments start
+with @samp{#} or @samp{//} and continue to the end of the line:
+
+@smallexample
+# This is a comment
+// This too is a comment
+@end smallexample
+
+@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.  However, single-line comments
+may well appear within multi-line ones.
+
+@node Pragmatic Comments
+@subsection Pragmatic Comments
+@cindex comments, pragmatic
+@cindex pragmatic comments
+  Pragmatic comments are similar to usual single-line comments,
+except that they cause some changes in the way the configuration is
+parsed.  Pragmatic comments begin with a @samp{#} sign and end with the
+next physical newline character.
+
+@table @code
+@kwindex #include
+@item #include <@var{file}>
+@itemx #include @var{file}
+Include the contents of the file @var{file}.  If @var{file} is an
+absolute file name, both forms are equivalent.  Otherwise, the form
+with angle brackets searches for the 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.
+
+The default include search path is:
+
+@enumerate 1
+@item @file{@var{prefix}/share/slb/@value{VERSION}/include}
+@item @file{@var{prefix}/share/slb/include}
+@end enumerate
+
+@noindent
+where @var{prefix} is the installation prefix.
+
+@c FIXME: Uncomment this, if necessary:
+@c FIXME:  New directories can be appended in front of it using @option{-I}
+@c FIXME: (@option{--include-directory}) command line option
+@c FIXME: (@pxref{Preprocessor, include-directory}).  
+
+@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.
+
+@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
+
+  In fact, these statements provide a rudimentary preprocessing
+features.  For more sophisticated ways to modify configuration before
+parsing, see @ref{Preprocessor}.
+
+@node Statements
+@subsection Statements
+@cindex statements, configuration file
+@cindex configuration file statements
+@cindex statement, simple
+@cindex simple statements
+  A @dfn{simple statement} consists of a keyword and value
+separated by any amount of whitespace.  Simple statement is terminated
+with a semicolon (@samp{;}).
+
+  The following is a simple statement:
+
+@smallexample
+standalone yes;
+pidfile /var/run/slb.pid;
+@end smallexample
+
+  A @dfn{keyword} begins with a letter and may contain letters,
+decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
+Examples of keywords are: @samp{expression}, @samp{output-file}.
+
+  A @dfn{value} can be one of the following:
+
+@table @asis
+@item number
+  A number is a sequence of decimal digits.
+
+@item boolean
+@cindex boolean value
+  A boolean value is one of the following: @samp{yes}, @samp{true},
+@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
+@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
+  
+@item unquoted string
+@cindex string, unquoted
+  An unquoted string may contain letters, digits, and any of the
+following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
+@samp{@@}, @samp{*}, @samp{:}.
+
+@item quoted string
+@cindex quoted string
+@cindex string, quoted
+@cindex escape sequence
+  A quoted string is any sequence of characters enclosed in
+double-quotes (@samp{"}).  A backslash appearing within a quoted
+string introduces an @dfn{escape sequence}, which is replaced
+with a single character according to the following rules:
+
+@float Table, backslash-interpretation
+@caption{Backslash escapes}
+@multitable @columnfractions 0.30 .5
+@item Sequence @tab Replaced with
+@item \a @tab Audible bell character (@acronym{ASCII} 7)
+@item \b @tab Backspace character (@acronym{ASCII} 8)
+@item \f @tab Form-feed character (@acronym{ASCII} 12)
+@item \n @tab Newline character (@acronym{ASCII} 10)
+@item \r @tab Carriage return character (@acronym{ASCII} 13)
+@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
+@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
+@item \\ @tab A single backslash (@samp{\})
+@item \" @tab A double-quote.
+@end multitable
+@end float
+
+  In addition, the sequence @samp{\@var{newline}} is removed from
+the string.  This allows to split long strings over several
+physical lines, e.g.:
+
+@smallexample
+@group