diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-22 14:16:19 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-22 14:16:19 +0200 |
commit | 18fee8d03201211170f2b8579921ce9da7c5a78b (patch) | |
tree | a799f907cb55a310b0c5dd8f2bad3f2dbde4ab2e /doc | |
parent | 6f49d439216e3067d3f2994221edb8ea16e2c74e (diff) | |
download | wydawca-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/Config | 364 | ||||
-rw-r--r-- | doc/Makefile.am | 14 | ||||
-rwxr-xr-x | doc/gendocs_template | 130 | ||||
-rw-r--r-- | doc/wydawca.texi | 374 |
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 |