aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ChangeLog4
-rw-r--r--README9
-rw-r--r--configure.ac2
-rw-r--r--doc/wydawca.texi371
4 files changed, 212 insertions, 174 deletions
diff --git a/ChangeLog b/ChangeLog
index b1f0d95..f8e05f9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2007-09-07 Sergey Poznyakoff <gray@gnu.org.ua>
+
+ Prepared for the release.
+
2007-09-06 Sergey Poznyakoff <gray@gnu.org.ua>
* bootstrap: Update
diff --git a/README b/README
index 52184b2..2df21a9 100644
--- a/README
+++ b/README
@@ -4,7 +4,12 @@ See the end of file for copying conditions.
* Introduction
-Wydawca is a daemon for automatic project upload.
+Wydawca is an automatic release submission daemon. It implements the
+automatic upload procedure specified in:
+
+http://www.gnu.org/prep/maintain/html_node/Automated-Upload-Procedure.html
+
+and supports version 1.1 of the directive file.
* Installation
@@ -27,7 +32,7 @@ described below:
* Bug reporting.
-Send bug reports to <gray@gnu.org.ua>.
+Send bug reports to <bug-wydawca@gnu.org.ua>.
* Copyright information:
diff --git a/configure.ac b/configure.ac
index c5ffd1c..2a9f89a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -15,7 +15,7 @@
# along with wydawca. If not, see <http://www.gnu.org/licenses/>.
AC_PREREQ(2.59)
-AC_INIT([wydawca], 1.0, [gray@gnu.org.ua])
+AC_INIT([wydawca], 1.0, [bug-wydawca@gnu.org.ua])
AC_CONFIG_SRCDIR([src/wydawca.c])
AC_CONFIG_AUX_DIR([build-aux])
AC_CONFIG_HEADER([config.h])
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 6bc79a9..02d650e 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -155,9 +155,9 @@ distributed tarball must be placed, and clear-signs it using his
@file{/incoming/ftp}.
@cindex release submission daemon
- From now on it is the responsibility of an @dfn{release submission daemon}
-to scan the source directories, to gather the triplets, verify them,
-and to any files that had passed the verification successfully to
+ 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
their distribution sites.
@command{Wydawca} is such a release submission daemon. It is able to
@@ -166,6 +166,18 @@ 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
+@ifnothtml
+@ref{FTP Upload Directive File - v1.1,
+Standalone directives, Standalone directives,
+maintain, Information for maintainers of GNU software}.
+@end ifnothtml
+@ifhtml
+@uref{http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e1.html,
+Standalone directives}.
+@end ifhtml
+
The program is written entirely in @acronym{C}, is highly
effective and consumes little resources.
@@ -190,19 +202,19 @@ special provisions for that case.
@cindex directory, distribution
@cindex destination directory
@cindex directory, destination
- The configuration file supplies the utility with the set of
+ 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. It also supplies all the information
+-- @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
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, that contains directive regarding the
-placement of the uploaded files. A @dfn{triplet}, is a standard
+supplied with each upload and that contains directive 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.
In some special cases, a clear-signed directive file alone is valid,
@@ -220,13 +232,13 @@ Standalone directives}.
Each @dfn{incomplete} triplet, i.e. such that misses one or more
necessary files, is then verified by checking if the modification
-date of its oldest file is older than a predefined amount
+date of its oldest file is older than a predefined amount of time
(@pxref{file-sweep-time}), and if so, all files from this triplet are
removed (an @dfn{expired triplet}). This gives users the possibility
to restart interrupted or otherwise broken uploads later.
- Then the utility ensures that each of the remaining triplets is
-created by a single person, any triplets that do not are immediately
+ Then, the utility ensures that each of the remaining triplets is
+created by a single person. Any triplets that do not are immediately
removed.
@cindex @acronym{PGP}
@@ -267,8 +279,8 @@ error and exits with code 0 if the file is OK, or 1 otherwise.
@sopindex{e, described}
@xopindex{syslog, described}
Normally, @command{wydawca} attempts to detect automatically whether
-it is run from an interactive console, and if so it prints it
-diagnostics to the standard error. Otherwise, the diagnostics is
+it is run from an interactive console, and if so it prints its
+diagnostics on the standard error. Otherwise, the diagnostics is
directed to the @command{syslog}, and the facility to use is gotten from the
@code{syslog-facility} configuration file statement
(@pxref{syslog}). Two options are provided if you wish to disable this
@@ -287,26 +299,28 @@ the same as @option{--syslog}, but it may change in the future.
@xopindex{debug, described}
@sopindex{d, described}
The @option{--debug} (@option{-d}) tells the program to increase its
-debugging level by 1. The @dfn{debugging level} determines the amount
+debugging level by 1. @dfn{Debugging level} determines the amount
of information the program reports when it runs. By default it is 0,
meaning to report only errors and other critical conditions. Raising
it may be necessary when debugging new configurations. Each
@option{-d} option raises the level by one, so you can say
@command{wydawca -dd} to obtain level 2, for example. The maximum
-debugging level currently is 4, which prints impractically many
-information and is useful primarily for @command{wydawca} developers.
+debugging level currently is 4, which prints an impractically big
+amount of information, which is useful mainly for @command{wydawca}
+developers.
@anchor{dry-run}
@xopindex{dry-run, described}
@sopindex{n, described}
Yet another debugging facility is the @option{--dry-run}
-(@option{-n}) option. It instructs @command{wydawca} no to do any
-modifications to the disk contents, but to verbosely print them. It
-set the debugging level to 1 and directs the diagnostics output to the
-standard error, as if @option{--debug --stderr} options have been
-given. You can raise debugging level further by supplying additional
-@option{--debug} options. The @option{--dry-run} option is useful when
-testing new configurations, for example:
+(@option{-n}) option. It instructs @command{wydawca} to avoid doing any
+modifications to the disk contents, but to verbosely print any actions
+it would have taken. Its set the debugging level to 1 and directs the
+diagnostics output to the standard error, as if @option{--debug
+--stderr} options have been given. You can raise debugging level
+further by supplying additional @option{--debug} options. The
+@option{--dry-run} option is useful when testing new configurations,
+for example:
@smallexample
$ wydawca -c new.cfg --dry-run
@@ -316,7 +330,7 @@ $ wydawca -c new.cfg --dry-run
@sopindex{h, described}
@xopindex{version, described}
@sopindex{v, described}
- Two usual informational options are available as well:
+ In addition, the two usual informational options are available as well:
@option{--help} (@option{-h}) prints a short usage summary, and
@option{--version} (@option{-v}) prints program version number.
@@ -325,8 +339,8 @@ $ wydawca -c new.cfg --dry-run
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. Non-empty non-comment lines
-contain configuration statements.
+@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
@@ -356,16 +370,16 @@ user-data sql default SELECT realname, email \
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).
+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 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}.
This subsection will guide you through the @command{wydawca}
-configuration on step-by-step basis.
+configuration on a step-by-step basis.
@menu
* include::
@@ -383,7 +397,7 @@ configuration on step-by-step basis.
@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
+using @code{include} statement. Its only argument supplies the name of
file to be included. For example:
@smallexample
@@ -397,13 +411,16 @@ 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}).
+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
- Argument to the @code{include} statement may also be a relative
+ 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 the @dfn{inclusion
+@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:
@@ -425,10 +442,10 @@ 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
+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 invocation
+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:
@@ -447,9 +464,10 @@ effect.
@section Syslog Configuration Directives
@cindex syslog, configuration
@kwindex syslog-facility
- Syslog is the default diagnostics channel for @command{wydawca}. By
-default, the program uses facility @samp{local1}. To change this, use
-@code{syslog-facility} statement:
+ 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:
@smallexample
syslog-facility local2
@@ -465,16 +483,16 @@ syslog-facility local2
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_}. The default is @samp{local1}.
+prefixed with @samp{log_} (case-insensitive as well).
@kwindex syslog-tag
@cindex syslog tag, configuring
- Another thing you may wish to tune is @dfn{syslog tag}, a string
+ 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 wydawca
+syslog-tag uploads
@end smallexample
@kwindex syslog-print-priority
@@ -511,11 +529,11 @@ end
@end group
@end smallexample
- Here, the @var{identifier} is a string uniquely identifying this
+ Here, @var{identifier} 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. The
-@var{statements} is a set of statements determining access to the
-database. Allowed statements are:
+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:
@table @code
@kwindex host
@@ -537,9 +555,10 @@ Specifies the database user name.
@kwindex password
@item password @var{string}
-Specifies password for accessing the database.
+Specifies the password for accessing the database.
@end table
+@noindent
An example @code{sql} statement follows:
@smallexample
@@ -557,14 +576,14 @@ end
@section Access Methods
@cindex Access method
@cindex @acronym{PGP} key
- An @dfn{access method} defines how @command{wydawca} can access some
+ 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.
- @command{Wydawca} understands three access methods, only one of them
-being implemented right now. These methods are summarized in the table
-below:
+ @command{Wydawca} understands three types of access methods, only
+one of them being implemented right now. These methods are summarized
+in the table below:
@table @asis
@kwindex builtin@r{, access method type}
@@ -582,7 +601,7 @@ below:
future use.
@end table
- Access methods are defined in the configuration file using the
+ Access methods are defined in configuration file using the
following syntax:
@smallexample
@@ -596,25 +615,26 @@ where @var{method-name} is the predefined name of the access method,
Access method statements can appear either in the global scope of
the configuration file, or inside a @code{directory} statement
-(@pxref{directory pairs}). The global definitions affect all directory
-pairs in the configuration file, the ones inside a @code{directory}
+(@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.
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 the identifier of one of the preceding @code{sql} blocks
+@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 should be issued to obtain the requested data. A set of
-@dfn{meta-variables} is available for use in @var{param2}. These
-variables allow to supply to the query such additional information
-that is available only at run-time. To use a meta-variable in a
-query, it is preceded by a percent sign. If its name consists of
-several letters, it must be surrounded by curly braces. For example,
-following are two valid uses of macro-variables: @code{%u} and
-@code{%@{user@}}, the first of them expands macro variable @samp{u},
-and the second one expands the variable @samp{user}. Undefined
-variables are not expanded, but are left in the query intact.
+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:
@@ -660,7 +680,7 @@ gpg-key sql default SELECT gpg_key \
@deffn {Access Method} 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: email address and user name, in this order.
+consisting of two columns: an email address and a user name, in this order.
@smallexample
@group
@@ -676,7 +696,7 @@ project-owner sql default SELECT user.email, user.realname \
@deffn {Access Method} user-data
Return email address and real name of a user. This method must
-return one tuple, consisting of two columns: email address and user
+return one tuple, consisting of two columns: an email address and a user
name, in this order.
@smallexample
@@ -693,7 +713,7 @@ user-data sql default SELECT email, realname \
method must return the system name of the user if he is allowed to
make uploads.
- The following definition allows uploads only to project
+ The following definition allows uploads only for project
administrators:
@smallexample
@@ -712,12 +732,13 @@ verify-user sql default SELECT user.user_name \
@node archivation
@section Archivation
@cindex archivation, defined
- Project maintainers may upload files having the same names as
-the ones uploaded earlier. Although this practice is not encouraged,
-it still can happen. In that case, @command{wydawca} needs to first
-@dfn{archive} the already existing file, and then put the new one in
-its place. Moreover, the directive file format allows maintainers to
-explicitly require archivation of their existing files.
+ There may be cases when project maintainers need to overwrite
+existing distributed files with another ones, having the same names.
+(Note, hovewer, that this practice is not encouraged). In that case,
+@command{wydawca} needs to first @dfn{archive} the already existing
+file, and then put the new one in its place. Moreover, the directive
+file format allows maintainers to explicitly require archivation of
+their existing files.
@cindex archivation methods
@kwindex archive
@@ -742,10 +763,10 @@ the archivation type:
@kwindex directory@r{, archivation}
@item directory
- Use separate directory or directory hierarchy.
+ Use a separate directory or a directory hierarchy.
@end table
- When archivation type @asis{tar} is used, the second argument to
+ When the archivation type @asis{tar} is used, the second argument to
@code{archive} sets the full name of the tar archive to use, e.g.:
@smallexample
@@ -776,7 +797,7 @@ archive directory /var/backups/gnu
@noindent
all files from @file{/home/@/ftp/@/gnu/@/tar} will be archived in
-@file{/var/@/backups/@/gnu/@/tar}, files from
+@file{/var/@/backups/@/gnu/@/tar}, and files from
@file{/home/@/ftp/@/gnu/@/tar/@/old}
will be archived in @file{/var/@/backups/@/gnu/@/tar/@/old}, etc.
@@ -796,13 +817,12 @@ directory @file{/home/@/ftp/@/gnu/@/tar/@/.archive}, files from
@anchor{backup-methods}
@vindex version-control @r{Emacs variable}
- With the @samp{directory} archivation type, it may happen that the
+ When using the @samp{directory} archivation type, it may happen that the
archive file with the same name as the one about to be created already
-exists. In this case the third argument to @code{archive} specifies
-how to handle the existing copy, in other words, how to @dfn{backup}
-it. This argument corresponds to the Emacs variable @samp{version-control},
-and it accepts the same values as in Emacs. The following table
-describes them:
+exists. The third argument to @code{archive} specifies how to handle
+the existing copy, in other words, how to @dfn{backup} it. This
+argument corresponds to the Emacs variable @samp{version-control}, and
+it accepts the same values as in Emacs. The following table describes them:
@table @samp
@item t
@@ -841,26 +861,26 @@ not set, the @samp{existing} is used by default.
@kwindex source
@kwindex destination
A @dfn{directory pair} definition is a core of @command{wydawca}
-configuration. It defines the location of the source directory and its
-corresponding distribution directory. It may also set the archivation
-type being used for that directory and various access methods, thus
-overriding the global settings. The directory pair definition begins with
-the @code{directory} keyword, optionally followed by the @acronym{URL}
-of the distribution directory. This @acronym{URL}, if specified, is
-then used in diagnostic messages regarding this directory
-pair. Following the @code{directory} keyword is a list of statements
-describing the pair. At least two statements are required:
-@code{source}, specifying the location of the source directory and
-@code{destination}, which specifies the location of destination (or
-distribution) directory. Apart from these obligatory statements, the
-@code{directory} block may contain @code{archive} statement
+configuration. It defines the location of the source directory and the
+corresponding distribution (or @dfn{destination}) directory. It may
+also set the archivation type being used for that directory and
+various access methods, thus overriding the global settings. The
+directory pair definition begins with the @code{directory} keyword,
+optionally followed by the @acronym{URL} of the distribution
+directory. This @acronym{URL}, if specified, is used in diagnostic
+messages regarding this directory pair. Following the @code{directory}
+keyword is a list of statements describing the pair. At least two
+statements are required: @code{source}, specifying location of the
+source directory and @code{destination}, which specifies location of
+the destination directory. Apart from these obligatory statements, a
+@code{directory} block may contain an @code{archive} statement
(@pxref{archivation}) and access method definitions (@pxref{access
methods}). Any of these statements, if present, overrides the
-corresponding global definition for this directory pair. The
+corresponding global definition for this directory pair. A
@code{directory} statement ends with the @code{end} keyword on a
separate line.
- For example, the following definition says that the valid uploads to
+ For example, the following definition says that valid uploads to
@file{/home/ftp/incoming/ftp} should be transferred to @file{/home/ftp/gnu}:
@smallexample
@@ -872,11 +892,12 @@ end
@end group
@end smallexample
- This directory pair will be using archivation type and access methods
+@noindent
+This directory pair will be using the archivation type and access methods
defined globally.
The following example shows the same directory pair block, that
-additionally overrides archivation method:
+additionally sets its own archivation method:
@smallexample
@group
@@ -890,14 +911,14 @@ end
The distribution directory is implicitly supposed to be located on
the same machine as the upload directory. If they are located on
-different machines, one of the directories can be mounted using
-@acronym{NFS}. The future versions will contain special provisions for
-such case.
+different machines, one of the directories should be mounted using
+@acronym{NFS}. Future @command{wydawca} versions will contain special
+provisions for such case.
@node statistics
@section Statistics
@cindex statistics
- At the end of the run, @command{wydawca} can print the detailed
+ At the end of the run, @command{wydawca} prints a 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:
@@ -930,7 +951,7 @@ Any error that occurred during the run.
@kwindex warnings@r{, statistics}
@item warnings
-Any warning conditions occurred during the run.
+Any warning condition occurred during the run.
@kwindex bad-signatures@r{, statistics}
@item bad-signatures
@@ -968,9 +989,8 @@ 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.
+An upload is processed successfully. An upload is defined as a move of
+a file and its detached signature from the source to the destination directory.
@kwindex archives@r{, statistics}
@item archives
@@ -978,7 +998,7 @@ An archivation is performed
@kwindex symlinks@r{, statistics}
@item symlinks
-A symlinks is created.
+A symlink is created.
@kwindex rmsymlinks@r{, statistics}
@item rmsymlinks
@@ -986,9 +1006,9 @@ 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
+ 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
above. For example, the following statement causes only the
information about errors and warnings to be printed:
@@ -996,7 +1016,8 @@ information about errors and warnings to be printed:
statistics errors warnings
@end smallexample
- It will produce the following output:
+@noindent
+It will produce the following output:
@smallexample
errors: 0
@@ -1034,7 +1055,7 @@ choose to obtain via email the execution statistics, described in the
previous section.
@kwindex from-address
- The sender email for these notifications can be set using the
+ The sender email address for these notifications is set using the
@code{from-address} statement, e.g.:
@smallexample
@@ -1106,7 +1127,7 @@ macro in your @file{/usr/include/paths.h} file''. This is the default
mailer.
The @samp{smtp} protocol means to use an @acronym{SMTP} server directly.
-In this case, the mailer location consists of two slashes,
+In this case, mailer location consists of two slashes,
followed by the @acronym{IP} address or host name of the @acronym{SMTP}
server, and, optionally, the port number. If the port number is
present, it is separated from the rest of @acronym{URL} by a colon.
@@ -1126,7 +1147,7 @@ mailer smtp://remote.server.net:24
@cindex message template
Each notification message is build from a message template, by
expanding any occurrences of @samp{%@{@var{name}@}} within it with the value
-of macro-variable @var{name}. The sets of defined macro-variables
+of macro-variable @var{name}. Sets of defined macro-variables
depend on the type of the notification and are described below.
@kwindex define-message
@@ -1139,12 +1160,13 @@ define-message @var{id} [-]@var{delimiter}
@var{delimiter}
@end smallexample
- The @var{id} is a symbolic identifier used to refer to this message
+@noindent
+where @var{id} is a symbolic identifier used to refer to this message
in another configuration statements, @var{delimiter} is a delimiter
used to mark the end of the message template, and @var{lines} are any
number of lines that form the message template. If @var{delimiter} is
prefixed by a minus sign, any leading whitespace will be removed from
-each template line, thus allowing to indent it in a natural
+each template line, thus allowing to indent the template text in a natural
way. Furthermore, the @var{delimiter} itself is optional. If it is
omitted, the string @samp{end} is used to delimit the message.
The following example illustrates the simplest way to define a message
@@ -1272,7 +1294,7 @@ end
@subsection Event Notification
@cindex event notification
The following @dfn{events} are tracked during the execution. Any of
-them can be used to trigger sending an email notification to any party
+them can be used to trigger an email notification of any party
concerned: the system administrator, project administrators, or
the user that initiated the upload:
@@ -1324,7 +1346,7 @@ A user who uploaded files.
@end table
For example, the following two statements instruct @command{wydawca}
-to email notifications about @code{bad-directive-signature} event to
+to email notifications about any @code{bad-directive-signature} event to
project administrators and to the user who did the upload, using two
different templates:
@@ -1342,21 +1364,25 @@ notifications:
Project system name.
@kwindex url
+@item url
@acronym{URL} of the distribution site.
@kwindex dir
+@item dir
Directory (relative to the project distribution root) to where the
files where uploaded.
@kwindex dest-dir
+@item dest-dir
Value of the @code{destination} keyword.
@kwindex source-dir
+@item source-dir
Value of the @code{source} keyword.
@kwindex triplet:full
@item triplet:full
-Full listing of the uploaded triplet. It is equivalent to:
+A full listing of the uploaded triplet. It is equivalent to:
@smallexample
@group
@@ -1366,34 +1392,23 @@ Full listing of the uploaded triplet. It is equivalent to:
@end group
@end smallexample
-For example:
-
-@smallexample
--rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz
--rw-r--r-- gray users 189 2007-09-06 22:14:35 tar-1.18.tar.gz.sig
--rw-r--r-- gray user 62 2007-09-06 22:14:35 tar-1.18.tar.gz.directive.asc
-@end smallexample
+See below for an example.
@kwindex triplet:upload
@item triplet:upload
-Listing of the uploaded files. E.g.:
-
-@smallexample
--rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz
--rw-r--r-- gray users 189 2007-09-06 22:14:35 tar-1.18.tar.gz.sig
-@end smallexample
+Listing of the uploaded files (see below).
@kwindex triplet:dist
@item triplet:dist
-Listing of the main distribution file.
+Listing of the main distribution file (see below).
@kwindex triplet:sig
@item triplet:sig
-Listing of the detached signature file.
+Listing of the detached signature file (see below).
@kwindex triplet:dir
@item triplet:dir
-Listing of the directive file.
+Listing of the directive file (see below).
@kwindex user
@kwindex user:name
@@ -1410,10 +1425,24 @@ Real name of the user who uploaded the triplet.
Email of the user who uploaded the triplet.
@end table
+ @dfn{Listings} referred to in the table above, are similar to those
+produced by @code{ls} command, and include information
+on file permissions, ownership, size and modification date. For
+example, here is a possible @code{%@{triplet:full@}} listing:
+
+@smallexample
+-rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz
+-rw-r--r-- gray users 189 2007-09-06 22:14:35 tar-1.18.tar.gz.sig
+-rw-r--r-- gray user 62 2007-09-06 22:14:35 tar-1.18.tar.gz.directive.asc
+@end smallexample
+
+
+
The following example shows how to configure success notification
for the user:
@smallexample
+# @r{Define a message template.}
define-message user-success
Subject: Upload of %@{project@} successful
@@ -1427,6 +1456,7 @@ Wydawca
The Project Submission Robot
end
+# @r{Use this template in a success notification.}
notify-event success user user-success
@end smallexample
@@ -1438,13 +1468,14 @@ file statements.
@deffn {Wydawca Statement} archive @var{type} @var{archive-name} @
[@var{backup-method}]
-Defines archivation and backup methods for the destination
-directory. @xref{archivation}, for a detailed discussion. The
-@var{type} specifies the archivation type:
+Defines archivation and backup methods. @xref{archivation}, for a
+detailed discussion. @xref{archivation}, for a detailed explanation.
+
+The archivation type is specified by @var{type} argument:
@table @asis
@item tar
-The @var{archive-name} is a full file name of the @command{tar}
+@var{archive-name} is a full file name of the @command{tar}
archive used for archivation. Files being archived are appended to
that archive using @command{tar -r} command (@pxref{appending files,
Appending Files to an Archive, Appending Files to an Archive, tar,
@@ -1452,7 +1483,7 @@ Appending Files to an Archive, Appending Files to an Archive, tar,
@command{tar} binary is set by @code{tar-program} statement.
@item directory
-The @var{archive-name} specifies a directory name where to store
+@var{archive-name} specifies a directory name where to store
archive copies. If it is a relative file name, this directory will be
created under the @code{destination} directory. If it is absolute file
name, the archive name directory will be constructed for each triplet
@@ -1465,11 +1496,12 @@ using the following rule:
@noindent
where @var{dir} is the value of @code{directory} directive from the
triplet file.
+@end table
@vindex VERSION_CONTROL
@cindex backups
For @samp{directive} archivation type, the optional @var{backup-method}
-parameter specifies how to back up an existing archive whose name
+parameter specifies how to back up an existing file whose name
coincides with the one @command{wydawca} is about to create. If
@var{backup-method} is not specified, the value of the @env{VERSION_CONTROL}
environment variable will be used. And if @env{VERSION_CONTROL} is not set,
@@ -1478,7 +1510,7 @@ the @samp{existing} method (see below) is used by default.
@vindex version-control @r{Emacs variable}
This option corresponds to the Emacs variable @samp{version-control};
the same values for @var{backup-method} are accepted as in Emacs. This option
-also allows more descriptive names. The valid @var{method}s are:
+also allows more descriptive names. Valid @var{method}s are:
@table @samp
@item t
@@ -1495,25 +1527,30 @@ of the others.
Always make simple backups.
@end table
-@end table
@end deffn
@deffn {Wydawca Statement} syslog-facility @var{facility}
Output diagnostics to the given syslog facility. The @var{facility}
-may be one of the following: @samp{USER}, @samp{DAEMON}, @samp{AUTH},
-@samp{AUTHPRIV}, @samp{LOCAL0} through @samp{LOCAL7}, and @samp{MAIL}.
-The string matching is case insensitive. Optionally, @samp{LOG_}
-prefix may be prepended to @var{facility}.
+may be one of the following: @samp{user}, @samp{daemon}, @samp{auth},
+@samp{authpriv}, @samp{local0} through @samp{local7}, and @samp{mail}.
+the string matching is case insensitive. optionally, @samp{log_}
+(sense-insensitive as well) prefix may be prepended to @var{facility}.
+
+@xref{syslog}, for more information.
@end deffn
@deffn {Wydawca Statement} syslog-tag @var{tag}
Mark @command{wydawca} diagnostics with the given syslog tag. By
default the string @samp{wydawca} is used.
+
+@xref{syslog}, for more information.
@end deffn
@deffn {Wydawca Statement} syslog-print-priority @var{bool}
Begin each diagnostic message with its priority.
+
+@xref{syslog}, for more information.
@end deffn
@deffn {Wydawca Statement} statistics @var{stat-list}
@@ -1567,22 +1604,7 @@ Print all information.
Do not print any statistics.
@end table
- These keywords must be the very first items in @var{stat-list}.
-When followed by another keywords, these special keywords modify list
-handling as follows:
-
-@table @option
-@item all
-The sense of all subsequent items is inverted. For example, to print
-everything, except the number of warnings and errors, one would use:
-
-@smallexample
-statistics all errors warning
-@end smallexample
-
-@item none
-Is ignored.
-@end table
+@xref{statistics}, for more information.
@end deffn
@anchor{file-sweep-time}
@@ -1627,7 +1649,7 @@ statement ends with the @code{end} keyword on a line by itself.
@xref{sql}, for more information.
-The @var{identifier} is the symbolic name that can be used in
+@var{Identifier} is the symbolic name that can be used in
subsequent configuration statements to refer to this @acronym{SQL}
database.
@@ -1644,13 +1666,13 @@ The following statements are recognized within the @code{sql} block:
@anchor{sql-host}
@deffn {Wydawca Statement} host @var{hostname}[:@var{port-or-socket}]
-Hostname where the database is running. The @var{hostname} is either
+Hostname where the database is running; @var{hostname} is either
a symbolic hostname of the machine, or its IP address in usual
@samp{dotted-quad} notation.
The 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} may be omitted. If,
+to use. In the latter case, @var{hostname} may be omitted. If,
however, it is present, it must be @samp{localhost}.
Examples:
@@ -1770,7 +1792,8 @@ define-message @var{id} [[-]@var{delimiter}]
@var{delimiter}
@end smallexample
- The @var{id} supplies the template identifier, @var{lines} gives
+@noindent
+where @var{id} supplies the template identifier, @var{lines} gives
message headers and body, separated by a newline. If @var{delimiter}
is prefixed by @samp{-}, any leading whitespace is removed from the
template lines. If @var{delimiter} is not given, @samp{end} is
@@ -1789,7 +1812,7 @@ Sets the mailer @acronym{URL} to use.
@chapter @command{Wydawca} invocation summary.
@cindex invocation
@cindex command line options
- This chapter presents a short reference to all @command{wydawca}
+ This chapter presents a short reference of all @command{wydawca}