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 868 additions and 448 deletions
1 2008-09-21 Sergey Poznyakoff <gray@gnu.org.ua>
2
3 * configure.ac: Configure doc hints.
4 * config/mailutils-config.c (main): Use mu_fprint_conf_option.
5 * mailbox/version.c (mu_conf_option): Change type.
6 (mu_fprint_conf_option): New function.
7 (mu_fprint_options): Use mu_fprint_conf_option.
8 (mu_print_options): Fix signature
9 (mu_check_option): Change return type.
10 * testsuite/lib/mailutils.exp (mu_version): Reflect changes in the
11 output produced by --show-config-options.
12
13 * include/mailutils/version.h (struct mu_conf_option): New data
14 type.
15 (mu_check_option): Change return type.
16 (mu_fprint_conf_option): New prototype.
17 * libargp/common.c (mu_common_argp): Rename --rcfile-* options
18 to --config-*. Retain old names for a while.
19
20 * doc/texinfo/Makefile.am (RENDITION_TEXI): New variable.
21 (check-format, check-refs, check-fixmes, check-unrevised)
22 (all-check-docs, check-docs): New rules.
23 * doc/texinfo/rendition.texi: New file.
24 * doc/texinfo/macros.texi: New file.
25 * doc/texinfo/mailutils.texi: Start rewriting
26 * doc/texinfo/programs.texi: Likewise.
27
28 * doc/texinfo/c-api.texi: Reformat.
29 * doc/texinfo/fdl.texi: Likewise.
30 * doc/texinfo/libmuauth.texi: Likewise.
31 * doc/texinfo/libsieve.texi: Likewise.
32 * doc/texinfo/mu-mh.texi: Likewise.
33 * doc/texinfo/sieve.texi: Likewise.
34
35 * doc/texinfo/gendocs_template: Rewrite.
36
1 2008-08-24 Sergey Poznyakoff <gray@gnu.org.ua> 37 2008-08-24 Sergey Poznyakoff <gray@gnu.org.ua>
2 38
3 Fix testsuite to avoid spawning /bin/cp. 39 Fix testsuite to avoid spawning /bin/cp.
......
...@@ -276,11 +276,11 @@ main (int argc, char **argv) ...@@ -276,11 +276,11 @@ main (int argc, char **argv)
276 276
277 for (i = 0; i < argc; i++) 277 for (i = 0; i < argc; i++)
278 { 278 {
279 const char *val = mu_check_option (argv[i]); 279 const struct mu_conf_option *opt = mu_check_option (argv[i]);
280 if (val) 280 if (opt)
281 { 281 {
282 found++; 282 found++;
283 printf ("%s\n", val); 283 mu_fprint_conf_option (stdout, opt);
284 } 284 }
285 } 285 }
286 return found == argc ? 0 : 1; 286 return found == argc ? 0 : 1;
......
...@@ -1103,6 +1103,24 @@ dnl get sysconfdir expanded. ...@@ -1103,6 +1103,24 @@ dnl get sysconfdir expanded.
1103 1103
1104 CPPFLAGS="$CPPFLAGS -DSYSCONFDIR=\\\"\$(sysconfdir)\\\"" 1104 CPPFLAGS="$CPPFLAGS -DSYSCONFDIR=\\\"\$(sysconfdir)\\\""
1105 1105
1106 # Doc hints.
1107 # Select a rendition level:
1108 # DISTRIB for stable releases (at most one dot in the version number)
1109 # and maintenance releases (two dots, patchlevel < 50)
1110 # PROOF for alpha releases.
1111 # PUBLISH can only be required manually when running make in doc/
1112 AC_SUBST(RENDITION)
1113 case `echo $VERSION|sed 's/[[^.]]//g'` in
1114 ""|".") RENDITION=DISTRIB;;
1115 "..") if test `echo $VERSION | sed 's/.*\.//'` -lt 50; then
1116 RENDITION=DISTRIB
1117 else
1118 RENDITION=PROOF
1119 fi;;
1120 *) RENDITION=PROOF;;
1121 esac
1122
1123
1106 AC_CONFIG_COMMANDS([status],[ 1124 AC_CONFIG_COMMANDS([status],[
1107 cat <<EOF 1125 cat <<EOF
1108 1126
......
...@@ -28,6 +28,8 @@ INCFILES = \ ...@@ -28,6 +28,8 @@ INCFILES = \
28 sfrom.inc\ 28 sfrom.inc\
29 url-parse.inc 29 url-parse.inc
30 30
31 RENDITION_TEXI=rendition.texi macros.texi
32
31 mailutils_TEXINFOS = \ 33 mailutils_TEXINFOS = \
32 address.texi\ 34 address.texi\
33 attribute.texi\ 35 attribute.texi\
...@@ -70,12 +72,9 @@ mailutils_TEXINFOS = \ ...@@ -70,12 +72,9 @@ mailutils_TEXINFOS = \
70 smtp.texi\ 72 smtp.texi\
71 stream.texi\ 73 stream.texi\
72 url.texi\ 74 url.texi\
75 $(RENDITION_TEXI)\
73 $(INCFILES) 76 $(INCFILES)
74 77
75 muint_TEXINFOS = \
76 muint.texi\
77 mom.texi
78
79 ## Fake configure into including srcdir to VPATH: 78 ## Fake configure into including srcdir to VPATH:
80 s=${srcdir}:${top_srcdir}/examples/ 79 s=${srcdir}:${top_srcdir}/examples/
81 VPATH = $(s) 80 VPATH = $(s)
...@@ -89,9 +88,12 @@ MAINTAINERCLEANFILES=$(INCFILES) ...@@ -89,9 +88,12 @@ MAINTAINERCLEANFILES=$(INCFILES)
89 clean-local: 88 clean-local:
90 rm -rf manual 89 rm -rf manual
91 90
91 # The rendering level is one of PUBLISH, DISTRIB or PROOF.
92 # Just call `make RENDITION=PROOF [target]' if you want PROOF rendition.
93
94 MAKEINFOFLAGS=-D$(RENDITION)
92 GENDOCS=gendocs.sh 95 GENDOCS=gendocs.sh
93 TEXI2DVI=texi2dvi 96 TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E
94 MAKEINFOFLAGS=
95 97
96 # Make sure you set TEXINPUTS. 98 # Make sure you set TEXINPUTS.
97 # TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions 99 # TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions
...@@ -114,3 +116,57 @@ untabify: ...@@ -114,3 +116,57 @@ untabify:
114 emacs -batch -l untabify.el $(info_TEXINFOS) $(mailutils_TEXINFOS) 116 emacs -batch -l untabify.el $(info_TEXINFOS) $(mailutils_TEXINFOS)
115 117
116 final: untabify master-menu 118 final: untabify master-menu
119
120
121 # Checks
122 check-format:
123 @if test -n "`cat $(info_TEXINFOS) $(mailutils_TEXINFOS) |\
124 tr -d -c '\t'`"; then \
125 echo "Sources contain tabs; run make untabify"; \
126 false; \
127 fi
128
129 check-refs:
130 @for file in $(info_TEXINFOS) $(dico_TEXINFOS); \
131 do \
132 sed -e = $$file | \
133 sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\)}.*/'$$file':\1: \2/gp}'; \
134 done > $@-t; \
135 if [ -s $@-t ]; then \
136 echo "Unresolved cross-references:"; \
137 cat $@-t;\
138 rm $@-t; \
139 else \
140 rm -f $@-t; \
141 fi
142
143 check-fixmes:
144 @for file in $(info_TEXINFOS); \
145 do \
146 sed -e = $$file | \
147 sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \
148 done > $@-t; \
149 if [ -s $@-t ]; then \
150 echo "Unresolved FIXMEs:"; \
151 cat $@-t; \
152 rm $@-t; \
153 false; \
154 else \
155 rm -f $@-t; \
156 fi
157
158 check-unrevised:
159 @grep -Hn @UNREVISED $(info_TEXINFOS) $(dico_TEXINFOS) > $@-t; \
160 if [ -s $@-t ]; then \
161 echo "Unrevised nodes:"; \
162 cat $@-t; \
163 rm $@-t; \
164 false;\
165 else \
166 rm $@-t; \
167 fi
168
169 all-check-docs: check-format check-refs check-fixmes check-unrevised
170
171 check-docs:
172 $(MAKE) -k all-check-docs
......
...@@ -16,49 +16,41 @@ ...@@ -16,49 +16,41 @@
16 @end menu 16 @end menu
17 17
18 @node POP3 18 @node POP3
19 @comment node-name, next, previous, up
20 @section POP3 19 @section POP3
21 @cindex POP3 20 @cindex POP3
22 @include pop3.texi 21 @include pop3.texi
23 22
24 @node IMAP4 23 @node IMAP4
25 @comment node-name, next, previous, up
26 @section IMAP4 24 @section IMAP4
27 @cindex IMAP4 25 @cindex IMAP4
28 @include imap4.texi 26 @include imap4.texi
29 27
30 @node Mbox 28 @node Mbox
31 @comment node-name, next, previous, up
32 @section Mbox 29 @section Mbox
33 @cindex Mbox 30 @cindex Mbox
34 @include mbox.texi 31 @include mbox.texi
35 32
36 @node Mh 33 @node Mh
37 @comment node-name, next, previous, up
38 @section Mh 34 @section Mh
39 @cindex Mh 35 @cindex Mh
40 @include mh.texi 36 @include mh.texi
41 37
42 @node Maildir 38 @node Maildir
43 @comment node-name, next, previous, up
44 @section Maildir 39 @section Maildir
45 @cindex Maildir 40 @cindex Maildir
46 @include maildir.texi 41 @include maildir.texi
47 42
48 @node SMTP 43 @node SMTP
49 @comment node-name, next, previous, up
50 @section SMTP 44 @section SMTP
51 @cindex SMTP 45 @cindex SMTP
52 @include smtp.texi 46 @include smtp.texi
53 47
54 @node Sendmail 48 @node Sendmail
55 @comment node-name, next, previous, up
56 @section Sendmail 49 @section Sendmail
57 @cindex Sendmail 50 @cindex Sendmail
58 @include sendmail.texi 51 @include sendmail.texi
59 52
60 @node Parse822 53 @node Parse822
61 @comment node-name, next, previous, up
62 @section Parse822 54 @section Parse822
63 @cindex Parse822 55 @cindex Parse822
64 @include parse822.texi 56 @include parse822.texi
......
1 @setfilename fdl.info 1 @setfilename fdl.info
2 @node GNU FDL
2 @appendix GNU Free Documentation License 3 @appendix GNU Free Documentation License
3 @cindex FDL, GNU Free Documentation License 4 @cindex FDL, GNU Free Documentation License
4 @center Version 1.2, November 2002 5 @center Version 1.2, November 2002
......
...@@ -34,7 +34,7 @@ ...@@ -34,7 +34,7 @@
34 </p> 34 </p>
35 <hr /> 35 <hr />
36 36
37 The manual for %%PACKAGE%% is available in the following formats:</p> 37 <p>The manual for %%PACKAGE%% is available in the following formats:</p>
38 38
39 <ul> 39 <ul>
40 <li><a href="%%PACKAGE%%.html">HTML 40 <li><a href="%%PACKAGE%%.html">HTML
...@@ -44,10 +44,10 @@ The manual for %%PACKAGE%% is available in the following formats:</p> ...@@ -44,10 +44,10 @@ The manual for %%PACKAGE%% is available in the following formats:</p>
44 <li><a href="%%PACKAGE%%.html.gz">HTML compressed 44 <li><a href="%%PACKAGE%%.html.gz">HTML compressed
45 (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on 45 (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
46 one web page.</li> 46 one web page.</li>
47 <li><a href="%%PACKAGE%%_html_node.tar.gz">HTML compressed 47 <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
48 (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> - 48 (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
49 with one web page per node.</li> 49 with one web page per node.</li>
50 <li><a href="%%PACKAGE%%-info.tar.gz">Info document 50 <li><a href="%%PACKAGE%%.info.tar.gz">Info document
51 (%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li> 51 (%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li>
52 <li><a href="%%PACKAGE%%.txt">ASCII text 52 <li><a href="%%PACKAGE%%.txt">ASCII text
53 (%%ASCII_SIZE%%K characters)</a>.</li> 53 (%%ASCII_SIZE%%K characters)</a>.</li>
...@@ -77,7 +77,9 @@ href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.) ...@@ -77,7 +77,9 @@ href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.)
77 <p> 77 <p>
78 Return to the <a href="/home.html">GNU Project home page</a>. 78 Return to the <a href="/home.html">GNU Project home page</a>.
79 </p> 79 </p>
80 80 <p>
81 Return to <a href="/software/%%PACKAGE%%">GNU %%PACKAGE%% home page</a>.
82 </p>
81 <p> 83 <p>
82 Please send FSF &amp; GNU inquiries to 84 Please send FSF &amp; GNU inquiries to
83 <a href="mailto:gnu@gnu.org"><em>gnu@gnu.org</em></a>. 85 <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 ...@@ -89,8 +91,8 @@ Please send broken links and other corrections (or suggestions) to
89 </p> 91 </p>
90 92
91 <p> 93 <p>
92 Copyright (C) 2004 Free Software Foundation, Inc., 94 Copyright (C) 2005 Free Software Foundation, Inc.,
93 59 Temple Place - Suite 330, Boston, MA 02111, USA 95 51 Franklin Street, Fifth Floor, Boston, MA 02111, USA
94 <br /> 96 <br />
95 Verbatim copying and distribution of this entire article is 97 Verbatim copying and distribution of this entire article is
96 permitted in any medium, provided this notice is preserved. 98 permitted in any medium, provided this notice is preserved.
......
...@@ -216,7 +216,7 @@ credentials for accessing the database are taken from global variables ...@@ -216,7 +216,7 @@ credentials for accessing the database are taken from global variables
216 and @code{sql_db}. The SQL queries for retrieving user information 216 and @code{sql_db}. The SQL queries for retrieving user information
217 from global variables @code{sql_getpwnam_query} and 217 from global variables @code{sql_getpwnam_query} and
218 @code{sql_getpwuid_query}. The variable @code{sql_getpass_query} keeps 218 @code{sql_getpwuid_query}. The variable @code{sql_getpass_query} keeps
219 the query used for retrieving user's password. @xref{auth}, for 219 the query used for retrieving user's password. @FIXME-xref{auth}, for
220 information on command line options used to set these variables. 220 information on command line options used to set these variables.
221 @end defvar 221 @end defvar
222 222
......
1 @macro xopindex{option,text}
2 @opindex \option\, --\option\ @r{option, \text\}
3 @end macro
...@@ -6,14 +6,9 @@ ...@@ -6,14 +6,9 @@
6 @finalout 6 @finalout
7 @c %**end of header 7 @c %**end of header
8 8
9 @c This file has the new style title page commands.
10 @c Run `makeinfo' rather than `texinfo-format-buffer'.
11 @c smallbook
12 @c tex
13 @c \overfullrule=0pt
14 @c end tex
15
16 @include version.texi 9 @include version.texi
10 @include macros.texi
11 @include rendition.texi
17 12
18 @c Combine indices. 13 @c Combine indices.
19 @defcodeindex op 14 @defcodeindex op
...@@ -23,7 +18,7 @@ ...@@ -23,7 +18,7 @@
23 @ifinfo 18 @ifinfo
24 @dircategory Email 19 @dircategory Email
25 @direntry 20 @direntry
26 * Mailutils: (mailutils). Utilities & library for mailboxes, protocols. 21 * Mailutils: (mailutils). GNU Mail Utilities.
27 @end direntry 22 @end direntry
28 @dircategory Individual utilities 23 @dircategory Individual utilities
29 @direntry 24 @direntry
...@@ -45,7 +40,7 @@ Published by the Free Software Foundation, ...@@ -45,7 +40,7 @@ Published by the Free Software Foundation,
45 51 Franklin Street, Fifth Floor 40 51 Franklin Street, Fifth Floor
46 Boston, MA 02110-1301, USA 41 Boston, MA 02110-1301, USA
47 42
48 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 43 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2008
49 Free Software Foundation, Inc. 44 Free Software Foundation, Inc.
50 45
51 Permission is granted to copy, distribute and/or modify this document 46 Permission is granted to copy, distribute and/or modify this document
...@@ -63,7 +58,7 @@ Software Foundation raise funds for GNU development.'' ...@@ -63,7 +58,7 @@ Software Foundation raise funds for GNU development.''
63 @titlepage 58 @titlepage
64 @title GNU Mailutils 59 @title GNU Mailutils
65 @subtitle version @value{VERSION}, @value{UPDATED} 60 @subtitle version @value{VERSION}, @value{UPDATED}
66 @author Alain Magloire et al. 61 @author Alain Magloire, Sergey Pozbyakoff et al.
67 @page 62 @page
68 @vskip 0pt plus 1filll 63 @vskip 0pt plus 1filll
69 @insertcopying 64 @insertcopying
...@@ -74,14 +69,13 @@ Software Foundation raise funds for GNU development.'' ...@@ -74,14 +69,13 @@ Software Foundation raise funds for GNU development.''
74 @page 69 @page
75 @contents 70 @contents
76 71
77 @node Top, Introduction, (dir), (dir) 72 @ifnottex
78 @comment node-name, next, previous, up 73 @node Top
74 @top GNU Mailutils
79 75
80 @ifinfo 76 This edition of the @cite{GNU Mailutils Manual}, last updated on
81 @chapter GNU Mailutils 77 @value{UPDATED}, documents GNU Mailutils Version @value{VERSION}.
82 This edition of the @cite{GNU Mailutils Manual}, last updated @value{UPDATED}, 78 @end ifnottex
83 documents GNU Mailutils Version @value{VERSION}.
84 @end ifinfo
85 79
86 @menu 80 @menu
87 * Introduction:: Preliminary Information. 81 * Introduction:: Preliminary Information.
...@@ -89,12 +83,13 @@ documents GNU Mailutils Version @value{VERSION}. ...@@ -89,12 +83,13 @@ documents GNU Mailutils Version @value{VERSION}.
89 * Libraries:: Mailutils Libraries. 83 * Libraries:: Mailutils Libraries.
90 * Sieve Language:: The Sieve Language. 84 * Sieve Language:: The Sieve Language.
91 * Reporting Bugs:: How to Report a Bug. 85 * Reporting Bugs:: How to Report a Bug.
92 * News:: Getting News About @sc{gnu} Mailutils. 86 * News:: Getting News About GNU Mailutils.
93 * Acknowledgement:: Thanks and Credits. 87 * Acknowledgement:: Thanks and Credits.
94 88
95 Appendices 89 Appendices
96 90
97 * References:: References. 91 * References:: References.
92 * Usage Vars:: Configuring Help Summary
98 * GNU FDL:: This manual is under the GNU Free 93 * GNU FDL:: This manual is under the GNU Free
99 Documentation License. 94 Documentation License.
100 95
...@@ -136,18 +131,6 @@ Mailutils Programs ...@@ -136,18 +131,6 @@ Mailutils Programs
136 131
137 * mailutils-config:: Get the Information about the Mailutils Build. 132 * mailutils-config:: Get the Information about the Mailutils Build.
138 133
139 Mailutils Configuration File
140
141 * common:: Options understood by most @sc{gnu} utilities.
142 * mailbox:: Specifies the mail spool location, and locking strategy.
143 * mailer:: Sets the mailer URL.
144 * address:: Specifies the default email address and domain.
145 * daemon:: Options common for daemon programs.
146 * auth:: Authentication-specific options.
147 * encryption:: Encryption options.
148 * logging:: Logging control options.
149 * sieve: sieve group. Sieve specific options
150 * config sample:: A sample configuration file.
151 134
152 @command{mail} --- Send and Receive Mail 135 @command{mail} --- Send and Receive Mail
153 136
...@@ -360,24 +343,60 @@ Preprocessor ...@@ -360,24 +343,60 @@ Preprocessor
360 @end detailmenu 343 @end detailmenu
361 @end menu 344 @end menu
362 345
363 @node Introduction, Programs, Top, Top 346 @node Introduction
364 @comment node-name, next, previous, up
365 @chapter Introduction 347 @chapter Introduction
366 348
367 @sc{gnu} Mailutils contains a series of useful mail clients, servers, 349 GNU Mailutils contains a series of useful mail clients, servers,
368 and libraries. These are the primary mail utilities of the GNU system. 350 and libraries. These are the primary mail utilities of the GNU system.
369 Specifically, this package contains a POP3 server, an IMAP4 server, 351 Specifically, this package contains a POP3 server, an IMAP4 server,
370 and a Sieve mail filter. It also provides a POSIX `mailx' client, 352 and a Sieve mail filter. It also provides a POSIX `mailx' client,
371 and a collection of other tools. The central library is capable of 353 and a collection of other tools. All utilities can manipulate the
372 accessing different mailbox formats and mailers as well as off of 354 mailboxes of various formats, both local, stored on the hard disk,
373 local or remote POP3 and IMAP4 servers. 355 and remote, accessed via network protocols, such as POP3 or IMAP4.
356
357 The GNU Mailutils libraries supply a rich set of primitives for
358 handling electronic mail in programs written in C, C++ or Scheme.
374 359
375 This software is part of the GNU Project and belongs to the Free 360 This software is part of the GNU Project and belongs to the Free
376 Software Foundation. All libraries are licensed using the GNU LGPL. 361 Software Foundation. All libraries are licensed using the GNU LGPL.
377 The documentation is licensed under the GNU FDL, and everything 362 The documentation is licensed under the GNU FDL, and everything
378 else is licensed using the GNU GPL. 363 else is licensed using the GNU GPL.
379 364
380 @subheading Why use this package? 365 @menu
366 * Book Contents:: What this Book Contains
367 * History:: A bit of History
368 @end menu
369
370 @node Book Contents
371 @section What this Book Contains
372 @UNREVISED
373
374 @FIXME{This is more a plan on how the document should be structured,
375 than a description of its actual structure. However it is:}
376
377 This book addresses a wide audience of both system administrators
378 and users that aim to use Mailutils programs, and programmers who wish
379 to use Mailutils libraries in their programs. Given this audience,
380 the book is divided in three major parts.
381
382 The first part provides a detailed description of each Mailutils
383 utility, and advices on how to use them in various situations. This
384 part is intended for users and system administrators who are using
385 Mailutils programs. If you are not interested in programming using
386 Mailutils, this is the only part you need to read.
387
388 Subsequent parts address programmers.
389
390 The second part is a tutorial which provides an introduction to
391 programming techniques for writing mail applications using GNU
392 Mailutils.
393
394 Finally, the third part contains a complete Mailutils library
395 reference.
396
397 @node History
398 @section A bit of History, and why use this package?
399 @UNREVISED
381 400
382 This package started off to try and handle large mailbox files more 401 This package started off to try and handle large mailbox files more
383 gracefully then current POP3 servers did. While it handles this task, 402 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 ...@@ -386,14 +405,12 @@ without any real effort on your part. Also, if a new format is added
386 at a later date, your program will support that new format 405 at a later date, your program will support that new format
387 automatically as soon as it is compiled against the new library. 406 automatically as soon as it is compiled against the new library.
388 407
389 @node Programs, Libraries, Introduction, Top 408 @node Programs
390 @comment node-name, next, previous, up
391 @chapter Mailutils Programs 409 @chapter Mailutils Programs
392 @cindex Programs 410 @cindex Programs
393 @include programs.texi 411 @include programs.texi
394 412
395 @node Libraries, Sieve Language, Programs, Top 413 @node Libraries
396 @comment node-name, next, previous, up
397 @chapter Mailutils Libraries 414 @chapter Mailutils Libraries
398 @cindex Libraries 415 @cindex Libraries
399 416
...@@ -404,46 +421,38 @@ automatically as soon as it is compiled against the new library. ...@@ -404,46 +421,38 @@ automatically as soon as it is compiled against the new library.
404 * libsieve:: GNU Implementation of Sieve Mail Filtering. 421 * libsieve:: GNU Implementation of Sieve Mail Filtering.
405 @end menu 422 @end menu
406 423
407 @node libmailbox, libmuauth, Libraries, Libraries 424 @node libmailbox
408 @comment node-name, next, previous, up
409 @section Framework 425 @section Framework
410 @cindex Framework 426 @cindex Framework
411 @include framework.texi 427 @include framework.texi
412 428
413 @node libmuauth, libmu_scm, libmailbox, Libraries 429 @node libmuauth
414 @comment node-name, next, previous, up
415 @section Authentication Library 430 @section Authentication Library
416 @cindex Authentication Library 431 @cindex Authentication Library
417 @cindex libmuauth 432 @cindex libmuauth
418 @include libmuauth.texi 433 @include libmuauth.texi
419 434
420 @node libmu_scm, libsieve, libmuauth, Libraries 435 @node libmu_scm
421 @comment node-name, next, previous, up
422 @section Mailutils to Scheme Interface 436 @section Mailutils to Scheme Interface
423 @cindex Scheme 437 @cindex Scheme
424 @cindex libmu_scm 438 @cindex libmu_scm
425 @include libmu_scm.texi 439 @include libmu_scm.texi
426 440
427 @node libsieve, , libmu_scm, Libraries 441 @node libsieve
428 @comment node-name, next, previous, up
429 @section Sieve Library 442 @section Sieve Library
430 @cindex Sieve Library 443 @cindex Sieve Library
431 @cindex libsieve 444 @cindex libsieve
432 @include libsieve.texi 445 @include libsieve.texi
433 446
434 @node Sieve Language, Reporting Bugs, Libraries, Top 447 @node Sieve Language
435 @comment node-name, next, previous, up
436 @chapter Sieve Language 448 @chapter Sieve Language
437 @cindex Sieve Language 449 @cindex Sieve Language
438 @include sieve.texi 450 @include sieve.texi
439 451
440 @node Reporting Bugs, News, Sieve Language, Top 452 @node Reporting Bugs
441 @comment node-name, next, previous, up
442 @chapter Reporting Bugs 453 @chapter Reporting Bugs
443 454
444 Email bug reports to @email{bug-mailutils@@gnu.org}. 455 Email bug reports to @email{bug-mailutils@@gnu.org}.
445 Be sure to include the word ``mailutils'' somewhere
446 in the ``Subject:'' field.
447 456
448 As the purpose of bug reporting is to improve software, please be sure 457 As the purpose of bug reporting is to improve software, please be sure
449 to include maximum information when reporting a bug. The information 458 to include maximum information when reporting a bug. The information
...@@ -458,19 +467,17 @@ needed is: ...@@ -458,19 +467,17 @@ needed is:
458 The archives of bug-mailutils mailing list are available from 467 The archives of bug-mailutils mailing list are available from
459 @url{http://mail.gnu.org/@/mailman/@/listinfo/@/bug-mailutils}. 468 @url{http://mail.gnu.org/@/mailman/@/listinfo/@/bug-mailutils}.
460 469
461 @node News, Acknowledgement, Reporting Bugs, Top 470 @node News
462 @comment node-name, next, previous, up 471 @chapter Getting News About GNU Mailutils
463 @chapter Getting News About @sc{gnu} Mailutils
464 472
465 The two places to look for any news regarding @sc{gnu} Mailutils are the 473 The two places to look for any news regarding GNU Mailutils are the
466 Mailutils homepage at @url{http://www.gnu.org/@/software/@/mailutils}, and the 474 Mailutils homepage at @url{http://www.gnu.org/@/software/@/mailutils}, and the
467 project page at @url{http://savannah.gnu.org/@/projects/@/mailutils}. 475 project page at @url{http://savannah.gnu.org/@/projects/@/mailutils}.
468 476
469 The updated versions of this manual are available online from 477 The updated versions of this manual are available online from
470 @url{http://www.gnu.org/@/software/@/mailutils/@/manual}. 478 @url{http://www.gnu.org/@/software/@/mailutils/@/manual}.
471 479
472 @node Acknowledgement, References, News, Top 480 @node Acknowledgement
473 @comment node-name, next, previous, up
474 @chapter Acknowledgement 481 @chapter Acknowledgement
475 482
476 In no particular order, 483 In no particular order,
...@@ -500,8 +507,7 @@ Jordi Mallach @email{jordi@@sindominio.net} ...@@ -500,8 +507,7 @@ Jordi Mallach @email{jordi@@sindominio.net}
500 Wojciech Polak @email{polak@@gnu.org} 507 Wojciech Polak @email{polak@@gnu.org}
501 @end itemize 508 @end itemize
502 509
503 @node References, GNU FDL, Acknowledgement, Top 510 @node References
504 @comment node-name, next, previous, up
505 @appendix References 511 @appendix References
506 512
507 @itemize @bullet 513 @itemize @bullet
...@@ -619,12 +625,11 @@ Notifications} ...@@ -619,12 +625,11 @@ Notifications}
619 @end itemize 625 @end itemize
620 @end itemize 626 @end itemize
621 627
622 @node GNU FDL, Function Index, References, Top 628 @include usage.texi
623 @comment node-name, next, previous, up 629
624 @include fdl.texi 630 @include fdl.texi
625 631
626 @node Function Index, Variable Index, GNU FDL, Top 632 @node Function Index
627 @comment node-name, next, previous, up
628 @unnumbered Function Index 633 @unnumbered Function Index
629 634
630 This is an alphabetical list of all Mailutils functions. 635 This is an alphabetical list of all Mailutils functions.
...@@ -632,25 +637,23 @@ This is an alphabetical list of all Mailutils functions. ...@@ -632,25 +637,23 @@ This is an alphabetical list of all Mailutils functions.
632 @printindex fn 637 @printindex fn
633 @page 638 @page
634 639
635 @node Variable Index, Keyword Index, Function Index, Top 640 @node Variable Index
636 @unnumbered Variable Index 641 @unnumbered Variable Index
637 @printindex vr 642 @printindex vr
638 @page 643 @page
639 644
640 @node Keyword Index, Program Index, Variable Index, Top 645 @node Keyword Index
641 @unnumbered Keyword Index 646 @unnumbered Keyword Index
642 @printindex ky 647 @printindex ky
643 @page 648 @page
644 649
645 @node Program Index, Concept Index, Keyword Index, Top 650 @node Program Index
646 @comment node-name, next, previous, up
647 @unnumbered Program Index 651 @unnumbered Program Index
648 652
649 @printindex pg 653 @printindex pg
650 @page 654 @page
651 655
652 @node Concept Index, , Program Index, Top 656 @node Concept Index
653 @comment node-name, next, previous, up
654 @unnumbered Concept Index 657 @unnumbered Concept Index
655 658
656 This is a general index of all issues discussed in this manual 659 This is a general index of all issues discussed in this manual
......
1 @c This is part of the GNU Mailutils manual. 1 @c This is part of the GNU Mailutils manual.
2 @c Copyright (C) 1999,2000,2001,2002,2003,2004,2005,2006,2007 2 @c Copyright (C) 1999,2000,2001,2002,2003,2004,2005,2006,2007,2008
3 @c Free Software Foundation, Inc. 3 @c Free Software Foundation, Inc.
4 @c See file mailutils.texi for copying conditions. 4 @c See file mailutils.texi for copying conditions.
5 @comment ******************************************************************* 5 @comment *******************************************************************
6 6
7 @sc{gnu} Mailutils provides a set of programs for handling the e-mail. 7 GNU Mailutils provides a broad set of utilities for handling
8 electronic mail. These utilities address the needs of both system
9 adminsitrators and users.
10
11 All utilities are built around a single core subsistem and share many
12 common aspects. All of them are able to work with almost any existing
13 mailbox formats. They use a common configuration file syntax, and
14 their configuration files are located in a single subdirectory.
15
16 In this chapter we will discuss each utility, and give some advices on
17 how to use them in various real life situations.
18
19 First of all we will describe command line and configuration file
20 syntax.
8 21
9 @menu 22 @menu
23 * command line:: Command Line Syntax.
10 * configuration:: Common Configuration File. 24 * configuration:: Common Configuration File.
11 * authentication:: Authorization and Authentication Principles. 25 * authentication:: Authorization and Authentication Principles.
12 26
...@@ -33,351 +47,537 @@ ...@@ -33,351 +47,537 @@
33 * mailutils-config:: Get the Information about the Mailutils Build. 47 * mailutils-config:: Get the Information about the Mailutils Build.
34 @end menu 48 @end menu
35 49
36 @node configuration 50 @node command line
37 @section Mailutils Configuration File 51 @section Command Line
38 @cindex Mailutils configuration file 52 @UNREVISED
39 @cindex mailutils.rc
40 53
41 There are some command line options that are used so often that it is 54 @menu
42 inconvenient to specify them in the command line each time you run 55 * Option Basics:: Basic Notions About Command Line Options.
43 a Mailutils utility. The @dfn{configuration files} provide a way to 56 * Common Options:: Options That are Common for All Utilities.
44 add default command line arguments without having to type them in 57 @end menu
45 the command line. Upon startup, each Mailutils utility scans and
46 processes the contents of the three startup files, none of which
47 are required to exist:
48 58
49 @enumerate 59 @node Option Basics
50 @item the site-wide configuration file 60 @subsection Basic Notions About Command Line Options
61
62 Many command line options have two forms, called short and long
63 forms. Both forms are absolutely identical in function; they are
64 interchangeable.
65
66 The @dfn{short} form is a traditional form for UNIX utilities.
67 In this form, the option consists of a single dash, followed by a
68 single letter, e.g. @option{-c}.
69
70 Short options which require arguments take their arguments
71 immediately following the option letter, optionally separated by white
72 space. For example, you might write @option{-f name}, or @option{-fname}.
73 Here, @option{-f} is the option, and @option{name} is its argument.
74
75 Short options which allow optional arguments take their arguments
76 immediately following the option letter, @emph{without any intervening
77 white space characters}. This is important, so that the command line
78 parser might discern that the text following option is its argument,
79 not the next command line parameter. For example, if option @option{-d}
80 took an optional argument, then @option{-dname} would mean the option
81 with its argument (@option{name} in this case), and @option{-d name} would
82 mean the @option{-d} option without any argument, followed by command
83 line argument @option{name}.
84
85 Short options' letters may be clumped together, but you are not
86 required to do this. When short options are clumped as a set, use one
87 (single) dash for them all, e.g. @option{-cvl} is equivalent to @option{-c
88 -v -l}. However, only options that do not take arguments may be
89 clustered this way. If an option takes an argument, it can only be
90 the last option in such a cluster, otherwise it would be impossible to
91 specify the argument for it. Anyway, it is much more readable to
92 specify such options separated.
93
94 The @dfn{long} option names are probably easier to memorize than
95 their short counterparts. They consist of two dashes, followed by a
96 multi-letter option name, which is usually selected to be a mnemonics
97 for the operation it requests. For example, @option{--verbose} is a
98 long option that increases the verbosity of a utility. In addition,
99 long option names can abbreviated, provided that such an abbreviation
100 is unique among the options understood by a given utility. For
101 example, if a utility takes options @option{--foreground} and
102 @option{--forward}, then the shortest possible abbreviations for these
103 options are @option{--fore} and @option{--forw}, correspondingly. If
104 you try to use @option{--for}, the utility will abort and inform you
105 that the abbreviation you use is ambiguous, so it is not clear which
106 of the options you intended to use.
107
108 Long options which require arguments take those arguments following
109 the option name. There are two ways of specifying a mandatory
110 argument. It can be separated from the option name either by an equal
111 sign, or by any amount of white space characters. For example, if the
112 @option{--file} option requires an argument, and you wish to supply
113 @file{name} as its argument, then you can do so using any of the
114 following notations: @option{--file=name} or @option{--file name}.
115
116 In contrast, optional arguments must always be introduced using an
117 equal sign.
51 118
52 @file{mailutils.rc}, found in your your system configuration directory 119 @node Common Options
53 (usually @file{/etc} or @file{/usr/local/etc}). 120 @subsection Options That are Common for All Utilities.
54 121
55 @item the user-specific configuration file 122 All GNU Mailutils programs understand a common subset of options.
56 123
57 Usually @file{~/.mailutils}, unless @file{~/.mailutils} is a directory, 124 @table @option
58 in which case @file{~/.mailutils/mailutils} is used. 125 @xopindex{help, described}
126 @item --help
127 @itemx -?
128 Display a short summary of the command line options understood by
129 this utilities, along with a terse description of each.
59 130
60 @item the programs-specific configuration file 131 The output of this option consists of three major parts. First, a
132 usage synopsis is displayed. For example:
61 133
62 Usually @file{~/.mu.@var{program}rc}, unless @file{~/.mailutils} is a 134 @smallexample
63 directory, in which case @file{~/.mailutils/@var{program}rc} is used 135 @group
64 (where @var{program} means the program name). 136 Usage: sieve [OPTION...] SCRIPT
65 @end enumerate 137 GNU sieve -- a mail filtering tool
138 @end group
139 @end smallexample
66 140
67 These files have simple line-oriented syntax. Comments begin with the 141 The first line tells that the @command{sieve} utility takes any
68 pound sign (@samp{#}) and extend through the end of the line 142 number of options (brackets indicate optional part) and a single
69 @footnote{If @samp{#} is not the first character on the line, it 143 mandatory argument (@samp{SCRIPT}). The second lines summarizes the
70 should be separated from the previous word by any amount of whitespace.}. 144 purpose of the utility.
71 Very long lines may be split across several lines by escaping final newline
72 with a backslash (@samp{\}) character.
73
74 In the non-program-specific configuration files, any configuration line
75 must start with a @dfn{tag}. In the program-specific configuration
76 file the tag must not be present, all options are for that specific
77 program.
78
79 A tag is either a name of a particular Mailutils utility or @dfn{option
80 group}, prefixed with colon (@samp{:}). The command line options common for
81 several Mailutils programs are divided into @dfn{option groups} or
82 @dfn{capabilities}, e.g. the options @option{--mail-spool} and
83 @option{--lock-flags} form group @samp{mailbox}. These groups are discussed
84 in detail below.
85
86 When processing the non-program-specific configuration files,
87 a Mailutils utility selects those lines whose tag is either the name
88 of that utility or the name of the option group supported by it.
89 In the program-specific configuration file, all lines are selected.
90 For each line found, its tag (if present) is stripped away, and the
91 rest of the line is split up into words. These words are regarded as
92 command line options and are inserted to the program arguments
93 @emph{before} any options from the command line. Thus the options
94 from @file{.mailutils} take precedence over those from @file{mailutils.rc},
95 and the options from the command line take precedence over those from
96 all three configuration files.
97
98 The word splitting occurs at whitespace characters and is similar to
99 that performed by the shell. If an option must contain embedded
100 whitespace, it should be enclosed in a pair of quotes (either double
101 or single quotes).
102 145
103 @menu 146 Following this header is an option summary. It consists of two
104 * common:: Options understood by most @sc{gnu} utilities. 147 columns:
105 * mailbox:: Specifies the mail spool location, and locking strategy.
106 * mailer:: Sets the mailer URL.
107 * address:: Specifies the default email address and domain.
108 * daemon:: Options common for daemon programs.
109 * auth:: Authentication-specific options.
110 * encryption:: Encryption options.
111 * logging:: Logging control options.
112 * sieve: sieve group. Sieve specific options
113 * config sample:: A sample configuration file.
114 @end menu
115 148
116 @node common 149 @verbatim
117 @subsection Common 150 -c, --compile-only Compile script and exit
151 -d, --debug[=FLAGS] Debug flags
152 -e, --email=ADDRESS Override user email address
153 @end verbatim
118 154
119 Each program understands the following informational options:
120 155
121 @table @option 156 The leftmost column contains a comma-separated list of option
122 @item -u 157 names. Short options are listed first. The options are ordered
123 @itemx --usage 158 alphabetically. Arguments, if any, are specified after the last
124 Display a short usage message and exit. 159 option name in the list, so that, e.g. the option @samp{-e} in the
125 @item -h 160 example above requires an argument: @samp{-e ADDRESS}. Optional
126 @itemx --help 161 arguments are enclosed in square brackets, as in @option{--debug}
127 Display help message and exit. 162 option in the example above.
128 @item -L
129 @itemx --license
130 Display @sc{gnu} General Public License and exit.
131 @item -v
132 @itemx --version
133 Display program version and exit.
134 @end table
135 163
136 @node mailbox 164 The rightmost column contains a short description of the option
137 @subsection Mailbox 165 purpose.
138 @cindex :mailbox
139 166
140 Option group @samp{mailbox} consists of options used to specify the 167 The last part of @option{--help} output contains some additional
141 location of the mail spool, and the locking strategy. 168 notices and lists the email address for reporting bugs.
142 169
143 @table @option 170 @xopindex{usage, described}
144 @item -m @var{path} 171 @item --usage
145 @itemx --mail-spool=@var{path} 172 Display a short summary of options. In the contrast to the
146 Set path to the mailspool directory 173 @option{--help} option, only option names and arguments
147 @item --lock-flags=@var{flags} 174 are printed, without any textual description. For example:
148 Set the default mailbox lock flags (E=external, R=retry, T=time, P=pid).
149 @end table
150 175
151 @node mailer 176 @smallexample
152 @subsection Mailer 177 @group
153 @cindex :mailer 178 Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]]
179 [--email=ADDRESS] SCRIPT
180 @end group
181 @end smallexample
182 @end table
154 183
155 This option group overrides the default mailer URL (@url{sendmail:}). 184 The exact formatting of the output produced by these two options is
185 configurable. @xref{Usage Vars}, for a detailed descriptions of it.
156 186
157 @table @option 187 @table @option
158 @item -m @var{url} 188 @xopindex{version, described}
159 @itemx --mailer @var{url} 189 @item --version
190 @itemx -V
191 Print program version and exit.
192
193 @xopindex{show-config-options, described}
194 @item --show-config-options
195 Show configuration options used when compiling the package. You can
196 use this option to verify if support for a particular mailbox format
197 or other functionality is compiled in the binary. The output of this
198 option is intended to be both machine-readable and understandable by
199 humans.
160 @end table 200 @end table
161 201
162 @node address 202 The following command line options affect parsing of configuration
163 @subsection Address 203 files. Here we provide a short summary, the next section will
164 @cindex :address 204 describe them in detail.
165 205
166 Option group @samp{address} consists of options used to specify how to 206 @table @option
167 qualify email addresses. 207 @xopindex{config-file, introduced}
208 @item --config-file=@var{file}
209 Load this configuration file, instead of the default.
168 210
169 An unqualified address (one without an @var{@@}) is qualified by appending 211 @xopindex{config-help, introduced}
170 @var{@@}@var{defaultdomain}. @var{defaultdomain} is the return of 212 @item --config-help
171 @code{gethostname()}, or the result of @code{gethostbyname()} on the return 213 Show configuration file summary.
172 of @code{gethostname()} (if the DNS lookup is successful).
173 214
174 If the email address of the current user is needed, either the address set by 215 @xopindex{config-lint, introduced}
175 @option{--email-addr} is returned, or the current uid is looked up in the user 216 @item --config-lint
176 database, and qualified with the @var{defaultdomain}. 217 Check configuration file syntax and exit
177 218
178 @table @option 219 @xopindex{config-verbose, introduced}
179 @item -E @var{email} 220 @item --config-verbose
180 @itemx --email-addr=@var{email} 221 Verbosely log parsing of the configuration files.
181 Set the current user's email address, this it makes more sense to use
182 this in one of the per-user configuration files.
183 @item -D @var{domain}
184 @itemx --email-domain=@var{domain}
185 Set the default email domain, this might make sense to use in either
186 the global or one of the per-user configuration files.
187 @end table
188 222
189 @node daemon 223 @xopindex{no-site-config, introduced}
190 @subsection Daemon 224 @item --no-site-config
191 @cindex :daemon 225 Do not load site-wide configuration file.
192 226
193 @table @option 227 @xopindex{no-user-config, introduced}
194 @item -d[@var{number}] 228 @item --no-user-config
195 @itemx --daemon[=@var{number}] 229 Do not load user configuration file.
196 Run in standalone mode. An optional @var{number} specifies the maximum number
197 of child processes the daemon is allowed to fork. When it is omitted,
198 it defaults to 20 processes.
199 @emph{Please note}, that there should be no whitespace between the
200 @option{-d} and its parameter.
201 @item -i
202 @itemx --inetd
203 Run in inetd mode.
204 @item -p @var{number}
205 @itemx --port @var{number}
206 Listen on given port @var{number}. This option is meaningful only in
207 standalone mode. It defaults to port 143.
208 @item -t @var{number}
209 @itemx --timeout @var{number}
210 Set idle timeout to given @var{number} of seconds. The daemon breaks the
211 connection if it receives no commands from the client within that number
212 of seconds.
213 @end table 230 @end table
214 231
215 @node auth 232 @node configuration
216 @subsection Auth 233 @section Mailutils Configuration File
217 @cindex :auth 234 @cindex Mailutils configuration file
235 @cindex mailutils.rc
236 @UNREVISED
218 237
219 These options control the authorization and authentication module 238 Configuration files are the principal means of configuring any GNU
220 lists. For a description of authentication concepts, refer to 239 Mailutil component. When started, each utility tries to load its
221 @xref{authentication}. 240 configuration from the following locations, in that order:
222 241
223 @table @option 242 @enumerate 1
224 @item --authorization @var{modlist} 243 @item Main site-wide configuration file.
225 244
226 This option allows to set up a list of modules to be used for 245 It is named @file{@var{sysconfdir}/mailutils.rc}, where @var{sysconfdir} stands
227 authorization. @var{modlist} is a colon-separated list of 246 for the system configuration directory set when compiling the package.
228 modules. Valid modules are: 247 Usually @var{sysconfdir} is @file{/etc} (or @file{/usr/local/etc}).
229 248
230 @table @asis 249 @xopindex{no-site-config, described}
231 @item system 250 This configuration file is not read if the @option{--no-site-config}
232 User credentials are retrieved from the system user database 251 command line option was given.
233 (@file{/etc/password}). 252
234 @item sql 253 @item Per-user configuration file.
235 User credentials are retrieved from the @acronym{sql} database. The set 254
236 of @option{--sql-} options (see below) is used to configure 255 A per user configuration file is located in the user home directory
237 access to the database. 256 and is named @samp{.@var{prog}}, where @var{prog} is the name of the
238 @item virtdomain 257 utility. For example, the per-user configuration file for
239 User credentials are retrieved from a ``virtual domain'' user 258 @command{sieve} utility is named @file{.sieve}.
240 database. 259
241 @end table 260 @xopindex{no-user-config, described}
261 This configuration file is not read if the @option{--no-user-config}
262 command line option was given.
242 263
243 @item --authentication @var{modlist} 264 @xopindex{config-file, described}
265 @item Additional configuration file, if specified using the
266 @option{--config-file} command line option.
267 @end enumerate
268
269 The order in which configuration files are loaded defines the
270 precedence of their settings. Thus, the settings from additional
271 configuration file override those set in per-user configuration file.
272 The latter, in their turn, take precedence over the settings from the
273 site-wide configuration file.
274
275 @xopindex{config-verbose, described}
276 Neither site-wide nor user configuration files are required to
277 exist. If any or both of them are absent, GNU Mailutils does not
278 complain, and the utility falls back to its default settings. To make
279 configuration processing more verbose, use the
280 @option{--config-verbose} command line option. Here is an example of
281 what you might get using this option:
282
283 @smallexample
284 imap4d: Info: parsing file `/etc/mailutils.rc'
285 imap4d: Info: finished parsing file `/etc/mailutils.rc'
286 @end smallexample
287
288 Specifying this option more than once adds more verbosity to this
289 output. If this option is given two times, GNU Mailutils will print
290 any configuration file statement it parsed, along with the exact
291 location where it occurred (the exact meaning of each statement will
292 be described later in this chapter):
293
294 @smallexample
295 imap4d: Info: parsing file `/etc/mailutils.rc'
296 # 1 "/etc/mailutils.rc"
297 mailbox @{
298 # 2 "/etc/mailutils.rc"
299 mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=$@{user@};
300 # 3 "/etc/mailutils.rc"
301 mailbox-type maildir;
302 @};
303 # 6 "/etc/mailutils.rc"
304 include /etc/mailutils.d;
305 imap4d: Info: parsing file `/etc/mailutils.d/imap4d'
306 ...
307 @end smallexample
244 308
245 This option allows to set up a list of modules to be used for 309 @xopindex{config-lint, described}
246 authentication. @var{modlist} is a colon-separated list of 310 To test configuration file without actually starting the utility,
247 modules. Valid modules are: 311 use the @option{--config-lint} command line option. With this option,
312 any Mailutils utility exits after finishing parsing of the
313 configuration files. Any errors occurred during parsing are displayed
314 on the standard error output. This option can be combined with
315 @option{--config-verbose} to obtain more detailed output.
316
317 @xopindex{config-help, described}
318 The @option{--config-help} command line option produces on the
319 standard output the summary of all configuration statements understood
320 by the utility, with detailed comments and in the form suitable for
321 configuration file. For example, the simplest way to write a
322 configuration file for, say, @command{imap4d} is to run
323
324 @smallexample
325 $ imap4d --config-help > imap4d.rc
326 @end smallexample
327
328 @noindent
329 and to edit the @file{imap4d.rc} file with your editor of choice.
330
331 @menu
332 * conf-syntax:: Configuration File Syntax
333 @end menu
334
335 @node conf-syntax
336 @subsection Configuration File Syntax
337 @UNREVISED
338 Configuration files consist of a series of statements. Blanks,
339 tabs, newlines and comments, collectively called @dfn{white space} are
340 ignored except as they serve to separate tokens. Some white space is
341 required to separate otherwise adjacent keywords and values.
342
343 @menu
344 * Comments::
345 * Statements::
346 * Includes::
347 * Block Statements::
348 @end menu
349
350 @node Comments
351 @subsubsection Comments
352 @cindex comments, configuration file
353 @cindex comments, single-line
354 @cindex single-line comments
355 @dfn{Comments} may appear anywhere where white space may appear in the
356 configuration file. There are two kinds of comments:
357 single-line and multi-line comments. @dfn{Single-line} comments start
358 with @samp{#} or @samp{//} and continue to the end of the line:
359
360 @smallexample
361 # This is a comment
362 // This too is a comment
363 @end smallexample
364
365 @cindex comments, multi-line
366 @cindex multi-line comments
367 @dfn{Multi-line} or @dfn{C-style} comments start with the two
368 characters @samp{/*} (slash, star) and continue until the first
369 occurrence of @samp{*/} (star, slash).
370
371 Multi-line comments cannot be nested.
372
373 @node Statements
374 @subsubsection Statements
375 @cindex statements, configuration file
376 @cindex configuration file statements
377 @cindex statement, simple
378 @cindex simple statements
379 A @dfn{simple statement}, consists of a keyword and value
380 separated by any amount of whitespace. Simple statement is terminated
381 with a semicolon (@samp{;}), unless it contains a @dfn{here-document}
382 (see below), in which case semicolon is optional.
383
384 Examples of simple statements:
385
386 @smallexample
387 pidfile /var/run/imap4d.pid;
388 transcript yes;
389 @end smallexample
390
391 A @dfn{keyword} begins with a letter and may contain letters,
392 decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
393 Examples of keywords are: @samp{group}, @samp{identity-check}.
394
395 A @dfn{value} can be one of the following:
248 396
249 @table @asis 397 @table @asis
250 @item generic 398 @item number
251 The generic authentication type. User password is hashed and compared 399 A number is a sequence of decimal digits.
252 against the hash value returned in authorization stage. 400
253 @item system 401 @item boolean
254 The hashed value of the user password is retrieved from 402 @cindex boolean value
255 @file{/etc/shadow} file on systems that support it. 403 A boolean value is one of the following: @samp{yes}, @samp{true},
256 @item sql 404 @samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
257 The hashed value of the user password is retrieved from the @acronym{sql} 405 @samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
258 database using query supplied by @option{--sql-getpass} option 406
259 (see below). 407 @item unquoted string
260 @item pam 408 @cindex string, unquoted
261 The user is authenticated via pluggable authentication module 409 An unquoted string may contain letters, digits, and any of the
262 (@acronym{pam}). The @acronym{pam} service name to be used is 410 following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
263 configured via @option{--pam-service} option (see below). 411 @samp{:}.
264 @end table 412
413 @item quoted string
414 @cindex quoted string
415 @cindex string, quoted
416 @cindex escape sequence
417 A quoted string is any sequence of characters enclosed in
418 double-quotes (@samp{"}). A backslash appearing within a quoted
419 string introduces an @dfn{escape sequence}, which is replaced
420 with a single character according to the following rules:
421
422 @float Table, backslash-interpretation
423 @caption{Backslash escapes}
424 @multitable @columnfractions 0.30 .5
425 @item Sequence @tab Replaced with
426 @item \a @tab Audible bell character (@acronym{ASCII} 7)
427 @item \b @tab Backspace character (@acronym{ASCII} 8)
428 @item \f @tab Form-feed character (@acronym{ASCII} 12)
429 @item \n @tab Newline character (@acronym{ASCII} 10)
430 @item \r @tab Carriage return character (@acronym{ASCII} 13)
431 @item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
432 @item \\ @tab A single backslash (@samp{\})
433 @item \" @tab A double-quote.
434 @end multitable
435 @end float
265 436
266 @item --pam-service @var{name} 437 In addition, the sequence @samp{\@var{newline}} is removed from
267 When compiled with @acronym{pam} support, this option specifies the 438 the string. This allows to split long strings over several
268 name of @acronym{pam} service to be used when authenticating. 439 physical lines, e.g.:
269 @end table
270 440
271 The following options exist in this group if the package was configured 441 @smallexample
272 with @option{--enable-sql} option. They take effect only if the 442 @group
273 @samp{sql} module is used in authentication and/or authorization. 443 "a long string may be\
444 split over several lines"
445 @end group
446 @end smallexample
274 447
275 @table @option 448 If the character following a backslash is not one of those specified
276 @item --sql-interface @var{iface} 449 above, the backslash is ignored and a warning is issued.
277 Specify @sc{sql} interface to use. @var{Iface} is either @samp{mysql}
278 or @samp{postgres}. This allows to select @sc{sql} subsystem on
279 runtime if @code{mailutils} was compiled with support for several
280 @sc{sql} drivers.
281 450
282 If this option is omitted, @code{mailutils} will use the first 451 Two or more adjacent quoted strings are concatenated, which gives
283 available @sc{sql} driver. 452 another way to split long strings over several lines to improve
453 readability. The following fragment produces the same result as the
454 example above:
284 455
285 @item --sql-host @var{name} 456 @smallexample
286 Name or IP of MySQL server to connect to. 457 @group
458 "a long string may be"
459 " split over several lines"
460 @end group
461 @end smallexample
287 462
288 @item --sql-user @var{name} 463 @anchor{here-document}
289 @acronym{sql} user name 464 @item Here-document
465 @cindex here-document
466 @dfn{Here-document} is a special construct that allows to introduce
467 strings of text containing embedded newlines.
290 468
291 @item --sql-passwd @var{string} 469 The @code{<<@var{word}} construct instructs the parser to read all
292 @acronym{sql} connection password 470 the lines that follow up to the line containing only @var{word}, with
471 possible trailing blanks. Any lines thus read are concatenated
472 together into a single string. For example:
293 473
294 @item --sql-db @var{string} 474 @smallexample
295 Name of the database to connect to. 475 @group
476 <<EOT
477 A multiline
478 string
479 EOT
480 @end group
481 @end smallexample
296 482
297 @item --sql-port @var{number} 483 Body of a here-document is interpreted the same way as
298 Port to use 484 double-quoted string, unless @var{word} is preceded by a backslash
485 (e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case
486 the text is read as is, without interpretation of escape sequences.
299 487
300 @item --sql-getpwnam @var{query} 488 If @var{word} is prefixed with @code{-} (a dash), then all leading
301 @acronym{sql} query to retrieve a passwd entry based on username 489 tab characters are stripped from input lines and the line containing
490 @var{word}. Furthermore, if @code{-} is followed by a single space,
491 all leading whitespace is stripped from them. This allows to indent
492 here-documents in a natural fashion. For example:
302 493
303 @item --sql-getpwuid @var{query} 494 @smallexample
304 @acronym{sql} query to retrieve a passwd entry based on user ID 495 @group
496 <<- TEXT
497 All leading whitespace will be
498 ignored when reading these lines.
499 TEXT
500 @end group
501 @end smallexample
305 502
306 @item --sql-getpass @var{query} 503 It is important that the terminating delimiter be the only token on
307 @acronym{sql} query to retrieve a password from the database 504 its line. The only exception to this rule is allowed if a
308 @end table 505 here-document appears as the last element of a statement. In this
506 case a semicolon can be placed on the same line with its terminating
507 delimiter, as in:
309 508
310 @node encryption 509 @smallexample
311 @subsection Encryption 510 help-text <<-EOT
312 @cindex :encryption 511 A sample help text.
512 EOT;
513 @end smallexample
313 514
314 These options control TLS/SSL encryption in @command{imap4d} 515 However, terminated semicolon after a here-document is optional.
315 and @command{pop3d} daemons.
316 516
317 @table @option 517 @item list
318 @item --ssl-cert @var{file} 518 @cindex list
319 This option specifies the file name of the server side SSL certificate 519 A @dfn{list} is a comma-separated list of values. Lists are
320 (accepts PEM format). 520 enclosed in parentheses. The following example shows a statement
321 @item --ssl-key @var{file} 521 whose value is a list of strings:
322 This option specifies the file name of the server side private SSL key
323 (accepts PEM format). The key must be protected with 0600 file permissions
324 (u=rw,g=,o=), otherwise @command{imap4d} or @command{pop3d} daemons will
325 refuse to support TLS/SSL encryption.
326 @item --ssl-cafile @var{file}
327 This option specifies a file containing the list of trusted CAs (PEM list)
328 in order to verify client's certificates. This option is not required.
329 @end table
330 522
331 @node logging 523 @smallexample
332 @subsection Logging 524 shared-namespace ("/home", "/var/spool/common");
333 @cindex :logging 525 @end smallexample
334 526
335 @table @option 527 In any case where a list is appropriate, a single value is allowed
336 @item --log-facility @var{facility} 528 without being a member of a list: it is equivalent to a list with a
337 Output logs to the specified @command{syslog} facility. The following 529 single member. This means that, e.g. @samp{shared-namespace /home;} is
338 facility names are recognized: @samp{user}, @samp{daemon}, @samp{mail}, 530 equivalent to @samp{shared-namespace (/home);}.
339 @samp{auth} and @samp{local0} through @samp{local7}. These names are
340 case-insensitive.
341 @end table 531 @end table
342 532
343 @node sieve group 533 @node Includes
344 @subsection Sieve Specific Options 534 @subsubsection Include Statement
345 @cindex :sieve 535 @cindex include statement, configuration file
536 An @dfn{include statement} is a special statement that causes
537 inclusion of a named file. This statement has the following syntax:
346 538
347 The following options comprise this group: 539 @smallexample
540 include @var{file};
541 @end smallexample
348 542
349 @table @option 543 If @var{file} names a regular file, the contents of this file is
350 @item -I @var{dir} 544 included in this point. Otherwise, if @var{file} names a directory,
351 @itemx --includedir=@var{dir} 545 Mailutils searches in that directory for a file whose name coincides
352 Append directory @var{dir} to the list of directories searched for 546 with the name of utility being executed, and includes this file, if it
353 include files. 547 exists.
354
355 @item -L @var{dir}
356 @itemx --libdir=@var{dir}
357 Append directory @var{dir} to the list of directories searched for
358 library files.
359 @end table
360 548
361 @node config sample 549 It is a common approach to end the site-wide configuration file with
362 @subsection A Sample Configuration File 550 an include statement, e.g.:
363 @cindex mailutils.rc, an example
364 551
365 The following configuration file specifies that all Mailutils programs 552 @smallexample
366 should use @file{/var/spool/mail} as a local mailspool 553 include /etc/mailutils.d;
367 directory. Programs performing authentication will use @acronym{pam} 554 @end smallexample
368 service @samp{mailutils}. All programs, except @command{imap4d} will 555
369 issue log messages via @samp{mail} facility, @command{imap4d} will use 556 This allows each particular utility to have its own configuration
370 facility @samp{local1}. 557 file. Thus. @command{imap4d} will read
558 @file{/etc/mailutils.d/imap4d}, etc.
559
560 @node Block Statements
561 @subsubsection Block Statements
562 @cindex block statement, configuration file
563 A @dfn{block statement} introduces a logical group of another
564 statements. It consists of a keyword, followed by an optional value,
565 and a sequence of statements enclosed in curly braces, as shown in
566 example below:
371 567
372 @smallexample 568 @smallexample
373 @group 569 @group
374 :mailbox --mail-spool /var/spool/mail 570 tcp-wrappers @{
375 :auth --authentication pam --pam-service mailutils 571 enable yes;
376 :logging --log-facility mail 572 allow-syslog-priority info;
377 imap4d --daemon=20 --timeout=1800 --log-facility local1 573 deny-syslog-priority notice;
574 @}
378 @end group 575 @end group
379 @end smallexample 576 @end smallexample
380 577
578 The closing curly brace may be followed by a semicolon, although
579 this is not required.
580
381 @node authentication 581 @node authentication
382 @section Authorization and Authentication Principles 582 @section Authorization and Authentication Principles
383 @cindex authorization 583 @cindex authorization
...@@ -437,7 +637,7 @@ User credentials are retrieved from the system user database ...@@ -437,7 +637,7 @@ User credentials are retrieved from the system user database
437 (@file{/etc/password}). 637 (@file{/etc/password}).
438 @item sql 638 @item sql
439 User credentials are retrieved from the @acronym{sql} database. The set 639 User credentials are retrieved from the @acronym{sql} database. The set
440 of @option{--sql-} options (@pxref{auth}) is used to configure 640 of @option{--sql-} options (@FIXME-pxref{auth}) is used to configure
441 access to the database. 641 access to the database.
442 @item virtdomain 642 @item virtdomain
443 User credentials are retrieved from a ``virtual domain'' user 643 User credentials are retrieved from a ``virtual domain'' user
...@@ -456,11 +656,11 @@ The hashed value of the user password is retrieved from ...@@ -456,11 +656,11 @@ The hashed value of the user password is retrieved from
456 @item sql 656 @item sql
457 The hashed value of the user password is retrieved from the @acronym{sql} 657 The hashed value of the user password is retrieved from the @acronym{sql}
458 database using query supplied by @option{--sql-getpass} option 658 database using query supplied by @option{--sql-getpass} option
459 (@pxref{auth}). 659 (@FIXME-pxref{auth}).
460 @item pam 660 @item pam
461 The user is authenticated via pluggable authentication module 661 The user is authenticated via pluggable authentication module
462 (@acronym{pam}). The @acronym{pam} service name to be used is 662 (@acronym{pam}). The @acronym{pam} service name to be used is
463 configured via @option{--pam-service} option (@pxref{auth}) 663 configured via @option{--pam-service} option (@FIXME-pxref{auth})
464 @end table 664 @end table
465 665
466 Unless overridden by @option{--authentication} command line option, 666 Unless overridden by @option{--authentication} command line option,
...@@ -495,7 +695,7 @@ user's system mailbox and outputs the contents of @code{From} and ...@@ -495,7 +695,7 @@ user's system mailbox and outputs the contents of @code{From} and
495 the command line, the program reads that folder rather than the default 695 the command line, the program reads that folder rather than the default
496 mailbox. 696 mailbox.
497 697
498 The program uses following option groups: @xref{mailbox}. 698 The program uses following option groups: @FIXME-xref{mailbox}.
499 699
500 The following command line options alter the behavior of the program: 700 The following command line options alter the behavior of the program:
501 701
...@@ -612,7 +812,7 @@ General usage of @command{mail} program is: ...@@ -612,7 +812,7 @@ General usage of @command{mail} program is:
612 If [@var{address}...] part is present, @command{mail} switches to 812 If [@var{address}...] part is present, @command{mail} switches to
613 mail sending mode, otherwise it operates in mail reading mode. 813 mail sending mode, otherwise it operates in mail reading mode.
614 814
615 The program uses following option groups: @xref{mailbox}. 815 The program uses following option groups: @FIXME-xref{mailbox}.
616 816
617 @command{Mail} understands following command line options: 817 @command{Mail} understands following command line options:
618 818
...@@ -2345,7 +2545,7 @@ Number of messages in @var{folder}: @var{number} ...@@ -2345,7 +2545,7 @@ Number of messages in @var{folder}: @var{number}
2345 where @var{folder} represents the folder name, @var{number} represents 2545 where @var{folder} represents the folder name, @var{number} represents
2346 the number of messages. 2546 the number of messages.
2347 2547
2348 The program uses following option groups: @xref{mailbox}. 2548 The program uses following option groups: @FIXME-xref{mailbox}.
2349 2549
2350 The program accepts following command line options: 2550 The program accepts following command line options:
2351 2551
...@@ -2743,7 +2943,7 @@ sieve program. ...@@ -2743,7 +2943,7 @@ sieve program.
2743 2943
2744 By default @command{sieve} output all diagnostics on standard error and verbose 2944 By default @command{sieve} output all diagnostics on standard error and verbose
2745 logs on standard output. This behaviour is changed when 2945 logs on standard output. This behaviour is changed when
2746 @option{--log-facility} is given in the command line (@pxref{logging}). 2946 @option{--log-facility} is given in the command line (@FIXME-pxref{logging}).
2747 This option causes @command{sieve} to output its diagnostics to 2947 This option causes @command{sieve} to output its diagnostics to
2748 the given syslog facility. 2948 the given syslog facility.
2749 2949
...@@ -2863,7 +3063,7 @@ It processes mailboxes, applying the user-supplied scheme procedures ...@@ -2863,7 +3063,7 @@ It processes mailboxes, applying the user-supplied scheme procedures
2863 to each of them in turn and saves the resulting output in mailbox 3063 to each of them in turn and saves the resulting output in mailbox
2864 format. 3064 format.
2865 3065
2866 The program uses following option groups: @xref{mailbox}. 3066 The program uses following option groups: @FIXME-xref{mailbox}.
2867 3067
2868 @menu 3068 @menu
2869 * Specifying Scheme Program to Execute:: 3069 * Specifying Scheme Program to Execute::
...@@ -3040,8 +3240,8 @@ General usage of @command{mail.local} program is: ...@@ -3040,8 +3240,8 @@ General usage of @command{mail.local} program is:
3040 If recipient part is present is a FQDN, @command{mail.local} 3240 If recipient part is present is a FQDN, @command{mail.local}
3041 will attempt to deliver to a virtual host. 3241 will attempt to deliver to a virtual host.
3042 3242
3043 The program uses following option groups: @xref{mailbox}, @xref{auth}, 3243 The program uses following option groups: @FIXME-xref{mailbox}, @FIXME-xref{auth},
3044 @xref{logging}, @xref{sieve}. 3244 @FIXME-xref{logging}, @FIXME-xref{sieve}.
3045 3245
3046 @table @option 3246 @table @option
3047 @item -f @var{addr} 3247 @item -f @var{addr}
...@@ -3307,7 +3507,7 @@ Option @option{--quota-query} allows to specify a special query to ...@@ -3307,7 +3507,7 @@ Option @option{--quota-query} allows to specify a special query to
3307 retrieve the quota from the database. Currently (as of mailutils 3507 retrieve the quota from the database. Currently (as of mailutils
3308 version @value{VERSION}) it is assumed that this table can be accessed 3508 version @value{VERSION}) it is assumed that this table can be accessed
3309 using the same credentials as @sc{sql} authentication tables 3509 using the same credentials as @sc{sql} authentication tables
3310 (@xref{daemon}, for the detailed discussion of @option{--sql-} options). 3510 (@FIXME-xref{daemon}, for the detailed discussion of @option{--sql-} options).
3311 3511
3312 For example, suppose you have the following quota table: 3512 For example, suppose you have the following quota table:
3313 3513
...@@ -3547,8 +3747,8 @@ The server runs as daemon, forking a child for each new connection. This ...@@ -3547,8 +3747,8 @@ The server runs as daemon, forking a child for each new connection. This
3547 mode is triggered by @option{-d} command line switch. 3747 mode is triggered by @option{-d} command line switch.
3548 @end table 3748 @end table
3549 3749
3550 The program uses following option groups: @xref{mailbox}, 3750 The program uses following option groups: @FIXME-xref{mailbox},
3551 @xref{daemon}, @xref{logging}, @xref{auth}. 3751 @FIXME-xref{daemon}, @FIXME-xref{logging}, @FIXME-xref{auth}.
3552 3752
3553 @menu 3753 @menu
3554 * Login delay:: 3754 * Login delay::
...@@ -3864,8 +4064,8 @@ The ``inetd'' mode allows to start the server from ...@@ -3864,8 +4064,8 @@ The ``inetd'' mode allows to start the server from
3864 imap4 stream tcp nowait root /usr/local/sbin/imap4d imap4d 4064 imap4 stream tcp nowait root /usr/local/sbin/imap4d imap4d
3865 @end smallexample 4065 @end smallexample
3866 4066
3867 The program uses following option groups: @xref{mailbox}, 4067 The program uses following option groups: @FIXME-xref{mailbox},
3868 @xref{daemon}, @xref{logging}, @xref{auth}. 4068 @FIXME-xref{daemon}, @FIXME-xref{logging}, @FIXME-xref{auth}.
3869 4069
3870 @subheading Command Line Options 4070 @subheading Command Line Options
3871 4071
...@@ -3932,8 +4132,8 @@ either from @file{inetd.conf} or as a standalone daemon. ...@@ -3932,8 +4132,8 @@ either from @file{inetd.conf} or as a standalone daemon.
3932 @node Starting comsatd 4132 @node Starting comsatd
3933 @subsection Starting @command{comsatd} 4133 @subsection Starting @command{comsatd}
3934 4134
3935 @command{Comsatd} uses following option groups: @xref{mailbox}, 4135 @command{Comsatd} uses following option groups: @FIXME-xref{mailbox},
3936 @xref{daemon}, @xref{logging}. 4136 @FIXME-xref{daemon}, @FIXME-xref{logging}.
3937 4137
3938 @table @option 4138 @table @option
3939 @item -c @var{file} 4139 @item -c @var{file}
......
1 @c Let's use the concept of 'renditions' by Fra@,{c}ois Pinard
2 @c I extended it by adding a FIXME_FOOTNOTE variable, which controls
3 @c whether FIXME information should be placed in footnotes or
4 @c inlined.
5
6 @c ======================================================================
7 @c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
8 @c as decided by @set symbols. The PUBLISH rendition does not show
9 @c notes or marks asking for revision. Most users will prefer having more
10 @c information, even if this information is not fully revised for adequacy,
11 @c so DISTRIB is the default for distributions. The PROOF rendition
12 @c show all marks to the point of ugliness, but is nevertheless useful to
13 @c those working on the manual itself.
14 @c ======================================================================
15
16 @c Set this symbol if you wish FIXMEs to appear in footnotes, instead
17 @c of being inserted into the text.
18 @c @set PROOF_FOOTNOTED
19
20 @ifclear PUBLISH
21 @ifclear DISTRIB
22 @ifclear PROOF
23 @set DISTRIB
24 @end ifclear
25 @end ifclear
26 @end ifclear
27
28 @ifset PUBLISH
29 @set RENDITION The book, version
30 @end ifset
31
32 @ifset DISTRIB
33 @set RENDITION FTP release, version
34 @end ifset
35
36 @ifset PROOF
37 @set RENDITION Proof reading version
38 @end ifset
39
40 @c Output marks for nodes needing revision, but not in PUBLISH rendition.
41
42 @macro UNREVISED
43 @ifclear PUBLISH
44 @quotation
45 (@emph{The information in this node may be obsolete or otherwise inaccurate.}
46 This message will disappear, once this node revised.)
47 @end quotation
48 @end ifclear
49 @end macro
50
51 @c Output various FIXME information only in PROOF rendition.
52
53 @macro FIXME{string}
54 @ifset PROOF
55 @ifset PROOF_FOOTNOTED
56 @footnote{@strong{FIXME:} \string\}
57 @end ifset
58 @ifclear PROOF_FOOTNOTED
59 @cartouche
60 @strong{<FIXME>} \string\ @strong{</>}
61 @end cartouche
62 @end ifclear
63 @end ifset
64
65 @end macro
66
67 @macro FIXME-ref{string}
68 @ifset PROOF
69 @strong{<REF>} \string\ @strong{</>}
70 @end ifset
71
72 @end macro
73
74 @macro FIXME-pxref{string}
75 @ifset PROOF
76 @strong{<PXREF>} \string\ @strong{</>}
77 @end ifset
78
79 @end macro
80
81 @macro FIXME-xref{string}
82 @ifset PROOF
83 @strong{<XREF>} \string\ @strong{</>}
84 @end ifset
85
86 @end macro
...@@ -392,7 +392,7 @@ If @var{filename} starts with a directory separator character ...@@ -392,7 +392,7 @@ If @var{filename} starts with a directory separator character
392 The @code{#searchpath} directive adds its argument to the list of 392 The @code{#searchpath} directive adds its argument to the list of
393 directories searched for loadable modules. It has the same effect 393 directories searched for loadable modules. It has the same effect
394 as @option{-L} command line switch used by @sc{gnu} sieve utility 394 as @option{-L} command line switch used by @sc{gnu} sieve utility
395 (@pxref{sieve group}). 395 (@FIXME-pxref{sieve group}).
396 396
397 @node Require Statement 397 @node Require Statement
398 @section Require Statement 398 @section Require Statement
......
1 /* GNU Mailutils -- a suite of utilities for electronic mail 1 /* GNU Mailutils -- a suite of utilities for electronic mail
2 Copyright (C) 2007 Free Software Foundation, Inc. 2 Copyright (C) 2007, 2008 Free Software Foundation, Inc.
3 3
4 This library is free software; you can redistribute it and/or 4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public 5 modify it under the terms of the GNU Lesser General Public
...@@ -25,10 +25,17 @@ ...@@ -25,10 +25,17 @@
25 extern "C" { 25 extern "C" {
26 #endif 26 #endif
27 27
28 struct mu_conf_option
29 {
30 char *name;
31 char *descr;
32 };
33
28 extern char *mu_license_text; 34 extern char *mu_license_text;
29 extern void mu_print_options (void); 35 extern void mu_print_options (void);
30 extern void mu_fprint_options (FILE *fp); 36 extern void mu_fprint_options (FILE *fp);
31 extern const char *mu_check_option (char *name); 37 extern void mu_fprint_conf_option (FILE *fp, const struct mu_conf_option *opt);
38 extern const struct mu_conf_option *mu_check_option (char *name);
32 39
33 #ifdef __cplusplus 40 #ifdef __cplusplus
34 } 41 }
......
...@@ -58,16 +58,21 @@ static struct argp_option mu_common_argp_options[] = ...@@ -58,16 +58,21 @@ static struct argp_option mu_common_argp_options[] =
58 N_("Show compilation options"), 0 }, 58 N_("Show compilation options"), 0 },
59 { "config-help", OPT_HELP_CONFIG, NULL, 0, 59 { "config-help", OPT_HELP_CONFIG, NULL, 0,
60 N_("Show configuration file summary"), 0 }, 60 N_("Show configuration file summary"), 0 },
61 { "no-user-rcfile", OPT_NO_USER_RCFILE, NULL, 0, 61 { "no-user-config", OPT_NO_USER_RCFILE, NULL, 0,
62 N_("Do not load user configuration file"), 0 }, 62 N_("Do not load user configuration file"), 0 },
63 { "no-site-rcfile", OPT_NO_SITE_RCFILE, NULL, 0, 63 { "no-user-rcfile", 0, NULL, OPTION_ALIAS, NULL },
64 { "no-site-config", OPT_NO_SITE_RCFILE, NULL, 0,
64 N_("Do not load site configuration file"), 0 }, 65 N_("Do not load site configuration file"), 0 },
65 { "rcfile", OPT_RCFILE, N_("FILE"), 0, 66 { "no-site-rcfile", 0, NULL, OPTION_ALIAS, NULL },
67 { "config-file", OPT_RCFILE, N_("FILE"), 0,
66 N_("Load this configuration file"), 0, }, 68 N_("Load this configuration file"), 0, },
67 { "rcfile-verbose", OPT_RCFILE_VERBOSE, NULL, 0, 69 { "rcfile", 0, NULL, OPTION_ALIAS, NULL },
70 { "config-verbose", OPT_RCFILE_VERBOSE, NULL, 0,
68 N_("Verbosely log parsing of the configuration files"), 0 }, 71 N_("Verbosely log parsing of the configuration files"), 0 },
69 { "rcfile-lint", OPT_RCFILE_LINT, NULL, 0, 72 { "rcfile-verbose", 0, NULL, OPTION_ALIAS, NULL },
73 { "config-lint", OPT_RCFILE_LINT, NULL, 0,
70 N_("Check configuration file syntax and exit"), 0 }, 74 N_("Check configuration file syntax and exit"), 0 },
75 { "rcfile-lint", 0, NULL, OPTION_ALIAS, NULL },
71 { NULL, 0, NULL, 0, NULL, 0 } 76 { NULL, 0, NULL, 0, NULL, 0 }
72 }; 77 };
73 78
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
21 #endif 21 #endif
22 22
23 #include <mailutils/nls.h> 23 #include <mailutils/nls.h>
24 #include <mailutils/version.h>
24 #include <stdio.h> 25 #include <stdio.h>
25 #include <string.h> 26 #include <string.h>
26 27
...@@ -42,121 +43,130 @@ char *mu_license_text = ...@@ -42,121 +43,130 @@ char *mu_license_text =
42 "\n" 43 "\n"
43 ); 44 );
44 45
45 static char *mu_conf_option[] = { 46 static struct mu_conf_option mu_conf_option[] = {
46 "VERSION=" VERSION, 47 { "VERSION=" VERSION, N_("Version of this package") },
47 #ifdef USE_LIBPAM 48 #ifdef USE_LIBPAM
48 "USE_LIBPAM", 49 { "USE_LIBPAM", N_("PAM support") },
49 #endif 50 #endif
50 #ifdef HAVE_LIBLTDL 51 #ifdef HAVE_LIBLTDL
51 "HAVE_LIBLTDL", 52 { "HAVE_LIBLTDL", N_("a portable `dlopen' wrapper library") },
52 #endif 53 #endif
53 #ifdef WITH_BDB2 54 #ifdef WITH_BDB2
54 "WITH_BDB2", 55 { "WITH_BDB2", N_("Berkeley DB v. 2") },
55 #endif 56 #endif
56 #ifdef WITH_NDBM 57 #ifdef WITH_NDBM
57 "WITH_NDBM", 58 { "WITH_NDBM", },
58 #endif 59 #endif
59 #ifdef WITH_OLD_DBM 60 #ifdef WITH_OLD_DBM
60 "WITH_OLD_DBM", 61 { "WITH_OLD_DBM", N_("Old DBM support") },
61 #endif 62 #endif
62 #ifdef WITH_GDBM 63 #ifdef WITH_GDBM
63 "WITH_GDBM", 64 { "WITH_GDBM", N_("GNU DBM") },
64 #endif 65 #endif
65 #ifdef WITH_GNUTLS 66 #ifdef WITH_GNUTLS
66 "WITH_GNUTLS", 67 { "WITH_GNUTLS", N_("TLS support using GNU TLS") },
67 #endif 68 #endif
68 #ifdef WITH_GSASL 69 #ifdef WITH_GSASL
69 "WITH_GSASL", 70 { "WITH_GSASL", N_("SASL support using GNU SASL") },
70 #endif 71 #endif
71 #ifdef WITH_GSSAPI 72 #ifdef WITH_GSSAPI
72 "WITH_GSSAPI", 73 { "WITH_GSSAPI", N_("GSSAPI support") },
73 #endif 74 #endif
74 #ifdef WITH_GUILE 75 #ifdef WITH_GUILE
75 "WITH_GUILE", 76 { "WITH_GUILE", N_("Support for Guile as extension language") },
76 #endif 77 #endif
77 #ifdef WITH_PTHREAD 78 #ifdef WITH_PTHREAD
78 "WITH_PTHREAD", 79 { "WITH_PTHREAD", N_("Support for POSIX threads") },
79 #endif 80 #endif
80 #ifdef WITH_READLINE 81 #ifdef WITH_READLINE
81 "WITH_READLINE", 82 { "WITH_READLINE", N_("GNU Readline") },
82 #endif 83 #endif
83 #ifdef HAVE_MYSQL 84 #ifdef HAVE_MYSQL
84 "HAVE_MYSQL", 85 { "HAVE_MYSQL", N_("MySQL") },
85 #endif 86 #endif
86 #ifdef HAVE_PGSQL 87 #ifdef HAVE_PGSQL
87 "HAVE_PGSQL", 88 { "HAVE_PGSQL", N_("PostgreSQL") },
88 #endif 89 #endif
89 #ifdef WITH_LDAP 90 #ifdef WITH_LDAP
90 "WITH_LDAP", 91 { "WITH_LDAP", },
91 #endif 92 #endif
92 #ifdef ENABLE_VIRTUAL_DOMAINS 93 #ifdef ENABLE_VIRTUAL_DOMAINS
93 "ENABLE_VIRTUAL_DOMAINS", 94 { "ENABLE_VIRTUAL_DOMAINS", N_("Support for virtual mail domains") },
94 #endif 95 #endif
95 #ifdef ENABLE_IMAP 96 #ifdef ENABLE_IMAP
96 "ENABLE_IMAP", 97 { "ENABLE_IMAP", N_("IMAP4D protocol support") },
97 #endif 98 #endif
98 #ifdef ENABLE_POP 99 #ifdef ENABLE_POP
99 "ENABLE_POP", 100 { "ENABLE_POP", N_("POP3D protocol support") },
100 #endif 101 #endif
101 #ifdef ENABLE_MH 102 #ifdef ENABLE_MH
102 "ENABLE_MH", 103 { "ENABLE_MH", N_("MH mail storage support") },
103 #endif 104 #endif
104 #ifdef ENABLE_MAILDIR 105 #ifdef ENABLE_MAILDIR
105 "ENABLE_MAILDIR", 106 { "ENABLE_MAILDIR", N_("Maildir mail storage support") },
106 #endif 107 #endif
107 #ifdef ENABLE_SMTP 108 #ifdef ENABLE_SMTP
108 "ENABLE_SMTP", 109 { "ENABLE_SMTP", N_("SMTP protocol support") },
109 #endif 110 #endif
110 #ifdef ENABLE_SENDMAIL 111 #ifdef ENABLE_SENDMAIL
111 "ENABLE_SENDMAIL", 112 { "ENABLE_SENDMAIL", N_("Sendmail command line interface support")},
112 #endif 113 #endif
113 #ifdef ENABLE_NNTP 114 #ifdef ENABLE_NNTP
114 "ENABLE_NNTP", 115 { "ENABLE_NNTP", N_("NNTP protocol support") },
115 #endif 116 #endif
116 #ifdef ENABLE_RADIUS 117 #ifdef ENABLE_RADIUS
117 "ENABLE_RADIUS", 118 { "ENABLE_RADIUS", N_("RADIUS protocol support") },
118 #endif 119 #endif
119 #ifdef WITH_INCLUDED_LIBINTL 120 #ifdef WITH_INCLUDED_LIBINTL
120 "WITH_INCLUDED_LIBINTL", 121 { "WITH_INCLUDED_LIBINTL", N_("GNU libintl compiled in") },
121 #endif 122 #endif
122 NULL 123 { NULL }
123 }; 124 };
124 125
125 void 126 void
127 mu_fprint_conf_option (FILE *fp, const struct mu_conf_option *opt)
128 {
129 fprintf (fp, "%s", opt->name);
130 if (opt->descr)
131 fprintf (fp, "\t- %s", _(opt->descr));
132 fputc('\n', fp);
133 }
134
135 void
126 mu_fprint_options (FILE *fp) 136 mu_fprint_options (FILE *fp)
127 { 137 {
128 int i; 138 int i;
129 139
130 for (i = 0; mu_conf_option[i]; i++) 140 for (i = 0; mu_conf_option[i].name; i++)
131 fprintf (fp, "%s\n", mu_conf_option[i]); 141 mu_fprint_conf_option (fp, mu_conf_option + i);
132 } 142 }
133 143
134 void 144 void
135 mu_print_options (FILE *fp) 145 mu_print_options ()
136 { 146 {
137 mu_fprint_options (stdout); 147 mu_fprint_options (stdout);
138 } 148 }
139 149
140 const char * 150 const struct mu_conf_option *
141 mu_check_option (char *name) 151 mu_check_option (char *name)
142 { 152 {
143 int i; 153 int i;
144 154
145 for (i = 0; mu_conf_option[i]; i++) 155 for (i = 0; mu_conf_option[i].name; i++)
146 { 156 {
147 int len; 157 int len;
148 char *q, *p = strchr (mu_conf_option[i], '='); 158 char *q, *p = strchr (mu_conf_option[i].name, '=');
149 if (p) 159 if (p)
150 len = p - mu_conf_option[i]; 160 len = p - mu_conf_option[i].name;
151 else 161 else
152 len = strlen (mu_conf_option[i]); 162 len = strlen (mu_conf_option[i].name);
153 163
154 if (strncasecmp (mu_conf_option[i], name, len) == 0) 164 if (strncasecmp (mu_conf_option[i].name, name, len) == 0)
155 return mu_conf_option[i]; 165 return &mu_conf_option[i];
156 else if ((q = strchr (mu_conf_option[i], '_')) != NULL 166 else if ((q = strchr (mu_conf_option[i].name, '_')) != NULL
157 && strncasecmp (q + 1, name, 167 && strncasecmp (q + 1, name,
158 len - (q - mu_conf_option[i]) - 1) == 0) 168 len - (q - mu_conf_option[i].name) - 1) == 0)
159 return mu_conf_option[i]; 169 return &mu_conf_option[i];
160 } 170 }
161 return NULL; 171 return NULL;
162 } 172 }
......
...@@ -370,12 +370,13 @@ proc mu_version {} { ...@@ -370,12 +370,13 @@ proc mu_version {} {
370 } 370 }
371 371
372 set output [remote_exec host "$MU_TOOL --show-config-options"] 372 set output [remote_exec host "$MU_TOOL --show-config-options"]
373 set flg [split [lindex $output 1]] 373 set flg [split [lindex $output 1] "\n"]
374 for {set i 0} {$i < [llength $flg]} {incr i} { 374 for {set i 0} {$i < [llength $flg]} {incr i} {
375 if [regexp "(.*)=(.*)" [lindex $flg $i] var name value] { 375 regsub "(\t.*)?\r" [lindex $flg $i] "" string
376 if [regexp "(.*)=(.*)" $string var name value] {
376 set MU_CAPABILITY($name) $value 377 set MU_CAPABILITY($name) $value
377 } else { 378 } elseif {$string != ""} {
378 set MU_CAPABILITY([lindex $flg $i]) 1 379 set MU_CAPABILITY($string) 1
379 } 380 }
380 } 381 }
381 if [info exists MU_CAPABILITY(VERSION)] { 382 if [info exists MU_CAPABILITY(VERSION)] {
......