Set up documentation framework

git-svn-id: file:///svnroot/wydawca/trunk@307 6bb4bd81-ecc2-4fd4-a2d4-9571d19c0d33

6 files changed, 365 insertions, 39 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a06751b..fb4d036 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -15,7 +15,7 @@
 # with this program. If not, see <http://www.gnu.org/licenses/>.
 
 info_TEXINFOS=wydawca.texi
-wydawca_TEXINFOS=fdl.texi rendition.texi
+wydawca_TEXINFOS=fdl.texi rendition.texi macros.texi
 
 EXTRA_DIST = gendocs_template
 
@@ -40,3 +40,56 @@ manual:
 	 TEXI2DVI="$(TEXI2DVI) -t @finalout" \
 	 $(GENDOCS) $(PACKAGE) '$(PACKAGE_NAME) manual'
 
+# Checking
+check-format:
+	@if test -n "`cat $(info_TEXINFOS) $(wydawca_TEXINFOS) | tr -d -c '\t'`"; then \
+		echo "Sources contain tabs; run make untabify"; \
+		false; \
+	fi
+
+check-options:
+	@check-docs.sh options \
+	   '/option options\[\] = /,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
+	   's/@opindex *\([^@,]*\), --.*/\1/p' \
+	   $(top_srcdir)/src/wydawca.c -- \
+	   $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
+		$(info_TEXINFOS) 
+
+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
+	  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
+	  rm -f $@-t
+
+check-unrevised:
+	@grep -Hn @UNREVISED $(info_TEXINFOS) > $@-t; \
+	if [ -s $@-t ]; then \
+	  echo "Unrevised nodes:"; \
+	  cat $@-t; \
+	  rm $@-t; \
+	  false;\
+	else \
+          rm $@-t; \
+	fi
+
+all-check-docs: check-format check-options check-refs check-fixmes check-unrevised
+
+check-docs: 
+	$(MAKE) -k all-check-docs
+
+master-menu:
+	emacs -batch -l mastermenu.el -f make-master-menu $(info_TEXINFOS)
+
+untabify:
+	emacs -batch -l untabify.el $(info_TEXINFOS) $(wydawca_TEXINFOS)
+
+final: untabify master-menu
+
diff --git a/doc/check-docs.sh b/doc/check-docs.sh
new file mode 100755
index 0000000..c0b0487
--- /dev/null
+++ b/doc/check-docs.sh
@@ -0,0 +1,74 @@
+#! /bin/sh
+# This file is part of mailfrom filter.
+# Copyright (C) 2006, 2007 Sergey Poznyakoff
+#
+# This program 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.
+#
+# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+
+usage() {
+  cat <<EOT
+usage: $0 item code-sed doc-sed sources -- args...
+EOT
+}
+
+if [ $# -le 4 ]; then
+  usage
+  exit 2
+fi
+
+item=$1
+shift
+codesexp="$1"
+shift
+docsexp=$1
+shift
+
+source=
+while [ $# -ne 0 ]
+do
+	if [ "$1" = "--" ]; then
+		shift
+		break;
+	fi
+	source="$source $1"
+	shift
+done	
+
+TEMPDIR=/tmp/mfck.$$
+mkdir $TEMPDIR || exit 1
+trap 'rm -rf $TEMPDIR' 1 2 13 15
+
+sed -n "$codesexp" $source | sort | uniq > $TEMPDIR/src
+$* | \
+ sed -n '/^@macro/,/^@end macro/d;'"$docsexp" \
+  | sort | uniq > $TEMPDIR/doc
+
+join -v1 $TEMPDIR/src $TEMPDIR/doc > $TEMPDIR/src-doc
+join -v2 $TEMPDIR/src $TEMPDIR/doc > $TEMPDIR/doc-src
+(if [ -s $TEMPDIR/src-doc ]; then
+   echo "Not documented $item:"
+   cat $TEMPDIR/src-doc 
+ fi
+ if [ -s $TEMPDIR/doc-src ]; then
+   echo "Non-existing $item:"
+   cat $TEMPDIR/doc-src
+ fi) > $TEMPDIR/report
+
+if [ -s $TEMPDIR/report ]; then 
+  cat $TEMPDIR/report
+  rm -rf $TEMPDIR
+  exit 1
+else
+  rm -rf $TEMPDIR
+  exit 0
+fi
diff --git a/doc/macros.texi b/doc/macros.texi
new file mode 100644
index 0000000..0651f2e
--- /dev/null
+++ b/doc/macros.texi
@@ -0,0 +1,15 @@
+@macro xopindex{option,text}
+@opindex \option\, --\option\ @r{option, \text\}
+@end macro
+
+@macro sopindex{option,text}
+@opindex \option\, -\option\ @r{short option, \text\}
+@end macro
+
+@macro opsummary{option}
+@ifclear ANCHOR--\option\
+@set ANCHOR--\option\ 1
+@anchor{--\option\}
+@end ifclear
+@xopindex{\option\, summary}
+@end macro
diff --git a/doc/mastermenu.el b/doc/mastermenu.el
new file mode 100644
index 0000000..3ab3341
--- /dev/null
+++ b/doc/mastermenu.el
@@ -0,0 +1,90 @@
+;;; mastermenu.el --- Redefinition of texinfo-master-menu-list
+
+;; Copyright (C) 2006, 2007 Free Software Foundation, Inc.
+
+;; Author: Sergey Poznyakoff
+;; Maintainer: bug-tar@gnu.org
+;; Keywords: maint, tex, docs
+
+;; This file is part of GNU tar documentation suite
+
+;; This program 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.
+
+;; This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file redefines texinfo-master-menu-list so that it takes into
+;; account included files.
+
+;; Known bugs: @menu without previous sectioning command will inherit 
+;; documentation string from the previous menu. However, since such a
+;; menu is illegal in a texinfo file, we can live with it.
+
+(require 'texinfo)  
+(require 'texnfo-upd)
+
+(defun texinfo-master-menu-list-recursive (title)
+  "Auxiliary function used by `texinfo-master-menu-list'."
+  (save-excursion
+    (let (master-menu-list)
+      (while (re-search-forward "\\(^@menu\\|^@include\\)" nil t)
+	(cond
+	 ((string= (match-string 0) "@include")
+	  (skip-chars-forward " \t")
+	  (let ((included-name (let ((start (point)))
+				 (end-of-line)
+				 (skip-chars-backward " \t")
+				 (buffer-substring start (point)))))
+	    (end-of-line)
+	    (let ((prev-title (texinfo-copy-menu-title)))
+	      (save-excursion
+		(set-buffer (find-file-noselect included-name))
+		(setq master-menu-list
+		      (append (texinfo-master-menu-list-recursive prev-title)
+			      master-menu-list))))))
+	 (t
+	  (setq master-menu-list
+		(cons (list
+		       (texinfo-copy-menu)
+		       (let ((menu-title (texinfo-copy-menu-title)))
+			 (if (string= menu-title "")
+			     title
+			   menu-title)))
+		      master-menu-list)))))
+      master-menu-list)))
+
+(defun texinfo-master-menu-list ()
+  "Return a list of menu entries and header lines for the master menu,
+recursing into included files.
+
+Start with the menu for chapters and indices and then find each
+following menu and the title of the node preceding that menu.
+
+The master menu list has this form:
+
+    \(\(\(... \"entry-1-2\"  \"entry-1\"\) \"title-1\"\)
+      \(\(... \"entry-2-2\"  \"entry-2-1\"\) \"title-2\"\)
+      ...\)
+
+However, there does not need to be a title field."
+
+  (reverse (texinfo-master-menu-list-recursive "")))
+
+(defun make-master-menu ()
+  "Create master menu in the first Emacs argument."
+  (find-file (car command-line-args-left))
+  (texinfo-master-menu nil)
+  (save-buffer))
+
+
+;;; mastermenu.el ends here
diff --git a/doc/untabify.el b/doc/untabify.el
new file mode 100644
index 0000000..77dd5c0
--- /dev/null
+++ b/doc/untabify.el
@@ -0,0 +1,13 @@
+;;;; Untabify the sources.
+;;;; Usage: emacs -batch -l untabify.el [file ...]
+
+(defun global-untabify (buflist)
+  (mapcar
+   (lambda (bufname)
+     (set-buffer (find-file bufname))
+     (untabify (point-min) (point-max))
+     (save-buffer)
+     (kill-buffer (current-buffer)))
+   buflist))
+
+(global-untabify command-line-args-left)
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 713e015..ff52882 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -6,12 +6,17 @@
 @c %**end of header
 @setchapternewpage odd
 
+@defcodeindex kw
+@defcodeindex op
 @syncodeindex fn cp
 @syncodeindex vr cp
 @syncodeindex ky cp
 @syncodeindex pg cp
 @syncodeindex tp cp
+@syncodeindex kw cp
+@syncodeindex op cp
 
+@include macros.texi
 @include version.texi
 @include rendition.texi
 
@@ -64,7 +69,7 @@ documents Wydawca Version @value{VERSION}.
 
 @menu
 * Intro::                  What is Wydawca
-
+* overview::               Operation Overview
 * starting::               How to Invoke @command{wydawca}.
 * configuring::            How to Configure @command{wydawca}.
 * wydawca.rc::             @command{Wydawca} configuration file.
@@ -84,7 +89,7 @@ already listed, mentioned here so you can get to them in one step:
 @end detailmenu
 @end menu
 
-@node Intro, starting, Top, Top
+@node Intro, overview, Top, Top
 @chapter Introduction to Wydawca
 @UNREVISED{}
   Let's begin with a short synopsis. Suppose you run a developer's
@@ -136,13 +141,17 @@ about any occurring problems.
   The program is written entirely in @acronym{C}, is highly
 effective and consumes little resources.
 
-@node starting, configuring, Intro, Top
+@node overview, starting, Intro, Top
+@chapter Operation Overview
+@UNREVISED{}
+
+@node starting, configuring, overview, Top
 @chapter How to invoke @command{wydawca}.
 @UNREVISED{}
 
 @anchor{wydawca--config-file}
-@cindex @option{--config-file}, @command{wydawca} option
-@cindex @option{-c}, @command{wydawca} option
+@xopindex{config-file, described}
+@sopindex{c, described}
   @command{Wydawca} gets all information it needs from its
 @dfn{configuration file} (@pxref{wydawca.rc}). The default
 configuration file is @file{@var{sysconfdir}/wydawca.rc}, but if it is
@@ -150,17 +159,17 @@ located elsewhere, you can specify its new location with the
 @option{--config-file} (@option{-c}) command line option. 
 
 @anchor{wydawca--lint}
-@cindex @option{--lint}, @command{wydawca} option
-@cindex @option{-t}, @command{wydawca} option
+@xopindex{lint, described}
+@sopindex{t, described}
   If you wish to check your configuration file for syntax errors, use
 @option{--lint} (@option{-t}) command line option. When given this
 option, @command{wydawca} prints all diagnostics on its standard
 error and exits with code 0 if the file is OK, or 1 otherwise.
 
 @anchor{wydawca--stderr}
-@cindex @option{--stderr}, @command{wydawca} option
-@cindex @option{-e}, @command{wydawca} option
-@cindex @option{--syslog}, @command{wydawca} option
+@xopindex{stderr, described}
+@sopindex{e, described}
+@xopindex{syslog, described}
   Normally, @command{wydawca} attempts to detect automatically whether
 it is run from an interactive console, and if so it prints it
 diagnostics to the standard error. Otherwise, the diagnostics is
@@ -172,15 +181,15 @@ all diagnostics using @command{syslog}, and the option
 @option{--stderr} (or @option{-e}) instructs it to print everything on
 the standard error.
 
-@cindex @option{--cron}, @command{wydawca} option
+@xopindex{cron, described}
   Usually you will run @command{wydawca} as a cron job. In that case,
 it seldom needs any additional arguments, but we suggest to use
 @option{--cron} command line option anyway. Currently, its effect is
 the same as @option{--syslog}, but it may change in the future.
 
 @anchor{wydawca--debug}
-@cindex @option{--debug}, @command{wydawca} option
-@cindex @option{-d}, @command{wydawca} option
+@xopindex{debug, described}
+@sopindex{d, described}
   The @option{--debug} (@option{-d}) tells the program to inrease its
 debugging level by 1. The @dfn{debugging level} determines the amount
 of information the program reports when it runs. By default it is 0,
@@ -192,8 +201,8 @@ debugging level currently is 4, which prints impractically many
 information and is useful primarily for @command{wydawca} developers.
 
 @anchor{wydawca--dry-run}
-@cindex @option{--dry-run}, @command{wydawca} option
-@cindex @option{-n}, @command{wydawca} option
+@xopindex{dry-run, described}
+@sopindex{n, described}
   Yet another debugging facility is the @option{--dry-run}
 (@option{-n}) option. It instructs @command{wydawca} no to do any
 modifications to the disk contents, but to verbosely print them. It
@@ -207,10 +216,10 @@ testing new configurations, for example:
 $ wydawca -c new.cfg --dry-run
 @end smallexample
 
-@cindex @option{--help}, @command{wydawca} option
-@cindex @option{-h}, @command{wydawca} option
-@cindex @option{--version}, @command{wydawca} option
-@cindex @option{-v}, @command{wydawca} option
+@xopindex{help, described}
+@sopindex{h, described}
+@xopindex{version, described}
+@sopindex{v, described}
   Two usual informational options are available as well:
 @option{--help} (@option{-h}) prints a short usage summary, and
 @option{--version} (@option{-v}) prints program version number. 
@@ -235,10 +244,10 @@ syslog-print-priority yes
 @end smallexample
 
 If a simple statement is so long that it is inconvenient to keep it on
-a single line, it can be split to several lines by ending each line
-with a backslash character (@samp{\}). Notice, that the backslash
-character must immediately precede the terminating newline. For
-example, this is a single statement split over several lines:
+a single line, it can be split over several lines by ending each line
+except the last one with a backslash character (@samp{\}). Notice,
+that the backslash character must immediately precede the terminating
+newline. For example, this is a single statement split over several lines:
 
 @smallexample
 @group
@@ -267,7 +276,8 @@ configuration on step-by-step basis.
 
 @node syslog
 @section Syslog Configuration Directives
-@UNREVISED{}
+@cindex syslog, configuration
+@kwindex syslog-facility
   Syslog is the default diagnostics channel for @command{wydawca}. By
 default, the program uses facility @samp{local1}. To change this, use
 @code{syslog-facility} statement:
@@ -276,12 +286,20 @@ default, the program uses facility @samp{local1}. To change this, use
 syslog-facility local2
 @end smallexample
 
+@kwindex authpriv@r{, syslog facility}
+@kwindex cron@r{, syslog facility}
+@kwindex daemon@r{, syslog facility}
+@kwindex ftp@r{, syslog facility}
+@kwindex local0 @r{through} local7@r{, syslog facilities}
+@kwindex mail@r{, syslog facility}
   It takes a single argument, denoting the facility to use. Allowed
 values are: @samp{auth}, @samp{authpriv}, @samp{cron}, @samp{daemon},
 @samp{ftp}, @samp{local0} through @samp{local7}, and
 @samp{mail}. These names are case-insensitive and may be optionally
 prefixed with @samp{LOG_}. The default is @samp{local1}.
 
+@kwindex syslog-tag
+@cindex syslog tag, configuring
   Another thing you may wish to tune is @dfn{syslog tag}, a string
 identifying each message issued by the program. By default it is a
 string @samp{wydawca}. To change it, use @code{syslog-tag} statement:
@@ -290,6 +308,8 @@ string @samp{wydawca}. To change it, use @code{syslog-tag} statement:
 syslog-tag wydawca
 @end smallexample
 
+@kwindex syslog-print-priority
+@cindex syslog priority, printing in diagnostics
   In addition to priority segregation, provided by @command{syslog},
 you can instruct @command{wydawca} to prefix each syslog message with
 its priority. To do so, set:
@@ -298,7 +318,7 @@ its priority. To do so, set:
 syslog-print-priority yes
 @end smallexample
 
-  At the end of each run, the program can pring detailed summary of
+  At the end of each run, the program prints detailed summary of
 executed actions, which looks like that:
 
 @smallexample
@@ -317,6 +337,7 @@ symlinks created: 0
 symlinks removed: 0
 @end smallexample
 
+@kwindex statistics
   You can nofigure the information displayed, using @code{statistics}
 statement. It takes arbitrary number of arguments, each one specifying
 which part of the above statistics to display. For example, given the
@@ -334,13 +355,15 @@ errors: 0
 warnings: 2
 @end smallexample
 
+@kwindex none@r{, statistics}
   The special keyword @samp{none} can be used to suppress this output
 altogether (which is the default), as in
 
 @smallexample
-statistics no
+statistics none
 @end smallexample
 
+@kwindex all@r{, statistics}
   Another special keyword is @samp{all}, that enables all statistics
 output. This keyword may also be followed by any number of usual
 arguments, which are in this case @emph{subtracted}. For example, to
@@ -353,37 +376,82 @@ statistics all errors warnings
   The following table summarizes all the keywords, available for
 @code{statistics} statement:
 
-@FIXME{write descriptions}
 @table @asis
+@kwindex errors@r{, statistics}
 @item errors
+Total number of errors occurred during the run.
+
+@kwindex warnings@r{, statistics}
 @item warnings
+Total number of warning conditions occurred during the run.
+
+@kwindex bad_signatures@r{, statistics}
 @item bad_signatures
+Total number of bad signatures, i.e. the ones not matching their
+public key.
+
+@kwindex access_violations@r{, statistics}
 @item access_violations
+Number of files, owned by users who have no rights to upload them.
+
+@kwindex complete_triplets@r{, statistics}
 @item complete_triplets
+Number of complete triplets.
+
+@kwindex incomplete_triplets@r{, statistics}
 @item incomplete_triplets
+Number of incomplete triplets, i.e. such that miss one or more of
+their files. Notice, that a directive file alone is counted as a
+complete triplet, provided that its signature verifies correctly and
+that it does not contain @code{file} directive.
+
+@kwindex bad_triplets@r{, statistics}
 @item bad_triplets
+Number of triplets, whose components are owned by different users.
+
+@kwindex expired_triplets@r{, statistics}
 @item expired_triplets
+Number of triplets expired in the queue.
+
+@kwindex triplet_success@r{, statistics}
 @item triplet_success
+Number of successfully processed triplets.
+
+@kwindex uploads@r{, statistics}
 @item uploads
+Number of executed uploads. An upload is defined as a successful move
+of a file and its detached signature from the source to its destination
+directory.
+
+@kwindex archives@r{, statistics}
 @item archives
+Number of archivations performed.
+
+@kwindex symlinks@r{, statistics}
 @item symlinks
+Number of symlinks created.
+
+@kwindex rmsymlinks@r{, statistics}
 @item rmsymlinks
+Number of symlinks removed.
 @end table
 
 @node access methods
 @section Access Methods
 @UNREVISED{}
-
+ 
 @node archivation
 @section Archivation
 @cindex archivation, defined
   Project maintainers may upload files having the same names as
 the ones uploaded earlier. Although this practice is not encouraged,
-it stillcan happen. In that case, @command{wydawca} needs to first
+it still can happen. In that case, @command{wydawca} needs to first
 @dfn{archive} the already existing file, and then put the new one in
 its place. Moreover, the directive file format allows maintainers to
 explicitely require archivation of their existing files.
 
+@cindex archivation methods
+@kwindex archive
   @code{Wydawca} supports two basic archivation methods: to a
 @command{tar} file, and to a separate directory. The method to be used
 is configured using @code{archive} statement. This statement can
@@ -395,12 +463,15 @@ pairs}), where it affects only the given directory pair.
 the archivation type: 
 
 @table @asis
+@kwindex none@r{, archivation}
 @item none
   Disable archivation.
   
+@kwindex tar@r{, archivation}
 @item tar
   Use @command{tar} archive.
   
+@kwindex directory@r{, archivation}
 @item directory
   Use separate directory or directory hierarchy.
 @end table
@@ -467,18 +538,21 @@ describes them:
 @table @samp
 @item t
 @itemx numbered
-@cindex numbered @r{backup method}
+@kwindex t@r{, backup method}
+@kwindex numbered@r{, backup method}
 Always make numbered backups.
 
 @item nil
 @itemx existing
-@cindex existing @r{backup method}
+@kwindex nil@r{, backup method}
+@kwindex existing@r{, backup method}
 Make numbered backups of files that already have them, simple backups.
 of the others.
 
 @item never
 @itemx simple
-@cindex simple @r{backup method}
+@kwindex never@r{, backup method}
+@kwindex simple@r{, backup method}
 Always make simple backups.
 
 @end table
@@ -728,9 +802,10 @@ Defines archivation defaults for the destination directory. The
 @item tar
 The @var{archive-name} is a full file name of the @command{tar}
 archive used for archivation. Files being archived are appended to
-that archive using @command{tar -r} command (@FIXME-pxref{tar}).
-The default file name of the @command{tar} binary is set by
-@code{tar-program} statement.
+that archive using @command{tar -r} command (@pxref{appending files,
+Appending Files to an Archive, Appending Files to an Archive, tar,
+@acronym{GNU} tar: an archiver tool}). The default file name of the
+@command{tar} binary is set by @code{tar-program} statement.
 
 @item directory
 The @var{archive-name} specifies a directory name where to store
@@ -764,18 +839,15 @@ also allows more descriptive names.  The valid @var{method}s are:
 @table @samp
 @item t
 @itemx numbered
-@cindex numbered @r{backup method}
 Always make numbered backups.
 
 @item nil
 @itemx existing
-@cindex existing @r{backup method}
 Make numbered backups of files that already have them, simple backups.
 of the others.
 
 @item never
 @itemx simple
-@cindex simple @r{backup method}
 Always make simple backups.
 
 @end table
@@ -789,6 +861,7 @@ Always make simple backups.
 @UNREVISED{}
 
 @table @option
+@opsummary{config-file}
 @item --config-file=@var{file}
 @itemx -c @var{file}
 Use @var{FILE} instead of the default configuration
@@ -796,24 +869,29 @@ file.
 
 @xref{wydawca--config-file, The @option{--config-file} option}.
 
+@opsummary{cron}
+@opsummary{syslog}
 @item --cron
 @itemx --syslog
 Log all diagnostics to syslog.
 
 @xref{wydawca--stderr, The @option{--syslog} option}.
 
+@opsummary{debug}
 @item --debug 
 @itemx -d
 Increase debugging level by 1.
 
 @xref{wydawca--debug, The @option{--debug} option}.
 
+@opsummary{stderr}
 @item --stderr
 @itemx -e
 Log to the standard error.
 
 @xref{wydawca--stderr, The @option{--syslog} option}.
 
+@opsummary{stderr}
 @item --dry-run
 @itemx -n
 @dfn{Dry-run mode}: do nothing, print almost everything. This option
@@ -821,6 +899,7 @@ implies @option{--debug --stderr}.
 
 @xref{wydawca--dry-run, The dry-run mode}.
 
+@opsummary{lint}
 @item --lint
 @itemx -t
 Parse configuration file, report any errors on the standard error and
@@ -828,10 +907,12 @@ exit with code 0, if the syntax is OK, and with code 1 otherwise.
 
 @xref{wydawca--lint, The @option{--lint} option}.
 
+@opsummary{help}
 @item --help
 @itemx -h
 Print a concise usage summary and exit.
 
+@opsummary{version}
 @item --version 
 @itemx -v
 Print the program version and exit.