aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/fdl.texi1
-rw-r--r--doc/rendition.texi13
-rw-r--r--doc/wydawca.texi1035
-rw-r--r--src/cmdline.opt2
-rw-r--r--src/config.c4
-rw-r--r--src/vtab.c3
6 files changed, 694 insertions, 364 deletions
diff --git a/doc/fdl.texi b/doc/fdl.texi
index f13635b..edd86d4 100644
--- a/doc/fdl.texi
+++ b/doc/fdl.texi
@@ -1,5 +1,4 @@
@setfilename fdl.info
-@appendix GNU Free Documentation License
@cindex FDL, GNU Free Documentation License
@center Version 1.2, November 2002
diff --git a/doc/rendition.texi b/doc/rendition.texi
index c4092ea..45ac068 100644
--- a/doc/rendition.texi
+++ b/doc/rendition.texi
@@ -1,7 +1,7 @@
@c Let's use the concept of 'renditions' by Fra@,{c}ois Pinard
@c I extended it by adding a FIXME_FOOTNOTE variable, which controls
@c whether FIXME information should be placed in footnotes or
-@c inlined.
+@c inlined.
@c ======================================================================
@c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
@@ -39,10 +39,19 @@
@c Output marks for nodes needing revision, but not in PUBLISH rendition.
+@macro WRITEME
+@ifclear PUBLISH
+@quotation
+@emph{This node is to be written.}
+@end quotation
+@end ifclear
+@end macro
+
@macro UNREVISED
@ifclear PUBLISH
@quotation
-@emph{(This message will disappear, once this node revised.)}
+(@emph{The information in this node may be obsolete or otherwise inaccurate.}
+This message will disappear, once this node revised.)
@end quotation
@end ifclear
@end macro
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index ad274b2..589f2f7 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -31,7 +31,7 @@ Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA
-Copyright @copyright{} 2007 Sergey Poznyakoff
+Copyright @copyright{} 2007, 2009 Sergey Poznyakoff
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
@@ -59,13 +59,12 @@ Software Foundation raise funds for GNU development.''
@page
@contents
-@node Top, Intro, (dir), (dir)
-
-@ifinfo
-@chapter Wydawca
+@ifnottex
+@node Top
+@top Wydawca
This edition of the @cite{Wydawca Manual}, last updated @value{UPDATED},
documents Wydawca Version @value{VERSION}.
-@end ifinfo
+@end ifnottex
@menu
* Intro:: What is Wydawca
@@ -90,12 +89,11 @@ already listed, mentioned here so you can get to them in one step:
How to Configure @command{wydawca}.
-* include::
* syslog::
* sql::
* access methods::
* archivation::
-* directory pairs::
+* spool::
* statistics::
* notification::
@@ -109,7 +107,7 @@ Mail Notification
@end detailmenu
@end menu
-@node Intro, overview, Top, Top
+@node Intro
@chapter Introduction to Wydawca
@cindex introduction
Let's begin with a short synopsis. Suppose you run a developer's
@@ -150,21 +148,21 @@ signature @file{foo-1.0.tar.gz.sig}. Then he creates a special
@dfn{directive} file, that contains information about where the
distributed tarball must be placed, and clear-signs it using his
@acronym{PGP} key, thus obtaining file
-@file{foo-1.0.tar.gz.directive.asc}. Then he uploads these three files
+@file{foo-1.0.tar.gz.directive.asc}. Finally, he uploads these three files
(a @dfn{triplet}) to the upload site, storing them into the directory
@file{/incoming/ftp}.
@cindex release submission daemon
From now on, it is the responsibility of a @dfn{release submission daemon}
to scan the source directories, gather the triplets, verify them,
-and to move any files that had passed the verification successfully to
+and to move any files that had successfully passed verification to
their distribution sites.
@command{Wydawca} is such a release submission daemon. It is able to
-handle any number of @samp{source/destination} pairs, offers an
-extensible logging and mail notification mechanism, allowing both
-package maintainers and site administrators to be immediately notified
-about any occurring problems.
+handle any number of @samp{source/destination} pairs (called
+@dfn{spools}, offers an extensible logging and mail notification
+mechanism, allowing both package maintainers and site administrators
+to be immediately notified about any occurring problems.
@command{Wydawca} supports version 1.1 of directory file, as
described in
@@ -181,19 +179,20 @@ Standalone directives}.
The program is written entirely in @acronym{C}, is highly
effective and consumes little resources.
-@node overview, starting, Intro, Top
+@node overview
@chapter Operation Overview
@cindex operation
@cindex overview
Usually, @command{wydawca} is installed on the machine that receives
-release uploads and is run periodically as a cron-job. It supposes
-that both upload and distribution directories are accessible in the
-local file system hierarchy. If that is not the case (e.g. if upload
-and distribution sites are handled by different machines), one of them
-should be mounted using @acronym{NFS}. Future versions will contain
-special provisions for that case.
-
-@cindex directory pair
+release uploads. It may be run either periodically as a cron-job, or
+as a standalone daemon. It supposes that both upload and distribution
+directories are accessible in the local file system hierarchy. If that
+is not the case (e.g. if upload and distribution sites are handled by
+different machines), one of them should be mounted using
+@acronym{NFS}. Future versions will contain special provisions for
+that case.
+
+@cindex spool
@cindex upload directory
@cindex directory, upload
@cindex source directory
@@ -202,11 +201,11 @@ special provisions for that case.
@cindex directory, distribution
@cindex destination directory
@cindex directory, destination
- A configuration file supplies the utility with the set of
-@dfn{directory pairs}, i.e. pairs of upload and corresponding
-distribution directories. In @command{wydawca} terminology, upload
-directories are also called @dfn{source}, and distribution directories
--- @dfn{destination} directories. The file also supplies all the information
+ A configuration file defines a set of @dfn{spools}, i.e. pairs of
+upload and corresponding distribution directories. In
+@command{wydawca} terminology, upload directories are also called
+@dfn{source}, and distribution directories -- @dfn{destination}
+directories. The file also supplies all the information
necessary to access user and project databases.
When started, @command{wydawca} scans each source directory and
@@ -254,12 +253,13 @@ this stage of the processing, the uploaded files are actually moved to
their destination directories, requested symbolic links are created,
etc.
-@node starting, configuring, overview, Top
+@node starting
@chapter How to invoke @command{wydawca}.
@cindex invocation
@anchor{config-file}
@xopindex{config-file, described}
@sopindex{c, described}
+@UNREVISED{}
@command{Wydawca} gets all information it needs from its
@dfn{configuration file} (@pxref{wydawca.rc}). The default
configuration file is @file{@var{sysconfdir}/wydawca.rc}, but if it is
@@ -292,8 +292,7 @@ the standard error.
@xopindex{cron, described}
Usually you will run @command{wydawca} as a cron job. In that case,
it seldom needs any additional arguments, but we suggest to use
-@option{--cron} command line option anyway. Currently, its effect is
-the same as @option{--syslog}, but it may change in the future.
+@option{--cron} command line option anyway.
@anchor{debug}
@xopindex{debug, described}
@@ -334,179 +333,379 @@ $ wydawca -c new.cfg --dry-run
@option{--help} (@option{-h}) prints a short usage summary, and
@option{--version} (@option{-v}) prints program version number.
-@node configuring, wydawca.rc, starting, Top
+@node configuring
@chapter How to Configure @command{wydawca}.
-@UNREVISED
- The @command{wydawca} configuration file has a simple line-oriented
-syntax. Empty lines are ignored. Comments are introduced by a pound
-sign (@samp{#}): everything starting from the first occurrence of
-@samp{#} up to the end of line is ignored as well. Non-empty
-and non-comment lines must contain valid configuration statements.
-
- A @dfn{configuration statement} consists of a @dfn{command word}
-optionally followed by one or more @dfn{arguments}, separated by any
-amount of whitespace. There are @samp{simple} and @samp{compound}
-configuration statements. @dfn{Simple statements} occupy a single
-line, for example:
+ Upon startup, @command{wydawca} reads its settings from the
+@dfn{configuration file} @file{wydawca.rc}. By default it is located
+in @var{$sysconfidr} (i.e., in most cases @file{/usr/local/etc}, or
+@file{/etc}), but an alternative location may be specified using
+@option{--config} command line option (@FIXME-pxref{--config}).
+
+ If any errors are encountered in the configuration file, the program
+reports them on its error output and exits with a non-zero status.
+
+@xopindex{lint, introduced}
+ To test the configuration file without starting the server use
+@option{--lint} (@option{-t}) command line option. It causes
+@command{wydawca} to check configuration file for syntax errors and
+other inconsistencies and to exit with status 0 if no errors were
+detected, and withs status 1 otherwise.
+
+@opindex -E, introduced
+@xopindex{no-preprocessor, introduced}
+ Before parsing, configuration file is preprocessed using
+@command{m4} (@FIXME-pxref{Preprocessor}). To see the preprocessed
+configuration without actually parsing it, use @option{-E} command
+line option. To avoid preprocessing it, use
+@option{--no-preprocessor} option.
+
+@xopindex{config-help, introduced}
+ The rest of this section describes the configuration file syntax in
+detail. You can receive a concise summary of all configuration
+directives any time by running @command{wydawca --config-help}.
+
+@menu
+* Syntax:: Configuration file syntax.
+* syslog::
+* sql::
+* access methods::
+* archivation::
+* spool::
+* statistics::
+* notification::
+@end menu
+
+@node Syntax
+@section Configuration file syntax
+
+ Wydawca 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::
+@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. Wydawca version @value{VERSION},
+understands the following pragmatic comments:
+
+@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/wydawca/@value{VERSION}/include}
+@item @file{@var{prefix}/share/wydawca/include}
+@end enumerate
+
+@noindent
+where @var{prefix} is the installation prefix.
+
+ New directories can be appended in front of it using @option{-I}
+(@option{--include-dir}) command line option (@FIXME-pxref{--include-dir}).
+
+@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 @command{wydawca} 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 @FIXME-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{;}).
+
+ Examples of simple statements:
@smallexample
-syslog-print-priority yes
+daemon yes;
+pidfile /var/run/wydawca.pid;
@end smallexample
-If a simple statement is so long that it is inconvenient to keep it on
-a single line, it can be split over several lines by ending each line
-except the last one with a backslash character (@samp{\}). Notice,
-that the backslash character must immediately precede the terminating
-newline. For example, this is a single statement split over several lines:
+ A @dfn{keyword} begins with a letter and may contain letters,
+decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
+Examples of keywords are: @samp{group}, @samp{file-sweep-time}.
+
+ 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
-user-data sql default SELECT realname, email \
- FROM user \
- WHERE user_name='%@{user@}'
+"a long string may be\
+ split over several lines"
@end group
@end smallexample
+ If the character following a backslash is not one of those specified
+above, the backslash is ignored and a warning is issued.
-A @dfn{compound statement} begins with a simple statement, occupies
-several lines, and ends with @code{end} statement, appearing on a line
-by itself. Within a compound statement any number of another
-statements (both simple and compound) may appear.
+ 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:
-@cindex scope of a statement
-When a statement appears outside of any block statement, we say that
-it appears at @dfn{the top level} or @dfn{its scope is global}. When
-it appears within a block statement, we say that @dfn{it has block
-scope}.
+@smallexample
+@group
+"a long string may be"
+" split over several lines"
+@end group
+@end smallexample
- This subsection will guide you through the @command{wydawca}
-configuration on a step-by-step basis.
+@anchor{here-document}
+@item Here-document
+@cindex here-document
+ A @dfn{here-document} is a special construct that allows to introduce
+strings of text containing embedded newlines.
-@menu
-* include::
-* syslog::
-* sql::
-* access methods::
-* archivation::
-* directory pairs::
-* statistics::
-* notification::
-@end menu
+ The @code{<<@var{word}} construct instructs the parser to read all
+the following lines up to the line containing only @var{word}, with
+possible trailing blanks. Any lines thus read are concatenated
+together into a single string. For example:
-@node include
-@section Include Statement
-@cindex inclusion, configuration file
-@kwindex include
-@UNREVISED
-You can request inclusion of any file into your configuration file
-using @code{include} statement. Its only argument supplies the name of
-file to be included. For example:
+@smallexample
+@group
+<<EOT
+A multiline
+string
+EOT
+@end group
+@end smallexample
+
+ Body of a here-document is interpreted the same way as
+double-quoted string, unless @var{word} is preceded by a backslash
+(e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case
+the text is read as is, without interpretation of escape sequences.
+
+ If @var{word} is prefixed with @code{-} (a dash), then all leading
+tab characters are stripped from input lines and the line containing
+@var{word}. Furthermore, if @code{-} 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:
@smallexample
-include /etc/wydawca/msg
+@group
+<<- TEXT
+ All leading whitespace will be
+ ignored when reading these lines.
+TEXT
+@end group
@end smallexample
- The effect of the above statement is that the contents of file
-@file{/etc/wydawca/msg} is read and processed as if it were here,
-instead of the @code{include} statement.
-
- The include statement is especially useful if you wish to avoid
-keeping large static blocks of text in your configuration file, to
-make it more readable. An example of such large blocks of text are
-templates for notification messages (@pxref{notification}), which we
-suggest to keep in a separate file, and to include this file into the
-main configuration (this approach is used in the default configuration
-files).
-
-@cindex inclusion directory
-@cindex default inclusion directory
- The @code{include} argument may also be a relative
-file name (i.e. one not beginning with @samp{/}). In this case,
-@command{wydawca} will look for that file in its @dfn{inclusion
-directory}. By default, the inclusion directory is your system
-configuration directory. So, for example, in the default
-configuration, the following two statements are equivalent:
+ 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:
@smallexample
-include message/stat
-include /usr/local/etc/message/stat
+help-text <<-EOT
+ A sample help text.
+EOT;
@end smallexample
-@xopindex{include-directory, described}
-@sopindex{I, described}
- The value of the inclusion directory can be changed at run time,
-using the @option{--include-directory} (@option{-I}) command line
-option. This option takes an @emph{optional} argument, which means
-that if the argument is supplied, it must follow the short form of the
-option immediately, without any intervening whitespace, as in
-@option{-I/var/inc}. Similarly, when the long option form is used, the
-argument must be separated from it by a single equals sign, as in
-@option{--include-directory=/var/inc}.
-
- If an argument is given, this option instructs @command{wydawca} to
-use it as the new inclusion path. Otherwise, if argument is omitted,
-the include directory is defined as a directory part of the full
-file name of the configuration file. This form might be useful when
-debugging new configurations. For example, the following command
-runs @command{wydawca} in dry run mode, using configuration file
-@file{./test.rc}, and looking for include files in the current working
-directory:
+@item list
+@cindex list
+ A @dfn{list} is a comma-separated list of values. Lists are
+enclosed in parentheses. The following example shows a statement
+whose value is a list of strings:
@smallexample
-$ wydawca --config ./test.rc -I --dry-run
+alias (test,null);
@end smallexample
- Please notice, that unlike many other programs (e.g. @command{cc} or
-@command{make}), @command{wydawca} allows only one value of the
-inclusion directory: inclusion paths are not supported. If the command
-line contains several @option{-I} options, only the last of them takes
-effect.
+ In any case 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.
+
+@smallexample
+alias test;
+@end smallexample
+
+@noindent
+is equivalent to
+
+@smallexample
+alias (test);
+@end smallexample
+@end table
+
+@cindex statement, block
+@cindex block statement
+ A @dfn{block statement} introduces a logical group of
+statements. It consists of a keyword, followed by an optional value,
+and a sequence of statements enclosed in curly braces, as shown in
+the example below:
+
+@smallexample
+@group
+spool download @{
+ source /home/ftp/incoming/ftp;
+ destination /home/ftp/pub;
+@}
+@end group
+@end smallexample
+ The closing curly brace may be followed by a semicolon, although
+this is not required.
+
@node syslog
@section Syslog Configuration Directives
@cindex syslog, configuration
-@kwindex syslog-facility
-@UNREVISED
+@kwindex syslog
+
Unless told otherwise, @command{wydawca} uses @code{syslog} to print
its diagnostic messages. By default, the program uses the
-@samp{local1} facility. To change this, use @code{syslog-facility}
-statement:
+@samp{local1} facility. The @code{syslog} statement allows to change that:
@smallexample
-syslog-facility local2
+syslog @{
+ facility local1;
+ tag wydawca;
+ print-priority yes;
+@}
@end smallexample
+@deffn {Configuration} facility @var{name}
@kwindex authpriv@r{, syslog facility}
@kwindex cron@r{, syslog facility}
@kwindex daemon@r{, syslog facility}
@kwindex ftp@r{, syslog facility}
@kwindex local0 @r{through} local7@r{, syslog facilities}
@kwindex mail@r{, syslog facility}
- It takes a single argument, denoting the facility to use. Allowed
-values are: @samp{auth}, @samp{authpriv}, @samp{cron}, @samp{daemon},
-@samp{ftp}, @samp{local0} through @samp{local7}, and
-@samp{mail}. These names are case-insensitive and may be optionally
-prefixed with @samp{log_} (case-insensitive as well).
+ Configures the syslog facility to use. Allowed values are:
+@samp{auth}, @samp{authpriv}, @samp{cron}, @samp{daemon}, @samp{ftp},
+@samp{local0} through @samp{local7}, and @samp{mail}. These names are
+case-insensitive and may be optionally prefixed with @samp{log_}
+(case-insensitive as well).
+@end deffn
-@kwindex syslog-tag
+@deffn {Configuration} tag @var{string}
@cindex syslog tag, configuring
- Another thing you may wish to tune is the @dfn{syslog tag}, a string
-identifying each message issued by the program. By default it is a
-string @samp{wydawca}. To change it, use @code{syslog-tag} statement:
-
-@smallexample
-syslog-tag uploads
-@end smallexample
+ This statement sets the @dfn{syslog tag}, a string
+identifying each message issued by the program. By default, the
+name of the program (@samp{wydawca}) is used.
+@end deffn
-@kwindex syslog-print-priority
+@deffn {Configuration} print-priority @var{bool}
@cindex syslog priority, printing in diagnostics
In addition to priority segregation, provided by @command{syslog},
you can instruct @command{wydawca} to prefix each syslog message with
its priority. To do so, set:
@smallexample
-syslog-print-priority yes
+print-priority yes;
@end smallexample
+@end deffn
@node sql
@section @acronym{SQL} Databases
@@ -514,9 +713,9 @@ syslog-print-priority yes
@cindex @acronym{SQL} databases
@cindex @command{MySQL} databases
@cindex database, @command{MySQL}
-@UNREVISED
-Several statements in configuration file may need to access
-@acronym{SQL} database. @command{Wydawca} can use any number of
+
+Several statements in configuration file may need to access an
+@acronym{SQL} database. @command{Wydawca} is able to use any number of
databases simultaneously, the only restriction being that they must be
@command{MySQL} databases (this restriction will be removed in future
releases).
@@ -527,52 +726,52 @@ following syntax:
@smallexample
@group
-sql @var{identifier}
- @var{statements}
-end
+sql @var{id} @{
+ host @var{hostname};
+ database @var{dbname};
+ user @var{username};
+ password @var{string};
+@}
@end group
@end smallexample
- Here, @var{identifier} is a string uniquely identifying this
+ Here, @var{id} is a string uniquely identifying this
database. It is used by another configuration statements (e.g. by
access methods, see the next section) to refer to this
-database. @var{statements} stand for a set of statements that
-determine access credentials for the database. Allowed statements are:
+database.
-@table @code
-@kwindex host
-@item host @var{hostname}[:@var{port-or-socket}]
+@deffn {Configuration} host @var{hostname}[:@var{port-or-socket}]
Set the hostname or @acronym{IP} address of the host running the
-database. The optional @var{port-or-socket} specifies port number (for
+database. Optional @var{port-or-socket} specifies port number (for
@acronym{TCP} connections) or socket name (for @acronym{UNIX} sockets)
to use. In the latter case, the @var{hostname} and the colon may be
omitted. If, however, it is present, it must be @samp{localhost}.
@xref{sql-host}, for more information and examples.
+@end deffn
-@kwindex database
-@item database @var{name}
+@deffn {Configuration} database @var{name}
Specifies the database name.
+@end deffn
-@kwindex user
-@item user @var{name}
-Specifies the database user name.
+@deffn {Configuration} user @var{name}
+Sets the database user name.
+@end deffn
-@kwindex password
-@item password @var{string}
-Specifies the password for accessing the database.
-@end table
+@deffn {Configuration} password @var{string}
+Sets the password for accessing the database.
+@end deffn
@noindent
An example @code{sql} statement follows:
@smallexample
@group
-sql default
- host project.database.com:3306
- database savane
- user savane
- password guessme
-end
+sql default @{
+ host project.database.com:3306;
+ database savane;
+ user root;
+ password guessme;
+@}
@end group
@end smallexample
@@ -581,67 +780,84 @@ end
@cindex Access method
@cindex @acronym{PGP} key
@UNREVISED
-An @dfn{access method} defines how @command{wydawca} accesses some
-piece of information it needs while verifying the submission. This
-information can be, for example, the user's @acronym{PGP} key or his
-permissions on a project.
+An @dfn{access method} defines the ways to retrieve user information
+needed to verify the submission. This information can be, for example,
+the user's @acronym{PGP} key or his permissions on a project.
- @command{Wydawca} understands three types of access methods, only
-one of them being implemented right now. These methods are summarized
-in the table below:
+ Access methods are defined in configuration file using the
+following syntax:
+
+@smallexample
+access-method @var{method-name} @{
+ type @var{type};
+ query @var{string};
+ params (@var{param1},@var{param2},...);
+@}
+@end smallexample
+
+ Access method statements can appear either in the global scope of
+the configuration file, or inside a @code{spool} statement
+(@FIXME-pxref{spool}). Global definitions affect all directory
+pairs in the configuration file, and ones inside a @code{directory}
+statement override them for that particular directory pair.
+
+There are four access methods, identified by the value of
+@var{method-name} tag:
+
+@table @asis
+@kwindex gpg-key
+@item gpg-key
+Retrieve the public @acronym{PGP} key of a user. This method must
+return exactly one string.
+
+@kwindex project-owner
+@item project-owner
+ Retrieve email addresses and real names of administrators (or
+@dfn{owners}) of a project. It may return any number of rows, each one
+consisting of two columns: an email address and a user name, in this
+order.
+
+@kwindex user-data
+@item user-data
+ Return email address and real name of a user. This method must
+return one tuple, consisting of two columns: an email address and a user
+name, in this order.
+
+@kwindex verify-user
+@item verify-user
+ Verify if a user is allowed to make uploads for a certain project. This
+method must return the system name of the user if he is allowed to
+make uploads.
+@end table
+
+The sub-statements of @code{access-method} are:
+
+@deffn {Configuration} type @var{name}
+Defines the type of this method. @var{Name} is one of the following:
@table @asis
-@kwindex builtin@r{, access method type}
+@kwindex builtin
@item builtin
- This method is reserved for future use.
+ The data are supplied in the configuration file.
-@kwindex sql@r{, access method type}
+@kwindex sql
@item sql
Retrieve data from an @acronym{SQL} database. Currently only
@command{MySQL} is supported.
-@kwindex external@r{, access method type}
+@kwindex external
@item external
Retrieve data using an external program. This method is reserved for
future use.
@end table
- Access methods are defined in configuration file using the
-following syntax:
-
-@smallexample
-@var{method-name} @var{type} @var{param1} @var{param2}
-@end smallexample
-
-@noindent
-where @var{method-name} is the predefined name of the access method,
-@var{type} is its type and @var{param1} and @var{param2} are
-@dfn{parameters}, that describe the method.
-
- Access method statements can appear either in the global scope of
-the configuration file, or inside a @code{directory} statement
-(@pxref{directory pairs}). Global definitions affect all directory
-pairs in the configuration file, and ones inside a @code{directory}
-statement override them for that particular directory pair.
+See below for a detailed description of these access methods.
+@end deffn
- There are four predefined methods, which are described later in this
-section. The @var{type} must currently always be @samp{sql}. The
-@var{param1} is an identifier of one of the preceding @code{sql} blocks
-(@pxref{sql}), which determines database name and user
-credentials needed to access it. The @var{param2} is an @acronym{SQL}
-statement that must be issued to obtain the requested data. Before
-execution, this statement undergoes @dfn{variable expansion}, whereby
-each occurrence of @code{%@{@var{name}@}} is replaced with the value
-of meta-variable @var{name} (if @var{name} consists of a single
-letter, the curly braces may be omitted).
-
- For example, following are two valid uses of macro-variables:
-@code{%u} and @code{%@{user@}}, the first of them expands to the value
-of macro variable @samp{u}, and the second one expands to the value of
-the variable @samp{user}. Undefined variables are not expanded, but
-are left in the query intact.
-
- The variables defined for use in access methods are:
+@deffn {Configuration} query @var{string}
+Sets the query used for retrieving the data. The @var{string} is
+subject to meta-variable expansion (@FIXME-pxref{meta-variables}). The
+following meta-variables are defined:
@table @code
@kwindex u
@@ -659,85 +875,127 @@ submitted. It is defined as the value of directive
@code{directory}, or, in case this value contains slashes, the
shortest initial prefix of that value, not containing slashes.
@end table
+@end deffn
+
+@deffn {Configuration} params (@var{param1}, @var{param2}, ...)
+Supplies additional parameters for the method.
+@end deffn
+
+@menu
+* sql type::
+* builtin type::
+* external type::
+@end menu
+
+@node sql type
+@subsection SQL Access Methods
+@cindex sql access type
+Access methods having the type @samp{sql} retrieve information from an
+@acronym{SQL} database (as of version @value{VERSION}, only
+@samp{MySQL} databases are supported).
+
+The @code{query} statement supplies the @acronym{SQL} query to
+execute. Normally, it should be a @code{SELECT} query.
+
+The @code{params} statement must supply a single parameter --
+an identifier of one of the preceding @code{sql} blocks (@pxref{sql}),
+which determines database name and user credentials needed to access it.
@cindex Savane
- The rest of this section describes the access methods (referred to
-by @var{method-name} in the syntax above) used by
-@command{wydawca}. They are illustrated by example definitions, based
+ The following sub-nodes contain sample definitions of all four
+access methods using the @code{sql} type. They are based
on the database structure used in
@uref{http://gna.org/projects/savane, @command{Savane} system}.
-@deffn {Access Method} gpg-key
-@cindex @acronym{PGP} public key, retrieving
-@cindex public @acronym{PGP} key, retrieving
+@menu
+* gpg-key-sql::
+* project-owner-sql::
+* user-data-sql::
+* verify-user-sql::
+@end menu
+
+@node gpg-key-sql
+@subsubsection Gpg-key: an SQL Implementation
+@cindex gpg-key
Retrieve the public @acronym{PGP} key of a user. This method must
return exactly one string.
- The sample definition is:
-
@smallexample
-gpg-key sql default SELECT gpg_key \
- FROM user \
- WHERE user_name='%@{user@}'
+access-method gpg-key @{
+ type sql;
+ params (default);
+ query "SELECT gpg_key FROM user WHERE user_name='$@{user@}'";
+@}
@end smallexample
-@end deffn
-@deffn {Access Method} project-owner
+@node project-owner-sql
+@subsubsection Project-owner: an SQL Implementation
+@cindex project-owner
Retrieve email addresses and real names of administrators (or
@dfn{owners}) of a project. It may return any number of rows, each one
consisting of two columns: an email address and a user name, in this order.
@smallexample
-@group
-project-owner sql default SELECT user.email, user.realname \
- FROM user,user_group,groups \
- WHERE user_group.user_id=user.user_id \
- AND user_group.group_id=groups.group_id \
- AND user_group.admin_flags = 'A' \
- AND groups.unix_group_name='%@{project@}'
-@end group
+access-method project-owner @{
+ type sql;
+ params (default);
+ query "SELECT user.email, user.realname "
+ "FROM user,user_group,groups "
+ "WHERE user_group.user_id=user.user_id "
+ "