From 0711072135b526c33086175f5e5a82a201b207ac Mon Sep 17 00:00:00 2001
From: Sergey Poznyakoff <gray@gnu.org.ua>
Date: Wed, 9 Dec 2009 17:43:46 +0200
Subject: Improve docs + bugfix.

* doc/Makefile.am (check-options): Fix sed expression.
* doc/wydawca.texi: Update.
* src/job.c (job_start): Don't fork if single_process is set.
---
 doc/wydawca.texi | 277 ++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 171 insertions(+), 106 deletions(-)

(limited to 'doc/wydawca.texi')

diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 82b8403..a136fd6 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -113,10 +113,8 @@ Access Methods
 
 SQL Access Methods
 
-* gpg-key-sql::
 * project-owner-sql::
-* user-data-sql::
-* verify-user-sql::
+* project-uploader-sql::
 
 Mail Notification
 
@@ -372,7 +370,7 @@ reports them on its error output and exits with a non-zero status.
 other inconsistencies and to exit with status 0 if no errors were
 detected, and withs status 1 otherwise. 
 
-@opindex -E, introduced
+@sopindex{E, introduced}
 @xopindex{no-preprocessor, introduced}
   Before parsing, configuration file is preprocessed using
 @command{m4} (@pxref{Preprocessor}). To see the preprocessed
@@ -748,21 +746,48 @@ diagnostic. An initial set of macro definitions is supplied by the
 @file{@var{$prefix}/share/wydawca/@var{version}/include} directory (where
 @var{version} means the version of Wydawca package).
 
-The default @file{pp-setup} file renames all @command{m4} built-in
+  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.  
+well.
+
+  Additional control over the preprocessor is provided via the
+following command line options:
+
+@table @option
+@xopindex{define, introduced}
+@sopindex{D, introduced}
+@item --define=@var{name}[=@var{value}]
+@itemx -D@var{name}[=@var{value}]
+  Define the preprocessor symbol @var{name} as having @var{value}, or
+empty.
+
+@xopindex{include-directory, introduced}
+@sopindex{I, introduced}
+@item --include-directory=@var{dir}
+@itemx -I@var{dir}
+  Add @var{dir} to the list of directories searched for preprocessor
+include files.
+
+@xopindex{no-preprocessor, defined}
+@item --no-preprocessor
+  Disable preprocessor.
+
+@xopindex{preprocessor, defined}
+@item --preprocessor=@var{command}
+Use @var{command} instead of the default preprocessor.
+@end table
 
 @node syslog
 @section Syslog Configuration Directives
 @cindex syslog, configuration
-@kwindex syslog
 
 Unless told otherwise, @command{wydawca} uses @code{syslog} to print
 its diagnostic messages. By default, the program uses the
 @samp{local1} facility. The @code{syslog} statement allows to change that:
 
