Update

git-svn-id: file:///svnroot/wydawca/trunk@312 6bb4bd81-ecc2-4fd4-a2d4-9571d19c0d33

1 files changed, 222 insertions, 123 deletions

diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index d991461..1e3fe75 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -90,6 +90,7 @@ already listed, mentioned here so you can get to them in one step:
 
 How to Configure @command{wydawca}.
 
+* include::
 * syslog::
 * sql::
 * access methods::
@@ -267,23 +268,96 @@ user-data sql default   SELECT realname, email \
 @end smallexample
 
 
-@dfn{Compound statements} begin with a simple statement, occupy
-several lines, and end with @code{end} statement, appearing on a line
-by itself. Each line of a compound statement is itself a simple
-statement. 
+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).
+
+@cindex scope of a statement
+When a statement appears outside of any block statement, we say that
+@dfn{it appears at the top level} or @dfn{its scope is global}. When
+it appears within a block statement, we say that @dfn{it has block
+scope}. 
 
   This subsection will guide you through the @command{wydawca}
 configuration on step-by-step basis.
 
 @menu
+* include::
 * syslog::
 * sql::
 * access methods::
 * archivation::
 * directory pairs::
+* statistics::
 * notification::
 @end menu
 
+@node include
+@section Include Statement
+@cindex inclusion, configuration file
+@kwindex include
+  You can request inclusion of any file into your configuration file
+using @code{include} statement. As its argument give it the name of
+file to be included. For example: 
+
+@smallexample
+include /etc/wydawca/msg
+@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}).
+
+@cindex inclusion directory
+@cindex default inclusion directory
+  Argument to the @code{include} statement 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 the @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:
+
+@smallexample
+include message/stat
+include /usr/local/etc/message/stat
+@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 inclusion path. Otherwise, if argument is omitted,
+the include directory is defined as the directory part of the full
+file name of the configuration file. This form might be useful when
+debugging new configurations. For example, the following invocation
+runs @command{wydawca} in dry run mode, using configuration file
+@file{./test.rc}, and looking for include files in the current working
+directory: 
+
+@smallexample
+$ wydawca --config ./test.rc -I --dry-run
+@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.
+
 @node syslog
 @section Syslog Configuration Directives
 @cindex syslog, configuration
@@ -328,124 +402,6 @@ its priority. To do so, set:
 syslog-print-priority yes
 @end smallexample
 
-  At the end of each run, the program prints detailed summary of
-executed actions, which looks like that:
-
-@smallexample
-errors: 0
-warnings: 2
-bad signatures: 0
-access violation attempts: 0
-complete triplets: 6
-incomplete triplets: 2
-bad triplets: 0
-expired triplets: 0
-triplet successes: 6
-files uploaded: 12
-files archived: 2
-symlinks created: 0
-symlinks removed: 0
-@end smallexample
-
-@kwindex statistics
-  You can nofigure the information displayed, using @code{statistics}
-statement. It takes arbitrary number of arguments, each one specifying
-which part of the above statistics to display. For example, given the
-following statement:
-
-@smallexample
-statistics errors warnings
-@end smallexample
-
-@noindent
-the above output will be reduced to
-
-@smallexample
-errors: 0
-warnings: 2
-@end smallexample
-
-@kwindex none@r{, statistics}
-  The special keyword @samp{none} can be used to suppress this output
-altogether (which is the default), as in
-
-@smallexample
-statistics none
-@end smallexample
-
-@kwindex all@r{, statistics}
-  Another special keyword is @samp{all}, that enables all statistics
-output. This keyword may also be followed by any number of usual
-arguments, which are in this case @emph{subtracted}. For example, to
-output all statistics, except errors and warnings one would set:
-
-@smallexample
-statistics all errors warnings
-@end smallexample
-
-  The following table summarizes all the keywords, available for
-@code{statistics} statement:
-
-@table @asis
-@kwindex errors@r{, statistics}
-@item errors
-Total number of errors occurred during the run.
-
-@kwindex warnings@r{, statistics}
-@item warnings
-Total number of warning conditions occurred during the run.
-
-@kwindex bad_signatures@r{, statistics}
-@item bad_signatures
-Total number of bad signatures, i.e. the ones not matching their
-public key.
-
-@kwindex access_violations@r{, statistics}
-@item access_violations
-Number of files, owned by users who have no rights to upload them.
-
-@kwindex complete_triplets@r{, statistics}
-@item complete_triplets
-Number of complete triplets.
-
-@kwindex incomplete_triplets@r{, statistics}
-@item incomplete_triplets
-Number of incomplete triplets, i.e. such that miss one or more of
-their files. Notice, that a directive file alone is counted as a
-complete triplet, provided that its signature verifies correctly and
-that it does not contain @code{file} directive.
-
-@kwindex bad_triplets@r{, statistics}
-@item bad_triplets
-Number of triplets, whose components are owned by different users.
-
-@kwindex expired_triplets@r{, statistics}
-@item expired_triplets
-Number of triplets expired in the queue.
-
-@kwindex triplet_success@r{, statistics}
-@item triplet_success
-Number of successfully processed triplets.
-
-@kwindex uploads@r{, statistics}
-@item uploads
-Number of executed uploads. An upload is defined as a successful move
-of a file and its detached signature from the source to its destination
-directory.
-
-@kwindex archives@r{, statistics}
-@item archives
-Number of archivations performed.
-
-@kwindex symlinks@r{, statistics}
-@item symlinks
-Number of symlinks created.
-
-@kwindex rmsymlinks@r{, statistics}
-@item rmsymlinks
-Number of symlinks removed.
-@end table
-
 @node sql
 @section @acronym{SQL} Databases
 @cindex database, @acronym{SQL}
