aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore3
-rw-r--r--Makefile.am2
-rw-r--r--am/grecs.m421
-rw-r--r--doc/GRECS_SETUP.3131
-rw-r--r--doc/Makefile.am33
-rw-r--r--doc/grecs-syntax.texi10
-rw-r--r--doc/grecs_asprintf.390
-rw-r--r--doc/grecs_config.5343
-rw-r--r--doc/grecs_error.3132
-rw-r--r--doc/grecs_format_locus.368
-rw-r--r--doc/grecs_format_node.3102
-rw-r--r--doc/grecs_format_node_path.371
-rw-r--r--doc/grecs_format_value.366
-rw-r--r--doc/grecs_include_path_setup.368
-rw-r--r--doc/grecs_malloc.3129
-rw-r--r--doc/grecs_node_free.363
-rw-r--r--doc/grecs_parse.3185
-rw-r--r--doc/grecs_stmt_path.5123
-rw-r--r--doc/grecs_strdup.370
-rw-r--r--doc/grecs_tree_free.361
-rw-r--r--doc/tmpl.354
-rw-r--r--src/.gitignore2
-rw-r--r--src/Make-inst.am19
-rw-r--r--src/Make-noinst.am18
-rw-r--r--src/Make.am42
-rw-r--r--tests/Makefile.am2
26 files changed, 1900 insertions, 8 deletions
diff --git a/.gitignore b/.gitignore
index 4e0f5dd..b4b4597 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,14 +1,17 @@
*.a
+*.la
+*.lo
*.o
*.tar.*
*~
.deps
.emacs.desktop
.emacs.desktop.lock
.emacsrc
+.libs
ABOUT-NLS
ChangeLog
INSTALL
Makefile
Makefile.in
TAGS
diff --git a/Makefile.am b/Makefile.am
index 96bfab7..643d06a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,2 +1,2 @@
-SUBDIRS=src @GRECS_TESTDIR@
+SUBDIRS=src @GRECS_TESTDIR@ @GRECS_DOCDIR@
EXTRA_DIST=@GRECS_BUILD_AUX@
diff --git a/am/grecs.m4 b/am/grecs.m4
index 8de0d08..764ce46 100644
--- a/am/grecs.m4
+++ b/am/grecs.m4
@@ -69,12 +69,14 @@ AC_DEFUN([_GRECS_SET_OPTIONS],
# no preprocessor setup file is installed.
AC_DEFUN([GRECS_SETUP],[
AC_PROG_YACC
AM_PROG_LEX
+ AC_HEADER_SYS_WAIT
+
AC_SUBST([GRECS_SUBDIR],m4_if([$1],,grecs,$1))
_GRECS_SET_OPTIONS([$2])
# **********************
# Preprocessor
# **********************
_GRECS_IF_OPTION_SET([no-preproc],
@@ -136,12 +138,29 @@ AC_DEFUN([GRECS_SETUP],[
AC_CONFIG_TESTDIR(TESTDIR)
AC_CONFIG_FILES(TESTDIR/Makefile TESTDIR/atlocal)
m4_popdef([TESTDIR])
AM_MISSING_PROG([AUTOM4TE], [autom4te])
GRECS_TESTDIR=tests
])
- _GRECS_IF_OPTION_SET([getopt],[GRECS_BUILD_AUX="build-aux/getopt.m4"])
+ _GRECS_IF_OPTION_SET([getopt],[
+ AC_CHECK_HEADERS([getopt.h])
+ AC_CHECK_FUNCS([sysconf getdtablesize getopt_long])
+ GRECS_BUILD_AUX="build-aux/getopt.m4"
+ ])
_GRECS_IF_OPTION_SET([git2chg],[GRECS_BUILD_AUX="$GRECS_BUILD_AUX build-aux/git2chg.awk"])
AC_SUBST([GRECS_BUILD_AUX])
AC_SUBST([GRECS_INCLUDES])
AC_SUBST([GRECS_TESTDIR])
+ AC_SUBST([GRECS_LDADD])
+ AC_SUBST([GRECS_DOCDIR])
+ _GRECS_IF_OPTION_SET([install],[
+ LT_INIT
+ GRECS_LDADD='$(top_builddir)/m4_if([$1],,grecs,$1)/src/libgrecs.la'
+ GRECS_DOCDIR='doc'
+ AC_CONFIG_FILES(m4_if([$1],,grecs,$1)/src/Makefile:m4_if([$1],,grecs,$1)/src/Make-inst.in
+ m4_if([$1],,grecs,$1)/doc/Makefile)
+ ],[
+ GRECS_LDADD='$(top_builddir)/m4_if([$1],,grecs,$1)/src/libgrecs.a'
+ AC_CONFIG_FILES(m4_if([$1],,grecs,$1)/src/Makefile:m4_if([$1],,grecs,$1)/src/Make-noinst.in)
+ ])
+ AC_CONFIG_FILES(m4_if([$1],,grecs,$1)/Makefile)
])
diff --git a/doc/GRECS_SETUP.3 b/doc/GRECS_SETUP.3
new file mode 100644
index 0000000..23c0ad5
--- /dev/null
+++ b/doc/GRECS_SETUP.3
@@ -0,0 +1,131 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_SETUP 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+GRECS_SETUP \- Initialize \fBgrecs\fR submodule.
+.SH SYNOPSIS
+.BI "GRECS_SETUP(" "dir" ", " "options" ", " "pp-setup-file" )
+.SH DESCRIPTION
+The \fBGRECS_SETUP\fR macro is invoked from the host project's
+\fBconfigure.ac\fR. It initializes the \fBgrecs\fR submodule
+variables for compilation within that project.
+.PP
+All arguments are optional.
+.PP
+The
+.I dir
+argument specifies the directory, relative to the source tree top,
+where \fBgrecs\fR has been cloned. If omitted, \fBgrecs\fR is assumed.
+.sp
+For example, if \fBgrecs\fR was cloned using the following command:
+.sp
+.nf
+ git clone ssh://git.gnu.org.ua/gitroot/grecs.git lib/grecs
+.fi
+.sp
+then the \fIdir\fR argument must be \fBlib/grecs\fR.
+.PP
+The
+.I options
+argument is a space-separated list of options. The following options
+are understood:
+.TP
+.B no-preproc
+Disable the use of preprocessor.
+.TP
+.B install
+Create and install shared library \fBlibgrecs.so\fR. Install the
+documentation as well.
+.TP
+.B std-pp-setup
+Install the standard \fBpp-setup\fR file.
+.TP
+.B pp-setup-option
+Add the
+.B --with-pp-setup-file
+option to the produced configuration file. This option allows user to
+control whether to install the \fBpp-setup\fR file.
+.TP
+.B tests
+Build tests.
+.TP
+.B getopt
+Add \fBgetopt.m4\fR to the distributed tarball. The file is located
+in \fIdir\fR/build-aux.
+.TP
+.B git2chg
+Add \fBgit2chg.awk\fR to the distributed tarball. The file is located
+in \fIdir\fR/build-aux.
+.PP
+The
+.I pp-setup-file
+argument supplies the pathname of the alternative preprocessor
+setup file. It is ignored if
+.B std-pp-setup option
+is given.
+.PP
+If neither
+.B std-pp-setup
+option, nor
+.I pp-setup-file
+parameter are supplied, no preprocessor setup file is installed.
+.SH EXAMPLE
+.SS "Default setup"
+.RS 4
+.nf
+GRECS_SETUP
+.fi
+.RE
+.SS "Complex setup"
+The library sources are in \fBlib/grecs\fR. Configure the testsuite
+and add the \fBgetopt.m4\fR file to the distribution. Install
+preprocessor setup file from \fBsrc/pp-setup\fR:
+.sp
+.RS 4
+.nf
+GRECS_SETUP(lib/grecs, [tests getopt], [$(top_srcdir)/src/pp-setup])
+.RE
+.SH "SEE ALSO"
+.BR getopt.m4 (5),
+.BR pp-setup (5).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..9ee12bf
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,33 @@
+# This file is part of grecs - Gray's Extensible Configuration System
+# Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+#
+# Grecs is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# Grecs is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+
+dist_man_MANS = \
+ GRECS_SETUP.3\
+ grecs_asprintf.3\
+ grecs_config.5\
+ grecs_error.3\
+ grecs_format_locus.3\
+ grecs_format_node_path.3\
+ grecs_format_node.3\
+ grecs_format_value.3\
+ grecs_include_path_setup.3\
+ grecs_malloc.3\
+ grecs_node_free.3\
+ grecs_parse.3\
+ grecs_stmt_path.5\
+ grecs_strdup.3\
+ grecs_tree_free.3
+
diff --git a/doc/grecs-syntax.texi b/doc/grecs-syntax.texi
index b95a0ba..5c7c5ca 100644
--- a/doc/grecs-syntax.texi
+++ b/doc/grecs-syntax.texi
@@ -91,14 +91,14 @@ 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}
+@item @file{@var{prefix}/share/@value{PROGNAME}/@value{VERSION}/include}
+@item @file{@var{prefix}/share/@value{PROGNAME}/include}
@end enumerate
@noindent
where @var{prefix} is the installation prefix.
@c FIXME: Uncomment this, if necessary:
@@ -342,18 +342,18 @@ acquainted with @command{m4} macro processor.
instructs 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/@value{PROGNAME}/@var{version}/include}
-directory (where @var{version} means the version of @value{PACKAGE}).
+@file{@var{prefix}/share/@value{PROGNAME}/@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
+is similar to GNU m4 @option{--prefix-builtin} option, but has an
advantage that it works with non-GNU @command{m4} implementations as
well.
@c FIXME:
@ignore
Additional control over the preprocessor is provided via the
diff --git a/doc/grecs_asprintf.3 b/doc/grecs_asprintf.3
new file mode 100644
index 0000000..73be7f0
--- /dev/null
+++ b/doc/grecs_asprintf.3
@@ -0,0 +1,90 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_ASPRINTF 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+grecs_asprintf, grecs_vasprintf \- print to allocated string
+.SH SYNOPSIS
+.nf
+.B #include <grecs.h>
+.sp
+.BI "int grecs_vasprintf(char " "**pbuf" ", size_t " "*psize" \
+ ", const char " "*format" ", "
+.ti +17
+.BI "va_list " "ap" );
+.br
+.BI "int grecs_asprintf(char " "**pbuf" ", size_t " "*psize" \
+ ", const char *" "format" ", ...);"
+.SH DESCRIPTION
+The functions
+.BI grecs_asprintf ()
+and
+.BI grecs_vasprintf ()
+are analogs of
+.BR sprintf (3)
+and
+.BR vsprintf (3),
+except that they operate on dynamically allocated buffers.
+.PP
+If, on entry to the function, \fB*pbuf\fR is NULL and \fB*psize\fR is
+0, both functions will allocate a buffer large enough to hold the
+formatted message and will fill it with the formatted text.
+.PP
+If \fB*pbuf\fR is not NULL, \fBpsize\fR must point to its actual size.
+If that size is not large enough to accomodate the formatted message,
+the buffer will be reallocated accordingly, otherwise it will remain
+unchanged.
+.PP
+In both cases, if the buffer has been reallocated, on return
+\fBpbuf\fR will contain its new address and \fBpsize\fR its new size.
+.PP
+For initial allocation,
+.BR grecs_malloc (3)
+is used. To reallocate memory, both functions use
+.BR grecs_realloc (3).
+.SH RETURN VALUE
+None. If memory allocation fails, a diagnostics is output and the
+program is terminated.
+.SH "SEE ALSO"
+.BR grecs_malloc (3),
+.BR grecs_realloc (3).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/grecs_config.5 b/doc/grecs_config.5
new file mode 100644
index 0000000..579875b
--- /dev/null
+++ b/doc/grecs_config.5
@@ -0,0 +1,343 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_CONFIG 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+\fBGrecs\fR configuration file syntax
+.SH DESCRIPTION
+.PP
+A configuration file consists of statements and comments.
+.PP
+There are three classes of lexical tokens: keywords, values, and
+separators. Blanks, tabs, newlines and comments, collectively called
+\fIwhite space\fR are ignored except as they serve to separate
+tokens. Some white space is required to separate otherwise adjacent
+keywords and values.
+.SH COMMENTS
+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. Single-line comments start
+with
+.B #
+or
+.B //
+and continue to the end of the line:
+.sp
+.RS 4
+.nf
+# This is a comment
+// This too is a comment
+.fi
+.RE
+.PP
+\fIMulti-line\fB or \fIC-style\fB comments start with the two
+characters
+.B /*
+(slash, star) and continue until the first occurrence of
+.B */
+(star, slash).
+.PP
+Multi-line comments cannot be nested. However, single-line comments
+may well appear within multi-line ones.
+.SS "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
+.B #
+sign and end with the next physical newline character.
+.TP
+.BR "#include <" "file" >
+.PD 0
+.TP
+.BR "#include " "file"
+.PD
+Include the contents of the file \fIfile\fR. If it is an
+absolute file name, both forms are equivalent. Otherwise, the form
+with angle brackets searches for the file in the \fIinclude
+search path\fR, while the second one looks for it in the current working
+directory first, and, if not found there, in the include search
+path.
+.sp
+The default include search path is:
+.sp
+\fIprefix\fR/share/\fIPROGNAME\fR/\fIVERSION\fR/include
+.br
+\fIprefix\fR/share/\fIPROGNAME\fR/include
+.sp
+where \fIprefix\fR stands for the installation prefix (normally
+\fB/usr\fR or \fB/usr/local\fR), \fIPROGNAME\fR stands for the name of
+the program which uses the configuration file, and \fIVERSION\fR for
+its version number.
+.sp
+The include search path can be modified using the
+.BI grecs_include_path_setup ()
+and
+.BI grecs_include_path_setup_v ()
+functions. Refer to
+.BR grecs_include_path_setup (3),
+for a detailed discussion.
+.TP
+.BR "#include_once <" "file" >
+.PD 0
+.TP
+.BR "#include_once " "file"
+.PD
+Same as \fB#include\fR, except that, if the \fIfile\fR has already
+been included, it will not be included again.
+.TP
+.BR "#line " "num"
+.PD 0
+.TP
+.BR "#line " "num" " \(dq" "file" "\(dq"
+.PD
+This line causes the parser to believe, for purposes of error
+diagnostics, that the line number of the next source line
+is given by \fInum\fR and the current input file is named by
+\fIfile\fR. If the latter is absent, the remembered file name
+does not change.
+.TP
+.BR "# " "num" " \(dq" "file" "\(dq"
+This is a special form of the \fB#line\fR statement, understood for
+compatibility with the C preprocessor.
+.PP
+These statements provide a rudimentary preprocessing
+features. For more sophisticated ways to modify configuration before
+parsing, see \fBPREPROCESSOR\fR.
+.SH STATEMENTS
+.SS "Simple statement"
+A \fIsimple statement\fR consists of a keyword and value
+separated by any amount of whitespace. Simple statement is terminated
+with a semicolon (\fB;\fR).
+.PP
+The following is a simple statement:
+.sp
+.RS 4
+.nf
+standalone yes;
+pidfile /var/run/slb.pid;
+.RE
+.fi
+.PP
+A \fIkeyword\fR begins with a letter and may contain letters,
+decimal digits, underscores (\fB_\fR) and dashes (\fB-\fR).
+Examples of keywords are:
+.sp
+.RS 4
+.nf
+expression
+output-file
+.RE
+.fi
+.PP
+A \fIvalue\fR can be one of the following:
+.TP
+.I number
+A number is a sequence of decimal digits.
+.TP
+.I boolean
+A boolean value is one of the following: \fByes\fR, \fBtrue\fR,
+\fBt\fR or \fB1\fR, meaning \fItrue\fR, and \fBno\fR,
+\fBfalse\fR, \fBnil\fR, \fB0\fR meaning \fIfalse\fR.
+.TP
+.I unquoted string
+An unquoted string may contain letters, digits, and any of the
+following characters: \fB_\fR, \fB\-\fR, \fB.\fR, \fB/\fR,
+\fB@\fR, \fB*\fR, \fB:\fR.
+.TP
+.I quoted string
+A quoted string is any sequence of characters enclosed in
+double-quotes (\fB\(dq\fR). A backslash appearing within a quoted
+string introduces an \fIescape sequence\fR, which is replaced
+with a single character according to the following rules:
+.nf
+.ul
+ Sequence Replaced with
+ \\a Audible bell character (ASCII 7)
+ \\b Backspace character (ASCII 8)
+ \\f Form-feed character (ASCII 12)
+ \\n Newline character (ASCII 10)
+ \\r Carriage return character (ASCII 13)
+ \\t Horizontal tabulation character (ASCII 9)
+ \\v Vertical tabulation character (ASCII 11)
+ \\\\ A single backslash
+ \\\(dq A double-quote.
+.fi
+In addition, the sequence \fB\\\fInewline\fR is removed from
+the string. This allows to split long strings over several
+physical lines, e.g.:
+.sp
+.nf
+ "a long string may be\\
+ split over several lines"
+.fi
+.sp
+If the character following a backslash is not one of those specified
+above, the backslash is ignored and a warning is issued.
+
+Two or more adjacent quoted strings are concatenated, which gives
+another way to split long strings over several lines to improve
+readability. The following fragment produces the same result as the
+example above:
+.sp
+.nf
+ "a long string may be"
+ " split over several lines"
+.fi
+.TP
+.I Here-document
+A \fIhere-document\fR is a special construct that allows to introduce
+strings of text containing embedded newlines.
+
+The
+.BI "<<" "word"
+construct instructs the parser to read all the following lines up to
+the line containing only \fIword\fR, with possible trailing blanks.
+Any lines thus read are concatenated together into a single string.
+For example:
+.sp
+.nf
+ <<EOT
+ A multiline
+ string
+ EOT
+.fi
+.sp
+The body of a here-document is interpreted the same way as a
+double-quoted string, unless \fIword\fR is preceded by a backslash
+(e.g. \fB<<\\EOT\fR) or enclosed in double-quotes, in which case
+the text is read as is, without interpretation of escape sequences.
+
+If \fIword\fR is prefixed with \fB\-\fR (a dash), then all leading
+tab characters are stripped from input lines and the line containing
+\fIword\fR. Furthermore, \fB\-\fR is followed by a single space,
+all leading whitespace is stripped from them. This allows to indent
+here-documents in a natural fashion. For example:
+.sp
+.nf
+ <<- TEXT
+ The leading whitespace will be
+ ignored when reading these lines.
+ TEXT
+.fi
+.sp
+It is important that the terminating delimiter be the only token on
+its line. The only exception to this rule is allowed if a
+here-document appears as the last element of a statement. In this
+case a semicolon can be placed on the same line with its terminating
+delimiter, as in:
+.sp
+.nf
+ help-text <<-EOT
+ A sample help text.
+ EOT;
+.fi
+.TP
+.I list
+A comma-separated list of values, enclosed in parentheses. The
+following example shows a statement whose value is a list of strings:
+.sp
+.nf
+ alias (test, null);
+.fi
+.sp
+In any context where a list is appropriate, a single value is allowed
+without being a member of a list: it is equivalent to a list with a
+single member. This means that, e.g.
+.sp
+.nf
+ alias test;
+.fi
+.sp
+is equivalent to
+.sp
+.nf
+ alias (test);
+.fi
+.sp
+provided that the \fBalias\fR statement is defined as taking a list as
+its argument.
+.TP
+.I block statement
+A block statement introduces a logical group of
+statements. It consists of a keyword, followed by an optional value,
+called a \fBtag\fR, and a sequence of statements enclosed in curly
+braces, as shown in the example below:
+.sp
+.nf
+ server srv1 {
+ host 10.0.0.1;
+ community "foo";
+ }
+.fi
+.sp
+The closing curly brace may be followed by a semicolon, although
+this is not required.
+.SS PREPROCESSOR
+Before being parsed, the configuration file is preprocessed.
+The built-in preprocessor handles only file inclusion
+and
+.B #line
+statements, while the rest of traditional preprocessing facilities,
+such as macro expansion, is supported via
+.BR m4 (1),
+which is used as external preprocessor.
+.PP
+The external preprocessor is invoked with the \fB-s\fR flag, which
+instructs it to include line synchronization information in its
+output. This information is then used by the parser to display meaningful
+diagnostic.
+.PP
+An initial set of macro definitions is supplied in the file named
+\fBpp-setup\fR file, which is located in
+\fIprefix\fB/share/\fIPROGNAME\fR/\fIVERSION\fR/include}
+directory.
+.PP
+The default \fBpp-setup\fR file renames all m4 built-in
+macro names so they all start with the prefix \fBm4_\fI. This
+is similar to GNU m4 \fB--prefix-builtin\fR option, but has an
+advantage that it works with non-GNU m4 implementations as
+well.
+.SH "SEE ALSO"
+.BR m4 (1),
+.BR grecs_parse (3),
+.BR grecs_include_path_setup (3),
+.BR grecs_tree_process (3).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
diff --git a/doc/grecs_error.3 b/doc/grecs_error.3
new file mode 100644
index 0000000..d747d9a
--- /dev/null
+++ b/doc/grecs_error.3
@@ -0,0 +1,132 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_ERROR 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+grecs_error, grecs_warning \- grecs error reporting functions
+.SH SYNOPSIS
+.nf
+.B #include <grecs.h>
+.sp
+.BI "void grecs_error(grecs_locus_t " "*locus" ", int " "errnum" ", "
+.ti +17
+.BI "const char " "*format" ", ...);"
+.br
+.BI "void grecs_warning(grecs_locus_t " "*locus" ", int " "errnum" ", "
+.ti +17
+.BI "const char " "*format" ", ...);"
+.sp
+.BI "void (*grecs_print_diag_fun)(grecs_locus_t " "*locus" ", "
+.ti +17
+.BI "int " "err" ", int " "errnum" ", const char " "*msg" );
+.sp
+.B extern int grecs_error_count;
+.SH DESCRIPTION
+.BI grecs_error ()
+is a error reporting function for \fBgrecs\fR library. It flushes
+stdout, and outputs to stderr the file name and line number, as
+supplied by the
+.BI locus
+argument, a colon and a space, the message specified by the
+.BR printf (3)-style
+format string \fIformat\fR, and, if \fIerrnum\fR is non-zero, a second
+colon and a space followed by the string given by
+.BI perror (errnum).
+Any arguments required for format should follow \fIformat\fR in the
+argument list. The output is terminated by a newline character.
+.PP
+If \fIlocus\fR is \fBNULL\fR, it is ignored and no file location is
+printed.
+.PP
+Each call to
+.BI grecs_error ()
+increments the value of the
+.BI grecs_error_count
+global variable.
+The
+.BI grecs_warning ()
+function works the same as
+.BI grecs_error (),
+except that it outputs, before the formatted message and after the
+file location, the word \fBwarning\fR, followed by a semicolon
+and a space character. It does not modify the
+.BI grecs_error_count
+variable.
+.PP
+Calling program can modify the behavior of both functions by setting
+.BI grecs_print_diag_fun
+to the address of a custom error-reporting function. This function is
+called with the following arguments:
+.TP
+.I locus
+Location in the file where the error or warning condition is
+encountered. Can be \fBNULL\fR if the condition occurred outside of
+input file context.
+.TP
+.I err
+This argument is \fB1\fR, if the function is called to report an error
+condition and \fB0\fR otherwise (i.e. a warning).
+.TP
+.I errnum
+System error code, or \fB0\fR, if no system error occurred.
+.TP
+.I msg
+Formatted message.
+.PP
+The \fBgrecs_locus_t\fR structure is defined as:
+.sp
+.nf
+.in +5
+typedef struct {
+ char *file;
+ int line;
+} grecs_locus_t;
+.in
+.fi
+.PP
+The \fBfile\fR member points to the file name, and the \fBline\fR
+member contains the input line number.
+.SH RETURN VALUE
+None.
+.SH "SEE ALSO"
+.BR errno (3)
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/grecs_format_locus.3 b/doc/grecs_format_locus.3
new file mode 100644
index 0000000..3803c2b
--- /dev/null
+++ b/doc/grecs_format_locus.3
@@ -0,0 +1,68 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_FORMAT_LOCUS 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+grecs_format_locus \- format and output source file location
+.SH SYNOPSIS
+.nf
+.B #include <grecs.h>
+.sp
+.BI "void grecs_format_locus(grecs_locus_t " "*locus" ", FILE " "*fp" );
+.SH DESCRIPTION
+\fBgrecs_format_locus\fR formats the location from \fIlocus\fR in the
+human-readable form and outputs it to file \fBfp\fR.
+.PP
+The location is output as follows: the file name, followed by a
+semicolon, followed by line number and another semicolon.</