diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-09-07 12:56:50 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-09-07 12:56:50 +0000 |
commit | 5e889958688b0ae315a93f4230f2e9a71a9095e9 (patch) | |
tree | b95b4d1e4370abd0dabb40123105feaf031389f4 /doc | |
parent | 399b6a3682437d576dc4b7d77f66b5d88be4f7f3 (diff) | |
download | wydawca-5e889958688b0ae315a93f4230f2e9a71a9095e9.tar.gz wydawca-5e889958688b0ae315a93f4230f2e9a71a9095e9.tar.bz2 |
Prepare for the release
git-svn-id: file:///svnroot/wydawca/trunk@320 6bb4bd81-ecc2-4fd4-a2d4-9571d19c0d33
Diffstat (limited to 'doc')
-rw-r--r-- | doc/wydawca.texi | 371 |
1 files changed, 200 insertions, 171 deletions
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} command line options, in alphabetical order. @table @option @@ -1862,13 +1885,19 @@ Print the program version and exit. @node Reporting Bugs, Copying This Manual, invocation, Top @chapter How to Report a Bug - As the purpose of bug reporting is to improve software, please be + Email bug reports to @email{bug-wydawca@@gnu.org.ua}. + + As the purpose of bug reporting is to improve software, please be sure to include maximum information when reporting a bug. The minimum information needed is: @itemize -@item Topmost date from the @file{ChangeLog} file. +@item Program version you use (see the output of @command{wydawca --version}. +@item A description of the bug. @item Conditions under which the bug appears. +@item It is often helpful to send the contents of @file{config.log} +file along with your bug report. This file is created after running +@command{./configure} in @command{wydawca} source root directory. @end itemize @node Copying This Manual, Concept Index, Reporting Bugs, Top |