aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-02-28 18:54:48 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-02-28 18:54:48 +0200
commit5fc738e4d43eb708428c4b30e60e570e2dd55470 (patch)
treea96f33c70162ff8a825b800fc9276360d95d154a /doc
parent514797c56e431f37de9a00834281f990a7b15c46 (diff)
downloadwydawca-5fc738e4d43eb708428c4b30e60e570e2dd55470.tar.gz
wydawca-5fc738e4d43eb708428c4b30e60e570e2dd55470.tar.bz2
Various fixes
* doc/Makefile.am: Improve checking and final rules. * doc/fdl.texi, doc/rendition.texi: Use single-space sentence separators. * doc/wydawca.texi: Update. * src/config.c (cb_email_address): Accept a list of addresses. * src/meta.c (meta_expand_string): Take two additional arguments. Quote expansions if they are provided. * src/triplet.c (triplet_expand_method_query): New function. * src/mail.c, src/verify.c: Use triplet_expand_method_query * src/wydawca.h: Update. * src/meta.c (meta_escape): Remove.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am23
-rw-r--r--doc/fdl.texi82
-rw-r--r--doc/rendition.texi6
-rw-r--r--doc/wydawca.texi1031
4 files changed, 624 insertions, 518 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 0ef1e64..f53e47c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -41,12 +41,20 @@ manual:
$(GENDOCS) $(PACKAGE) '$(PACKAGE_NAME) manual'
# Checking
-check-format:
+check-tabs:
@if test -n "`cat $(info_TEXINFOS) $(wydawca_TEXINFOS) | tr -d -c '\t'`"; then \
echo "Sources contain tabs; run make untabify"; \
false; \
fi
+check-sentence-spacing:
+ @if grep -q '\. [@A-Z]' $(info_TEXINFOS) $(wydawca_TEXINFOS); then \
+ echo >&2 "Sources contain double-space sentence separators"; \
+ echo >&2 "Run make fix-sentence-spacing to fix"; \
+ fi
+
+check-format: check-tabs check-sentence-spacing
+
check-options:
@check-docs.sh options \
'/OPTIONS_BEGIN/,/OPTIONS_END/s/OPTION( *\([^,][^,]*\),.*/\1/pg' \
@@ -70,7 +78,7 @@ check-fixmes:
rm -f $@-t
check-writeme:
- @grep -Hn @WRITEME $(info_TEXINFOS) $(mailfromd_TEXINFOS) > $@-t; \
+ @grep -Hn @WRITEME $(info_TEXINFOS) $(wydawca_TEXINFOS) > $@-t; \
if [ -s $@-t ]; then \
echo "Empty nodes:"; \
cat $@-t; \
@@ -102,5 +110,14 @@ master-menu:
untabify:
emacs -batch -l untabify.el $(info_TEXINFOS) $(wydawca_TEXINFOS)
-final: untabify master-menu
+fix-sentence-spacing:
+ for file in $(info_TEXINFOS) $(wydawca_TEXINFOS); \
+ do \
+ if grep -q '\. [@A-Z]' $$file; then \
+ mv $$file $${file}~; \
+ sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \
+ fi; \
+ done
+
+final: untabify fix-sentence-spacing master-menu
diff --git a/doc/fdl.texi b/doc/fdl.texi
index edd86d4..3f42957 100644
--- a/doc/fdl.texi
+++ b/doc/fdl.texi
@@ -23,16 +23,16 @@ to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of ``copyleft'', which means that derivative
-works of the document must themselves be free in the same sense. It
+works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals;
+software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book. We recommend this License
+whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
@item
@@ -40,11 +40,11 @@ APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License. Such a notice grants a
+distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein. The ``Document'', below,
-refers to any such manual or work. Any member of the public is a
-licensee, and is addressed as ``you''. You accept the license if you
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
@@ -65,15 +65,15 @@ them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License. If a
+that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant. The Document may contain zero
-Invariant Sections. If the Document does not identify any Invariant
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License. A Front-Cover Text may
+the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
@@ -83,19 +83,19 @@ straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
-to text formatters. A copy made in an otherwise Transparent file
+to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
-of text. A copy that is not ``Transparent'' is called ``Opaque''.
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input
format, @acronym{SGML} or @acronym{XML} using a publicly available
@acronym{DTD}, and standard-conforming simple @acronym{HTML},
-PostScript or @acronym{PDF} designed for human modification. Examples
+PostScript or @acronym{PDF} designed for human modification. Examples
of transparent image formats include @acronym{PNG}, @acronym{XCF} and
-@acronym{JPG}. Opaque formats include proprietary formats that can be
+@acronym{JPG}. Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, @acronym{SGML} or
@acronym{XML} for which the @acronym{DTD} and/or processing tools are
not generally available, and the machine-generated @acronym{HTML},
@@ -104,7 +104,7 @@ output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in
+this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
@@ -118,7 +118,7 @@ of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document. These Warranty
+states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
@@ -131,10 +131,10 @@ You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use
+conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
@@ -148,10 +148,10 @@ printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover. Both covers must also clearly and legibly identify
-you as the publisher of these copies. The front cover must present
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition.
+visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
@@ -186,14 +186,14 @@ the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
-of it. In addition, you must do these things in the Modified Version:
+of it. In addition, you must do these things in the Modified Version:
@enumerate A
@item
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
-of the Document). You may use the same title as a previous version
+of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
@item
@@ -229,7 +229,7 @@ Include an unaltered copy of this License.
@item
Preserve the section Entitled ``History'', Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page. If
+publisher of the Modified Version as given on the Title Page. If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
@@ -239,7 +239,7 @@ Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
-it was based on. These may be placed in the ``History'' section.
+it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
@@ -252,11 +252,11 @@ dedications given therein.
@item
Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles. Section numbers
+unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
@item
-Delete any section Entitled ``Endorsements''. Such a section
+Delete any section Entitled ``Endorsements''. Such a section
may not be included in the Modified Version.
@item
@@ -270,7 +270,7 @@ Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the
+of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
@@ -282,9 +282,9 @@ standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version. Only one passage of
+of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity. If the Document already
+through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
@@ -306,7 +306,7 @@ license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
-copy. If there are multiple Invariant Sections with the same name but
+copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
@@ -316,7 +316,7 @@ Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements'',
-and any sections Entitled ``Dedications''. You must delete all
+and any sections Entitled ``Dedications''. You must delete all
sections Entitled ``Endorsements.''
@item
@@ -361,11 +361,11 @@ distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
+original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
-of those notices and disclaimers. In case of a disagreement between
+of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
@@ -378,9 +378,9 @@ title.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
-as expressly provided for under this License. Any other attempt to
+as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License. However,
+automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
@@ -389,9 +389,9 @@ parties remain in full compliance.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time. Such new
+of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns. See
+differ in detail to address new problems or concerns. See
@uref{http://www.gnu.org/copyleft/}.
Each version of the License is given a distinguishing version number.
@@ -399,7 +399,7 @@ If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
-Free Software Foundation. If the Document does not specify a version
+Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
@end enumerate
diff --git a/doc/rendition.texi b/doc/rendition.texi
index 45ac068..5d04105 100644
--- a/doc/rendition.texi
+++ b/doc/rendition.texi
@@ -5,10 +5,10 @@
@c ======================================================================
@c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
-@c as decided by @set symbols. The PUBLISH rendition does not show
-@c notes or marks asking for revision. Most users will prefer having more
+@c as decided by @set symbols. The PUBLISH rendition does not show
+@c notes or marks asking for revision. Most users will prefer having more
@c information, even if this information is not fully revised for adequacy,
-@c so DISTRIB is the default for distributions. The PROOF rendition
+@c so DISTRIB is the default for distributions. The PROOF rendition
@c show all marks to the point of ugliness, but is nevertheless useful to
@c those working on the manual itself.
@c ======================================================================
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 589f2f7..237f196 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -37,11 +37,11 @@ Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
-and with the Back-Cover Texts as in (a) below. A copy of the license
+and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
+this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
@end copying
@@ -89,6 +89,7 @@ already listed, mentioned here so you can get to them in one step:
How to Configure @command{wydawca}.
+* Syntax:: Configuration file syntax.
* syslog::
* sql::
* access methods::
@@ -97,12 +98,32 @@ How to Configure @command{wydawca}.
* statistics::
* notification::
+Configuration file syntax
+
+* Comments::
+* Pragmatic Comments::
+* Statements::
+* Preprocessor::
+
+Access Methods
+
+* sql type::
+* builtin type::
+* external type::
+
+SQL Access Methods
+
+* gpg-key-sql::
+* project-owner-sql::
+* user-data-sql::
+* verify-user-sql::
+
Mail Notification
-* mailer::
-* templates::
-* statreports::
-* event notification::
+* mailer::
+* templates::
+* statreports::
+* event notification::
@end detailmenu
@end menu
@@ -184,8 +205,8 @@ effective and consumes little resources.
@cindex operation
@cindex overview
Usually, @command{wydawca} is installed on the machine that receives
-release uploads. It may be run either periodically as a cron-job, or
-as a standalone daemon. It supposes that both upload and distribution
+release uploads. It may be run either periodically as a cron-job, or
+as a standalone daemon. It supposes that both upload and distribution
directories are accessible in the local file system hierarchy. If that
is not the case (e.g. if upload and distribution sites are handled by
different machines), one of them should be mounted using
@@ -232,7 +253,7 @@ 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 of time
-(@pxref{file-sweep-time}), and if so, all files from this triplet are
+(@FIXME-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.
@@ -354,7 +375,7 @@ detected, and withs status 1 otherwise.
@opindex -E, introduced
@xopindex{no-preprocessor, introduced}
Before parsing, configuration file is preprocessed using
-@command{m4} (@FIXME-pxref{Preprocessor}). To see the preprocessed
+@command{m4} (@pxref{Preprocessor}). To see the preprocessed
configuration without actually parsing it, use @option{-E} command
line option. To avoid preprocessing it, use
@option{--no-preprocessor} option.
@@ -383,13 +404,14 @@ directives any time by running @command{wydawca --config-help}.
There are three classes of lexical tokens: keywords, values, and
separators. Blanks, tabs, newlines and comments, collectively called
@dfn{white space} are ignored except as they serve to separate
-tokens. Some white space is required to separate otherwise adjacent
+tokens. Some white space is required to separate otherwise adjacent
keywords and values.
@menu
* Comments::
* Pragmatic Comments::
* Statements::
+* Preprocessor::
@end menu
@node Comments
@@ -469,7 +491,7 @@ compatibility with the @sc{c} preprocessor.
In fact, these statements provide a rudimentary preprocessing
features. For more sophisticated ways to modify configuration before
-parsing, see @FIXME-ref{Preprocessor}.
+parsing, see @ref{Preprocessor}.
@node Statements
@subsection Statements
@@ -478,7 +500,7 @@ parsing, see @FIXME-ref{Preprocessor}.
@cindex statement, simple
@cindex simple statements
A @dfn{simple statement} consists of a keyword and value
-separated by any amount of whitespace. Simple statement is terminated
+separated by any amount of whitespace. Simple statement is terminated
with a semicolon (@samp{;}).
Examples of simple statements:
@@ -561,6 +583,44 @@ example above:
@end group
@end smallexample
+@anchor{meta-interpretation}
+Depending on the context, the contents of a quoted string may be
+subject to @dfn{meta-variable interpretation}. During this process,
+any sequence
+
+@smallexample
+$@{@var{var}@}
+@end smallexample
+
+@noindent
+where @var{var} is the name of a defined meta-variable, is replaced with
+the value of the variable. This sequence is called @dfn{meta-
+reference}. For example, if the meta-variable @samp{user} has the
+value @samp{smith}, then the string
+
+@smallexample
+"where user = '$@{user@}'"
+@end smallexample
+
+@noindent
+becomes
+
+@smallexample
+"where user = 'smith'"
+@end smallexample
+
+If the name of the variable consists of a single character, the curly
+braces around it may be omitted. Thus, @code{$@{u@}} and @code{$u} are
+equivalent.
+
+If @var{var} is not defined, the meta-reference is left unchanged.
+
+To insert a literal @samp{$} character in a string that is subject to
+meta-variable interpretation, duplicate it: @samp{$$}.
+
+The exact set of defined meta-variables and their values depend on the
+context and are discussed in detail below.
+
@anchor{here-document}
@item Here-document
@cindex here-document
@@ -569,8 +629,8 @@ strings of text containing embedded newlines.
The @code{<<@var{word}} construct instructs the parser to read all
the following lines up to the line containing only @var{word}, with
-possible trailing blanks. Any lines thus read are concatenated
-together into a single string. For example:
+possible trailing blanks. Any lines thus read are concatenated
+together into a single string. For example:
@smallexample
@group
@@ -657,7 +717,43 @@ spool download @{
The closing curly brace may be followed by a semicolon, although
this is not required.
-
+
+@node Preprocessor
+@subsection Preprocessor
+@cindex preprocessor
+@cindex m4
+ Before parsing its configuration file, @command{wydawca} preprocesses
+it. The built-in preprocessor handles only file inclusion
+and @code{#line} statements (@pxref{Pragmatic Comments}), while the
+rest of traditional preprocessing facilities, such as macro expansion,
+is supported via @command{m4}, which is used as an external preprocessor.
+
+ The detailed description of @command{m4} facilities lies far beyond
+the scope of this document. You will find a complete user manual in
+@ifnothtml
+@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
+@end ifnothtml
+@ifhtml
+@uref{http://www.gnu.org/software/m4/manual}.
+@end ifhtml
+For the rest of this subsection we assume the reader is sufficiently
+acquainted with @command{m4} macro processor.
+
+@cindex @file{pp-setup}
+ The external preprocessor is invoked with @option{-s} flag, which
+instructs it to include line synchronization information in its
+output. This information is then used by the parser to display meaningful
+diagnostic. An initial set of macro definitions is supplied by the
+@file{pp-setup} file, located in
+@file{@var{$prefix}/share/wydawca/@var{version}/include} directory (where
+@var{version} means the version of Wydawca package).
+
+The default @file{pp-setup} file renames all @command{m4} built-in
+macro names so they all start with the prefix @samp{m4_}. This
+is similar to GNU m4 @option{--prefix-builtin} options, but has an
+advantage that it works with non-GNU @command{m4} implementations as
+well.
+
@node syslog
@section Syslog Configuration Directives
@cindex syslog, configuration
@@ -746,7 +842,7 @@ database. 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} and the colon may be
omitted. If, however, it is present, it must be @samp{localhost}.
-@xref{sql-host}, for more information and examples.
+@FIXME-xref{sql-host}, for more information and examples.
@end deffn
@deffn {Configuration} database @var{name}
@@ -797,7 +893,7 @@ access-method @var{method-name} @{
Access method statements can appear either in the global scope of
the configuration file, or inside a @code{spool} statement
-(@FIXME-pxref{spool}). Global definitions affect all directory
+(@pxref{spool}). Global definitions affect all directory
pairs in the configuration file, and ones inside a @code{directory}
statement override them for that particular directory pair.
@@ -856,7 +952,7 @@ See below for a detailed description of these access methods.
@deffn {Configuration} query @var{string}
Sets the query used for retrieving the data. The @var{string} is
-subject to meta-variable expansion (@FIXME-pxref{meta-variables}). The
+subject to meta-variable interpretation (@pxref{meta-interpretation}). The
following meta-variables are defined:
@table @code
@@ -864,6 +960,7 @@ following meta-variables are defined:
@kwindex user
@item u
@itemx user
+@itemx user:name
The system name of the user that submitted the triplet.
@kwindex p
@@ -874,6 +971,24 @@ following meta-variables are defined:
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.
+
+@item spool
+ The name of the distribution spool where this upload originates
+(@pxref{spool}).
+
+@item url
+ The @acronym{URL} of the spool, as set in the @code{url} statement
+of the @code{spool} block (@pxref{spool, url}).
+
+@item dir
+Directory (relative to the project distribution root) where the
+files are going to be uploaded.
+
+@item dest-dir
+Spool destination directory (@pxref{spool, destination}).
+
+@item source-dir
+Spool source directory (@pxref{spool, source}).
@end table
@end deffn
@@ -940,11 +1055,11 @@ access-method project-owner @{
type sql;
params (default);
query "SELECT user.email, user.realname "
- "FROM user,user_group,groups "
- "WHERE user_group.user_id=user.user_id "
- "AND user_group.group_id=groups.group_id "
- "AND user_group.admin_flags = 'A' "
- "AND groups.unix_group_name = '$@{project@}'";
+ "FROM user,user_group,groups "
+ "WHERE user_group.user_id=user.user_id "
+ "AND user_group.group_id=groups.group_id "
+ "AND user_group.admin_flags = 'A' "
+ "AND groups.unix_group_name = '$@{project@}'";
@}
@end smallexample
@@ -972,11 +1087,11 @@ access-method verify-user @{
type sql;
params (default);
query "SELECT user.user_name "
- "FROM user,user_group, groups "
- "WHERE user_group.user_id=user.user_id "
- "AND user_group.group_id=groups.group_id "
- "AND user_group.admin_flags = 'A' "
- "AND groups.unix_group_name='$@{project@}' "
+ "FROM user,user_group, groups "
+ "WHERE user_group.user_id=user.user_id "
+ "AND user_group.group_id=groups.group_id "
+ "AND user_group.admin_flags = 'A' "
+ "AND groups.unix_group_name='$@{project@}' "
"AND user.user_name='$@{user@}'";
@}
@end smallexample
@@ -1010,7 +1125,7 @@ their existing files.
@command{tar} file, and to a separate directory. The method to be used
is configured using @code{archive} statement. This statement can
appear either in the global scope, in which case it affects all
-spools, or within a @code{spool} block (@FIXME-pxref{spool}),
+spools, or within a @code{spool} block (@pxref{spool}),
where it affects only the given spool.
@kwindex archive
@@ -1186,7 +1301,7 @@ spool @var{tag} @{
The @var{tag} argument defines a unique identifier for this spool. It
will be used in log messages, timers (@FIXME-pxref{timers}) and in
-meta-substitutions (@FIXME-pxref{meta-variables, spool}).
+meta-variable interpretation (@pxref{meta-interpretation}).
@deffn {Configuration} url @var{string}
Defines download @acronym{URL}, associated with this spool. Its value
@@ -1264,10 +1379,9 @@ spool ftp @{
@node statistics
@section Statistics
@cindex statistics
-@UNREVISED
At the end of the run, @command{wydawca} prints a detailed
statistics of its execution on the diagnostic channel @samp{info}.
-The statistics is printed only if at least one of the items is not zero.
+The statistics is printed only if at least one of its items is not zero.
The following example illustrates what you might get if you configured
full statistics output:
@@ -1354,18 +1468,18 @@ A symlink is removed.
@end table
@kwindex statistics
- Amount of information included in the statistics summary is
+ The 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:
@smallexample
-statistics errors warnings
+statistics (errors, warnings);
@end smallexample
@noindent
-It will produce the following output:
+The output produced looks like:
@smallexample
errors: 0
@@ -1373,28 +1487,27 @@ warnings: 2
@end smallexample
@kwindex none@r{, statistics}
- The special keyword @samp{none} can be used to suppress this output
+ A special keyword @samp{none} can be used to suppress this output
altogether (which is the default), as in
@smallexample
-statistics none
+statistics none;
@end smallexample
@kwindex all@r{, statistics}
- Another special keyword is @samp{all}, that enables all statistics
+ Another special keyword is @samp{all}. It enables full statistics
output. This keyword may also be followed by any number of statistics
keywords, which are in this case @emph{excluded} from the
summary. For example, to output all statistics, except errors and
warnings one would set:
@smallexample
-statistics all errors warnings
+statistics (all, errors, warnings);
@end smallexample
@node notification
@section Mail Notification
@cindex mail notification
-@UNREVISED
While running, @command{wydawca} keeps track of certain events
occurring, such as, for example, broken @acronym{PGP} signatures or
file uploads attempted by unauthorized users. The utility can notify,
@@ -1403,168 +1516,229 @@ concern their projects. Additionally, the system administrator can
choose to obtain via email the execution statistics, described in the
previous section.
-@kwindex from-address
The sender email address for these notifications is set using the
-@code{from-address} statement, e.g.:
+@code{from-address} statement.
+
+@deffn {Configuration} from-address @var{address}
+Set sender address for outgoing mails. E.g.:
@smallexample
-from-address ftp-uploads@@gnu.org.ua
+from-address ftp-uploads@@gnu.org.ua;
@end smallexample
+@end deffn
-@noindent
-It is not strictly necessary to specify it, however. In the absence of
-@code{from-address} statement, the sender email will be constructed
-from the name of the user @command{wydawca} runs as (usually
-@samp{root}) and the full domain name of the machine it runs at.
+It is not strictly necessary to specify the sender address. In the
+absence of @code{from-address} statement, the sender email will be
+constructed from the name of the user @command{wydawca} runs as
+(@FIXME-pxref{user privs}) and the full domain name of the machine it
+runs at.
+
+@deffn {Configuration} admin-address @var{email}
+Sets the admin email address or addresses. The statistics
+notifications and any notifications configured to be sent to admins
+will be forwarded to this address. The @var{email} argument is either
+a @acronym{RFC} 822 email address, or a list of such addresses. For
+example, the following statement configures a single admin address:
+
+@smallexample
+admin-address root@@gnu.org.ua;
+@end smallexample
+
+The example below illustrates how to configure multiple addresses:
+
+@smallexample
+admin-address "root@@gnu.org.ua,ftp-adm@@gnu.org.ua";
+@end smallexample
+
+Yet another way to configure them is:
+
+@smallexample
+admin-address (root@@gnu.org.ua, ftp-adm@@gnu.org.ua);
+@end smallexample
+@end deffn
@menu
-* mailer::
-* templates::
-* statreports::
-* event notification::
+* mailer::
+* templates::
+* statreports::
+* event notification::
@end menu
@node mailer
@subsection Mailer
@cindex mailer
-@kwindex mailer
-@UNREVISED
To send messages, @command{wydawca} uses a special logical entity
-called @dfn{mailer}. It is set in the configuration file using
-@code{mailer} keyword:
+called a @dfn{mailer}. It is set in the configuration file using
+@code{mailer} keyword.
-@smallexample
-mailer @var{url}
-@end smallexample
+@deffn {Configuration} mailer @var{url}
+Set mailer @acronym{URL}.
+@end deffn
@cindex @acronym{URL}, mailer
@cindex mailer @acronym{URL}
- A mailer @acronym{URL} begins with a protocol specification.
-Two protocol specifications are currently supported: @samp{sendmail}
-and @samp{smtp}. The former means to use a
-@command{sendmail}-compatible program to send mails. Such a program
-must be able to read mail from its standard input and must support the
-following options:
+ A mailer @acronym{URL} consists of a scheme specification, followed
+by @samp{://} separator and additional data. The @acronym{URL}s
+supported by Wydawca version @value{VERSION} are described in the
+table below. As usual, square brackets indicate optional parts:
+
+@table @asis
+@item smtp://@var{host}[:@var{port}]
+Use an SMTP server on @var{host} to relay messages. The @var{host} part is
+either an IP address in dotted-quad notation or as a symbolic host
+name. In the latter case, DNS system is be used to resolve
+it. Optional @var{port} specifies port number or symbolic name (as
+defined in @file{/etc/services}). It defaults to 25. For example:
+
+@smallexample
+mailer smtp://remote.server.net:24;
+@end smallexample
+
+@item sendmail://@var{progname}
+Use sendmail-compatible program
+@var{progname}. @dfn{Sendmail-compatible} means that the program must
+be able to read an RFC-822 message from its standard input and must
+support the following command line options:
@table @option
@item -oi
-Do not treat '.' as message terminator.
+Do not treat @samp{.} as message terminator.
@item -f @var{addr}
-Use @var{addr} as the address of the sender.
+Use @var{addr} as the sender address.
@item -t
Get recipient addresses from the message.
@end table
-These conditions are met by most existing @acronym{MTA} programs, such
-as @command{exim} or @command{postfix} (to say nothing of
-@command{sendmail} itself).
+Example:
+
+@smallexample
+mailer sendmail:///usr/sbin/exim;
+@end smallexample
+
+@item sendmail:
+This is a special form of the @samp{sendmail} mailer. It uses the
+@command{sendmail} binary from the @code{_PATH_SENDMAIL} macro in your
+@file{/usr/include/paths.h}. It is the default mailer.
-Following the protocol specification is the @dfn{mailer location}, which
-is separated from it with a colon. For the @samp{sendmail} protocol,
-the mailer location sets the full file name of the sendmail-co