aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-22 14:16:19 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-22 14:16:19 +0200
commit18fee8d03201211170f2b8579921ce9da7c5a78b (patch)
treea799f907cb55a310b0c5dd8f2bad3f2dbde4ab2e /doc
parent6f49d439216e3067d3f2994221edb8ea16e2c74e (diff)
downloadwydawca-18fee8d03201211170f2b8579921ce9da7c5a78b.tar.gz
wydawca-18fee8d03201211170f2b8579921ce9da7c5a78b.tar.bz2
Finish documentation
* doc/Makefile.am (manual.tar.bz2) (man-tar): New rules. * doc/gendocs_template: Rewrite. * doc/wydawca.texi: Update. * doc/Config: New file.
Diffstat (limited to 'doc')
-rw-r--r--doc/Config364
-rw-r--r--doc/Makefile.am14
-rwxr-xr-xdoc/gendocs_template130
-rw-r--r--doc/wydawca.texi374
4 files changed, 684 insertions, 198 deletions
diff --git a/doc/Config b/doc/Config
new file mode 100644
index 0000000..6ef0796
--- /dev/null
+++ b/doc/Config
@@ -0,0 +1,364 @@
+# Texi2html configuration for Wydawca documentation. -*- perl -*-
+# Copyright (C) 2009 Sergey Poznyakoff
+#
+# Wydawca is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# Wydawca is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Wydawca. If not, see <http://www.gnu.org/licenses/>.
+
+$top_html_dir="/software/wydawca";
+$graphics_dir="$top_html_dir/graphics";
+
+## texi2html configuration
+
+# Show TOC in place of the @contents directive.
+$INLINE_CONTENTS = 1;
+# Do not show Texinfo menus.
+$SHOW_MENU = 0;
+# Inhibit output of CSS lines in page headers.
+$CSS_LINES='';
+# Print footnotes at the end of each file (if the document is split).
+$SEPARATED_FOOTNOTES = 0;
+
+$BODYTEXT = "";
+
+$EXTRA_HEAD=qq{
+ <link rev="made" href="mailto:gray@gnu.org.ua">
+ <link rel="stylesheet" type="text/css" href="${top_html_dir}/gray.css">
+ <link rel="stylesheet" type="text/css" href="${top_html_dir}/texi.css">
+ <link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png">};
+
+$AFTER_BODY_OPEN=qq{
+<!--#include virtual="${top_html_dir}/inc/header.html" -->
+<ul class="tabs">
+ <li><a href="${top_html_dir}/wydawca.html">Main</a></li>
+ <li><a href="${top_html_dir}/download.html">Downloads</a></li>
+ <li><a class="active" href="${top_html_dir}/manual.html">Documentation</a></li>
+</ul>};
+
+$PRE_BODY_CLOSE="Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.";
+
+$format_map{'multitable'}='table class="multitable"';
+
+$SMALL_RULE = '';
+$DEFAULT_RULE = '';
+$MIDDLE_RULE = '';
+# This is output at the end of a section.
+$BIG_RULE = '';
+
+# Use navigation icons
+$ICONS = 1;
+%ACTIVE_ICONS =
+ (
+ 'Top', "$graphics_dir/top.png",
+ 'Contents', "$graphics_dir/ctx.png",
+ 'Overview', '',
+ 'Index', "$graphics_dir/idx.png",
+ 'This', '',
+ 'Back', "$graphics_dir/left.png",
+ 'FastBack', "$graphics_dir/bwd.png",
+ 'Prev', "",
+ 'Up', "$graphics_dir/up.png",
+ 'Next', "$graphics_dir/right.png",
+ 'NodeUp', "$graphics_dir/left.png",
+ 'NodeNext', "$graphics_dir/up.png",
+ 'NodePrev', "$graphics_dir/right.png",
+ 'Following', "$graphics_dir/right.png",
+ 'Forward', "$graphics_dir/right.png",
+ 'FastForward', "$graphics_dir/fwd.png",
+ 'About' , '',
+ 'First', '',
+ 'Last', '',
+ ' ', ''
+ );
+
+@SECTION_BUTTONS =
+ (
+ \&gray_document_title,
+ \&gray_sec_ref,
+ 'Back', 'Forward',
+ \&gray_chap_ref, 'FastBack', 'Up', 'FastForward',
+ \&gray_doc_ref,
+ 'Contents', 'Index',
+ ' ','About',
+ );
+
+@SECTION_FOOTER_BUTTONS = @SECTION_BUTTONS;
+@NODE_FOOTER_BUTTONS = @SECTION_BUTTONS;
+
+# buttons for misc stuff
+@MISC_BUTTONS = (
+ \&gray_document_title,
+ 'Contents',
+ 'Index',
+ ' ',
+ 'About'
+ );
+
+
+$print_section = \&gray_print_section;
+$print_navigation = \&gray_print_navigation;
+$print_head_navigation = \&gray_print_head_navigation;
+$print_foot_navigation = \&gray_print_foot_navigation;
+$print_About = \&gray_print_About;
+$cell = \&gray_multitable_cell;
+$print_page_foot = \&gray_print_page_foot;
+
+sub gray_multitable_cell($$)
+{
+ my $text = shift;
+ my $row_macro = shift;
+
+ $text =~ s/<p>//;
+ $text =~ s/<\/p>//;
+ if ($row_macro eq 'headitem')
+ {
+ return '<th>' . $text . '</th>';
+ }
+ return '<td>' . $text . '</td>';
+}
+
+sub gray_print_About
+{
+ return &$print_misc(@_) if (!($SPLIT eq '') or $SECTION_NAVIGATION);
+}
+
+sub gray_split_status()
+{
+ if ($SPLIT eq '') {
+ return '';
+ } elsif ($SPLIT eq 'node') {
+ return ' <span class="splitstatus">(split by node)</span>';
+ } elsif ($SPLIT eq 'section') {
+ return ' <span class="splitstatus">(split by section)</span>';
+ } elsif ($SPLIT eq 'chapter') {
+ return ' <span class="splitstatus">(split by chapter)</span>';
+ }
+}
+
+sub gray_document_title($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ my $status = gray_split_status();
+ print $fh qq{<td class="title">} . $Texi2HTML::THISDOC{title} . $status . ":</td>\n";
+}
+
+sub gray_node_ref($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ print $fh qq{<span class="navtext">Node:</span>};
+}
+
+sub gray_sec_ref($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ print $fh qq{<span class="navtext">Section:</span>};
+}
+
+sub gray_chap_ref($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ print $fh qq{<span class="navtext">Chapter:</span>};
+}
+
+sub gray_doc_ref($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ print $fh qq{<span class="navtext">Doc:</span>};
+}
+
+sub gray_print_navigation
+{
+ my $fh = shift;
+ my $buttons = shift;
+ my $vertical = shift;
+ my $spacing = 1;
+ my $class="nav";
+
+ print $fh qq{<table class="nav">\n};
+
+ print $fh "<tr>" unless $vertical;
+ for my $button (@$buttons)
+ {
+ if ($button =~ /^\@class=(.*)/) {
+ $class = "$class $1";
+ next;
+ }
+ print $fh "<tr>\n" if $vertical;
+ print $fh qq{<td class="$class">};
+
+ if (ref($button) eq 'CODE')
+ {
+ &$button($fh, $vertical);
+ }
+ elsif (ref($button) eq 'SCALAR')
+ {
+ print $fh "$$button" if defined($$button);
+ }
+ elsif (ref($button) eq 'ARRAY')
+ {
+ my $text = $button->[1];
+ my $button_href = $button->[0];
+ # verify that $button_href is simple text and text is a reference
+ if (defined($button_href) and !ref($button_href)
+ and defined($text) and (ref($text) eq 'SCALAR') and defined($$text))
+ { # use given text
+ if ($Texi2HTML::HREF{$button_href})
+ {
+ print $fh "" .
+ &$anchor('',
+ $Texi2HTML::HREF{$button_href},
+ $$text
+ )
+ ;
+ }
+ else
+ {
+ print $fh $$text;
+ }
+ }
+ }
+ elsif ($button eq ' ')
+ { # handle space button
+ print $fh
+ ($ICONS && $ACTIVE_ICONS{' '}) ?
+ &$button_icon_img($BUTTONS_NAME{$button}, $ACTIVE_ICONS{' '}) :
+ $NAVIGATION_TEXT{' '};
+ #next;
+ }
+ elsif ($Texi2HTML::HREF{$button})
+ { # button is active
+ my $btitle = $BUTTONS_GOTO{$button} ?
+ 'title="' . $BUTTONS_GOTO{$button} . '"' : '';
+ if ($ICONS && $ACTIVE_ICONS{$button})
+ { # use icon
+ print $fh '' .
+ &$anchor('',
+ $Texi2HTML::HREF{$button},
+ &$button_icon_img($BUTTONS_NAME{$button},
+ $ACTIVE_ICONS{$button},
+ $Texi2HTML::SIMPLE_TEXT{$button}),
+ $btitle
+ );
+ }
+ else
+ { # use text
+ print $fh
+ '' .
+ &$anchor('',
+ $Texi2HTML::HREF{$button},
+ $NAVIGATION_TEXT{$button},
+ $btitle
+ );
+ }
+ }
+ else { # button is passive
+ print $fh '<span class="passive">' .
+ ($ICONS && $PASSIVE_ICONS{$button} ?
+ &$button_icon_img($BUTTONS_NAME{$button},
+ $PASSIVE_ICONS{$button},
+ $Texi2HTML::SIMPLE_TEXT{$button}) :
+
+ $NAVIGATION_TEXT{$button}) . '</span>';
+ }
+ print $fh "</td>\n";
+ print $fh "</tr>\n" if $vertical;
+ $class = "nav";
+ }
+ print $fh "</tr>" unless $vertical;
+ print $fh "</table>\n";
+}
+
+sub gray_print_head_navigation($$)
+{
+ my $fh = shift;
+ my $buttons = shift;
+
+ return if ($SPLIT eq '');
+ if ($VERTICAL_HEAD_NAVIGATION)
+ {
+ print $fh <<EOT;
+<table class='nav'>
+<tr>
+<td>
+EOT
+ }
+ main::print_lines($fh, $Texi2HTML::THIS_HEADER);
+ &$print_navigation($fh, $buttons, $VERTICAL_HEAD_NAVIGATION);
+ if ($VERTICAL_HEAD_NAVIGATION)
+ {
+ print $fh <<EOT;
+</td>
+<td>
+EOT
+ }
+}
+
+sub gray_print_foot_navigation
+{
+ my $fh = shift;
+
+ return if ($SPLIT eq '');
+ if ($VERTICAL_HEAD_NAVIGATION)
+ {
+ print $fh <<EOT;
+</td>
+</tr>
+</table>
+EOT
+ }
+}
+
+sub gray_print_page_foot($)
+{
+ my $fh = shift;
+ my $program_string = program_string();
+ print $fh <<EOT;
+<div class="copyright">
+$program_string
+EOT
+ if (defined($PRE_BODY_CLOSE) && $PRE_BODY_CLOSE) {
+ print $fh "<p>$PRE_BODY_CLOSE</p>";
+ }
+ print $fh <<EOT;
+</div>
+</body>
+</html>
+EOT
+}
+
+sub gray_print_section
+{
+ my $fh = shift;
+ my $first_in_page = shift;
+ my $previous_is_top = shift;
+ my $buttons = \@SECTION_BUTTONS;
+
+ if ($first_in_page) {
+ &$print_head_navigation($fh, $buttons)
+ } else {
+ main::print_lines($fh, $Texi2HTML::THIS_HEADER);
+ }
+ my $nw = main::print_lines($fh);
+ if (defined $SPLIT
+ and ($SPLIT eq 'node')) {
+ &$print_foot_navigation($fh);
+ print $fh "$SMALL_RULE\n";
+ &$print_navigation($fh, \@NODE_FOOTER_BUTTONS) if (!defined($WORDS_IN_PAGE) or (defined ($nw)
+ and $nw >= $WORDS_IN_PAGE));
+ }
+}
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2fe7be7..824ed25 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -34,11 +34,19 @@ TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E
# Make sure you set TEXINPUTS.
# TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions
+.PHONY: manual
manual:
TEXINPUTS=$(srcdir):$(top_srcdir)/build-aux:$(TEXINPUTS) \
MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS)" \
TEXI2DVI="$(TEXI2DVI) -t @finalout" \
- $(GENDOCS) $(PACKAGE) '$(PACKAGE_NAME) manual'
+ $(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual'
+
+
+manual.tar.bz2: manual
+ tar cfj manual.tar.bz2 manual
+
+man-tar: manual.tar.bz2
+
# Checking
check-tabs:
@@ -67,14 +75,14 @@ check-refs:
@sed -e = $(info_TEXINFOS) $(wydawca_TEXINFOS) | \
sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\)}.*/$(info_TEXINFOS):\1: \2/gp}' > $@-t; \
if [ -s $@-t ]; then echo "Unresolved cross-references:"; cat $@-t;\
- fi
+ fi; \
rm -f $@-t
check-fixmes:
@sed -e = $(info_TEXINFOS) | \
sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/$(info_TEXINFOS):\1: \2/gp}' > $@-t; \
if [ -s $@-t ]; then echo "Unresolved FIXMEs:"; cat $@-t;\
- fi
+ fi; \
rm -f $@-t
check-writeme:
diff --git a/doc/gendocs_template b/doc/gendocs_template
index 83a33d9..463dcdb 100755
--- a/doc/gendocs_template
+++ b/doc/gendocs_template
@@ -1,105 +1,67 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<!-- $Id: gendocs_template 259 2007-06-06 12:43:37Z gray $ -->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
-
-<head>
-<title>%%TITLE%% - Free Software - puszcza.gnu.org.ua</title>
-<meta http-equiv="content-type" content='text/html; charset=utf-8' />
-<link rel="stylesheet" type="text/css" href="/local/css/gnu.css" />
-<link rev="made" href="mailto:gray@gnu.org" />
- <link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png" />
-</head>
-
-<!-- This document is in XML, and xhtml 1.0 -->
-<!-- Please make sure to properly nest your tags -->
-<!-- and ensure that your final document validates -->
-<!-- consistent with W3C xhtml 1.0 and CSS standards -->
-<!-- See validator.w3.org -->
-
-<body>
-
-<h3>%%TITLE%%</h3>
-
-<address>Sergey Poznyakoff</address>
-<address>last updated %%DATE%%</address>
-<p>
-<a href="/graphics/gnu-head.jpg">
- <img src="/graphics/gnu-head-sm.jpg"
- alt=" [image of the head of a GNU] "
- width="129" height="122" />
-</a>
-
-</p>
-<hr />
+<!--#include virtual="inc/pagehdr.html" -->
+<!--#include virtual="inc/header.html" -->
+<ul class='tabs'>
+ <li><a href="wydawca.html">Main</a></li>
+ <li><a href="download.html">Downloads</a></li>
+ <li><a class="active" href="manual.html">Documentation</a></li>
+</ul>
-<p>The manual for %%PACKAGE%% is available in the following formats:</p>
+<div id="main">
+<p>The manual for <b>%%PACKAGE%%</b> is available in the following formats:</p>
<ul>
- <li><a href="%%PACKAGE%%.html">HTML
- (%%HTML_MONO_SIZE%%K characters)</a> - entirely on one web page.</li>
- <li><a href="html_node/index.html">HTML</a> - with one web page per
+ <li><a href="manual/%%PACKAGE%%.html">HTML
+ (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
+ <li><a href="manual/html_node/index.html">HTML</a> - with one web page per
node.</li>
- <li><a href="%%PACKAGE%%.html.gz">HTML compressed
- (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
- one web page.</li>
- <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
+%%IF HTML_SECTION%%
+ <li><a href="manual/html_section/index.html">HTML</a> - with one web page per
+ section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+ <li><a href="manual/html_chapter/index.html">HTML</a> - with one web page per
+ chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+ <li><a href="manual/%%PACKAGE%%.html.gz">HTML compressed
+ (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
+ one web page.</li>
+ <li><a href="manual/%%PACKAGE%%.html_node.tar.gz">HTML compressed
(%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
with one web page per node.</li>
- <li><a href="%%PACKAGE%%.info.tar.gz">Info document
+%%IF HTML_SECTION%%
+ <li><a href="manual/%%PACKAGE%%.html_section.tar.gz">HTML compressed
+ (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
+ with one web page per section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+ <li><a href="manual/%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
+ (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> -
+ with one web page per chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+ <li><a href="manual/%%PACKAGE%%.info.tar.gz">Info document
(%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li>
- <li><a href="%%PACKAGE%%.txt">ASCII text
+ <li><a href="manual/%%PACKAGE%%.txt">ASCII text
(%%ASCII_SIZE%%K characters)</a>.</li>
- <li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
+ <li><a href="manual/%%PACKAGE%%.txt.gz">ASCII text compressed
(%%ASCII_GZ_SIZE%%K gzipped characters)</a>.</li>
- <li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
+ <li><a href="manual/%%PACKAGE%%.dvi.gz">TeX dvi file
(%%DVI_GZ_SIZE%%K characters gzipped)</a>.</li>
- <li><a href="%%PACKAGE%%.ps.gz">PostScript file
+ <li><a href="manual/%%PACKAGE%%.ps.gz">PostScript file
(%%PS_GZ_SIZE%%K characters gzipped)</a>.</li>
- <li><a href="%%PACKAGE%%.pdf">PDF file
+ <li><a href="manual/%%PACKAGE%%.pdf">PDF file
(%%PDF_SIZE%%K characters)</a>.</li>
- <li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
+ <li><a href="manual/%%PACKAGE%%.texi.tar.gz">Texinfo source
(%%TEXI_TGZ_SIZE%%K characters gzipped tar file)</a></li>
</ul>
-<p>(This page generated by the <a
-href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.)
-</p>
-
-<p>
-<a href="http://validator.w3.org/check?uri=referer"><img
- src="http://www.w3.org/Icons/valid-xhtml10"
- alt="Valid XHTML 1.0!" height="31" width="88" /></a>
-</p>
-
-<div class="copyright">
-<p>
-Return to <a href="http://gray.gnu.org.ua">Sergey Poznyakoff home page</a>.
-</p>
-<p>
-Return to the <a href="http://puszcza.gnu.org.ua">Puszcza home page</a>.
-</p>
-
-<p>
-Please send broken links and other corrections (or suggestions) to
-<a href="mailto:webmaster@gnu.org.ua"><em>webmaster at gnu dot org dot ua</em></a>.
-</p>
-
-<p>
-Copyright (C) 2005 Sergey Poznyakoff
-<br />
-Verbatim copying and distribution of this entire article is
-permitted in any medium, provided this notice is preserved.
-</p>
+</div>
-<p>
-Updated:
-<!-- timestamp start -->
-$Date: 2007-06-06 15:43:37 +0300 (Wed, 06 Jun 2007) $ $Author: gray $
-<!-- timestamp end -->
+<div class="generator">
+<p>(This page is generated by the <a
+href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.)
</p>
</div>
+<!--#include virtual="inc/footer.html" -->
</body>
</html>
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 201b960..da58e41 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -87,9 +87,18 @@ already listed, mentioned here so you can get to them in one step:
@detailmenu
--- The Detailed Node Listing ---
+Operation Overview
+
+* operation modes::
+
How to Configure @command{wydawca}.
* Syntax:: Configuration file syntax.
+* general::
+* user privileges::
+* daemon::
+* tcp-wrapper::
+* locking::
* syslog::
* sql::
* dictionaries::
@@ -152,7 +161,7 @@ The following is a short summary of it: there is an @acronym{FTP}
@dfn{upload site}, which has two @dfn{source directories}, each one
corresponding to a certain distribution @acronym{URL}. For example,
-@multitable @columnfractions 0.4 0.4
+@multitable @columnfractions 0.4 0.6
@headitem Source Directory @tab Distribution Site
@item @file{/incoming/ftp} @tab @indicateurl{ftp.gnu.org}
@item @file{/incoming/alpha} @tab @indicateurl{alpha.gnu.org}
@@ -304,23 +313,23 @@ this is the usual way for @command{wydawca} to be used as a cron job.
@cindex daemon mode
In @dfn{daemon mode}, @command{wydawca} detaches itself from
-the conrolling terminal and runs in the background, listening on
+the controlling terminal and runs in the background, listening on
a preconfigured socket. The socket implements the @acronym{TCPMUX}
protocol@footnote{@uref{http://www.rfc-editor.org/rfc/rfc1078.txt, RFC
1078}.} and operates as follows:
After establishing connection, the remote party (the @dfn{client})
-sends the spool tag followed by a CRLF pair. The server
+sends the spool tag followed by a CRLF pair. The server
scans its configuration for a spool that has the requested
-@acronym{ID}. If no such spool is found, the server replies
+@acronym{ID}. If no such spool is found, the server replies
with the string @samp{- Unknown service name}, followed by a CRLF pair
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
+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
+did the upload. The following sample transaction illustrates
this:
@smallexample
@@ -378,7 +387,7 @@ running.
@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 may instruct it to process only a subset of these
by using the following options:
@table @option
@@ -791,7 +800,7 @@ alias (test);
@cindex Time Interval Specification
The @dfn{time interval specification} is a string that defines an
interval, much the same way we do this in English: it consists of one
-or more pairs @samp{number}-@samp{time unit}. For example, the
+or more pairs @samp{number}-@samp{time unit}. For example, the
following are valid interval specifications:
@smallexample
@@ -804,7 +813,7 @@ following are valid interval specifications:
@noindent
The pairs can occur in any order, however unusual it may sound to a
-human ear, e.g. @samp{2 days 1 year}. If the @samp{time unit} is
+human ear, e.g. @samp{2 days 1 year}. If the @samp{time unit} is
omitted, seconds are supposed.
@end table
@@ -895,13 +904,13 @@ Use @var{command} instead of the default preprocessor.
@section General Settings
@deffn {Config} foreground bool
-If @var{bool} is @samp{yes}, run in foreground. @xref{invocation,
+If @var{bool} is @samp{yes}, run in foreground. @xref{invocation,
foreground}.
@end deffn
@deffn {Config} single-process bool
Configure single process mode. Normally @command{wydawca}
-spawns podprocesses for handling incoming connections and spool jobs.
+spawns subprocesses for handling incoming connections and spool jobs.
This is disabled if @var{bool} is @samp{yes} (a so-called
@dfn{single-processs mode}). This mode is designed for debugging
purposes. Do not use it in production environments, because it
@@ -921,7 +930,7 @@ This parameter may also be set for each spool
individually. @xref{spool, file-sweep-time}.
@end deffn
-@acronym{gpg-homedir}
+@anchor{gpg-homedir}
@deffn {Config} gpg-homedir dir
Set default @acronym{GPG} home directory. The keys for signing
outgoing messages are looked up in this directory. @xref{statreports,
@@ -950,14 +959,15 @@ group (nogroup, ftp);
@node daemon
@section Daemon Configuration
-@UNREVISED
+
+ Statements in this section configure the daemon mode.
@deffn {Config} daemon bool
Enable daemon mode.
@end deffn
@deffn {Config} listen url
-Define a socket to listen on. Allowed values for @var{url}
+Define a socket to listen on. Allowed values for @var{url}
are:
@table @asis
@@ -994,7 +1004,6 @@ statement (@pxref{general, file-sweep-time}).
@deffn {Config} pidfile file
Store master process @acronym{PID} in @var{file}. Default pidfile
location is @file{@var{localstatedir}/run/wydawca.pid}.
-@FIXME{weird location}.
@end deffn
@node tcp-wrapper
@@ -1055,7 +1064,11 @@ and @samp{deny-syslog-priority} statements are: @samp{emerg},
@node locking
@section Locking Configuration
-@UNREVISED
+ To avoid a possibility of two @command{wydawca} instances handling
+the same triplet, @command{wydawca} @dfn{locks} the spool before
+processing it. This is done by creating a @dfn{lock file}. The
+parameters of the locking subsystem are configured via the
+@code{locking} statement:
@deffn {Config} locking @{ @dots{} @}
@smallexample
@@ -1069,12 +1082,15 @@ locking @{
@end deffn
@deffn {Config: locking} enable bool
-Enable or disable locking.
+Enable or disable locking. By default it is enabled.
@end deffn
@deffn {Config: locking} directory dir
-Sets directory for lock files. The default is
-@file{@var{localstatedir}/@/lock/@/wydawca}.
+Sets directory for lock files. Make sure @var{dir} is writable
+for the user (or group) @command{wydawca} runs at (@pxref{user
+privileges}.
+
+The default directory is @file{@var{localstatedir}/@/lock/@/wydawca}.
@end deffn
@deffn {Config: locking} expire-time time
@@ -1085,7 +1101,10 @@ older than @var{time} is considered stale and removed.
@end deffn
@deffn {Config: locking} timeout time
-Timeout for acquring locks.
+Timeout for acquiring locks. If a lock file cannot be acquired during
+this time, @command{wydawca} reports error and exits.
+
+@xref{time interval specification}, for the syntax of @var{time}.
@end deffn
@node syslog
@@ -1179,7 +1198,6 @@ 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}.
-@FIXME-xref{sql-host}, for more information and examples.
@end deffn
@deffn {Config: sql} database name
@@ -1281,6 +1299,7 @@ reserved for future use.
See below for a detailed description of these dictionary types.
@end deffn
+@anchor{query}
@deffn {Config: dictionary} query string
Sets the query used for retrieving the data. The @var{string} is
subject to meta-variable interpretation (@pxref{meta-interpretation}). The
@@ -1381,7 +1400,10 @@ dictionary project-owner @{
@node project-uploader-sql
@subsubsection Project-uploader: an SQL Implementation
@cindex project-uploader-sql
-@UNREVISED
+
+ This dictionary assumes that the @samp{user} table has a special
+column, @samp{upload_flags}, whose value is @samp{Y} for those users
+who can do uploads for this project:
@smallexample
dictionary project-uploader @{
@@ -1391,7 +1413,7 @@ dictionary project-uploader @{
"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 user_group.upload_flags = 'Y' "
"AND groups.unix_group_name = '$@{project@}'";
@}
@end smallexample
@@ -1399,7 +1421,110 @@ dictionary project-uploader @{
@node builtin type
@subsection Built-in Dictionary
@cindex builtin dictionary
-@WRITEME
+
+ @dfn{Builtin dictionaries} are small dictionaries that keep all data
+in their @code{params} list. They are designed mainly for testing
+purposes.
+
+ Look ups in builtin dictionaries are performed as follows:
+The @code{query} value is expanded (@pxref{query}). The resulting
+value is used as a @dfn{key} for lookup in @code{params} list.
+The list scanned as follows:
+
+@enumerate 1
+@item INIT
+
+Let @var{i} be the index of the current element in @code{params}.
+Set @var{i} to 0.
+
+@item GETEL
+
+Get the @var{i}th element.
+
+@item
+
+If it begins with a slash, interpret it as @dfn{comparison type
+indicator}. Its possible values are:
+
+@table @asis
+@item /exact
+Exact comparison. The key must be exactly equivalent to the
+dictionary field.
+
+@item /fnmatch
+Dictionary field is treated as an @dfn{fnmatch globbing
+pattern}. @xref{globbing pattern,,,glob(7),glob man page}.
+
+@item /regex
+Dictionary field is treated as a regular expression.
+Unless configured otherwise by flags (see below), @acronym{POSIX}
+extended regular expressions are used (@pxref{Extended
+regexps, Extended regular expressions, Extended regular expressions,
+sed, GNU sed}).
+@end table
+
+If that word ends with a comma, the characters following it
+are @dfn{flags}, defining the type of matching. Allowed flags
+are:
+
+@multitable @columnfractions 0.2 0.8
+@headitem Flag @tab Meaning
+@item i @tab Ignore case
+@item b @tab Use basic regular expressions
+@end multitable
+
+ For example, the string @samp{/exact,i} specifies case-insensitive
+exact comparison, the string @samp{/regex,bi} specifies
+case-insensitive basic regular expression matching, etc.
+
+ Go to step @samp{INCR}.
+
+@item COMP
+
+Compare the element with the key, using currently selected comparison
+method.
+
+@item
+
+If the element matches the key, add elements @code{@var{i}+1}
+through @code{@var{i}+@var{n}} to the result set. The value for
+@var{n} is selected as follows:
+
+@multitable @columnfractions 0.8 0.2
+@headitem Dictionary @tab @var{n}
+@item project-owner @tab 2
+@item project-uploader @tab 4
+@end multitable
+
+@item
+
+Set @code{@var{i} = @var{i} + @var{n}}
+
+@item INCR
+
+Set @code{@var{i} = @var{i} + 1}.
+
+@item LOOP
+
+If @var{i} is greater than the number of elements in @code{param},
+then stop. Otherwise, go to step @samp{GETEL}.
+@end enumerate
+
+ For example, the following defines the @samp{project-owner}
+dictionary, containing data for projects @samp{foo} and @samp{bar}:
+
+@smallexample
+@group
+dictionary project-owner @{
+ type builtin;
+ query "$@{project@}";
+ params ("/exact",
+ "foo", "foo-owner@@domain.net", "Foo Admin",
+ "bar", "smith@@other.net", "John Smith");
+@}
+@end group
+@end smallexample
+
@node external type
@subsection External Dictionary
@@ -1413,7 +1538,7 @@ implemented.
@cindex archivation, defined
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,
+(Note, however, 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
@@ -1599,7 +1724,7 @@ spool @var{tag} @{
@end smallexample
The @var{tag} argument defines a unique identifier for this spool. It
-will be used in log messages, timers (@FIXME-pxref{timers}) and in
+will be used in log messages, timers (@pxref{spool-timers}) and in
meta-variable interpretation (@pxref{meta-interpretation}).
@end deffn
@@ -2079,7 +2204,7 @@ statistics (stat-msg, errors, access-violations, bad-signatures);
@deffn {Config: mail-statistics} 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 supplied @acronym{GPG} @var{key}. The key is looked up in
the @acronym{GPG} home directory (@pxref{gpg-homedir}).
@end deffn
@@ -2089,7 +2214,7 @@ The statistics message is sent to addresses configured by
@cindex meta-variables in admin notifications
The meta-variables available for use in statistics reports are:
-@multitable @columnfractions 0.50 0.50
+@multitable @columnfractions 0.30 0.70
@headitem Variable @tab Replaced with
@kwindex date
@item date @tab Current date and time in the current locale.
@@ -2124,7 +2249,32 @@ triplets.
@item stat:rmsymlinks @tab Number of symbolic links removed.
@end multitable
-@FIXME{timers: @code{timer:@var{id}:user} }
+@anchor{spool-timers}
+@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:
+
+@multitable @columnfractions 0.30 0.70
+@kwindex timer:wydawca:real
+@item timer:wydawca:real @tab Real time spent in @command{wydawca}
+main code.
+@kwindex timer:wydawca:system
+@item timer:wydawca:system @tab System @acronym{CPU} time spent in
+@command{wydawca} main code.
+@kwindex timer:wydawca:user
+@item timer:wydawca:user @tab User @acronym{CPU} time spent in
+@command{wydawca} main code.
+@kwindex timer:@var{tag}:real
+@item timer:@var{tag}:real @tab Real time spent processing the
+@var{tag} spool.
+@kwindex timer:@var{tag}:system
+@item timer:@var{tag}:system @tab System @acronym{CPU} time spent
+processing the @var{tag} spool.
+@kwindex timer:@var{tag}:user
+@item timer:@var{tag}:user @tab User @acronym{CPU} time spent
+processing the @var{tag} spool.
+@end multitable
An example definition of the admin notification template follows:
@@ -2135,16 +2285,31 @@ mail-statistics @{
message <<EOT
Subject: Wydawca stats
-This is to notify you that my run on %@{date@}
+This is to notify you that my run on $@{date@}
caused the following results:
-errors ............................. %@{stat:errors@}
-warning ............................ %@{stat:warnings@}
-bad signatures ..................... %@{stat:bad_signatures@}
-access violation attempts .......... %@{stat:access_violations@}
+errors ............................. $@{stat:errors@}
+warning ............................ $@{stat:warnings@}
+bad signatures ..................... $@{stat:bad_signatures@}
+access violation attempts .......... $@{stat:access_violations@}
+
+Timings:
+Real ............................... $@{timer:wydawca:real@} \
+($@{timer:releases:real@} + \
+$@{timer:alpha:real@} + \
+$@{timer:test:real@})
+System ............................. $@{timer:wydawca:system@} \
+($@{timer:releases:system@} + \
+$@{timer:alpha:system@} + \
+$@{timer:test:system@})
+User ............................... $@{timer:wydawca:user@} \
+($@{timer:releases:user@} + \
+$@{timer:alpha:user@} + \
+$@{timer:test:user@})
Regards,
Wydawca
+EOT;
@}
@end smallexample
@@ -2232,7 +2397,7 @@ template, or a reference to a template previously defined by a
@deffn {Config: notify-event} 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 supplied @acronym{GPG} @var{key}. The key is looked up in
the @acronym{GPG} home directory (@pxref{gpg-homedir}).
@end deffn
@@ -2258,100 +2423,87 @@ notify-event @{
The following macro-variab