Document the module subsystem

1 files changed, 407 insertions, 172 deletions

diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index ca58d1d..db06139 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -37,13 +37,10 @@ Copyright @copyright{} 2007, 2009, 2010, 2011, 2012, 2013, 2014, 2015,
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
-and with the Back-Cover Texts as in (a) below. A copy of the license
-is included in the section entitled ``GNU Free Documentation License''.
+Invariant Sections, no Front-Cover, and no Back-Cover texts.
 
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
+A copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
 @end copying
 
 @titlepage
@@ -144,7 +141,7 @@ Mail Notification
 @chapter Introduction to Wydawca
 @cindex introduction
   Let's begin with a short synopsis. Suppose you run a developer's
-site, like, e.g. @indicateurl{gnu.org}. You have two
+site, such as e.g. @indicateurl{gnu.org}. You have two
 @dfn{distribution @acronym{URL}s}: @indicateurl{ftp.gnu.org}, which
 distributes stable versions of the software, and
 @indicateurl{alpha.gnu.org}, which distributes alpha and pre-test
@@ -194,8 +191,8 @@ their distribution sites.
 
   @command{Wydawca} is such a release submission daemon. It is able to
 handle any number of @samp{source/destination} pairs (called
-@dfn{spools}) in real time, and offers an extensible logging and mail
-notification mechanism, allowing both package maintainers and site
+@dfn{spools}) in real time, and offers extensible logging and 
+notification mechanisms, allowing both package maintainers and site
 administrators to be immediately notified about any occurring problems.
 
   @command{Wydawca} supports upload directive versions 1.1@footnote{
@@ -249,14 +246,14 @@ that case.
 upload and corresponding distribution directories. In
 @command{wydawca} terminology, upload directories are also called
 @dfn{source}, and distribution directories -- @dfn{destination}
-directories. The configuration file also supplies all the information 
+directories. The configuration file supplies also the information 
 necessary to access user and project databases.
 
   When started, @command{wydawca} scans each source directory and
 prepares a list of files found there. Then, it compacts this list by
 looking for @dfn{directive files} and re-arranging list members in
 @dfn{triplets}. A @dfn{directive file} is a special file that must be
-supplied with each upload and that contains directive regarding the
+supplied with each upload and that contains instructions regarding the
 placement of the uploaded files. A @dfn{triplet} is a standard
 entity, consisting of three files: a clear-signed directive file, a
 file to be distributed, and a detached signature of the latter.
@@ -288,8 +285,8 @@ possibility to restart interrupted or otherwise broken uploads later.
 @cindex @acronym{PGP}
   After completing these preliminary stages, @command{wydawca}
 analyzes the directive file and extracts the project name
-from it. Using this name as a key, it looks up in the @dfn{project
-dictionary} a list of users authorized to make uploads for this
+from it. Using this name as a key, it searches in the @dfn{project
+dictionary} for a list of users authorized to make uploads for this
 project. This list contains user names and their corresponding public
 @acronym{PGP} keys. @command{Wydawca} tries to verify the directive
 file using each @acronym{PGP} key from this list, until a matching
@@ -435,6 +432,11 @@ by using the following options:
 $ wydawca --spool=ftp --spool=test --source=/home/ftp/test-upload
 @end smallexample
 
+  Any non-optional arguments appearing in the command line, are
+treated as the uploaders' UIDs.  If present, only triplets uploaded by
+these users will be processed.  Of course, such UIDs can be combined
+with the @option{--spool} and @option{--source} options.
+
 @anchor{debug}
 @xopindex{debug, described}
 @sopindex{d, described}
@@ -480,7 +482,7 @@ $ wydawca -c new.cfg --dry-run
 @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 (@pxref{starting, config-file}).
+@option{--config-file} command line option (@pxref{starting, config-file}).
 
   If any errors are encountered in the configuration file, the program
 reports them on its error output and exits with a non-zero status.
@@ -2252,20 +2254,196 @@ statistics (all, errors, warnings);
 @end deffn
 
 @node notification
-@section Mail Notification
-@cindex mail notification
+@section Notification Mechanism
+@cindex notification
 While running, @command{wydawca} keeps track of certain events
 occurring, such as, for example, broken @acronym{PGP} signatures or
-file uploads attempted by unauthorized users. The utility can notify,
-via email, project administrators about any of those events that
-concern their projects. Additionally, the system administrator can
-choose to obtain via email the execution statistics, described in the
-previous section.
+file uploads attempted by unauthorized users. It can issue
+notifications about such events using the supplied loadable modules.
+
+Configuration of notifications consists of two parts.  First the
+required loadable module must be loaded and configured.  Then,
+configure the notification itself.
+
+@menu
+* modules::
+* event notification::
+* mod_mailutils:: Mail Notification
+* mod_logstat:: Notification to syslog
+@end menu
+
+@node modules
+@subsection modules
+
+A @dfn{loadable module} is a piece of software that provides
+notification mechanism for @command{wydawca}.  It is built as a UNIX
+dynamically loaded library and placed in one of the preconfigured
+directories which constitute a @dfn{library load path}. To load a
+module, the following statement is used:
+
+@deffn {Config} module @var{name} @var{file}
+Load the module @var{name} from @var{file}. Other places of the
+configuration file can refer to the module as @var{name}.
+
+The @var{file} argument is a file name of the module (normally, a
+@samp{file.so} or @samp{file.la} file).
+@end deffn
+
+Unless @var{file} in the @samp{module} statement it is an absolute
+file name, it will be searched in the library load path, which is
+defined as:
+
+@enumerate 1
+@item
+Optional @dfn{prefix} search directories specified by the
+@samp{module-prepend-load-path} directive (see below).
+
+@item
+@command{Wydawca} module directory: @samp{@var{$prefix}/lib/wydawca}.
+
+@item 
+Additional search directories specified by the @command{module-load-path}
+directive (see below).
+
+@item
+The value of the environment variable @env{LTDL_LIBRARY_PATH}.
+
+@item
+The system dependent library search path (e.g. on GNU/Linux it is
+defined by the file @file{/etc/ld.so.conf} and the environment variable
+@env{LD_LIBRARY_PATH}).
+@end enumerate
+
+The value of @env{LTDL_LIBRARY_PATH} and @env{LD_LIBRARY_PATH} must be a
+colon-separated list of absolute directory names, for example
+@samp{/usr/lib/mypkg:/lib/foo}.
+
+In any of these directories, @command{wydawca} first attempts to find
+and load the given filename. If this fails, it tries to append the following
+suffixes to it:
+
+@enumerate 1
+@item the libtool archive suffix: @samp{.la}
+
+@item the suffix used for native dynamic libraries on the host platform,
+e.g., @samp{.so}, @samp{.sl}, etc.
+@end enumerate
+
+The statements that modify the module search path are:
+
+@deffn {Config} module-load-path @var{list}
+This directive adds the directories listed in its argument to the
+module load path.  Example:
+
+@example
+module-load-path (/usr/lib/wydawca,/usr/local/wydawca/lib);
+@end example
+@end deffn
+
+@deffn {Config} module-prepend-load-path @var{list}
+Same as above, but the directories from @var{list} are added to the
+beginning of the module search list, rather than to its end.  The
+order of directories in @var{list} is preserved in both cases.
+@end deffn
+
+Once loaded, the module can be initialized.  This is done by the
+following block statement:
+
+@deffn {Config} module-init @var{name} @{ ... @}
+Initialize the module identified by @var{name}. The module must have
+been previously loaded using the @samp{module} statement, as described
+above. The statements between curly braces are module-specific
+configuration statements. See the module descriptions below for a
+detailed discussion of these.
+@end deffn
+