@@ -850,10 +806,144 @@ different machines, one of the directories can be mounted using
 @acronym{NFS}. The future versions will contain special provisions for
 such case.
 
+@node statistics
+@section Statistics
+@UNREVISED{}
+
+  At the end of the run, @command{wydawca} can print the detailed
+statistics of its execution on the diagnostic channel @samp{info}.
+The following example illustrates what you might get if you configured
+full statistics output:
+
+@smallexample
+errors: 0
+warnings: 2
+bad signatures: 0
+access violation attempts: 0
+complete triplets: 6
+incomplete triplets: 2
+bad triplets: 0
+expired triplets: 0
+triplet successes: 6
+files uploaded: 12
+files archived: 2
+symlinks created: 0
+symlinks removed: 0
+@end smallexample
+
+  Each item in this statistics is configurable, and a
+unique configuration keyword is associated with it. The statistics
+items and their corresponding keywords are described in the table
+below: 
+
+@table @code
+@kwindex errors@r{, statistics}
+@item errors
+Any error that occurred during the run.
+
+@kwindex warnings@r{, statistics}
+@item warnings
+Any warning conditions occurred during the run.
+
+@kwindex bad-signatures@r{, statistics}
+@item bad-signatures
+A @acronym{PGP} signature not matches the public key for the user that
+issued it.
+
+@kwindex access-violations@r{, statistics}
+@item access-violations
+A user is attempting to upload files for some project, but it is not
+authorised to do so.
+
+@kwindex complete-triplets@r{, statistics}
+@item complete-triplets
+A complete triplet is registered.
+
+@kwindex incomplete-triplets@r{, statistics}
+@item incomplete-triplets
+An incomplete triplet is registered, i.e. such that misses one or more
+of its files. Notice, that a directive file alone is counted as a
+complete triplet, provided that its signature verifies correctly and
+that it does not contain @code{file} directive.
+
+@kwindex bad-triplets@r{, statistics}
+@item bad-triplets
+A triplet contains files owned by different users.
+
+@kwindex expired-triplets@r{, statistics}
+@item expired_triplets
+A triplet has expired.
+
+@kwindex triplet-success@r{, statistics}
+@item triplet_success
+A triplet is processed successfully
+
+@kwindex uploads@r{, statistics}
+@item uploads
+An upload is executed successfully. An upload is defined as a
+successful move of a file and its detached signature from the source
+to the destination directory.
+
+@kwindex archives@r{, statistics}
+@item archives
+An archivation is performed
+
+@kwindex symlinks@r{, statistics}
+@item symlinks
+A symlinks is created.
+
+@kwindex rmsymlinks@r{, statistics}
+@item rmsymlinks
+A symlink is removed.
+@end table
+
+@kwindex statistics
+  The amount of information included in the statistics summary is
+configured using the @code{statistics} statement. It takes arbitrary
+number of arguments, each one being one of the keywords, described
+above. For example, the following statement causes only the
+information about errors and warnings to be printed:
+
+@smallexample
+statistics errors warnings
+@end smallexample
+
+  It will produce the following output:
+
+@smallexample
+errors: 0
+warnings: 2
+@end smallexample
+
+@kwindex none@r{, statistics}
+  The special keyword @samp{none} can be used to suppress this output
+altogether (which is the default), as in
+
+@smallexample
+statistics none
+@end smallexample
+
+@kwindex all@r{, statistics}
+  Another special keyword is @samp{all}, that enables all statistics
+output. This keyword may also be followed by any number of statistics
+keywords, which are in this case @emph{excluded} from the
+summary. For example, to output all statistics, except errors and
+warnings one would set: 
+
+@smallexample
+statistics all errors warnings
+@end smallexample
+
 @node notification
 @section Mail Notification
 @UNREVISED{}
-  
+  While running, @command{wydawca} keeps track of certain events
+occurring, such as, for example, broken @acronym{PGP} signatures or
+attempts to upload files to projects by unauthorized users. The
+utility can notify, via email, the system administrator and/or project
+administrators about any of those events. 
+
+
 
 @node wydawca.rc, invocation, configuring, Top
 @chapter @command{Wydawca} configuration file.
@@ -1229,6 +1319,15 @@ implies @option{--debug --stderr}.
 
 @xref{dry-run, The dry-run mode}.
 
+@opsummary{include-directory}
+@item --include-directory[=@var{dir}]
+@itemx -I[@var{dir}]
+If @var{dir} is supplied it is set as the current inclusion
+directory. Otherwise, the inclusion directory is set to the directory
+part of the configuration file used.
+
+@xref{include, File inclusion}.
+
 @opsummary{lint}
 @item --lint
 @itemx -t