Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 19f006cd 19f006cd913e886c19e48aed683d19d512758d6f by Sergey Poznyakoff
Options

Begin rewriting the docs. 

* configure.ac: Configure doc hints.
* config/mailutils-config.c (main): Use mu_fprint_conf_option.
* mailbox/version.c (mu_conf_option): Change type.
(mu_fprint_conf_option): New function.
(mu_fprint_options): Use mu_fprint_conf_option.
(mu_print_options): Fix signature
(mu_check_option): Change return type.
* testsuite/lib/mailutils.exp (mu_version): Reflect changes in the
output produced by --show-config-options.

* include/mailutils/version.h (struct mu_conf_option): New data
type.
(mu_check_option): Change return type.
(mu_fprint_conf_option): New prototype.
* libargp/common.c (mu_common_argp): Rename --rcfile-* options
to --config-*. Retain old names for a while.

* doc/texinfo/Makefile.am (RENDITION_TEXI): New variable.
(check-format, check-refs, check-fixmes, check-unrevised)
(all-check-docs, check-docs): New rules.
* doc/texinfo/rendition.texi: New file.
* doc/texinfo/macros.texi: New file.
* doc/texinfo/mailutils.texi: Start rewriting
* doc/texinfo/programs.texi: Likewise.

* doc/texinfo/c-api.texi: Reformat.
* doc/texinfo/fdl.texi: Likewise.
* doc/texinfo/libmuauth.texi: Likewise.
* doc/texinfo/libsieve.texi: Likewise.
* doc/texinfo/mu-mh.texi: Likewise.
* doc/texinfo/sieve.texi: Likewise.

