aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2020-04-29 22:49:09 +0300
committerSergey Poznyakoff <gray@gnu.org>2020-04-29 22:49:09 +0300
commitb371ef0485a1df2430e953d3950fa4d3995e6455 (patch)
tree6594f4bf39924866b75b37e478140e4e1e155167
parent3f32d6ea3af2f27384e001dd2478aab285d42e25 (diff)
downloadwydawca-b371ef0485a1df2430e953d3950fa4d3995e6455.tar.gz
wydawca-b371ef0485a1df2430e953d3950fa4d3995e6455.tar.bz2
Proof-read the docs
-rw-r--r--doc/wydawca.texi175
1 files changed, 76 insertions, 99 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 0477147..b24d45c 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -153,9 +153,9 @@ 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
-versions. Now, package maintainers need to have a way of uploading
+versions. Package maintainers need a way of uploading
their packages to one of these sites. This is done using the
-@dfn{Automated FTP Upload} method, as described in
+@dfn{Automated FTP Upload} method described in
@ifnothtml
@ref{Automated FTP Uploads, Automated FTP Uploads, Automated FTP
Uploads, maintain, Information for maintainers of GNU software}.
@@ -181,7 +181,7 @@ corresponding to a certain distribution @acronym{URL}. For example,
@cindex @acronym{PGP}
@cindex detached signature
@cindex signature, detached
- Now, if maintainer of the project @samp{foo} wishes to make a release
+ If maintainer of the project @samp{foo} wishes to make a release
of the stable version @file{foo-1.0.tar.gz}, he first creates a detached
signature @file{foo-1.0.tar.gz.sig}. Then he creates a special
@dfn{directive} file, which contains information about where the
@@ -193,8 +193,8 @@ distributed tarball must be placed, and clear-signs it using his
@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 successfully passed verification to
+to scan source directories, gather triplets, verify them,
+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
@@ -204,25 +204,11 @@ 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{
-@ifnothtml
-@xref{FTP Upload Directive File - v1.1,
-Standalone directives, Standalone directives,
-maintain, Information for maintainers of GNU software}.
-@end ifnothtml
-@ifhtml
See @uref{http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e1.html,
Standalone directives}.
-@end ifhtml
} and 1.2@footnote{
-@ifnothtml
-@xref{FTP Upload Directive File - v1.2,
-Standalone directives, Standalone directives,
-maintain, Information for maintainers of GNU software}.
-@end ifnothtml
-@ifhtml
See @uref{http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e2.html,
Standalone directives}.
-@end ifhtml
}.
The program is written entirely in @acronym{C}, is highly
@@ -261,22 +247,15 @@ necessary to access user and project databases.
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 instructions regarding the
+supplied with each upload and 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.
In some special cases, a clear-signed directive file alone is valid.
-This happens when it contains only @dfn{standalone directives}, 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
+This happens when it contains only @dfn{standalone directives}@footnote{
@uref{http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e1.html,
Standalone directives}.
-@end ifhtml
+}.
@cindex triplet, incomplete
@cindex incomplete triplet
@@ -340,10 +319,11 @@ the incoming uploads using one or both of the following methods.
@cindex inotify
On modern GNU/Linux systems @command{wydawca} uses @dfn{inotify} API
(@pxref{monitoring file system events,,,inotify(7),inotify man page}),
-which makes it possible to react on each upload immediately after a
+which enables it to react on each upload immediately after a
complete triplet is uploaded and to clean up unfinished or incomplete
uploads. This is a preferred mode of operation.
+@anchor{upload notification}
@cindex TCPMUX notification
On other systems, the daemon can be configured to listen on
a socket for upload notifications. This method can also be used
@@ -362,9 +342,11 @@ and closes the connection.
If a matching spool is found, the server replies with @samp{+}
acknowledgment, immediately followed by an optional message of
explanation, and terminated with a CRLF. Upon receiving this
-acknowledgment, the client sends the user name of the user who
-did the upload. The following sample transaction illustrates
-this:
+acknowledgment, the client sends the login name of the user who
+did the upload@footnote{The user name requirement is retained for
+backward compatibility. In fact, it is not used, so that
+any word can be sent instead.}. The following sample transaction
+illustrates this:
@smallexample
C: stable
@@ -422,7 +404,7 @@ Similarly, the @option{--daemon} option enables daemon mode.
@anchor{spool selection}
Usually @command{wydawca} attempts to process all the configured
-spools. You may instruct it to process only a subset of these
+spools. You can instruct it to process only a subset of these
by using the following options:
@table @option
@@ -507,7 +489,7 @@ where it appeared.
@xopindex{no-preprocessor, introduced}
Before parsing, configuration file is preprocessed using
@command{m4} (@pxref{Preprocessor}). To see the preprocessed
-configuration without actually parsing it, use @option{-E} command
+configuration without actually parsing it, use the @option{-E} command
line option. To avoid preprocessing it, use
@option{--no-preprocessor} option.
@@ -598,8 +580,8 @@ 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}
+@item @file{@var{prefix}/share/wydawca/@value{VERSION}/include}
@end enumerate
@noindent
@@ -1012,26 +994,12 @@ The version 1.2 introduces a new keyword (@samp{replace}) for that
purpose, which determines its further actions.
For a detailed information about version 1.1, see
-@ifnothtml
-@xref{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 version 1.2 and its differences from 1.1 are discussed in
-@ifnothtml
-@xref{FTP Upload Directive File - v1.2,
-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_002e2.html,
Standalone directives}.
-@end ifhtml
By default, @command{wydawca} supports both versions. The supported range of
versions can be abridged using the following configuration statements:
@@ -1092,8 +1060,8 @@ this feature.
@end deffn
@deffn {Config} listen url
-Define a socket to listen on. Allowed values for @var{url}
-are:
+Listen on this socket for incoming upload notifications
+(@pxref{upload notification}). Allowed values for @var{url} are:
@table @asis
@findex /etc/services
@@ -1112,8 +1080,9 @@ an absolute or relative file name.
@end deffn
@deffn {Config} all-spools name
-Declare a special service name, which will be treated as a request to
-process all spools.
+Declare a special service name, which, when used in a upload
+notification request, will be treated as a request to process all
+spools.
@end deffn
@deffn {Config} max-connections n
@@ -1360,7 +1329,7 @@ wish to use a secure connection to the server via SSL.
@smallexample
@group
sql default @{
- host project.database.com:3306;
+ host db.example.org:3306;
database savane;
user root;
password guessme;
@@ -1374,7 +1343,7 @@ sql default @{
@group
sql default @{
config-file /etc/wydawca.sql;
- host project.database.com:3306;
+ host db.example.org:3306;
database savane;
@}
@end group
@@ -1407,8 +1376,8 @@ dictionary @var{dict-id} @{
The @code{dictionary} statement can appear either in the global scope of
the configuration file, or inside a @code{spool} statement
-(@pxref{spool}). Global definitions affect all directory
-pairs in the configuration file, and ones inside a @code{directory}
+(@pxref{spool}). Global definitions affect all spools
+in the configuration file, and ones inside a @code{spool}
statement override them for that particular spool.
There are two dictionaries, identified by the value of
@@ -1462,9 +1431,9 @@ following variables are defined in this context:
@kwindex project
@item project
The system name of the project for which the triplet is
-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.
+submitted. The project name is obtained from the @code{directory}
+directive. If the value of this directive contains subdirectories,
+the first (topmost) directory is used as @samp{project}.
@kwindex spool
@item spool
@@ -1528,7 +1497,8 @@ which determines database name and user credentials needed to access it.
@cindex Savane
The following sub-nodes contain sample definitions for the
@code{sql} dictionaries. They are based on the database structure used in
-@uref{http://gna.org/projects/savane, @command{Savane} system}.
+@uref{http://savannah.nongnu.org/projects/savane-cleanup,
+@command{Savane} system}.
@menu
* project-owner-sql::
@@ -1538,9 +1508,10 @@ which determines database name and user credentials needed to access it.
@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.
+ This dictionary retrieves 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
dictionary project-owner @{
@@ -1904,7 +1875,7 @@ This statement overrides the global @code{directory-mode} statement
(@pxref{directory setup}).
@end deffn
-@deffn {Config} directory-owner uid gid
+@deffn {Config: archive} directory-owner uid gid
Configures owner user and group IDs for created archive directories.
If the archive directory already exists, its ownership will be checked
and if necessary reverted to @var{uid}:@var{gid}.
@@ -1923,10 +1894,9 @@ located in the same directory as the files they sign. To enforce this
rule, @command{wydawca} implements @dfn{implicit signature
archivation} facility. It works as follows. When archivation of
@var{file} is requested by @code{archive: @var{file}} statement in the
-directive file (@pxref{FTP Upload Directive File - v1.1, Standalone
-directives,, maintain.info, Information For Maintainers of GNU Software}),
-@command{wydawca} also checks if the file named @file{@var{file}.sig}
-exists. If so, it is archived along with @file{@var{file}}.
+directive file, @command{wydawca} also checks if the file named
+@file{@var{file}.sig} exists. If so, it is archived along with
+@file{@var{file}}.
@deffn {Config} archive-signatures bool
If implicit signature archivation is not needed, use
@@ -1983,8 +1953,8 @@ spool.
@deffn {Config: spool} inotify bool
Enables or disables the @dfn{inotify} watcher for this spool. By
default, inotify is always enabled on GNU/Linux systems (unless
-disabled at the configure time). @xref{inotify}, for a detailed
-description of this feature.
+explicitly disabled at the configure time). @xref{inotify}, for a
+detailed description of this feature.
@end deffn
@deffn {Config: spool} url string
@@ -1996,7 +1966,7 @@ may be used as the variable @samp{$url} in mail notifications.
Specifies the location of the source directory.
@end deffn
-@deffn {Config: archive} source-mode mode
+@deffn {Config: spool} source-mode mode
Sets directory mode for creating the source directory (octal). If the
directory already exists, its mode will be checked and if necessary
changed to @var{mode}.
@@ -2005,7 +1975,7 @@ This statement overrides the global @code{directory-mode} statement
(@pxref{directory setup}).
@end deffn
-@deffn {Config} source-owner uid gid
+@deffn {Config: spool} source-owner uid gid
Configures owner user and group IDs for the source directory.
If the directory already exists, its ownership will be checked
and if necessary reverted to @var{uid}:@var{gid}.
@@ -2041,7 +2011,7 @@ are useful mainly for diagnostic purposes.
The following two statements apply only if the destination is a local
directory (@samp{file://} or @samp{dir://} URL scheme):
-@deffn {Config: archive} destination-mode mode
+@deffn {Config: spool} destination-mode mode
Sets directory mode for creating the destination directory (octal).
If the directory already exists, its mode will be checked and if
necessary changed to @var{mode}.
@@ -2050,10 +2020,10 @@ This statement overrides the global @code{directory-mode} statement
(@pxref{directory setup}).
@end deffn
-@deffn {Config} destination-owner uid gid
-Configures owner user and group IDs for the destination directory.
-If the directory already exists, its ownership will be checked
-and if necessary reverted to @var{uid}:@var{gid}.
+@deffn {Config: spool} destination-owner uid gid
+Configures the owner user and group IDs for the destination
+directory. If the directory already exists, its ownership will be
+checked and if necessary reverted to @var{uid}:@var{gid}.
@xref{directory setup, directory-owner}, for a discussion of the
syntax for @var{uid} and @var{gid}.
@@ -2429,7 +2399,7 @@ 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
+Unless @var{file} in the @samp{module} statement is an absolute
file name, it will be searched in the library load path, which is
defined as:
@@ -2487,7 +2457,7 @@ 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
+Once loaded, the module can be initialized. This is done in the
following block statement:
@deffn {Config} module-init @var{name} @{ ... @}
@@ -2539,7 +2509,7 @@ notify-event @{
@end smallexample
@end deffn
-@deffn {notify-event} event @var{eid}
+@deffn {Config: notify-event} event @var{eid}
Trigger the notification when the event identified by @var{eid}
occurs. The identified @var{eid} is one of the following:
@@ -2578,18 +2548,18 @@ it is emitted when all spools have been processed.
For compatibility with @command{wydawca} versions prior to 3.1.95, the
event name @samp{finish} can be used instead of @samp{statistics}.
-@xref{statreports}, for an example.
+@xref{statreports}, for a detailed discussion.
See also @ref{mod_logstat}.
@end table
@end deffn
-@deffn {notify-event} module @var{modname}
+@deffn {Config: notify-event} module @var{modname}
Identify the module responsible for the notification. The
@var{modname} argument must have been previously initialized in a
@code{module} statement (@pxref{modules}).
@end deffn
-@deffn {notify-event} module-config @{ ... @}
+@deffn {Config: notify-event} module-config @{ ... @}
This block provides module-specific configuration for @var{modname}.
Its content depends on the module used for notification. The version
@value{VERSION} of @command{wydawca} is shipped with two notification
@@ -2768,7 +2738,7 @@ mailer "|/bin/nullmail localhost -F$@{sender@} $@{rcpt@}"
@cindex templates, notification messages
@cindex notification message template
@cindex message template
-Each notification message is build from a message template, by
+Each notification message is built from a message template, by
expanding variables (@pxref{variable expansion}) within it.
The message text may be specified either in place within the
configuration directive it belongs to (@pxref{notification}), or
@@ -2826,7 +2796,7 @@ following statement:
@smallexample
notify-event @{
- event statistrics;
+ event statistics;
module mailutils;
@}
@end smallexample
@@ -2848,7 +2818,7 @@ where @var{name} is the message name as used in @code{define-message}.
@deffn {mail-statistics} statistics item-list
The argument is a list of statistic item names as described in
@ref{statistics}. A report will be sent only if statistic
-counters for at least one of the requested categories are not
+counters for at least one of the requested items are not
zero. For example, the following statement requires sending
notifications only if there occurred any errors or access violation
attempts, or any bad signature was uploaded:
@@ -2913,7 +2883,8 @@ triplets.
@cindex timers
The following special variables, called @dfn{timers}, are
replaced with the real or @acronym{CPU} time (in seconds)
-used while processing a certain task:
+used while processing a certain task. Timers are an obsolescent
+feature and will be removed in future versions.
@multitable @columnfractions 0.30 0.70
@kwindex timer:spool:real
@@ -3024,7 +2995,7 @@ for @var{who} are allowed:
@item read
@itemx message
Read recipients from the @samp{To}, @samp{Cc} and @samp{Bcc} headers
-of the message.
+of the message. This is the default.
@kwindex admin
@item admin
@@ -3043,7 +3014,7 @@ User name of the user who uploaded files.
@end table
@end deffn
-@deffn {Config: notify-event} gpg-sign key
+@deffn {mod_mailutils config} gpg-sign key
If this statement is present, the message will be signed using
the supplied @acronym{GPG} @var{key}. The key is looked up in
the @acronym{GPG} home directory (@pxref{gpg-homedir}).
@@ -3114,7 +3085,7 @@ administrator, as set by the @samp{admin-address}
administrator (@dfn{owner}).
@kwindex email:user
@item email:user @tab Full email address of the user who did
-the upload. Not to be confused with @samp{user:email}.
+the upload. Equivalent to @samp{"$@{user:real-name@}" <$@{user:email@}>}.
@anchor{check-result}
@kwindex check:result
@item check:result @tab Code returned by external checker, in
@@ -3269,8 +3240,8 @@ be added as needed.
@node mod_logstat
@subsection @command{mod_logstat} -- statistics logging
-The module @command{mod_logstat} logs the supplied message text at the
-end of the run.
+The module @command{mod_logstat} logs the supplied message at the
+@samp{statististics} event.
The simplest configuration for this module is:
@@ -3666,7 +3637,7 @@ modules. To display these, use the @option{--module-help} option
@opsummary{cron}
@item --cron
-Run in cron mode. @xref{starting,, cron}.
+Run in cron mode. Implies @option{--syslog}. @xref{starting,, cron}.
@xref{stderr, The @option{--syslog} option}.
@@ -3677,11 +3648,17 @@ Run in daemon mode. @xref{starting,, daemon}.
@opsummary{debug}
@sopindex{d, summary}
@item --debug=@var{n}
-@itemx -d @var{n}
-Set the debugging level to @var{n}.
+@itemx -d@var{n}
+Set the debugging level to @var{n}. The argument is optional. If
+specified, it must follow the short option immediately, with no
+whitespace between them. When used with the long option, the equals
+sign must be used.
-@xref{debug, The @option{--debug} option}.
+Without argument, increases the current debugging level by 1. For
+compatibility with previous version, @option{-d} options can be
+clustered. E.g. @option{-ddd} is equivalent to @option{-d3}.
+@xref{debug, The @option{--debug} option}.
@opsummary{define}
@sopindex{D, summary}
@item --define=@var{name}[=@var{value}]
@@ -3716,7 +3693,7 @@ Dump the preprocessed configuration to stdout and exit.
@opsummary{force}
@item --force
-Force start-up, even if if the PID file already exists.
+Force start-up, even if running as root or if the PID file already exists.
@opsummary{foreground}
@item --foreground

Return to:

Send suggestions and report system problems to the System administrator.