diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2002-12-13 15:52:11 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2002-12-13 15:52:11 +0000 |
commit | f3c0fbdc796a3d0c834df77810b6b2ee3d0d441d (patch) | |
tree | 136e58747b1b6a076cd8237813705769def9d46b /doc | |
parent | c197054dc521cb1dab7faf27ab3e48acbeba9a93 (diff) | |
download | mailutils-f3c0fbdc796a3d0c834df77810b6b2ee3d0d441d.tar.gz mailutils-f3c0fbdc796a3d0c834df77810b6b2ee3d0d441d.tar.bz2 |
Updated
Diffstat (limited to 'doc')
-rw-r--r-- | doc/texinfo/framework.texi | 15 | ||||
-rw-r--r-- | doc/texinfo/libsieve.texi | 34 | ||||
-rw-r--r-- | doc/texinfo/mailutils.texi | 58 | ||||
-rw-r--r-- | doc/texinfo/programs.texi | 121 |
4 files changed, 151 insertions, 77 deletions
diff --git a/doc/texinfo/framework.texi b/doc/texinfo/framework.texi index c92399099..bc772c90a 100644 --- a/doc/texinfo/framework.texi +++ b/doc/texinfo/framework.texi @@ -20,10 +20,11 @@ * Parse822:: Parsing RFC 822 headers @end menu -Wherever the mail is and whatever format it is stored in, the same operations -to manipulate emails are common. To unified the C API, GNU mailutils offers -a heteroclite set of objects that work in aggregation to do operations on -emails. Each object do a specific task and delegates non related tasks to +Wherever the mail is and whatever format it is stored in, it is operated +upon using the same set of functions. To unified the C API, +@sc{gnu} Mailutils offers a heteroclite set of objects that work in +aggregation to do operations on +emails. Each object does a specific task and delegates non-related tasks to others. The object comes alive by specifying a @emph{URL} parameter when created, it will indicate the storage format or protocol (POP3, IMAP4, MH, MAILDIR, etc ..). @@ -67,13 +68,15 @@ created, it will indicate the storage format or protocol @end group @end example -For example writing a simple @code{from} command that will list the -@emph{From} and @emph{Subject} headers of every mail in a mailbox. +As an example, here is a simplified version of @code{from} command. It +lists the @samp{From} and @samp{Subject} headers of every mail in a mailbox. @example @include sfrom.inc @end example +Here is a sample output produced by this program: + @example @cartouche % MAIL=pop://alain@@localhost ./sfrom diff --git a/doc/texinfo/libsieve.texi b/doc/texinfo/libsieve.texi index 343786636..653a7f225 100644 --- a/doc/texinfo/libsieve.texi +++ b/doc/texinfo/libsieve.texi @@ -3,7 +3,7 @@ @c See file mailutils.texi for copying conditions. @comment ******************************************************************* -This chapter describes GNU Sieve library. +This chapter describes @sc{gnu} Sieve library. @menu * Library Description:: @@ -587,7 +587,7 @@ Dump the disassembled code of the sieve machine @var{mach}. @node Input Language @section Input Language -The input language understood by the GNU Sieve Library is a superset of +The input language understood by the @sc{gnu} Sieve Library is a superset of the Sieve language as described in RFC 3028. @menu @@ -600,13 +600,13 @@ the Sieve language as described in RFC 3028. @end menu @node Syntax -@subsection +@subsection Syntax @node Preprocessor @subsection Preprocessor -@cindex Sieve preprocessor statements, a GNU extension +@cindex Sieve preprocessor statements, a @sc{gnu} extension -The preprocessor statements are a GNU extension to the Sieve language. +The preprocessor statements are a @sc{gnu} extension to the Sieve language. The syntax for a preprocessor statement is similar to that used in @code{C} programming language, i.e.: a pound character (@samp{#}) followed by a preprocessor directive and any arguments. Any amount of @@ -644,7 +644,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 GNU sieve utility +as @option{-L} command line switch used by @sc{gnu} sieve utility (@pxref{sieve group}). @node Require Statement @@ -672,7 +672,7 @@ Otherwise, the capability is understood as a name of an action to be used. The @code{require} statement, if present, must be used before any other -statement that is using the required capability. As an extension, the GNU +statement that is using the required capability. As an extension, the @sc{gnu} sieve allows the @code{require} and any other statements to be interspersed. @@ -695,7 +695,7 @@ require "fileinto"; require "comparator-i;ascii-numeric"; @end example -When processing arguments for @code{require} statement, GNU libsieve +When processing arguments for @code{require} statement, @sc{gnu} libsieve uses the following algorithm: @enumerate 1 @@ -765,7 +765,7 @@ source for the required action NAME is not available @node Comparators @subsection Comparators -GNU libsieve supports the following built-in comparators: +@sc{gnu} libsieve supports the following built-in comparators: @table @code @item i;octet @@ -784,7 +784,7 @@ be explicitly required prior to use. @node Tests @subsection Tests -This section describes the built-in tests supported by GNU libsieve. +This section describes the built-in tests supported by @sc{gnu} libsieve. In the discussion below the following macro-notations are used: @table @var @@ -961,7 +961,7 @@ If the argument is @samp{:under}, and the size of the message is less than the @var{number}, the test is true; otherwise, it is false. Otherwise, the test is true only if the size of the message equals -exactly @var{number}. This is a GNU extension. +exactly @var{number}. This is a @sc{gnu} extension. The size of a message is defined to be the number of octets from the initial header until the last character in the message body. @@ -1036,7 +1036,7 @@ if not exists ["From","Date"] @end example @end deffn -@deffn header [@var{comparator}] [@var{match-type}] [:mime] @var{header-names} @var{key-list} +@deffn Test header [@var{comparator}] [@var{match-type}] [:mime] @var{header-names} @var{key-list} @sp 1 @noindent Tagged arguments: @@ -1112,7 +1112,7 @@ If the tagged argument is not given, @samp{:over} is assumed. @node Actions @subsection Actions -The GNU libsieve supports the following default actions: +The @sc{gnu} libsieve supports the following default actions: @itemize @item stop @@ -1273,7 +1273,7 @@ the old message in a new one. @node Extensions @section Extensions -This section summarizes the GNU extensions to the sieve language +This section summarizes the @sc{gnu} extensions to the sieve language @enumerate 1 @@ -1281,7 +1281,7 @@ This section summarizes the GNU extensions to the sieve language @itemize @item According to the RFC an error must occur if a @code{require} appears -after a command other than @code{require}. The GNU sieve library allows +after a command other than @code{require}. The @sc{gnu} sieve library allows interspersing the @code{require} and other statements. The only requirement is that @code{require} must occur before a statement that is using the required capability (@pxref{Require Statement}). @@ -1309,7 +1309,7 @@ may disappear from the subsequent releases. @item Match type optional argument. Along with the usual @code{:is}, @code{:matches} and @code{contains} -matching type, GNU sieve library understands @code{:regex} type. This +matching type, @sc{gnu} sieve library understands @code{:regex} type. This matching type toggles POSIX Extended Regular Expression matching. @end enumerate @@ -1318,7 +1318,7 @@ matching type toggles POSIX Extended Regular Expression matching. @section Writing Loadable Commands This section contains an example of how to write external loadable -commands for GNU libsieve. +commands for @sc{gnu} libsieve. @example @include numaddr.inc diff --git a/doc/texinfo/mailutils.texi b/doc/texinfo/mailutils.texi index 9e1239c8d..e503d7d63 100644 --- a/doc/texinfo/mailutils.texi +++ b/doc/texinfo/mailutils.texi @@ -40,8 +40,9 @@ * pop3d: (mailutils)pop3d. POP3 daemon * readmsg: (mailutils)readmsg. Extract messages from a folder * sieve: (mailutils)sieve. Mail filtering utility +* mailutils-config: (mailutils)mailutils-config. Get the information about the Mailutils build. @end direntry -This file documents @sc{mailutils}, library API. +This file documents Mailutils, library API. Published by the Free Software Foundation, @@ -75,13 +76,13 @@ by the Foundation. @setchapternewpage off @titlepage -@title mailutils, SDK. +@title Mailutils, SDK. @subtitle version @value{VERSION}, @value{UPDATED} @author Alain Magloire et al. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc. +Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, Inc. @sp 2 Published by the Free Software Foundation, @* @@ -113,21 +114,22 @@ by the Foundation. @ifinfo This document was produced for version @value{VERSION} of @sc{gnu} -@sc{mailutils}. +Mailutils. @end ifinfo @menu -* Introduction:: GNU @sc{mailutils} +* Introduction:: GNU Mailutils @comment * Concrete API:: Concrete API. * Framework:: Framework. -* Authentication Library:: -* Sieve Library:: +* Authentication Library:: Auxiliary library for authenticating users. +* Sieve Library:: GNU implementation of Sieve mail filtering. * Programs:: Programs. -* Reporting Bugs:: Reporting Bugs. +* Reporting Bugs:: How to report a bug. +* News:: Where to get information about @sc{gnu} Mailutils * Acknowledgement:: Thanks and Credits. Indices -* Function Index:: All @sc{Mailutils} Functions. -* Program Index:: All @sc{Mailutils} Programs. +* Function Index:: All Mailutils Functions. +* Program Index:: All Mailutils Programs. * Concept Index:: Index of Concepts. @end menu @@ -137,7 +139,7 @@ Indices @chapter Introduction @cindex Introduction -@sc{gnu} @sc{Mailutils} offers a general purpose library whose aim is to +@sc{gnu} Mailutils offers a general purpose library whose aim is to provide a rich set of functions for accessing different mailbox formats and mailers. @@ -290,15 +292,39 @@ Notifications} @include programs.texi @page -@node Reporting Bugs, Acknowledgement, Programs, Top +@node Reporting Bugs, News, Programs, Top @comment node-name, next, previous, up @chapter Reporting Bugs @cindex Reporting Bugs Email bug reports to @email{bug-mailutils@@gnu.org}. -Be sure to include the word ``mailutils'' somewhere in the ``Subject:'' field. +Be sure to include the word ``mailutils'' somewhere in the ``Subject:'' +field. -@node Acknowledgement, Function Index , Reporting Bugs, Top +As the purpose of bug reporting is to improve software, please be sure +to include maximum information when reporting a bug. The information +needed is: + +@itemize +@item Version of the package you are using. +@item Compilation options used when configuring the package. +@item Conditions under which the bug appears. +@end itemize + +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 +@chapter Getting news about @sc{gnu} mailutils + +The two places to look for any news regarding @sc{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, Function Index , News, Top @comment node-name, next, previous, up @chapter Acknowledgement @cindex Acknowledgement @@ -324,6 +350,8 @@ Sam Roberts @email{sroberts@@uniserve.com}, Sergey Poznyakoff @email{gray@@Mirddin.farlep.net}, @item Fran@,{c}ois Pinard @email{pinard@@IRO.UMontreal.CA}. +@item +Jordi Mallach @email{jordi@@sindominio.net} @end itemize @page @@ -331,7 +359,7 @@ Fran@,{c}ois Pinard @email{pinard@@IRO.UMontreal.CA}. @comment node-name, next, previous, up @unnumbered Function Index -This is an alphabetical list of all @sc{mailutils} functions. +This is an alphabetical list of all Mailutils functions. @printindex fn @page diff --git a/doc/texinfo/programs.texi b/doc/texinfo/programs.texi index 88147721b..f817df50a 100644 --- a/doc/texinfo/programs.texi +++ b/doc/texinfo/programs.texi @@ -3,7 +3,7 @@ @c See file mailutils.texi for copying conditions. @comment ******************************************************************* -GNU Mailutils provides a set of programs for handling the email. +@sc{gnu} Mailutils provides a set of programs for handling the email. @menu * authentication:: Authorization and authentication principles. @@ -18,7 +18,7 @@ GNU Mailutils provides a set of programs for handling the email. * sieve:: Mail filtering utility. * guimb:: Mailbox scanning and processing language. * comsatd:: Comsat daemon. -* mailutils-config:: Get the information about the mailutils build. +* mailutils-config:: Get the information about the Mailutils build. @end menu @page @@ -130,9 +130,9 @@ the list of authorization modules is: 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 +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 +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: @@ -170,15 +170,15 @@ 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 +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 +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 +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) @@ -195,19 +195,19 @@ whitespace, it should be enclosed in a pair of quotes (either double or single quotes). @menu -* default:: Options understood by most GNU utilities. +* default:: 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. * logging:: Logging control options. -* sieve:sieve group. Sieve specific options +* sieve: sieve group. Sieve specific options * config sample:: A sample configuration file. @end menu @node default -@subsection default --- Options understood by most GNU utilities. +@subsection default --- Options understood by most @sc{gnu} utilities. Each program also understands the following informational options: @@ -220,7 +220,7 @@ Display a short usage message and exit. Display help message and exit. @item -L @itemx --license -Display GNU General Public License and exit. +Display @sc{gnu} General Public License and exit. @item -v @itemx --version Display program version and exit. @@ -418,7 +418,7 @@ library files. @subsection A sample configuration file. @cindex mailutils.rc, an example -The following configuration file specifies that all mailutils programs +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 @@ -439,7 +439,7 @@ imap4d --daemon=20 --timeout=1800 --log-facility local1 @section IMAP4 daemon @pindex imap4d -GNU imap4d is a daemon implementing @sc{imap4} rev1 protocol for +@sc{gnu} imap4d is a daemon implementing @sc{imap4} rev1 protocol for accessing and handling electronic mail messages on a server. It can be run either as a standalone program or from @file{inetd.conf} file. @@ -453,7 +453,7 @@ be run either as a standalone program or from @file{inetd.conf} file. @cindex namespace @cindex IMAP4 namespace -GNU imap4d supports a notion of @dfn{namespaces} defined in RFC 2342. A +@sc{gnu} imap4d supports a notion of @dfn{namespaces} defined in RFC 2342. A namespace is a set of directories upon which the user has certain permissions. It should be understood that these persmissions apply only if the underlying filesystem allows them. @@ -488,8 +488,10 @@ The home directory of the user, if exists. @item Other Users' Namespace Empty + @item Shared Namespace Empty + @end table @emph{Note}, that this means that by default, a user won't be able to @@ -1214,8 +1216,10 @@ If @var{mailbox} is omitted, the command prints the current mailbox name followed by the summary information regarding it, e.g.: @example +@cartouche & fold "/var/spool/mail/gray": 23 messages 22 unread +@end cartouche @end example @end table @@ -1283,8 +1287,10 @@ Displays the value of @code{folder} variable. Displays current mailbox summary. E.g.: @example +@cartouche & summary "/var/spool/mail/gray": 23 messages 22 unread +@end cartouche @end example @end table @@ -1315,6 +1321,7 @@ For detailed description of ignored header lists, see @ref{Controlling Header Di Print a multipart message. The @code{decode} command decodes and prints out specified message parts. E.g. @example +@cartouche & decode 15[2] +--------------------------------------- | Message=15[2] @@ -1323,6 +1330,7 @@ out specified message parts. E.g. +--------------------------------------- Content-Type: message/delivery-status ... +@end cartouche @end example @item top [@var{msglist}] @itemx to [@var{msglist}] @@ -1397,11 +1405,13 @@ sender of the first message in @var{msglist}. For example: @example @group +@cartouche & from 14 15 U 14 smith@@noldor.org Fri Jun 30 18:11 14/358 The Save c U 15 gray@@noldor.org Fri Jun 30 18:30 8/245 Re: The Sa & Save 14 15 "smith" 22/603 +@end cartouche @end group @end example @noindent @@ -1650,7 +1660,7 @@ command can also be spelled as @code{!}. @node Mail Variables @subsection How to alter the behavior of mail -Following variables control the behavior of GNU @command{mail}: +Following variables control the behavior of @sc{gnu} @command{mail}: @table @code @item Sign @@ -1945,8 +1955,9 @@ and appends the received data to the local mailboxes. @menu * Invocation:: Mail.local options * MTA:: Using mail.local with various MTAs -* Mailbox Quotas:: Setting up mailbox quotas. -* Filters:: Implementing user-defined mail filters. +* Mailbox Quotas:: Setting up mailbox quotas. +* Sieve Filters:: Implementing user-defined Sieve mail filters. +* Scheme Filters:: Implementing user-defined Scheme mail filters. @end menu @node Invocation @@ -1969,7 +1980,7 @@ creates the envelope by using current user name and date. Display this help and exit. @item -L @itemx --license -Display GNU General Public License and exit. +Display @sc{gnu} General Public License and exit. @item -m @var{path} @itemx --mail-spool @var{path} Specify path to mailspool directory. @@ -1978,7 +1989,17 @@ Specify path to mailspool directory. Specify path to mailbox quota database (@pxref{Mailbox Quotas}). @item -s @var{pattern} @itemx --source @var{pattern} -Set name pattern for user-defined mail filters (@pxref{Filters}). The +Set name pattern for user-defined mail filters written in Scheme +(@pxref{Scheme Filters}). The +metacharacters @samp{%u} and @samp{%h} in the pattern are expanded to +the current recipient user name and home directory correspondingly. + +This option is available only if the package has been configured to +use Guile extension language. +@item -S @var{pattern} +@itemx --sieve @var{pattern} +Set name pattern for user-defined mail filters written is Sieve +(@pxref{Sieve Filters}). The metacharacters @samp{%u} and @samp{%h} in the pattern are expanded to the current recipient user name and home directory correspondingly. @item -t @var{number} @@ -1986,13 +2007,32 @@ the current recipient user name and home directory correspondingly. Wait @var{number} seconds for acquiring the lockfile. If it doesn't become available after that amount of time, return failure. The timeout defaults to 5 minutes. -@item -x guile -@itemx --debug guile +@item -x @var{flags} +@itemx --debug @var{flags} +Enable debugging. The debugging information will be output using syslog. +The @var{flags} is a string consisting of the following flags: +Debug flags are: + +@table @samp +@item g Start with guile debugging evaluator and backtraces. This is convenient -for debugging user-defined filters (@pxref{Filters}). -@item -x @var{number} -@itemx --debug @var{number} -Set debugging level. +for debugging user-defined filters (@pxref{Scheme Filters}). + +@item T +Enable libmailutil traces (MU_DEBUG_TRACE). + +@item P +Enable network protocol traces (MU_DEBUG_PROT) + +@item t +Enable sieve trace (MU_SIEVE_DEBUG_TRACE) + +@item l +Enble sieve action logs +@end table + +The digits in the range @samp{0} -- @samp{9} used in @var{flags} set +@command{mail.local} debugging level. @item -v @itemx --version Display program version and exit. @@ -2080,8 +2120,11 @@ mail_local: @node Mailbox Quotas @subsection Setting up mailbox quotas -@node Filters -@subsection Implementing user-defined mail filters. +@node Sieve Filters +@subsection Implementing user-defined Sieve mail filters. + +@node Scheme Filters +@subsection Implementing user-defined Scheme mail filters. @page @node messages @@ -2197,7 +2240,7 @@ Default is --weedlist=''From Subject Date To CC Apparently-'' @pindex sieve Sieve is a language for filtering e-mail messages at time of final -delivery, described in RFC 3028. GNU mailutils provides two +delivery, described in RFC 3028. @sc{gnu} Mailutils provides two implementations of this language: a stand-alone @dfn{sieve interpreter} and a @dfn{sieve translator and filter}. The following sections describe these utilities in detail. @@ -2211,10 +2254,10 @@ utilities in detail. @subsection A Sieve Interpreter Sieve interpreter @command{sieve} allows to apply Sieve scripts to an -arbitrary number of mailboxes. GNU @command{sieve} implements a superset +arbitrary number of mailboxes. @sc{gnu} @command{sieve} implements a superset of the Sieve language as described in RFC 3028. @xref{Input Language}, for a description of the Sieve language. @xref{Extensions}, for a -discussion of differences between the GNU implementation of Sieve and +discussion of differences between the @sc{gnu} implementation of Sieve and its standard. @menu @@ -3067,13 +3110,13 @@ $B(,5)\ @page @node mailutils-config -@section mailutils-config --- Get the information about the mailutils build. +@section mailutils-config --- Get the information about the Mailutils build. @pindex mailutils-config This program is designed for developers wishing to link their programs against libmailbox. It allows to examine the particulars of the -current build of mailutils and to get the command line parameters -necessary for compiling and linking an application with mailutils +current build of Mailutils and to get the command line parameters +necessary for compiling and linking an application with Mailutils libraries. @menu @@ -3088,7 +3131,7 @@ libraries. When invoked with the option @option{--compile}, or its short form @option{-c}, @command{mailutils-config} prints the flags that must be given to the compiler for compiling the program using -mailutils functions. An example usage: +Mailutils functions. An example usage: @example cc -omyprog.o `mailutils-config --compile` myprog.c @@ -3099,10 +3142,10 @@ cc -omyprog.o `mailutils-config --compile` myprog.c The @option{--link}, or its short form @option{-l} prints to the standard output the loader flags necessary to link a program against -mailutils libraries. +Mailutils libraries. When invoked without arguments, it produces the flags necessary to -link against the basic library of mailutils: @file{libmailbox}. +link against the basic library of Mailutils: @file{libmailbox}. Up to two arguments may be given that alter this behavior. These are: @@ -3126,7 +3169,7 @@ cc -omyprog myprog.o `mailutils-config --link auth guile` @subsection Obtaining General Build Information The @option{--info}, or @option{-i} retrieves the options (flags) used -when building mailutils. It may be used with or without +when building Mailutils. It may be used with or without arguments. When used without arguments, it prints the list of all @@ -3199,11 +3242,11 @@ The flags and their meanings are: @table @asis @c @item VERSION=" VERSION, @item USE_LIBPAM -The mailutils uses @sc{pam} libraries. +The Mailutils uses @sc{pam} libraries. @item HAVE_LIBLTDL The @sc{gnu} wrapper library @file{libltdl} is present and is used -by mailutils. @xref{Using libltdl,,,libtool,Using libltdl}, for +by Mailutils. @xref{Using libltdl,,,libtool,Using libltdl}, for more information on @file{libltdl} library. |