From de64342dbb28c6a6b1cbc1186cf509be90a626f7 Mon Sep 17 00:00:00 2001
From: Stephan Bosch <stephan@rename-it.nl>
Date: Wed, 5 Oct 2011 18:45:10 +0200
Subject: [PATCH] Updated documentation of sieve tools.
---
doc/man/sieve-dump.1.in | 4 ++--
doc/man/sieve-filter.1.in | 4 ++--
doc/man/sieve-test.1.in | 30 ++++++++++++++++++++++--------
doc/man/sievec.1.in | 13 +++++++------
src/sieve-tools/sieve-dump.c | 2 +-
src/sieve-tools/sieve-test.c | 3 ++-
src/sieve-tools/sievec.c | 2 +-
7 files changed, 37 insertions(+), 21 deletions(-)
diff --git a/doc/man/sieve-dump.1.in b/doc/man/sieve-dump.1.in
index e0a58ec98..35764c798 100644
--- a/doc/man/sieve-dump.1.in
+++ b/doc/man/sieve-dump.1.in
@@ -1,5 +1,5 @@
.\" Copyright (c) 2010-2011 Pigeonhole authors, see the included COPYING file
-.TH "SIEVE\-DUMP" 1 "2011-06-21" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
+.TH "SIEVE\-DUMP" 1 "2011-10-04" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
.\"------------------------------------------------------------------------
.SH NAME
sieve\-dump \- Pigeonhole\(aqs Sieve script binary dump tool
@@ -72,7 +72,7 @@ omitted, the output is written to \fBstdout\fR.
will exit with one of the following values:
.TP 4
.B 0
-Dump was successful. (EX_OK, EXIT_SUCCES)
+Dump was successful. (EX_OK, EXIT_SUCCESS)
.TP
.B 1
Operation failed. This is returned for almost all failures.
diff --git a/doc/man/sieve-filter.1.in b/doc/man/sieve-filter.1.in
index a9141264a..e65466820 100644
--- a/doc/man/sieve-filter.1.in
+++ b/doc/man/sieve-filter.1.in
@@ -1,5 +1,5 @@
.\" Copyright (c) 2010-2011 Pigeonhole authors, see the included COPYING file
-.TH "SIEVE\-FILTER" 1 "2011-02-23" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
+.TH "SIEVE\-FILTER" 1 "2011-10-04" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
.SH NAME
sieve\-filter \- Pigeonhole\(aqs Sieve mailbox filter tool
@@ -196,7 +196,7 @@ and not affected by the \fIsource\-action\fP.
will exit with one of the following values:
.TP 4
.B 0
-Sieve filter applied successfully. (EX_OK, EXIT_SUCCES)
+Sieve filter applied successfully. (EX_OK, EXIT_SUCCESS)
.TP
.B 1
Operation failed. This is returned for almost all failures.
diff --git a/doc/man/sieve-test.1.in b/doc/man/sieve-test.1.in
index 9125e18be..26b446280 100644
--- a/doc/man/sieve-test.1.in
+++ b/doc/man/sieve-test.1.in
@@ -1,5 +1,5 @@
.\" Copyright (c) 2010-2011 Pigeonhole authors, see the included COPYING file
-.TH "SIEVE\-TEST" 1 "2011-06-21" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
+.TH "SIEVE\-TEST" 1 "2011-10-04" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
.SH NAME
sieve\-test \- Pigeonhole\(aqs Sieve script tester
.\"------------------------------------------------------------------------
@@ -32,6 +32,15 @@ evaluation of commands and tests respectively.
.\"------------------------------------------------------------------------
.SH OPTIONS
.TP
+.BI \-a\ orig\-recipient\-address
+The original 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 script owner\(aqs e\-mail address. If this
+option is omitted, the recipient address is retrieved from the
+\(dqEnvelope-To:\(dq, or \(dqTo:\(dq message headers. If none of these headers
+is present either, the recipient address defaults to
+\fIrecipient@example.com\fP.
+.TP
.BI \-c\ config\-file
Alternative Dovecot configuration file path.
.TP
@@ -58,9 +67,12 @@ messages can be tested. Note that this will not transmit any messages to remote
SMTP recipients. Such actions only print the outgoing message to \fBstdout\fP.
.TP
.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.
+The envelope sender address (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 \(aqsent\(aq to. If this option is omitted, the sender
+address is retrieved from the \(dqReturn-Path:\(dq, \(dqSender:\(dq or
+\(dqFrom:\(dq message headers. If none of these headers is present either,
+the sender envelope address defaults to \fIsender@example.com\fP.
.TP
.BI \-l\ mail\-location
The location of the user\(aqs mail store. The syntax of this option\(aqs
@@ -75,9 +87,11 @@ The mailbox where the keep action stores the message. This is \(dqINBOX\(dq
by default.
.TP
.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.
+The final envelope recipient address. Some tests and actions will
+use this as the script owner\(aqs e\-mail address. For example, this is what is
+used by the vacation action to check whether a reply is appropriate. If the
+\fB\-r\fP option is omitted, the orignal envelope recipient address will be used
+in stead (see \fB\-a\fP option for more info).
.TP
.BI \-s\ script\-file
Specify additional scripts to be executed before the main script. Multiple
@@ -196,7 +210,7 @@ messages are logged through the default Dovecot logging facility.
will exit with one of the following values:
.TP 4
.B 0
-Execution was successful. (EX_OK, EXIT_SUCCES)
+Execution was successful. (EX_OK, EXIT_SUCCESS)
.TP
.B 1
Operation failed. This is returned for almost all failures.
diff --git a/doc/man/sievec.1.in b/doc/man/sievec.1.in
index c5fe3132e..3b10a0767 100644
--- a/doc/man/sievec.1.in
+++ b/doc/man/sievec.1.in
@@ -1,5 +1,5 @@
.\" Copyright (c) 2010-2011 Pigeonhole authors, see the included COPYING file
-.TH "SIEVEC" 1 "2011-06-21" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
+.TH "SIEVEC" 1 "2011-10-04" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
.\"------------------------------------------------------------------------
.SH NAME
sievec \- Pigeonhole\(aqs Sieve script compiler
@@ -32,7 +32,8 @@ The Pigeonhole Sieve implementation recognizes files with a \fB.sieve\fP
extension as Sieve scripts and corresponding files with a \fB.svbin\fP extension
as the associated compiled binary. This means for example that Dovecot\(aqs LDA
process will first look for a binary file \(dqdovecot.svbin\(dq when it needs to
-execute \(dqdovecot.sieve\(dq. It will compile a new binary when it is missing.
+execute \(dqdovecot.sieve\(dq. It will compile a new binary when it is missing
+or outdated.
.PP
The \fBsievec\fP command is also useful to verify Sieve scripts before using.
Additionally, with the \fB\-d\fP option it can output a textual (and thus
@@ -82,16 +83,16 @@ not allowed when the \fIscript\-file\fP argument is a directory.
.TP
.I out\-file
Specifies where the (binary) output is to be written. This argument is optional.
-If omitted a binary compiled from <scriptname>.sieve is saved as
-<scriptname>.svbin. If \fB\-b\fP is specified, the binary dump is output to
-\fBstdout\fP.
+If this argument is omitted, a binary compiled from <scriptname>.sieve is saved
+as <scriptname>.svbin. If this argument is omitted and \fB\-b\fP is specified,
+the binary dump is output to \fBstdout\fP.
.\"------------------------------------------------------------------------
.SH "EXIT STATUS"
.B sievec
will exit with one of the following values:
.TP 4
.B 0
-Compile was successful. (EX_OK, EXIT_SUCCES)
+Compile was successful. (EX_OK, EXIT_SUCCESS)
.TP
.B 1
Operation failed. This is returned for almost all failures.
diff --git a/src/sieve-tools/sieve-dump.c b/src/sieve-tools/sieve-dump.c
index d898b63dd..6c12362fe 100644
--- a/src/sieve-tools/sieve-dump.c
+++ b/src/sieve-tools/sieve-dump.c
@@ -28,7 +28,7 @@
static void print_help(void)
{
printf(
-"Usage: sieve-dump [-h] [-P <plugin>] [-x <extensions>]\n"
+"Usage: sieve-dump [-c <config-file>] [-h] [-P <plugin>] [-x <extensions>]\n"
" <sieve-binary> [<out-file>]\n"
);
}
diff --git a/src/sieve-tools/sieve-test.c b/src/sieve-tools/sieve-test.c
index 3c9263c66..a1f9f53a7 100644
--- a/src/sieve-tools/sieve-test.c
+++ b/src/sieve-tools/sieve-test.c
@@ -42,7 +42,8 @@
static void print_help(void)
{
printf(
-"Usage: sieve-test [-c <config-file>] [-C] [-D] [-d <dump-filename>] [-e]\n"
+"Usage: sieve-test [-a <orig-recipient-address] [-c <config-file>]\n"
+" [-C] [-D] [-d <dump-filename>] [-e]\n"
" [-f <envelope-sender>] [-l <mail-location>]\n"
" [-m <default-mailbox>] [-P <plugin>]\n"
" [-r <recipient-address>] [-s <script-file>]\n"
diff --git a/src/sieve-tools/sievec.c b/src/sieve-tools/sievec.c
index f1f089630..cf81a067f 100644
--- a/src/sieve-tools/sievec.c
+++ b/src/sieve-tools/sievec.c
@@ -30,7 +30,7 @@
static void print_help(void)
{
printf(
-"Usage: sievec [-d] [-P <plugin>] [-x <extensions>] \n"
+"Usage: sievec [-c <config-file>] [-d] [-P <plugin>] [-x <extensions>] \n"
" <script-file> [<out-file>]\n"
);
}
--
GitLab