dovecot-2.0-pigeonhole: Sieve-filter: updated man page.

[pigeonhole at rename-it.nl]

details:   http://hg.rename-it.nl/dovecot-2.0-pigeonhole/rev/37f5c82f33c2
changeset: 1438:37f5c82f33c2
user:      Stephan Bosch <stephan at rename-it.nl>
date:      Thu Sep 30 23:21:54 2010 +0200
description:
Sieve-filter: updated man page.

diffstat:

 doc/man/sieve-filter.1.in |  247 +++++++++++++++++++++++++++----------------------
 1 files changed, 137 insertions(+), 110 deletions(-)

diffs (300 lines):

diff -r 0828e3600eec -r 37f5c82f33c2 doc/man/sieve-filter.1.in
--- a/doc/man/sieve-filter.1.in	Thu Sep 30 21:11:34 2010 +0200
+++ b/doc/man/sieve-filter.1.in	Thu Sep 30 23:21:54 2010 +0200
@@ -1,84 +1,70 @@
-.TH "SIEVE\-FILTER" "1" "11 July 2010"
+.\" Copyright (c) 2010 Pigeonhole authors, see the included COPYING file
+.TH "SIEVE-FILTER" 1 "2010-09-20" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
 .SH NAME
-sieve\-filter \- Sieve mailbox filter tool for the Dovecot secure IMAP server
+sieve\-filter \- Pigeonhole\(aqs Sieve mailbox filter tool
+
 .PP
-\fBWARNING: \fRThis tool is not finished and should \fB*NOT*\fR be used, unless you feel like testing newly developed
-features! The behavior described in this manual page represents the design and not necessarily what the tool currently implements.
-
+\fBWARNING: \fRThis tool is not finished and should \fB*NOT*\fR be used, unless
+you feel like testing newly developed features! The behavior described in this
+manual page represents the design and not necessarily what the tool currently
+implements.
+.\"------------------------------------------------------------------------
 .SH SYNOPSIS
-sieve\-filter [\fB\-c\fR \fIconfig\-file\fR] [\fIoptions\fR] \fIscript\-file\fR \fIsource\-location\fR \fIsource\-mailbox\fR [\fIinbox\-namespace\fR [\fInamespace\fR ...]]
-.TP
-\fInamepace\fR = [prefix=]location[;option=value,option=value,...]
-.TP
-[FIXME: what would be the easiest way to specify a filter operation without always needing to
-delve into the complexity of namespaces]
-
+.B sieve\-filter
+.RI [ options ]
+.I script\-file
+.I source\-mailbox
 .SH DESCRIPTION
 .PP
-The \fBsieve\-filter\fP command is part of the Pigeonhole Sieve implementation for the Dovecot secure 
-IMAP server. Sieve (RFC 5228) is a simple and highly extensible language for filtering 
-e\-mail messages. It can be implemented for any type of mail access protocol, mail 
-architecture and operating system. The language cannot execute external programs and in 
-its basic form it does not provide the means to cause infinite loops, making it suitable 
-for running securely on mail servers where mail users have no permission run arbitrary programs.
+The \fBsieve\-filter\fP command is part of the Pigeonhole Project
+(\fBpigeonhole\fR(7)), which adds Sieve (RFC 5228) support to the Dovecot
+secure IMAP and POP3 server (\fBdovecot\fR(1)).
 .PP
-The Sieve language was originally meant for filtering messages upon delivery. However, there are
-occasions when it is desirable to filter messages that are already stored in a mailbox, for
-instance when a bug in a Sieve script caused many messages to be delivered incorrectly.
-Using the sieve\-filter tool it is possible to apply a Sieve script on all messages in a particular
-mailbox, making it possible to delete messages, to store them in a different folder and to change
-the assigned IMAP flags and keywords. Attempts to send messages to the outside world are ignored by default
-for obvious reasons, but, using the proper command line options, it is possible to capture outgoing
-mail as well. 
+The Sieve language was originally meant for filtering messages upon delivery. 
+However, there are occasions when it is desirable to filter messages that are
+already stored in a mailbox, for instance when a bug in a Sieve script caused
+many messages to be delivered incorrectly. Using the sieve\-filter tool it is
+possible to apply a Sieve script on all messages in a particular mailbox, making
+it possible to delete messages, to store them in a different folder and to
+change the assigned IMAP flags and keywords. Attempts to send messages to the
+outside world are ignored by default for obvious reasons, but, using the proper
+command line options, it is possible to capture outgoing mail as well. 
 .PP
-The command has three mandatory arguments: the \fIscript\-file\fP argument, which specifies the path of the
-Sieve script, the \fIsource\-location\fP argument, which specifies the mail storage of the source mailbox 
-(e.g. `maildir:~/Maildir'), and the \fIsoure\-mailbox\fP argument, which specifies the name of the source 
-mailbox within the specified mail storage (e.g. `INBOX.Spam'). 
-.PP
-This tool does not (yet) use Dovecot's configuration file to obtain information on namespaces and the
-location of mailboxes. Therefore, any used namespaces need to be specified on the command line. These
-specifications directly follow the \fIsource\-mailbox\fP parameter. The first specified namespace will
-be the INBOX namespace.
-.PP
-If no namespaces are defined on the commandline, the source\-location is used as the default mail store
-where the INBOX is located. This means that the keep action could operate on the folder the message
-originates from. In this case the message remains untouched and it is not duplicated, but IMAP flags and
-keywords can be evaluated and changed with the imap4flags extension . If namespaces are defined explicitly, 
-the source location is available as a namespace with prefix `#src/'. 
-.PP
-If no options are specified, the sieve\-filter command runs in a simulation mode in which it only 
-prints what would be performed, without actually doing anything. Use the \fB\-e\fP option to activate
-true script execution. Also, the source mailbox is opened read\-only by default, so that the source mailbox
+If no options are specified, the sieve\-filter command runs in a simulation mode
+in which it only prints what would be performed, without actually doing
+anything. Use the \fB\-e\fP option to activate true script execution. Also, the
+source mailbox is opened read\-only by default, so that the source mailbox 
 remains unchanged. Use the \fB\-W\fP to allow changes in the source mailbox. 
-
-.SH CAUTION
-Although this is a very useful tool, it can also be very destructive when used improperly. A small 
-bug in your Sieve script in combination with the wrong command line options could cause it to 
-discard (many) more e\-mails than it was supposed to. Therefore, users are advised to read this manual
-carefully and to use the simulation mode first to check what the script will do. 
+.SS CAUTION
+Although this is a very useful tool, it can also be very destructive when used
+improperly. A small bug in your Sieve script in combination with the wrong
+command line options could cause it to discard the wrong e\-mails. Therefore, 
+users are advised to read this manual carefully and to use the simulation mode 
+first to check what the script will do. 
 .PP
 \fBMAKING A BACKUP IS IMPERATIVE FOR ANY IMPORTANT MAIL!\fP
 .PP
-By default, it will open the source mailbox in a read\-only mode, such that it will not delete any of your
-e\-mails. However, it can still litter other mailboxes with spurious copies of your e\-mails if your
-Sieve script decides to do so.
-
+By default, it will open the source mailbox in a read\-only mode, such that it
+will not delete any of your e\-mails. However, it can still litter other
+mailboxes with spurious copies of your e\-mails if your Sieve script decides to
+do so.
+.\"------------------------------------------------------------------------
 .SH OPTIONS
 .TP
-\fB\-c\fP \fIconfig\-file\fP
+.BI \-c\  config\-file
 Alternative Dovecot configuration file path.
 .TP 
-\fB\-D\fP \fIsource\-action\fP
-By default, the sieve\-filter command does not delete the messages from the source mailbox. This means that
-a copy operation is executed by default and the source mailbox is not altered. The \fIsource\-action\fP
-parameter of the \fB\-D\fP option can take four different values:
+.BI \-D\  source\-action
+By default, the sieve\-filter command does not delete the messages from the
+source mailbox. This means that a copy operation is executed by default and the
+source mailbox is not altered. The \fIsource\-action\fP parameter of the 
+\fB\-D\fP option can take four different values:
 .RS 7
 .TP 
 \fBkeep\fP (default)
-Keep messages in source folder. If \fB\-W\fR is specified and the source mailbox is the destination of
-a keep or fileinto action, flags can be changed by the Sieve script. Messages are never duplicated in the
-source mailbox.
+Keep messages in source folder. If \fB\-W\fR is specified and the source mailbox
+is the destination of a keep or fileinto action, flags can be changed by the
+Sieve script. Messages are never duplicated in the source mailbox.
 .TP 
 \fBflag\fP
 Flag messages as \\DELETED.
@@ -87,54 +73,79 @@
 Move messages to the indicated \fIfolder\fP.
 .TP 
 \fBexpunge\fP
-Expunge messages, meaning that these are removed irreversibly when the tool finishes filtering.
+Expunge messages, meaning that these are removed irreversibly when the tool
+finishes filtering.
 .PP
-Note that values other than `keep' have no effect, unless the \fB\-W\fP option is specified as well.
+Note that values other than `keep' have no effect, unless the \fB\-W\fP option
+is specified as well.
 .RE
 .TP
-\fB\-e\fP
-Turns on execution mode. By default, the sieve\-filter command runs in simulation mode in which it 
-changes nothing, meaning that no mailbox is altered in any way and no actions are performed. It only
-prints what would be done. Using this option the sieve\-filter command becomes active and performs the 
+.B \-e
+Turns on execution mode. By default, the sieve\-filter command runs in
+simulation mode in which it changes nothing, meaning that no mailbox is altered
+in any way and no actions are performed. It only prints what would be done.
+Using this option the sieve\-filter command becomes active and performs the 
 requested actions.
 .TP
-\fB\-f\fP \fIenvelope\-sender\fP
-The envelope sender or return path. This is what Sieve's envelope test will compare to when the 
-"from" envelope part is requested. Also, this is where response messages are sent to. 
+.BI \-f\  envelope\-sender
+The envelope sender or return path. This is what Sieve\(aqs envelope test will
+compare to when the \(dqfrom\(dq envelope part is requested. Also, this is
+where response messages are sent to.
 .TP
-\fB\-m\fP \fIdefault\-mailbox\fP
-The mailbox within the default namespace where the keep action stores the message. This is "INBOX"
+.BI \-m\  default\-mailbox
+The mailbox where the keep action stores the message. This is \(dqINBOX\(dq
 by default.
 .TP
-\fB\-Q\fP \fImail\-command\fP
-Send outgoing e\-mail through the specified program. By default, the sieve\-filter command ignores 
-Sieve actions such as redirect, reject, vacation and notify, but using this option outgoing messages
-can be fed to the \fBstdin\fP of an external shell command. This option has no effect in simulation
-mode, Unless you really know what you are doing, \fBDO NOT USE THIS TO FEED MAIL TO SENDMAIL!\f.
+.BI \-Q\  mail\-command
+Send outgoing e\-mail through the specified program. By default,
+the sieve\-filter command ignores Sieve actions such as redirect, reject,
+vacation and notify, but using this option outgoing messages can be fed to the
+\fBstdin\fP of an external shell command. This option has no effect in
+simulation mode. Unless you really know what you are doing, \fBDO NOT USE THIS
+TO FEED MAIL TO SENDMAIL!\f.
 .TP
-\fB\-r\fP \fIrecipient\-address\fP
-The envelope recipient address. This is what Sieve's envelope test will compare to when the "to"
-envelope part is requested. Some tests and actions will also use this as the owner's e\-mail address.
+.BI \-r\  recipient\-address
+The envelope recipient address. This is what Sieve\(aqs envelope test will
+compare to when the \(dqto\(dq envelope part is requested. Some tests and
+actions will also use this as the owner\(aqs e\-mail address.
 .TP
-\fB\-S\fP \fIscript\-file\fP
-Specify additional scripts to be executed before the main script. Multiple \fB\-s\fP arguments are
-allowed and the specified scripts are executed sequentially in the order specified at the command
-line.
+.BI \-s\  script\-file
+Specify additional scripts to be executed before the main script. Multiple
+\fB\-s\fP arguments are allowed and the specified scripts are executed
+sequentially in the order specified at the command
+line..TP
+.B \-W
+Enables write access to the source mailbox. This allows deleting the messages
+from the source mailbox and changing the assigned IMAP flags and keywords. 
 .TP
-\fB\-W\fP
-Enables write access to the source mailbox. This allows deleting the messages from the source mailbox
-and changing the assigned IMAP flags and keywords. 
+.BI \-x\  extensions
+Set the available extensions. The parameter is a space\-separated list of the
+active extensions. By prepending the extension identifiers with \fB+\fP or
+\fB\-\fP, extensions can be included or excluded relative to the default set of
+extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only those
+extensions that are explicitly listed will be enabled. Unknown extensions are
+ignored and a warning is produced. By default, all supported extensions are
+available, except for deprecated extensions or those that are still under
+development.
+
+For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated
+imapflags extension along with all extensions that are available by default,
+except for the enotify extension.
+
+.\"------------------------------------------------------------------------
+.SH ARGUMENTS
 .TP
-\fB\-x\fP "\fIextension extension ...\fP"
-Set the available extensions. The parameter is a space\-separated list of the active extensions. By
-prepending the extension identifiers with \fB+\fP or \fB\-\fP, extensions can be included or excluded
-relative to the default set of extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only 
-those extensions that are explicitly listed will be enabled. Unknown extensions are ignored and a 
-warning is produced. By default, all supported extensions are available, except for deprecated extensions 
-or those that are still under development.
+.I script\-file
+Specifies the script to (compile and) execute.
 
-For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated imapflags extension along with all
-extensions that are available by default, except for the enotify extension.
+Note that this tool looks for a pre\-compiled binary file with a \fI.svbin\fP
+extension and with basename and path identical to the specified script. Use the
+\fB\-C\fP option to disable this behavior by forcing the script to be compiled
+into a new binary.
+.TP
+.I source\-mailbox
+The name of the source mailbox.
+.\"------------------------------------------------------------------------
 
 .SH EXAMPLES
 
@@ -142,19 +153,35 @@
 [...]
 
 .\"------------------------------------------------------------------------
+.SH "EXIT STATUS"
+.B sieve\-filter
+will exit with one of the following values:
+.TP 4
+.B 0
+Sieve filter applied successfully. (EX_OK, EXIT_SUCCES)
+.TP
+.B 1
+Operation failed. This is returned for almost all failures.
+(EXIT_FAILURE)
+.TP
+.B 64
+Invalid parameter given. (EX_USAGE)
+.\"------------------------------------------------------------------------
+.SH FILES
+.TP
+.I /usr/local/etc/dovecot/dovecot.conf
+Dovecot\(aqs main configuration file.
+.TP
+.I /usr/local/etc/dovecot/conf.d/90\-sieve.conf
+Sieve interpreter settings (included from Dovecot\(aqs main configuration file)
+.\"------------------------------------------------------------------------
 @INCLUDE:reporting-bugs@
 .\"------------------------------------------------------------------------
-.SH AUTHOR
-.PP
-The Sieve implementation for Dovecot was written by Stephan Bosch <stephan at rename\-it.nl>.
-.PP
-Dovecot was written by Timo Sirainen <tss at iki.fi>.
-.\"------------------------------------------------------------------------
 .SH "SEE ALSO"
+.BR dovecot (1),
+.BR dovecot\-lda (1),
+.BR sieve\-dump (1),
+.BR sieve\-test (1),
 .BR sievec (1),
-.BR sieve\-dump (1),
-.BR sieve\-test (1)
-.PP
-Dovecot website: http://www.dovecot.org
-.PP
-Pigeonhole website: http://pigeonhole.dovecot.org
+.BR pigeonhole (7)
+