* doc/texinfo/gendocs_template: Rewrite.
1 parent 3f88df00
Inline Side-by-side
Showing 19 changed files with 872 additions and 452 deletions
2008-09-21 Sergey Poznyakoff <gray@gnu.org.ua>
* configure.ac: Configure doc hints.
* config/mailutils-config.c (main): Use mu_fprint_conf_option.
* mailbox/version.c (mu_conf_option): Change type.
(mu_fprint_conf_option): New function.
(mu_fprint_options): Use mu_fprint_conf_option.
(mu_print_options): Fix signature
(mu_check_option): Change return type.
* testsuite/lib/mailutils.exp (mu_version): Reflect changes in the
output produced by --show-config-options.
* include/mailutils/version.h (struct mu_conf_option): New data
type.
(mu_check_option): Change return type.
(mu_fprint_conf_option): New prototype.
* libargp/common.c (mu_common_argp): Rename --rcfile-* options
to --config-*. Retain old names for a while.
* doc/texinfo/Makefile.am (RENDITION_TEXI): New variable.
(check-format, check-refs, check-fixmes, check-unrevised)
(all-check-docs, check-docs): New rules.
* doc/texinfo/rendition.texi: New file.
* doc/texinfo/macros.texi: New file.
* doc/texinfo/mailutils.texi: Start rewriting
* doc/texinfo/programs.texi: Likewise.
* doc/texinfo/c-api.texi: Reformat.
* doc/texinfo/fdl.texi: Likewise.
* doc/texinfo/libmuauth.texi: Likewise.
* doc/texinfo/libsieve.texi: Likewise.
* doc/texinfo/mu-mh.texi: Likewise.
* doc/texinfo/sieve.texi: Likewise.
* doc/texinfo/gendocs_template: Rewrite.
2008-08-24 Sergey Poznyakoff <gray@gnu.org.ua>
Fix testsuite to avoid spawning /bin/cp.
......
......@@ -276,11 +276,11 @@ main (int argc, char **argv)
for (i = 0; i < argc; i++)
{
const char *val = mu_check_option (argv[i]);
if (val)
const struct mu_conf_option *opt = mu_check_option (argv[i]);
if (opt)
{
found++;
printf ("%s\n", val);
mu_fprint_conf_option (stdout, opt);
}
}
return found == argc ? 0 : 1;
......
......@@ -1103,6 +1103,24 @@ dnl get sysconfdir expanded.
CPPFLAGS="$CPPFLAGS -DSYSCONFDIR=\\\"\$(sysconfdir)\\\""
# Doc hints.
# Select a rendition level:
# DISTRIB for stable releases (at most one dot in the version number)
# and maintenance releases (two dots, patchlevel < 50)
# PROOF for alpha releases.
# PUBLISH can only be required manually when running make in doc/
AC_SUBST(RENDITION)
case `echo $VERSION|sed 's/[[^.]]//g'` in
""|".") RENDITION=DISTRIB;;
"..") if test `echo $VERSION | sed 's/.*\.//'` -lt 50; then
RENDITION=DISTRIB
else
RENDITION=PROOF
fi;;
*) RENDITION=PROOF;;
esac
AC_CONFIG_COMMANDS([status],[
cat <<EOF
......
......@@ -28,6 +28,8 @@ INCFILES = \
sfrom.inc\
url-parse.inc
RENDITION_TEXI=rendition.texi macros.texi
mailutils_TEXINFOS = \
address.texi\
attribute.texi\
......@@ -70,12 +72,9 @@ mailutils_TEXINFOS = \
smtp.texi\
stream.texi\
url.texi\
$(RENDITION_TEXI)\
$(INCFILES)
muint_TEXINFOS = \
muint.texi\
mom.texi
## Fake configure into including srcdir to VPATH:
s=${srcdir}:${top_srcdir}/examples/
VPATH = $(s)
......@@ -89,9 +88,12 @@ MAINTAINERCLEANFILES=$(INCFILES)
clean-local:
rm -rf manual
# The rendering level is one of PUBLISH, DISTRIB or PROOF.
# Just call `make RENDITION=PROOF [target]' if you want PROOF rendition.
MAKEINFOFLAGS=-D$(RENDITION)
GENDOCS=gendocs.sh
TEXI2DVI=texi2dvi
MAKEINFOFLAGS=
TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E
# Make sure you set TEXINPUTS.
# TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions
......@@ -114,3 +116,57 @@ untabify:
emacs -batch -l untabify.el $(info_TEXINFOS) $(mailutils_TEXINFOS)
final: untabify master-menu
# Checks
check-format:
@if test -n "`cat $(info_TEXINFOS) $(mailutils_TEXINFOS) |\
tr -d -c '\t'`"; then \
echo "Sources contain tabs; run make untabify"; \
false; \
fi
check-refs:
@for file in $(info_TEXINFOS) $(dico_TEXINFOS); \
do \
sed -e = $$file | \
sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\)}.*/'$$file':\1: \2/gp}'; \
done > $@-t; \
if [ -s $@-t ]; then \
echo "Unresolved cross-references:"; \
cat $@-t;\
rm $@-t; \
else \
rm -f $@-t; \
fi
check-fixmes:
@for file in $(info_TEXINFOS); \
do \
sed -e = $$file | \
sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \
done > $@-t; \
if [ -s $@-t ]; then \
echo "Unresolved FIXMEs:"; \
cat $@-t; \
rm $@-t; \
false; \
else \
rm -f $@-t; \
fi
check-unrevised:
@grep -Hn @UNREVISED $(info_TEXINFOS) $(dico_TEXINFOS) > $@-t; \
if [ -s $@-t ]; then \
echo "Unrevised nodes:"; \
cat $@-t; \
rm $@-t; \
false;\
else \
rm $@-t; \
fi
all-check-docs: check-format check-refs check-fixmes check-unrevised
check-docs:
$(MAKE) -k all-check-docs
......
......@@ -16,49 +16,41 @@
@end menu
@node POP3
@comment node-name, next, previous, up
@section POP3
@cindex POP3
@include pop3.texi
@node IMAP4
@comment node-name, next, previous, up
@section IMAP4
@cindex IMAP4
@include imap4.texi
@node Mbox
@comment node-name, next, previous, up
@section Mbox
@cindex Mbox
@include mbox.texi
@node Mh
@comment node-name, next, previous, up
@section Mh
@cindex Mh
@include mh.texi
@node Maildir
@comment node-name, next, previous, up
@section Maildir
@cindex Maildir
@include maildir.texi
@node SMTP
@comment node-name, next, previous, up
@section SMTP
@cindex SMTP
@include smtp.texi
@node Sendmail
@comment node-name, next, previous, up
@section Sendmail
@cindex Sendmail
@include sendmail.texi
@node Parse822
@comment node-name, next, previous, up
@section Parse822
@cindex Parse822
@include parse822.texi
......
@setfilename fdl.info
@node GNU FDL
@appendix GNU Free Documentation License
@cindex FDL, GNU Free Documentation License
@center Version 1.2, November 2002
......
......@@ -34,7 +34,7 @@
</p>
<hr />
The manual for %%PACKAGE%% is available in the following formats:</p>
<p>The manual for %%PACKAGE%% is available in the following formats:</p>
<ul>
<li><a href="%%PACKAGE%%.html">HTML
......@@ -44,10 +44,10 @@ The manual for %%PACKAGE%% is available in the following formats:</p>
<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
<li><a href="%%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
<li><a href="%%PACKAGE%%.info.tar.gz">Info document
(%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li>
<li><a href="%%PACKAGE%%.txt">ASCII text
(%%ASCII_SIZE%%K characters)</a>.</li>
......@@ -77,7 +77,9 @@ href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.)
<p>
Return to the <a href="/home.html">GNU Project home page</a>.
</p>
<p>
Return to <a href="/software/%%PACKAGE%%">GNU %%PACKAGE%% home page</a>.
</p>
<p>
Please send FSF &amp; GNU inquiries to
<a href="mailto:gnu@gnu.org"><em>gnu@gnu.org</em></a>.
......@@ -89,8 +91,8 @@ Please send broken links and other corrections (or suggestions) to
</p>
<p>
Copyright (C) 2004 Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA 02111, USA
Copyright (C) 2005 Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02111, USA
<br />
Verbatim copying and distribution of this entire article is
permitted in any medium, provided this notice is preserved.
......
......@@ -216,7 +216,7 @@ credentials for accessing the database are taken from global variables
and @code{sql_db}. The SQL queries for retrieving user information
from global variables @code{sql_getpwnam_query} and
@code{sql_getpwuid_query}. The variable @code{sql_getpass_query} keeps
the query used for retrieving user's password. @xref{auth}, for
the query used for retrieving user's password. @FIXME-xref{auth}, for
information on command line options used to set these variables.
@end defvar
......
......@@ -484,7 +484,7 @@ follows:
int
_sieve_default_parse_error (void *unused,
const char *filename, int lineno,
const char *fmt, va_list ap)
const char *fmt, va_list ap)
@{
if (filename)
fprintf (stderr, "%s:%d: ", filename, lineno);
......
@macro xopindex{option,text}
@opindex \option\, --\option\ @r{option, \text\}
@end macro
......@@ -6,14 +6,9 @@
@finalout
@c %**end of header
@c This file has the new style title page commands.
@c Run `makeinfo' rather than `texinfo-format-buffer'.
@c smallbook
@c tex
@c \overfullrule=0pt
@c end tex
@include version.texi
@include macros.texi
@include rendition.texi
@c Combine indices.
@defcodeindex op
......@@ -23,7 +18,7 @@
@ifinfo
@dircategory Email
@direntry
* Mailutils: (mailutils). Utilities & library for mailboxes, protocols.
* Mailutils: (mailutils). GNU Mail Utilities.
@end direntry
@dircategory Individual utilities
@direntry
......@@ -45,7 +40,7 @@ Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2008
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
......@@ -63,7 +58,7 @@ Software Foundation raise funds for GNU development.''
@titlepage
@title GNU Mailutils
@subtitle version @value{VERSION}, @value{UPDATED}
@author Alain Magloire et al.
@author Alain Magloire, Sergey Pozbyakoff et al.
@page
@vskip 0pt plus 1filll
@insertcopying
......@@ -74,14 +69,13 @@ Software Foundation raise funds for GNU development.''
@page
@contents
@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
@ifnottex
@node Top
@top GNU Mailutils
@ifinfo
@chapter GNU Mailutils
This edition of the @cite{GNU Mailutils Manual}, last updated @value{UPDATED},
documents GNU Mailutils Version @value{VERSION}.
@end ifinfo
This edition of the @cite{GNU Mailutils Manual}, last updated on
@value{UPDATED}, documents GNU Mailutils Version @value{VERSION}.
@end ifnottex
@menu
* Introduction:: Preliminary Information.
......@@ -89,12 +83,13 @@ documents GNU Mailutils Version @value{VERSION}.
* Libraries:: Mailutils Libraries.
* Sieve Language:: The Sieve Language.
* Reporting Bugs:: How to Report a Bug.
* News:: Getting News About @sc{gnu} Mailutils.
* News:: Getting News About GNU Mailutils.
* Acknowledgement:: Thanks and Credits.
Appendices
* References:: References.
* Usage Vars:: Configuring Help Summary
* GNU FDL:: This manual is under the GNU Free
Documentation License.
......@@ -136,18 +131,6 @@ Mailutils Programs
* mailutils-config:: Get the Information about the Mailutils Build.
Mailutils Configuration File
* common:: Options understood by most @sc{gnu} utilities.
* mailbox:: Specifies the mail spool location, and locking strategy.
* mailer:: Sets the mailer URL.
* address:: Specifies the default email address and domain.
* daemon:: Options common for daemon programs.
* auth:: Authentication-specific options.
* encryption:: Encryption options.
* logging:: Logging control options.
* sieve: sieve group. Sieve specific options
* config sample:: A sample configuration file.
@command{mail} --- Send and Receive Mail
......@@ -360,24 +343,60 @@ Preprocessor
@end detailmenu
@end menu
@node Introduction, Programs, Top, Top
@comment node-name, next, previous, up
@node Introduction
@chapter Introduction
@sc{gnu} Mailutils contains a series of useful mail clients, servers,
GNU Mailutils contains a series of useful mail clients, servers,
and libraries. These are the primary mail utilities of the GNU system.
Specifically, this package contains a POP3 server, an IMAP4 server,
and a Sieve mail filter. It also provides a POSIX `mailx' client,
and a collection of other tools. The central library is capable of
accessing different mailbox formats and mailers as well as off of
local or remote POP3 and IMAP4 servers.
and a collection of other tools. All utilities can manipulate the
mailboxes of various formats, both local, stored on the hard disk,
and remote, accessed via network protocols, such as POP3 or IMAP4.
The GNU Mailutils libraries supply a rich set of primitives for
handling electronic mail in programs written in C, C++ or Scheme.
This software is part of the GNU Project and belongs to the Free
Software Foundation. All libraries are licensed using the GNU LGPL.
The documentation is licensed under the GNU FDL, and everything
else is licensed using the GNU GPL.
@subheading Why use this package?
@menu
* Book Contents:: What this Book Contains
* History:: A bit of History
@end menu
@node Book Contents
@section What this Book Contains
@UNREVISED
@FIXME{This is more a plan on how the document should be structured,
than a description of its actual structure. However it is:}
This book addresses a wide audience of both system administrators
and users that aim to use Mailutils programs, and programmers who wish
to use Mailutils libraries in their programs. Given this audience,
the book is divided in three major parts.
The first part provides a detailed description of each Mailutils
utility, and advices on how to use them in various situations. This
part is intended for users and system administrators who are using
Mailutils programs. If you are not interested in programming using
Mailutils, this is the only part you need to read.
Subsequent parts address programmers.
The second part is a tutorial which provides an introduction to
programming techniques for writing mail applications using GNU
Mailutils.
Finally, the third part contains a complete Mailutils library
reference.
@node History
@section A bit of History, and why use this package?
@UNREVISED
This package started off to try and handle large mailbox files more
gracefully then current POP3 servers did. While it handles this task,
......@@ -386,14 +405,12 @@ without any real effort on your part. Also, if a new format is added
at a later date, your program will support that new format
automatically as soon as it is compiled against the new library.
@node Programs, Libraries, Introduction, Top
@comment node-name, next, previous, up
@node Programs
@chapter Mailutils Programs
@cindex Programs
@include programs.texi
@node Libraries, Sieve Language, Programs, Top
@comment node-name, next, previous, up
@node Libraries
@chapter Mailutils Libraries
@cindex Libraries
......@@ -404,46 +421,38 @@ automatically as soon as it is compiled against the new library.
* libsieve:: GNU Implementation of Sieve Mail Filtering.
@end menu
@node libmailbox, libmuauth, Libraries, Libraries
@comment node-name, next, previous, up
@node libmailbox
@section Framework
@cindex Framework
@include framework.texi
@node libmuauth, libmu_scm, libmailbox, Libraries
@comment node-name, next, previous, up
@node libmuauth
@section Authentication Library
@cindex Authentication Library
@cindex libmuauth
@include libmuauth.texi
@node libmu_scm, libsieve, libmuauth, Libraries
@comment node-name, next, previous, up
@node libmu_scm
@section Mailutils to Scheme Interface
@cindex Scheme
@cindex libmu_scm
@include libmu_scm.texi
@node libsieve, , libmu_scm, Libraries
@comment node-name, next, previous, up
@node libsieve
@section Sieve Library
@cindex Sieve Library
@cindex libsieve
@include libsieve.texi
@node Sieve Language, Reporting Bugs, Libraries, Top
@comment node-name, next, previous, up
@node Sieve Language
@chapter Sieve Language
@cindex Sieve Language
@include sieve.texi
@node Reporting Bugs, News, Sieve Language, Top
@comment node-name, next, previous, up
@node Reporting Bugs
@chapter Reporting Bugs
Email bug reports to @email{bug-mailutils@@gnu.org}.
Be sure to include the word ``mailutils'' somewhere
in the ``Subject:'' field.
As the purpose of bug reporting is to improve software, please be sure
to include maximum information when reporting a bug. The information
......@@ -458,19 +467,17 @@ needed is:
The archives of bug-mailutils mailing list are available from
@url{http://mail.gnu.org/@/mailman/@/listinfo/@/bug-mailutils}.
@node News, Acknowledgement, Reporting Bugs, Top
@comment node-name, next, previous, up
@chapter Getting News About @sc{gnu} Mailutils
@node News
@chapter Getting News About GNU Mailutils
The two places to look for any news regarding @sc{gnu} Mailutils are the
The two places to look for any news regarding GNU Mailutils are the
Mailutils homepage at @url{http://www.gnu.org/@/software/@/mailutils}, and the
project page at @url{http://savannah.gnu.org/@/projects/@/mailutils}.
The updated versions of this manual are available online from
@url{http://www.gnu.org/@/software/@/mailutils/@/manual}.
@node Acknowledgement, References, News, Top
@comment node-name, next, previous, up
@node Acknowledgement
@chapter Acknowledgement
In no particular order,
......@@ -500,8 +507,7 @@ Jordi Mallach @email{jordi@@sindominio.net}
Wojciech Polak @email{polak@@gnu.org}
@end itemize
@node References, GNU FDL, Acknowledgement, Top
@comment node-name, next, previous, up
@node References
@appendix References
@itemize @bullet
......@@ -619,12 +625,11 @@ Notifications}
@end itemize
@end itemize
@node GNU FDL, Function Index, References, Top
@comment node-name, next, previous, up
@include usage.texi
@include fdl.texi
@node Function Index, Variable Index, GNU FDL, Top
@comment node-name, next, previous, up
@node Function Index
@unnumbered Function Index
This is an alphabetical list of all Mailutils functions.
......@@ -632,25 +637,23 @@ This is an alphabetical list of all Mailutils functions.
@printindex fn
@page
@node Variable Index, Keyword Index, Function Index, Top
@node Variable Index
@unnumbered Variable Index
@printindex vr
@page
@node Keyword Index, Program Index, Variable Index, Top
@node Keyword Index
@unnumbered Keyword Index
@printindex ky
@page
@node Program Index, Concept Index, Keyword Index, Top
@comment node-name, next, previous, up
@node Program Index
@unnumbered Program Index
@printindex pg
@page
@node Concept Index, , Program Index, Top
@comment node-name, next, previous, up
@node Concept Index
@unnumbered Concept Index
This is a general index of all issues discussed in this manual
......
......@@ -324,7 +324,7 @@ aliases, like @option{--cc}, @option{--from}, etc.)
The argument to this option is a string of type specifications:
@multitable @columnfractions 0.20 0.80
@item B @tab Use basic regular expressions
@item B @tab Use basic regular expressions
@item E @tab Use extended regular expressions
@item I @tab Ignore case
@item C @tab Case sensitive
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002,2003,2004,2005,2006,2007
@c Copyright (C) 1999,2000,2001,2002,2003,2004,2005,2006,2007,2008
@c Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@sc{gnu} Mailutils provides a set of programs for handling the e-mail.
GNU Mailutils provides a broad set of utilities for handling
electronic mail. These utilities address the needs of both system
adminsitrators and users.
All utilities are built around a single core subsistem and share many
common aspects. All of them are able to work with almost any existing
mailbox formats. They use a common configuration file syntax, and
their configuration files are located in a single subdirectory.
In this chapter we will discuss each utility, and give some advices on
how to use them in various real life situations.
First of all we will describe command line and configuration file
syntax.
@menu
* command line:: Command Line Syntax.
* configuration:: Common Configuration File.
* authentication:: Authorization and Authentication Principles.
......@@ -33,351 +47,537 @@
* mailutils-config:: Get the Information about the Mailutils Build.
@end menu
@node configuration
@section Mailutils Configuration File
@cindex Mailutils configuration file
@cindex mailutils.rc
@node command line
@section Command Line
@UNREVISED
There are some command line options that are used so often that it is
inconvenient to specify them in the command line each time you run
a Mailutils utility. The @dfn{configuration files} provide a way to
add default command line arguments without having to type them in
the command line. Upon startup, each Mailutils utility scans and
processes the contents of the three startup files, none of which
are required to exist:
@menu
* Option Basics:: Basic Notions About Command Line Options.
* Common Options:: Options That are Common for All Utilities.
@end menu
@enumerate
@item the site-wide configuration file
@node Option Basics
@subsection Basic Notions About Command Line Options
Many command line options have two forms, called short and long
forms. Both forms are absolutely identical in function; they are
interchangeable.
The @dfn{short} form is a traditional form for UNIX utilities.
In this form, the option consists of a single dash, followed by a
single letter, e.g. @option{-c}.
Short options which require arguments take their arguments
immediately following the option letter, optionally separated by white
space. For example, you might write @option{-f name}, or @option{-fname}.
Here, @option{-f} is the option, and @option{name} is its argument.
Short options which allow optional arguments take their arguments
immediately following the option letter, @emph{without any intervening
white space characters}. This is important, so that the command line
parser might discern that the text following option is its argument,
not the next command line parameter. For example, if option @option{-d}
took an optional argument, then @option{-dname} would mean the option
with its argument (@option{name} in this case), and @option{-d name} would
mean the @option{-d} option without any argument, followed by command
line argument @option{name}.
Short options' letters may be clumped together, but you are not
required to do this. When short options are clumped as a set, use one
(single) dash for them all, e.g. @option{-cvl} is equivalent to @option{-c
-v -l}. However, only options that do not take arguments may be
clustered this way. If an option takes an argument, it can only be
the last option in such a cluster, otherwise it would be impossible to
specify the argument for it. Anyway, it is much more readable to
specify such options separated.
The @dfn{long} option names are probably easier to memorize than
their short counterparts. They consist of two dashes, followed by a
multi-letter option name, which is usually selected to be a mnemonics
for the operation it requests. For example, @option{--verbose} is a
long option that increases the verbosity of a utility. In addition,
long option names can abbreviated, provided that such an abbreviation
is unique among the options understood by a given utility. For
example, if a utility takes options @option{--foreground} and
@option{--forward}, then the shortest possible abbreviations for these
options are @option{--fore} and @option{--forw}, correspondingly. If
you try to use @option{--for}, the utility will abort and inform you
that the abbreviation you use is ambiguous, so it is not clear which
of the options you intended to use.
Long options which require arguments take those arguments following
the option name. There are two ways of specifying a mandatory
argument. It can be separated from the option name either by an equal
sign, or by any amount of white space characters. For example, if the
@option{--file} option requires an argument, and you wish to supply
@file{name} as its argument, then you can do so using any of the
following notations: @option{--file=name} or @option{--file name}.
In contrast, optional arguments must always be introduced using an
equal sign.
@file{mailutils.rc}, found in your your system configuration directory
(usually @file{/etc} or @file{/usr/local/etc}).
@node Common Options
@subsection Options That are Common for All Utilities.
@item the user-specific configuration file
All GNU Mailutils programs understand a common subset of options.
Usually @file{~/.mailutils}, unless @file{~/.mailutils} is a directory,
in which case @file{~/.mailutils/mailutils} is used.
@table @option
@xopindex{help, described}
@item --help
@itemx -?
Display a short summary of the command line options understood by
this utilities, along with a terse description of each.
@item the programs-specific configuration file
The output of this option consists of three major parts. First, a
usage synopsis is displayed. For example:
Usually @file{~/.mu.@var{program}rc}, unless @file{~/.mailutils} is a
directory, in which case @file{~/.mailutils/@var{program}rc} is used
(where @var{program} means the program name).
@end enumerate
@smallexample
@group
Usage: sieve [OPTION...] SCRIPT
GNU sieve -- a mail filtering tool
@end group
@end smallexample
These files have simple line-oriented syntax. Comments begin with the
pound sign (@samp{#}) and extend through the end of the line
@footnote{If @samp{#} is not the first character on the line, it
should be separated from the previous word by any amount of whitespace.}.
Very long lines may be split across several lines by escaping final newline
with a backslash (@samp{\}) character.
In the non-program-specific configuration files, any configuration line
must start with a @dfn{tag}. In the program-specific configuration
file the tag must not be present, all options are for that specific
program.
A tag is either a name of a particular Mailutils utility or @dfn{option
group}, prefixed with colon (@samp{:}). The command line options common for
several Mailutils programs are divided into @dfn{option groups} or
@dfn{capabilities}, e.g. the options @option{--mail-spool} and
@option{--lock-flags} form group @samp{mailbox}. These groups are discussed
in detail below.
When processing the non-program-specific configuration files,
a Mailutils utility selects those lines whose tag is either the name
of that utility or the name of the option group supported by it.
In the program-specific configuration file, all lines are selected.
For each line found, its tag (if present) is stripped away, and the
rest of the line is split up into words. These words are regarded as
command line options and are inserted to the program arguments
@emph{before} any options from the command line. Thus the options
from @file{.mailutils} take precedence over those from @file{mailutils.rc},
and the options from the command line take precedence over those from
all three configuration files.
The word splitting occurs at whitespace characters and is similar to
that performed by the shell. If an option must contain embedded
whitespace, it should be enclosed in a pair of quotes (either double
or single quotes).
The first line tells that the @command{sieve} utility takes any
number of options (brackets indicate optional part) and a single
mandatory argument (@samp{SCRIPT}). The second lines summarizes the
purpose of the utility.
@menu
* common:: Options understood by most @sc{gnu} utilities.
* mailbox:: Specifies the mail spool location, and locking strategy.
* mailer:: Sets the mailer URL.
* address:: Specifies the default email address and domain.
* daemon:: Options common for daemon programs.
* auth:: Authentication-specific options.
* encryption:: Encryption options.
* logging:: Logging control options.
* sieve: sieve group. Sieve specific options
* config sample:: A sample configuration file.
@end menu
Following this header is an option summary. It consists of two
columns:
@node common
@subsection Common
@verbatim
-c, --compile-only Compile script and exit
-d, --debug[=FLAGS] Debug flags
-e, --email=ADDRESS Override user email address
@end verbatim
Each program understands the following informational options:
@table @option
@item -u
@itemx --usage
Display a short usage message and exit.
@item -h
@itemx --help
Display help message and exit.
@item -L
@itemx --license
Display @sc{gnu} General Public License and exit.
@item -v
@itemx --version
Display program version and exit.
@end table
The leftmost column contains a comma-separated list of option
names. Short options are listed first. The options are ordered
alphabetically. Arguments, if any, are specified after the last
option name in the list, so that, e.g. the option @samp{-e} in the
example above requires an argument: @samp{-e ADDRESS}. Optional
arguments are enclosed in square brackets, as in @option{--debug}
option in the example above.
@node mailbox
@subsection Mailbox
@cindex :mailbox
The rightmost column contains a short description of the option
purpose.
Option group @samp{mailbox} consists of options used to specify the
location of the mail spool, and the locking strategy.
The last part of @option{--help} output contains some additional
notices and lists the email address for reporting bugs.
@table @option
@item -m @var{path}
@itemx --mail-spool=@var{path}
Set path to the mailspool directory
@item --lock-flags=@var{flags}
Set the default mailbox lock flags (E=external, R=retry, T=time, P=pid).
@end table
@xopindex{usage, described}
@item --usage
Display a short summary of options. In the contrast to the
@option{--help} option, only option names and arguments
are printed, without any textual description. For example:
@node mailer
@subsection Mailer
@cindex :mailer
@smallexample
@group
Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]]
[--email=ADDRESS] SCRIPT
@end group
@end smallexample
@end table
This option group overrides the default mailer URL (@url{sendmail:}).
The exact formatting of the output produced by these two options is
configurable. @xref{Usage Vars}, for a detailed descriptions of it.
@table @option
@item -m @var{url}
@itemx --mailer @var{url}
@xopindex{version, described}
@item --version
@itemx -V
Print program version and exit.
@xopindex{show-config-options, described}
@item --show-config-options
Show configuration options used when compiling the package. You can
use this option to verify if support for a particular mailbox format
or other functionality is compiled in the binary. The output of this
option is intended to be both machine-readable and understandable by
humans.
@end table
@node address
@subsection Address
@cindex :address
The following command line options affect parsing of configuration
files. Here we provide a short summary, the next section will
describe them in detail.
Option group @samp{address} consists of options used to specify how to
qualify email addresses.
@table @option
@xopindex{config-file, introduced}
@item --config-file=@var{file}
Load this configuration file, instead of the default.
An unqualified address (one without an @var{@@}) is qualified by appending
@var{@@}@var{defaultdomain}. @var{defaultdomain} is the return of
@code{gethostname()}, or the result of @code{gethostbyname()} on the return
of @code{gethostname()} (if the DNS lookup is successful).
@xopindex{config-help, introduced}
@item --config-help
Show configuration file summary.
If the email address of the current user is needed, either the address set by
@option{--email-addr} is returned, or the current uid is looked up in the user
database, and qualified with the @var{defaultdomain}.
@xopindex{config-lint, introduced}
@item --config-lint
Check configuration file syntax and exit
@table @option
@item -E @var{email}
@itemx --email-addr=@var{email}
Set the current user's email address, this it makes more sense to use
this in one of the per-user configuration files.
@item -D @var{domain}
@itemx --email-domain=@var{domain}
Set the default email domain, this might make sense to use in either
the global or one of the per-user configuration files.
@end table
@xopindex{config-verbose, introduced}
@item --config-verbose
Verbosely log parsing of the configuration files.
@node daemon
@subsection Daemon
@cindex :daemon
@xopindex{no-site-config, introduced}
@item --no-site-config
Do not load site-wide configuration file.
@table @option
@item -d[@var{number}]
@itemx --daemon[=@var{number}]
Run in standalone mode. An optional @var{number} specifies the maximum number
of child processes the daemon is allowed to fork. When it is omitted,
it defaults to 20 processes.
@emph{Please note}, that there should be no whitespace between the
@option{-d} and its parameter.
@item -i
@itemx --inetd
Run in inetd mode.
@item -p @var{number}
@itemx --port @var{number}
Listen on given port @var{number}. This option is meaningful only in
standalone mode. It defaults to port 143.
@item -t @var{number}
@itemx --timeout @var{number}
Set idle timeout to given @var{number} of seconds. The daemon breaks the
connection if it receives no commands from the client within that number
of seconds.
@xopindex{no-user-config, introduced}
@item --no-user-config
Do not load user configuration file.
@end table
@node auth
@subsection Auth
@cindex :auth
@node configuration
@section Mailutils Configuration File
@cindex Mailutils configuration file
@cindex mailutils.rc
@UNREVISED
These options control the authorization and authentication module
lists. For a description of authentication concepts, refer to
@xref{authentication}.
Configuration files are the principal means of configuring any GNU
Mailutil component. When started, each utility tries to load its
configuration from the following locations, in that order:
@table @option
@item --authorization @var{modlist}
@enumerate 1
@item Main site-wide configuration file.
This option allows to set up a list of modules to be used for
authorization. @var{modlist} is a colon-separated list of
modules. Valid modules are:
It is named @file{@var{sysconfdir}/mailutils.rc}, where @var{sysconfdir} stands
for the system configuration directory set when compiling the package.
Usually @var{sysconfdir} is @file{/etc} (or @file{/usr/local/etc}).
@table @asis
@item system
User credentials are retrieved from the system user database
(@file{/etc/password}).
@item sql
User credentials are retrieved from the @acronym{sql} database. The set
of @option{--sql-} options (see below) is used to configure
access to the database.
@item virtdomain
User credentials are retrieved from a ``virtual domain'' user
database.
@end table
@xopindex{no-site-config, described}
This configuration file is not read if the @option{--no-site-config}
command line option was given.
@item Per-user configuration file.
A per user configuration file is located in the user home directory
and is named @samp{.@var{prog}}, where @var{prog} is the name of the
utility. For example, the per-user configuration file for
@command{sieve} utility is named @file{.sieve}.
@xopindex{no-user-config, described}
This configuration file is not read if the @option{--no-user-config}
command line option was given.
@xopindex{config-file, described}
@item Additional configuration file, if specified using the
@option{--config-file} command line option.
@end enumerate
@item --authentication @var{modlist}
The order in which configuration files are loaded defines the
precedence of their settings. Thus, the settings from additional
configuration file override those set in per-user configuration file.
The latter, in their turn, take precedence over the settings from the
site-wide configuration file.
This option allows to set up a list of modules to be used for
authentication. @var{modlist} is a colon-separated list of
modules. Valid modules are:
@xopindex{config-verbose, described}
Neither site-wide nor user configuration files are required to
exist. If any or both of them are absent, GNU Mailutils does not
complain, and the utility falls back to its default settings. To make
configuration processing more verbose, use the
@option{--config-verbose} command line option. Here is an example of
what you might get using this option:
@smallexample
imap4d: Info: parsing file `/etc/mailutils.rc'
imap4d: Info: finished parsing file `/etc/mailutils.rc'
@end smallexample
Specifying this option more than once adds more verbosity to this
output. If this option is given two times, GNU Mailutils will print
any configuration file statement it parsed, along with the exact
location where it occurred (the exact meaning of each statement will
be described later in this chapter):
@smallexample
imap4d: Info: parsing file `/etc/mailutils.rc'
# 1 "/etc/mailutils.rc"
mailbox @{
# 2 "/etc/mailutils.rc"
mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=$@{user@};
# 3 "/etc/mailutils.rc"
mailbox-type maildir;
@};
# 6 "/etc/mailutils.rc"
include /etc/mailutils.d;
imap4d: Info: parsing file `/etc/mailutils.d/imap4d'
...
@end smallexample
@xopindex{config-lint, described}
To test configuration file without actually starting the utility,
use the @option{--config-lint} command line option. With this option,
any Mailutils utility exits after finishing parsing of the
configuration files. Any errors occurred during parsing are displayed
on the standard error output. This option can be combined with
@option{--config-verbose} to obtain more detailed output.
@xopindex{config-help, described}
The @option{--config-help} command line option produces on the
standard output the summary of all configuration statements understood
by the utility, with detailed comments and in the form suitable for
configuration file. For example, the simplest way to write a
configuration file for, say, @command{imap4d} is to run
@smallexample
$ imap4d --config-help > imap4d.rc
@end smallexample
@noindent
and to edit the @file{imap4d.rc} file with your editor of choice.
@menu
* conf-syntax:: Configuration File Syntax
@end menu
@node conf-syntax
@subsection Configuration File Syntax
@UNREVISED
Configuration files consist of a series of statements. 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 keywords and values.
@menu
* Comments::
* Statements::
* Includes::
* Block Statements::
@end menu
@node Comments
@subsubsection Comments
@cindex comments, configuration file
@cindex comments, single-line
@cindex single-line comments
@dfn{Comments} may appear anywhere where white space may appear in the
configuration file. There are two kinds of comments:
single-line and multi-line comments. @dfn{Single-line} comments start
with @samp{#} or @samp{//} and continue to the end of the line:
@smallexample
# This is a comment
// This too is a comment
@end smallexample
@cindex comments, multi-line
@cindex multi-line comments
@dfn{Multi-line} or @dfn{C-style} comments start with the two
characters @samp{/*} (slash, star) and continue until the first
occurrence of @samp{*/} (star, slash).
Multi-line comments cannot be nested.
@node Statements
@subsubsection Statements
@cindex statements, configuration file
@cindex configuration file statements
@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
with a semicolon (@samp{;}), unless it contains a @dfn{here-document}
(see below), in which case semicolon is optional.
Examples of simple statements:
@smallexample
pidfile /var/run/imap4d.pid;
transcript yes;
@end smallexample
A @dfn{keyword} begins with a letter and may contain letters,
decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
Examples of keywords are: @samp{group}, @samp{identity-check}.
A @dfn{value} can be one of the following:
@table @asis
@item generic
The generic authentication type. User password is hashed and compared
against the hash value returned in authorization stage.
@item system
The hashed value of the user password is retrieved from
@file{/etc/shadow} file on systems that support it.
@item sql
The hashed value of the user password is retrieved from the @acronym{sql}
database using query supplied by @option{--sql-getpass} option
(see below).
@item pam
The user is authenticated via pluggable authentication module
(@acronym{pam}). The @acronym{pam} service name to be used is
configured via @option{--pam-service} option (see below).
@end table
@item number
A number is a sequence of decimal digits.
@item boolean
@cindex boolean value
A boolean value is one of the following: @samp{yes}, @samp{true},
@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
@item unquoted string
@cindex string, unquoted
An unquoted string may contain letters, digits, and any of the
following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
@samp{:}.
@item quoted string
@cindex quoted string
@cindex string, quoted
@cindex escape sequence
A quoted string is any sequence of characters enclosed in
double-quotes (@samp{"}). A backslash appearing within a quoted
string introduces an @dfn{escape sequence}, which is replaced
with a single character according to the following rules:
@float Table, backslash-interpretation
@caption{Backslash escapes}
@multitable @columnfractions 0.30 .5
@item Sequence @tab Replaced with
@item \a @tab Audible bell character (@acronym{ASCII} 7)
@item \b @tab Backspace character (@acronym{ASCII} 8)
@item \f @tab Form-feed character (@acronym{ASCII} 12)
@item \n @tab Newline character (@acronym{ASCII} 10)
@item \r @tab Carriage return character (@acronym{ASCII} 13)
@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
@item \\ @tab A single backslash (@samp{\})
@item \" @tab A double-quote.
@end multitable
@end float
@item --pam-service @var{name}
When compiled with @acronym{pam} support, this option specifies the
name of @acronym{pam} service to be used when authenticating.
@end table
In addition, the sequence @samp{\@var{newline}} is removed from
the string. This allows to split long strings over several
physical lines, e.g.:
The following options exist in this group if the package was configured
with @option{--enable-sql} option. They take effect only if the
@samp{sql} module is used in authentication and/or authorization.
@smallexample
@group
"a long string may be\
split over several lines"
@end group
@end smallexample
@table @option
@item --sql-interface @var{iface}
Specify @sc{sql} interface to use. @var{Iface} is either @samp{mysql}
or @samp{postgres}. This allows to select @sc{sql} subsystem on
runtime if @code{mailutils} was compiled with support for several
@sc{sql} drivers.
If the character following a backslash is not one of those specified
above, the backslash is ignored and a warning is issued.
If this option is omitted, @code{mailutils} will use the first
available @sc{sql} driver.
Two or more adjacent quoted strings are concatenated, which gives
another way to split long strings over several lines to improve
readability. The following fragment produces the same result as the
example above:
@item --sql-host @var{name}
Name or IP of MySQL server to connect to.
@smallexample
@group
"a long string may be"
" split over several lines"
@end group
@end smallexample
@item --sql-user @var{name}
@acronym{sql} user name
@anchor{here-document}
@item Here-document
@cindex here-document
@dfn{Here-document} is a special construct that allows to introduce
strings of text containing embedded newlines.
@item --sql-passwd @var{string}
@acronym{sql} connection password
The @code{<<@var{word}} construct instructs the parser to read all
the lines that follow 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:
@item --sql-db @var{string}
Name of the database to connect to.
@smallexample
@group
<<EOT
A multiline
string
EOT
@end group
@end smallexample
@item --sql-port @var{number}
Port to use
Body of a here-document is interpreted the same way as
double-quoted string, unless @var{word} is preceded by a backslash
(e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case
the text is read as is, without interpretation of escape sequences.
@item --sql-getpwnam @var{query}
@acronym{sql} query to retrieve a passwd entry based on username
If @var{word} is prefixed with @code{-} (a dash), then all leading
tab characters are stripped from input lines and the line containing
@var{word}. Furthermore, if @code{-} is followed by a single space,
all leading whitespace is stripped from them. This allows to indent
here-documents in a natural fashion. For example:
@item --sql-getpwuid @var{query}
@acronym{sql} query to retrieve a passwd entry based on user ID
@item --sql-getpass @var{query}
@acronym{sql} query to retrieve a password from the database
@end table
@smallexample
@group
<<- TEXT
All leading whitespace will be
ignored when reading these lines.
TEXT
@end group
@end smallexample
@node encryption
@subsection Encryption
@cindex :encryption
It is important that the terminating delimiter be the only token on
its line. The only exception to this rule is allowed if a
here-document appears as the last element of a statement. In this
case a semicolon can be placed on the same line with its terminating
delimiter, as in:
These options control TLS/SSL encryption in @command{imap4d}
and @command{pop3d} daemons.
@smallexample
help-text <<-EOT
A sample help text.
EOT;
@end smallexample
@table @option
@item --ssl-cert @var{file}
This option specifies the file name of the server side SSL certificate
(accepts PEM format).
@item --ssl-key @var{file}
This option specifies the file name of the server side private SSL key
(accepts PEM format). The key must be protected with 0600 file permissions
(u=rw,g=,o=), otherwise @command{imap4d} or @command{pop3d} daemons will
refuse to support TLS/SSL encryption.
@item --ssl-cafile @var{file}
This option specifies a file containing the list of trusted CAs (PEM list)
in order to verify client's certificates. This option is not required.
@end table
However, terminated semicolon after a here-document is optional.
@node logging
@subsection Logging
@cindex :logging
@item list
@cindex list
A @dfn{list} is a comma-separated list of values. Lists are
enclosed in parentheses. The following example shows a statement
whose value is a list of strings:
@table @option
@item --log-facility @var{facility}
Output logs to the specified @command{syslog} facility. The following
facility names are recognized: @samp{user}, @samp{daemon}, @samp{mail},
@samp{auth} and @samp{local0} through @samp{local7}. These names are
case-insensitive.
@smallexample
shared-namespace ("/home", "/var/spool/common");
@end smallexample
In any case where a list is appropriate, a single value is allowed
without being a member of a list: it is equivalent to a list with a
single member. This means that, e.g. @samp{shared-namespace /home;} is
equivalent to @samp{shared-namespace (/home);}.
@end table
@node sieve group
@subsection Sieve Specific Options
@cindex :sieve
@node Includes
@subsubsection Include Statement
@cindex include statement, configuration file
An @dfn{include statement} is a special statement that causes
inclusion of a named file. This statement has the following syntax:
The following options comprise this group:
@smallexample
include @var{file};
@end smallexample
@table @option
@item -I @var{dir}
@itemx --includedir=@var{dir}
Append directory @var{dir} to the list of directories searched for
include files.
@item -L @var{dir}
@itemx --libdir=@var{dir}
Append directory @var{dir} to the list of directories searched for
library files.
@end table
If @var{file} names a regular file, the contents of this file is
included in this point. Otherwise, if @var{file} names a directory,
Mailutils searches in that directory for a file whose name coincides
with the name of utility being executed, and includes this file, if it
exists.
@node config sample
@subsection A Sample Configuration File
@cindex mailutils.rc, an example
It is a common approach to end the site-wide configuration file with
an include statement, e.g.:
The following configuration file specifies that all Mailutils programs
should use @file{/var/spool/mail} as a local mailspool
directory. Programs performing authentication will use @acronym{pam}
service @samp{mailutils}. All programs, except @command{imap4d} will
issue log messages via @samp{mail} facility, @command{imap4d} will use
facility @samp{local1}.
@smallexample
include /etc/mailutils.d;
@end smallexample
This allows each particular utility to have its own configuration
file. Thus. @command{imap4d} will read
@file{/etc/mailutils.d/imap4d}, etc.
@node Block Statements
@subsubsection Block Statements
@cindex block statement, configuration file
A @dfn{block statement} introduces a logical group of another
statements. It consists of a keyword, followed by an optional value,
and a sequence of statements enclosed in curly braces, as shown in
example below:
@smallexample
@group
:mailbox --mail-spool /var/spool/mail
:auth --authentication pam --pam-service mailutils
:logging --log-facility mail
imap4d --daemon=20 --timeout=1800 --log-facility local1
tcp-wrappers @{
enable yes;
allow-syslog-priority info;
deny-syslog-priority notice;
@}
@end group
@end smallexample
@end smallexample
The closing curly brace may be followed by a semicolon, although
this is not required.
@node authentication
@section Authorization and Authentication Principles
@cindex authorization
......@@ -437,7 +637,7 @@ User credentials are retrieved from the system user database
(@file{/etc/password}).
@item sql
User credentials are retrieved from the @acronym{sql} database. The set
of @option{--sql-} options (@pxref{auth}) is used to configure
of @option{--sql-} options (@FIXME-pxref{auth}) is used to configure
access to the database.
@item virtdomain
User credentials are retrieved from a ``virtual domain'' user
......@@ -456,11 +656,11 @@ The hashed value of the user password is retrieved from
@item sql
The hashed value of the user password is retrieved from the @acronym{sql}
database using query supplied by @option{--sql-getpass} option
(@pxref{auth}).
(@FIXME-pxref{auth}).
@item pam
The user is authenticated via pluggable authentication module
(@acronym{pam}). The @acronym{pam} service name to be used is
configured via @option{--pam-service} option (@pxref{auth})
configured via @option{--pam-service} option (@FIXME-pxref{auth})
@end table
Unless overridden by @option{--authentication} command line option,
......@@ -495,7 +695,7 @@ user's system mailbox and outputs the contents of @code{From} and
the command line, the program reads that folder rather than the default
mailbox.
The program uses following option groups: @xref{mailbox}.
The program uses following option groups: @FIXME-xref{mailbox}.
The following command line options alter the behavior of the program:
......@@ -612,7 +812,7 @@ General usage of @command{mail} program is:
If [@var{address}...] part is present, @command{mail} switches to
mail sending mode, otherwise it operates in mail reading mode.
The program uses following option groups: @xref{mailbox}.
The program uses following option groups: @FIXME-xref{mailbox}.
@command{Mail} understands following command line options:
......@@ -2345,7 +2545,7 @@ Number of messages in @var{folder}: @var{number}
where @var{folder} represents the folder name, @var{number} represents
the number of messages.
The program uses following option groups: @xref{mailbox}.
The program uses following option groups: @FIXME-xref{mailbox}.
The program accepts following command line options:
......@@ -2743,7 +2943,7 @@ sieve program.
By default @command{sieve} output all diagnostics on standard error and verbose
logs on standard output. This behaviour is changed when
@option{--log-facility} is given in the command line (@pxref{logging}).
@option{--log-facility} is given in the command line (@FIXME-pxref{logging}).
This option causes @command{sieve} to output its diagnostics to
the given syslog facility.
......@@ -2863,7 +3063,7 @@ It processes mailboxes, applying the user-supplied scheme procedures
to each of them in turn and saves the resulting output in mailbox
format.
The program uses following option groups: @xref{mailbox}.
The program uses following option groups: @FIXME-xref{mailbox}.
@menu
* Specifying Scheme Program to Execute::
......@@ -3040,8 +3240,8 @@ General usage of @command{mail.local} program is:
If recipient part is present is a FQDN, @command{mail.local}
will attempt to deliver to a virtual host.
The program uses following option groups: @xref{mailbox}, @xref{auth},
@xref{logging}, @xref{sieve}.
The program uses following option groups: @FIXME-xref{mailbox}, @FIXME-xref{auth},
@FIXME-xref{logging}, @FIXME-xref{sieve}.
@table @option
@item -f @var{addr}
......@@ -3307,7 +3507,7 @@ Option @option{--quota-query} allows to specify a special query to
retrieve the quota from the database. Currently (as of mailutils
version @value{VERSION}) it is assumed that this table can be accessed
using the same credentials as @sc{sql} authentication tables
(@xref{daemon}, for the detailed discussion of @option{--sql-} options).
(@FIXME-xref{daemon}, for the detailed discussion of @option{--sql-} options).
For example, suppose you have the following quota table:
......@@ -3547,8 +3747,8 @@ The server runs as daemon, forking a child for each new connection. This
mode is triggered by @option{-d} command line switch.
@end table
The program uses following option groups: @xref{mailbox},
@xref{daemon}, @xref{logging}, @xref{auth}.
The program uses following option groups: @FIXME-xref{mailbox},
@FIXME-xref{daemon}, @FIXME-xref{logging}, @FIXME-xref{auth}.
@menu
* Login delay::
......@@ -3864,8 +4064,8 @@ The ``inetd'' mode allows to start the server from
imap4 stream tcp nowait root /usr/local/sbin/imap4d imap4d
@end smallexample
The program uses following option groups: @xref{mailbox},
@xref{daemon}, @xref{logging}, @xref{auth}.
The program uses following option groups: @FIXME-xref{mailbox},
@FIXME-xref{daemon}, @FIXME-xref{logging}, @FIXME-xref{auth}.
@subheading Command Line Options
......@@ -3932,8 +4132,8 @@ either from @file{inetd.conf} or as a standalone daemon.
@node Starting comsatd
@subsection Starting @command{comsatd}
@command{Comsatd} uses following option groups: @xref{mailbox},
@xref{daemon}, @xref{logging}.
@command{Comsatd} uses following option groups: @FIXME-xref{mailbox},
@FIXME-xref{daemon}, @FIXME-xref{logging}.
@table @option
@item -c @var{file}
......
@c Let's use the concept of 'renditions' by Fra@,{c}ois Pinard
@c I extended it by adding a FIXME_FOOTNOTE variable, which controls
@c whether FIXME information should be placed in footnotes or
@c inlined.
@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 information, even if this information is not fully revised for adequacy,
@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 ======================================================================
@c Set this symbol if you wish FIXMEs to appear in footnotes, instead
@c of being inserted into the text.
@c @set PROOF_FOOTNOTED
@ifclear PUBLISH
@ifclear DISTRIB
@ifclear PROOF
@set DISTRIB
@end ifclear
@end ifclear
@end ifclear
@ifset PUBLISH
@set RENDITION The book, version
@end ifset
@ifset DISTRIB
@set RENDITION FTP release, version
@end ifset
@ifset PROOF
@set RENDITION Proof reading version
@end ifset
@c Output marks for nodes needing revision, but not in PUBLISH rendition.
@macro UNREVISED
@ifclear PUBLISH
@quotation
(@emph{The information in this node may be obsolete or otherwise inaccurate.}
This message will disappear, once this node revised.)
@end quotation
@end ifclear
@end macro
@c Output various FIXME information only in PROOF rendition.
@macro FIXME{string}
@ifset PROOF
@ifset PROOF_FOOTNOTED
@footnote{@strong{FIXME:} \string\}
@end ifset
@ifclear PROOF_FOOTNOTED
@cartouche
@strong{<FIXME>} \string\ @strong{</>}
@end cartouche
@end ifclear
@end ifset
@end macro
@macro FIXME-ref{string}
@ifset PROOF
@strong{<REF>} \string\ @strong{</>}
@end ifset
@end macro
@macro FIXME-pxref{string}
@ifset PROOF
@strong{<PXREF>} \string\ @strong{</>}
@end ifset
@end macro
@macro FIXME-xref{string}
@ifset PROOF
@strong{<XREF>} \string\ @strong{</>}
@end ifset
@end macro
......@@ -392,7 +392,7 @@ If @var{filename} starts with a directory separator character
The @code{#searchpath} directive adds its argument to the list of
directories searched for loadable modules. It has the same effect
as @option{-L} command line switch used by @sc{gnu} sieve utility
(@pxref{sieve group}).
(@FIXME-pxref{sieve group}).
@node Require Statement
@section Require Statement
......
/* GNU Mailutils -- a suite of utilities for electronic mail
Copyright (C) 2007 Free Software Foundation, Inc.
Copyright (C) 2007, 2008 Free Software Foundation, Inc.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
......@@ -25,10 +25,17 @@
extern "C" {
#endif
struct mu_conf_option
{
char *name;
char *descr;
};
extern char *mu_license_text;
extern void mu_print_options (void);
extern void mu_fprint_options (FILE *fp);
extern const char *mu_check_option (char *name);
extern void mu_fprint_conf_option (FILE *fp, const struct mu_conf_option *opt);
extern const struct mu_conf_option *mu_check_option (char *name);
#ifdef __cplusplus
}
......
......@@ -58,16 +58,21 @@ static struct argp_option mu_common_argp_options[] =
N_("Show compilation options"), 0 },
{ "config-help", OPT_HELP_CONFIG, NULL, 0,
N_("Show configuration file summary"), 0 },
{ "no-user-rcfile", OPT_NO_USER_RCFILE, NULL, 0,
{ "no-user-config", OPT_NO_USER_RCFILE, NULL, 0,
N_("Do not load user configuration file"), 0 },
{ "no-site-rcfile", OPT_NO_SITE_RCFILE, NULL, 0,
{ "no-user-rcfile", 0, NULL, OPTION_ALIAS, NULL },
{ "no-site-config", OPT_NO_SITE_RCFILE, NULL, 0,
N_("Do not load site configuration file"), 0 },
{ "rcfile", OPT_RCFILE, N_("FILE"), 0,
{ "no-site-rcfile", 0, NULL, OPTION_ALIAS, NULL },
{ "config-file", OPT_RCFILE, N_("FILE"), 0,
N_("Load this configuration file"), 0, },
{ "rcfile-verbose", OPT_RCFILE_VERBOSE, NULL, 0,
{ "rcfile", 0, NULL, OPTION_ALIAS, NULL },
{ "config-verbose", OPT_RCFILE_VERBOSE, NULL, 0,
N_("Verbosely log parsing of the configuration files"), 0 },
{ "rcfile-lint", OPT_RCFILE_LINT, NULL, 0,
{ "rcfile-verbose", 0, NULL, OPTION_ALIAS, NULL },
{ "config-lint", OPT_RCFILE_LINT, NULL, 0,
N_("Check configuration file syntax and exit"), 0 },
{ "rcfile-lint", 0, NULL, OPTION_ALIAS, NULL },
{ NULL, 0, NULL, 0, NULL, 0 }
};
......
......@@ -21,6 +21,7 @@
#endif
#include <mailutils/nls.h>
#include <mailutils/version.h>
#include <stdio.h>
#include <string.h>
......@@ -42,121 +43,130 @@ char *mu_license_text =
"\n"
);
static char *mu_conf_option[] = {
"VERSION=" VERSION,
static struct mu_conf_option mu_conf_option[] = {
{ "VERSION=" VERSION, N_("Version of this package") },
#ifdef USE_LIBPAM
"USE_LIBPAM",
{ "USE_LIBPAM", N_("PAM support") },
#endif
#ifdef HAVE_LIBLTDL
"HAVE_LIBLTDL",
{ "HAVE_LIBLTDL", N_("a portable `dlopen' wrapper library") },
#endif
#ifdef WITH_BDB2
"WITH_BDB2",
{ "WITH_BDB2", N_("Berkeley DB v. 2") },
#endif
#ifdef WITH_NDBM
"WITH_NDBM",
{ "WITH_NDBM", },
#endif
#ifdef WITH_OLD_DBM
"WITH_OLD_DBM",
{ "WITH_OLD_DBM", N_("Old DBM support") },
#endif
#ifdef WITH_GDBM
"WITH_GDBM",
{ "WITH_GDBM", N_("GNU DBM") },
#endif
#ifdef WITH_GNUTLS
"WITH_GNUTLS",
{ "WITH_GNUTLS", N_("TLS support using GNU TLS") },
#endif
#ifdef WITH_GSASL
"WITH_GSASL",
{ "WITH_GSASL", N_("SASL support using GNU SASL") },
#endif
#ifdef WITH_GSSAPI
"WITH_GSSAPI",
{ "WITH_GSSAPI", N_("GSSAPI support") },
#endif
#ifdef WITH_GUILE
"WITH_GUILE",
{ "WITH_GUILE", N_("Support for Guile as extension language") },
#endif
#ifdef WITH_PTHREAD
"WITH_PTHREAD",
{ "WITH_PTHREAD", N_("Support for POSIX threads") },
#endif
#ifdef WITH_READLINE
"WITH_READLINE",
{ "WITH_READLINE", N_("GNU Readline") },
#endif
#ifdef HAVE_MYSQL
"HAVE_MYSQL",
{ "HAVE_MYSQL", N_("MySQL") },
#endif
#ifdef HAVE_PGSQL
"HAVE_PGSQL",
{ "HAVE_PGSQL", N_("PostgreSQL") },
#endif
#ifdef WITH_LDAP
"WITH_LDAP",
{ "WITH_LDAP", },
#endif
#ifdef ENABLE_VIRTUAL_DOMAINS
"ENABLE_VIRTUAL_DOMAINS",
{ "ENABLE_VIRTUAL_DOMAINS", N_("Support for virtual mail domains") },
#endif
#ifdef ENABLE_IMAP
"ENABLE_IMAP",
{ "ENABLE_IMAP", N_("IMAP4D protocol support") },
#endif
#ifdef ENABLE_POP
"ENABLE_POP",
{ "ENABLE_POP", N_("POP3D protocol support") },
#endif
#ifdef ENABLE_MH
"ENABLE_MH",
{ "ENABLE_MH", N_("MH mail storage support") },
#endif
#ifdef ENABLE_MAILDIR
"ENABLE_MAILDIR",
{ "ENABLE_MAILDIR", N_("Maildir mail storage support") },
#endif
#ifdef ENABLE_SMTP
"ENABLE_SMTP",
{ "ENABLE_SMTP", N_("SMTP protocol support") },
#endif
#ifdef ENABLE_SENDMAIL
"ENABLE_SENDMAIL",
{ "ENABLE_SENDMAIL", N_("Sendmail command line interface support")},
#endif
#ifdef ENABLE_NNTP
"ENABLE_NNTP",
{ "ENABLE_NNTP", N_("NNTP protocol support") },
#endif
#ifdef ENABLE_RADIUS
"ENABLE_RADIUS",
{ "ENABLE_RADIUS", N_("RADIUS protocol support") },
#endif
#ifdef WITH_INCLUDED_LIBINTL
"WITH_INCLUDED_LIBINTL",
{ "WITH_INCLUDED_LIBINTL", N_("GNU libintl compiled in") },
#endif
NULL
{ NULL }
};
void
mu_fprint_conf_option (FILE *fp, const struct mu_conf_option *opt)
{
fprintf (fp, "%s", opt->name);
if (opt->descr)
fprintf (fp, "\t- %s", _(opt->descr));
fputc('\n', fp);
}
void
mu_fprint_options (FILE *fp)
{
int i;
for (i = 0; mu_conf_option[i]; i++)
fprintf (fp, "%s\n", mu_conf_option[i]);
for (i = 0; mu_conf_option[i].name; i++)
mu_fprint_conf_option (fp, mu_conf_option + i);
}
void
mu_print_options (FILE *fp)
mu_print_options ()
{
mu_fprint_options (stdout);
}
const char *
const struct mu_conf_option *
mu_check_option (char *name)
{
int i;
for (i = 0; mu_conf_option[i]; i++)
for (i = 0; mu_conf_option[i].name; i++)
{
int len;
char *q, *p = strchr (mu_conf_option[i], '=');
char *q, *p = strchr (mu_conf_option[i].name, '=');
if (p)
len = p - mu_conf_option[i];
len = p - mu_conf_option[i].name;
else
len = strlen (mu_conf_option[i]);
len = strlen (mu_conf_option[i].name);
if (strncasecmp (mu_conf_option[i], name, len) == 0)
return mu_conf_option[i];
else if ((q = strchr (mu_conf_option[i], '_')) != NULL
if (strncasecmp (mu_conf_option[i].name, name, len) == 0)
return &mu_conf_option[i];
else if ((q = strchr (mu_conf_option[i].name, '_')) != NULL
&& strncasecmp (q + 1, name,
len - (q - mu_conf_option[i]) - 1) == 0)
return mu_conf_option[i];
len - (q - mu_conf_option[i].name) - 1) == 0)
return &mu_conf_option[i];
}
return NULL;
}
......
......@@ -370,12 +370,13 @@ proc mu_version {} {
}
set output [remote_exec host "$MU_TOOL --show-config-options"]
set flg [split [lindex $output 1]]
set flg [split [lindex $output 1] "\n"]
for {set i 0} {$i < [llength $flg]} {incr i} {
if [regexp "(.*)=(.*)" [lindex $flg $i] var name value] {
regsub "(\t.*)?\r" [lindex $flg $i] "" string
if [regexp "(.*)=(.*)" $string var name value] {
set MU_CAPABILITY($name) $value
} else {
set MU_CAPABILITY([lindex $flg $i]) 1
} elseif {$string != ""} {
set MU_CAPABILITY($string) 1
}
}
if [info exists MU_CAPABILITY(VERSION)] {
......