+@deffn {Config} syslog @{ ... @}
 @smallexample
 syslog @{
   facility local1;
@@ -770,6 +795,8 @@ syslog @{
   print-priority yes;
 @}
 @end smallexample
+@end deffn
+
 
 @deffn {Config: syslog} facility @var{name}
 @kwindex authpriv@r{, syslog facility}
@@ -816,10 +843,9 @@ databases simultaneously, the only restriction being that they must be
 @command{MySQL} databases (this restriction will be removed in future
 releases).
 
-@kwindex sql
-  A database is defined using @code{sql} block statement. It has the
-following syntax:
+  A database is defined using @code{sql} block statement:
 
+@deffn {Config} sql @var{id} @{ ... @}
 @smallexample
 @group
 sql @var{id} @{
@@ -827,6 +853,7 @@ sql @var{id} @{
   database @var{dbname};
   user @var{username};
   password @var{string};
+  ssl-ca @var{string};
 @}
 @end group
 @end smallexample
@@ -835,6 +862,7 @@ sql @var{id} @{
 database. It is used by another configuration statements (e.g. by
 access methods, see the next section) to refer to this
 database. 
+@end deffn
 
 @deffn {Config: sql} host @var{hostname}[:@var{port-or-socket}]
   Set the hostname or @acronym{IP} address of the host running the
@@ -857,6 +885,11 @@ Sets the database user name.
 Sets the password for accessing the database.
 @end deffn
 
+@deffn {Config: sql} ssl-ca @var{file}
+Sets the pathname to the certificate authority file, if you
+wish to use a secure connection to the server via SSL.
+@end deffn
+
 @noindent
   An example @code{sql} statement follows:
 
@@ -875,14 +908,15 @@ sql default @{
 @section Access Methods
 @cindex Access method
 @cindex @acronym{PGP} key
-@UNREVISED
+
 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.
+necessary to verify the submission. This information can be, for
+example, the user's @acronym{PGP} key or his permissions on a project.
 
   Access methods are defined in configuration file using the
 following syntax:
 
+@deffn {Config} access-method
 @smallexample
 access-method @var{method-name} @{
   type @var{type};
@@ -890,6 +924,7 @@ access-method @var{method-name} @{
   params (@var{param1},@var{param2},...);
 @}
 @end smallexample
+@end deffn
 
   Access method statements can appear either in the global scope of
 the configuration file, or inside a @code{spool} statement
@@ -897,15 +932,10 @@ the configuration file, or inside a @code{spool} statement
 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
+There are two 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
@@ -913,17 +943,10 @@ return exactly one string.
 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.
+@kwindex project-uploader
+@item project-uploader
+  Return system user names, real names, emails and GPG keys of
+the users that are allowed to make uploads for the project.
 @end table
 
 The sub-statements of @code{access-method} are:
@@ -956,13 +979,6 @@ subject to meta-variable interpretation (@pxref{meta-interpretation}). The
 following meta-variables are defined:
 
 @table @code
-@kwindex u
-@kwindex user
-@item u
-@itemx user
-@itemx user:name
-  The system name of the user that submitted the triplet.
-
 @kwindex p
 @kwindex project
 @item p
@@ -989,6 +1005,14 @@ Spool destination directory (@pxref{spool, destination}).
 
 @item source-dir
 Spool source directory (@pxref{spool, source}).
+
+@kwindex u
+@kwindex user
+@item u
+@itemx user
+@itemx user:name
+  The system name of the user that submitted the triplet. This is
+defined only in @samp{project-owner} access method.
 @end table
 @end deffn
 
@@ -1005,7 +1029,7 @@ Supplies additional parameters for the method.
 @node sql type
 @subsection SQL Access Methods
 @cindex sql access type
-Access methods having the type @samp{sql} retrieve information from an
+Access methods of @samp{sql} type retrieve information from an
 @acronym{SQL} database (as of version @value{VERSION}, only
 @samp{MySQL} databases are supported).
 
@@ -1013,36 +1037,20 @@ 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}),
+the 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 following sub-nodes contain sample definitions of all four
+  The following sub-nodes contain sample definitions for the 
 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}.
 
 @menu
-* gpg-key-sql::
 * project-owner-sql::
-* user-data-sql::
-* verify-user-sql::
+* project-uploader-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.
-
-@smallexample
-access-method gpg-key @{
-  type sql;
-  params (default);
-  query "SELECT gpg_key FROM user WHERE user_name='$@{user@}'";
-@}
-@end smallexample
-
 @node project-owner-sql
 @subsubsection Project-owner: an SQL Implementation
 @cindex project-owner
@@ -1063,36 +1071,21 @@ access-method project-owner @{
 @}
 @end smallexample
 
-@node user-data-sql
-@subsubsection User-data-sql: an SQL Implementation
-@cindex 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.
-
-@smallexample
-access-method user-data @{
-  type sql;
-  params (default);
-  query  "SELECT email, realname FROM user WHERE user_name='$@{user@}'";
-@}
-@end smallexample
-
-@node verify-user-sql
-@subsubsection Verify-user-sql: an SQL Implementation
-@cindex verify-user-sql
+@node project-uploader-sql
+@subsubsection Project-uploader: an SQL Implementation
+@cindex project-uploader-sql
+@UNREVISED
 
 @smallexample
-access-method verify-user @{
+access-method project-owner @{
   type sql;
   params (default);
-  query   "SELECT user.user_name "
-          "FROM user,user_group, groups "
+  query   "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@}' "
-          "AND user.user_name='$@{user@}'";
+          "AND groups.unix_group_name = '$@{project@}'";
 @}
 @end smallexample
 
@@ -1128,7 +1121,7 @@ appear either in the global scope, in which case it affects all
 spools, or within a @code{spool} block (@pxref{spool}),
 where it affects only the given spool. 
 
-@kwindex archive
+@deffn {Config} archive @var{type}
 @smallexample
 archive @var{type} @{
   name @var{file-or-dir};
@@ -1151,6 +1144,7 @@ archive @var{type} @{
 @item directory
   Store file in a separate directory.
 @end table
+@end deffn
 
 @deffn {Config: archive} name @var{file-or-dir}
   Specify the name of the tar archive (if type @samp{tar} is used) or
@@ -1174,9 +1168,11 @@ using GNU tar @option{--occurrence} option (@pxref{multiple, Multiple
 Files with the Same Name, Multiple Files with the Same Name, tar,
 @acronym{GNU} tar: an archiver tool}).
 
+@deffn {Config} tar-program @var{name}
   By default, @code{wydawca} will search for @command{tar} binary in
 your search path. If you wish to use a particular binary, you may
 specify its full file name using @code{tar-program} statement.
+@end deffn
 
   The @samp{directory} archivation type means that archive copies will
 be stored in a directory specified by the @code{name} statement.
@@ -1270,7 +1266,6 @@ archive-signatures no;
 @node spool
 @section Distribution Spool
 @cindex distribution spool
-@kwindex spool
 @cindex defining source and distribution directories
 @cindex distribution directory, defining
 @cindex source directory, defining
@@ -1286,6 +1281,7 @@ global settings.
 Distribution spool is defined in the configuration file by the
 @code{spool} block statement:
 
+@deffn {Config} spool @var{tag}
 @smallexample
 spool @var{tag} @{
   url @var{url};
@@ -1293,15 +1289,16 @@ spool @var{tag} @{
   source @var{dir};
   destination @var{dir};
   file-sweep-time @var{interval};
-  access-method @dots{}
-  archive @dots{}
-  notify-event @dots{}
+  access-method @{ @dots{} @}
+  archive @{ @dots{} @}
+  notify-event @{ @dots{} @}
 @}
 @end smallexample
 
 The @var{tag} argument defines a unique identifier for this spool. It
 will be used in log messages, timers (@FIXME-pxref{timers}) and in
 meta-variable interpretation (@pxref{meta-interpretation}).
+@end deffn
 
 @deffn {Config: spool} url @var{string}
 Defines download @acronym{URL}, associated with this spool. Its value
@@ -1333,13 +1330,25 @@ are useful mainly for diagnostic purposes.
 @end table
 @end deffn
 
-  The @code{source} and @code{destination} statements are mandatory.
+The following statements, if present, override the corresponding global
+definitions for this spool.
+
+@deffn {Config: spool} archive @{ @dots{} @}
+Configure spool-specific archivation. @xref{archivation}, for its
+description.
+@end deffn
 
-  A @code{spool} block may also contain an @code{archive} statement
-(@pxref{archivation}), access method definitions (@pxref{access
-methods}) and notification statements (@pxref{notification}). Any of
-these statements, if present, override corresponding global definition
-for this spool.
+@deffn {Config: spool} access-method @var{tag} @{ @dots{} @}
+Configure spool-specific access-method. @xref{access
+methods}, for a detailed discussion of this statement.
+@end deffn
+
+@deffn {Config: spool} notify-event @{ @dots{} @}
+Configure spool-specific event notification. @xref{notification},
+for a detailed discussion of this statement.
+@end deffn
+
+  The @code{source} and @code{destination} statements are mandatory.
 
   For example, the following definition says that valid uploads to
 @file{/home/ftp/incoming/ftp} should be transferred to @file{/home/ftp/gnu}:
@@ -1467,7 +1476,7 @@ A symlink is created.
 A symlink is removed.
 @end table
 
-@kwindex statistics
+@deffn {Config} statistics @var{list}
   The amount of information included in the statistics summary is
 configured using the @code{statistics} statement. This statement takes
 a list of arguments, each one being one of the keywords, described
@@ -1504,6 +1513,7 @@ warnings one would set:
 @smallexample
 statistics (all, errors, warnings);
 @end smallexample
+@end deffn
 
 @node notification
 @section Mail Notification
@@ -1519,7 +1529,7 @@ previous section.
   The sender email address for these notifications is set using the
 @code{from-address} statement.
 
-@deffn {Configuration} from-address @var{address}
+@deffn {Config} from-address @var{address}
 Set sender address for outgoing mails. E.g.:
 
 @smallexample
@@ -1533,7 +1543,7 @@ constructed from the name of the user @command{wydawca} runs as
 (@FIXME-pxref{user privs}) and the full domain name of the machine it
 runs at. 
 
-@deffn {Configuration} admin-address @var{email}
+@deffn {Config} admin-address @var{email}
 Sets the admin email address or addresses. The statistics
 notifications and any notifications configured to be sent to admins
 will be forwarded to this address. The @var{email} argument is either
@@ -1571,7 +1581,7 @@ To send messages, @command{wydawca} uses a special logical entity
 called a @dfn{mailer}. It is set in the configuration file using
 @code{mailer} keyword.
 
-@deffn {Configuration} mailer @var{url}
+@deffn {Config} mailer @var{url}
 Set mailer @acronym{URL}.
 @end deffn
 
@@ -1679,7 +1689,7 @@ The message text may be specified either in place within the
 configuration directive it belongs to (@FIXME-pxref{notification}), or
 defined by @code{define-message} statement.
 
-@deffn {Configuration} define-message @var{name} @var{text};
+@deffn {Config} define-message @var{name} @var{text};
 Define message @var{name} to be @var{text}. This message can be
 referred to from other configuration statements by @code{@@@var{name}}
 notation.
@@ -1712,10 +1722,11 @@ EOT;
 
 @node statreports
 @subsection Statistic Reports
-@kwindex mail-statistics
 @UNREVISED
-Sending statistic reports to the system administrator is configured by
-@code{mail-statistics} statement.
+
+@deffn {Config} mail-statistics @{ ... @}
+The @code{mail-statistics} statement configures the statistic reports
+sent to the system administrator.
 
 @smallexample
 mail-statistics @{
@@ -1723,6 +1734,7 @@ mail-statistics @{
   statistics @var{item-list};
 @}
 @end smallexample
+@end deffn
 
 @deffn {Config: mail-statistics} message @var{text-or-id}
 Define the message text. The argument is either the message text
@@ -1825,7 +1837,7 @@ concerned: the system administrator, project administrators, or
 the user that initiated the upload. These notifications are configured
 using the @code{notify-event} statement:
 
-@kwindex notify-event
+@deffn {Config} notify-event @{ ... @}
 @smallexample
 notify-event @{
   event @var{ev-id};
@@ -1833,6 +1845,7 @@ notify-event @{
   message @var{text-or-id};
 @}
 @end smallexample
+@end deffn
 
 @deffn {Config: notify-event} event @var{ev-id}
 Send notification when the event @var{ev-id} occurs. The following
@@ -2292,12 +2305,21 @@ Increase debugging level by 1.
 
 @xref{debug, The @option{--debug} option}.
 
-@opsummary{stderr}
-@item --stderr
-@itemx -e
-Log to the standard error.
+@opsummary{define}
+@item --define=@var{name}[=@var{value}]
+@itemx -D@var{name}[=@var{value}]
+  Define the preprocessor symbol @var{name} as having @var{value}, or
+empty. @xref{Preprocessor}.
 
-@xref{stderr, The @option{--syslog} option}.
+@opsummary{dump-grammar-trace}
+@item --dump-grammar-trace
+Dump configuration grammar traces. This is useful for debugging
+@command{wydawca} configuration file parser.
+
+@opsummary{dump-lex-trace}
+@item --dump-lex-trace
+Dump lexical analyzer traces. This is useful for debugging
+@command{wydawca} configuration file parser.
 
 @opsummary{stderr}
 @item --dry-run
@@ -2307,12 +2329,28 @@ implies @option{--debug --stderr}.
 
 @xref{dry-run, The dry-run mode}.
 
+@opsummary{stderr}
+@item --stderr
+@itemx -e
+Log to the standard error.
+
+@xref{stderr, The @option{--syslog} option}.
+
+@opsummary{force}
+@item --force
+Force start-up, even if if the pid file already exists.
+
+@opsummary{foreground}
+@item --foreground
+Remain in the foreground. This is mostly for debugging
+@command{wydawca}.
+
 @opsummary{include-directory}
 @item --include-directory=@var{dir}
 @itemx -I @var{dir}
 Add @var{dir} to include search path.
 
-@xref{Pragmatic Comments, #include}.
+@xref{Pragmatic Comments, #include}. @xref{Preprocessor}.
 
 @opsummary{lint}
 @item --lint
@@ -2322,6 +2360,33 @@ exit with code 0, if the syntax is OK, and with code 1 otherwise.
 
 @xref{lint, The @option{--lint} option}.
 
+@opsummary{no-preprocessor}
+@item --no-preprocessor
+Disable preprocessor. @pxref{Preprocessor}.
+
+@opsummary{preprocessor}
+@item --preprocessor=@var{command}
+Use @var{command} instead of the default preprocessor. @pxref{Preprocessor}.
+
+@opsummary{single-process}
+@item --single-process
+Serialize job invocations by not forking subprocesses for each job.
+@emph{Do not use this option in production environment}.
+
+@opsummary{source}
+@item --source=@var{name}
+@itemx -s@var{name} 
+Process only the spool with the given source name. This option
+may be given multiple times, to select several spools by their
+source names.
+
+@opsummary{spool}
+@item --spool=@var{tag}
+@itemx -S@var{tag}
+Process only spool with the given tag. This option
+may be given multiple times, to select several spools by their
+tag names.
+
 @opsummary{help}
 @item --help
 @itemx -h
-- 
cgit v1.2.1