From 7ec4862e1ad0e2881ae298b68084b8e0a21c4a2e Mon Sep 17 00:00:00 2001
From: Stephan Bosch <stephan@rename-it.nl>
Date: Sun, 5 Jul 2009 10:11:13 +0200
Subject: [PATCH] Improved consistency of sieve tool documentation.
---
doc/man/sieve-test.1 | 2 +-
doc/man/sievec.1 | 22 +++++++++++-----------
doc/man/sieved.1 | 14 ++++++++------
src/sieve-tools/sieve-filter.c | 4 ++--
src/sieve-tools/sieve-test.c | 17 ++++++-----------
src/sieve-tools/sievec.c | 8 +++++---
src/sieve-tools/sieved.c | 8 +++++---
7 files changed, 38 insertions(+), 37 deletions(-)
diff --git a/doc/man/sieve-test.1 b/doc/man/sieve-test.1
index eabefc684..0db6710ee 100644
--- a/doc/man/sieve-test.1
+++ b/doc/man/sieve-test.1
@@ -1,4 +1,4 @@
-.TH "SIEVE-TEST" "1" "6 Januari 2009"
+.TH "SIEVE-TEST" "1" "4 July 2009"
.SH NAME
sieve-test \- Sieve script tester for the Dovecot secure IMAP server
.SH SYNOPSIS
diff --git a/doc/man/sievec.1 b/doc/man/sievec.1
index 049be8632..84781a118 100644
--- a/doc/man/sievec.1
+++ b/doc/man/sievec.1
@@ -1,8 +1,8 @@
-.TH "SIEVEC" "1" "6 January 2009"
+.TH "SIEVEC" "1" "4 July 2009"
.SH NAME
sievec \- Sieve script compiler for the Dovecot secure IMAP server
.SH SYNOPSIS
-sievec [\fB-d\fR] [\fB-x\fR "\fIextension extension ...\fR"] \fIsieve-script\fR [\fIoutfile\fR]
+sievec [\fB-d\fR] [\fB-x\fR "\fIextension extension ...\fR"] \fIscript-file\fR [\fIout-file\fR]
.SH DESCRIPTION
.PP
The \fBsievec\fP command is part of the Sieve implementation for the Dovecot secure
@@ -22,18 +22,18 @@ permission to write the compiled binary to disk, forcing it to recompile the scr
is executed. Using the \fBsievec\fP tool, this can be performed manually by an authorized user to
increase performance.
.PP
-The \fBsievec\fP command accepts two arguments: the \fIsieve-script\fP argument specifies the
-script to be compiled and the \fIoutfile\fR argument specifies where the (binary) output is to
+The \fBsievec\fP command accepts two arguments: the \fIscript-file\fP argument specifies the
+script to be compiled and the \fIout-file\fR argument specifies where the (binary) output is to
be written. This Sieve implementation reconizes 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's deliver process will look for a binary file 'dovecot.svbin'
when it needs to execute 'dovecot.sieve'. Such filename is chosen automatically for the binary output
-when the outfile argument is missing.
+when the out-file argument is missing.
.PP
-If the \fIscriptfile\fP argument is a directory, all files in that directory with a \fI.sieve\fP
+If the \fIscript-file\fP argument is a directory, all files in that directory with a \fI.sieve\fP
extension are compiled into a corresponding \fI.svbin\fP binary file. The compilation is not halted
upon errors; it attempts to compile as many scripts in the directory as possible. Note that the
-\fB-d\fP option and the \fIoutfile\fP argument are not allowed when the \fIscriptfile\fP argument
+\fB-d\fP option and the \fIout-file\fP argument are not allowed when the \fIscript-file\fP argument
is a directory.
.PP
The \fBsievec\fP command is also useful to verify Sieve scripts before using. Additionally, with
@@ -44,11 +44,11 @@ binaries.
.SH OPTIONS
.TP
\fB-d\fP
-Don't write the binary to \fIoutfile\fP, but write a textual dump of the binary in
-stead. In this context, the \fIoutfile\fP value '-' has special meaning: it causes the the textual
-dump to be written to \fBstdout\fP. The \fIoutfile\fP argument may also be omitted, which has
+Don't write the binary to \fIout-file\fP, but write a textual dump of the binary in
+stead. In this context, the \fIout-file\fP value '-' has special meaning: it causes the the textual
+dump to be written to \fBstdout\fP. The \fIout-file\fP argument may also be omitted, which has
the same effect as '-'. The output is identical to what the \fBsieved\fP(1) command produces for
-a compiled Sieve binary file. Note that this option is not allowed when the \fIoutfile\fP argument
+a compiled Sieve binary file. Note that this option is not allowed when the \fIout-file\fP argument
is a directory.
.TP
\fB-x\fP "\fIextension extension ...\fP"
diff --git a/doc/man/sieved.1 b/doc/man/sieved.1
index 15d53b90d..3758f7b0d 100644
--- a/doc/man/sieved.1
+++ b/doc/man/sieved.1
@@ -1,8 +1,8 @@
-.TH "SIEVED" "1" "6 January 2009"
+.TH "SIEVED" "1" "4 July 2009"
.SH NAME
sieved \- Sieve script binary dump tool for the Dovecot secure IMAP server
.SH SYNOPSIS
-sieved [\fB-x\fR "\fIextension extension ...\fR"] \fIsieve-binary\fR [\fIoutfile\fR]
+sieved [\fB-x\fR "\fIextension extension ...\fR"] \fIsieve-binary\fR [\fIout-file\fR]
.br
.SH DESCRIPTION
.PP
@@ -14,12 +14,14 @@ its basic form it does not provide the means to cause infinite loops, making it
for running securely on mail servers where mail users have no permission run arbitrary programs.
.PP
Using the \fBsieved\fP command, Sieve binaries, which are produced for instance by
-\fBsievec\fP(1), can be transformed into a human-readable textual representation. This can provide valuable
-insight in how the Sieve script is executed. This is also particularly useful to view corrupt
-binaries that can result from bugs in the Sieve implementation.
+\fBsievec\fP(1), can be transformed into a human-readable textual representation. This can
+provide valuable insight in how the Sieve script is executed. This is also particularly useful
+to view corrupt binaries that can result from bugs in the Sieve implementation. This tool is
+intended mainly for development purposes, so normally system administrators and users will not
+need to use this tool.
.PP
The \fIsieve-binary\fR argument specifies the Sieve binary file that needs to be dumped. The
-optional \fIoutfile\fR argument specifies where the output must be written. If omitted, the
+optional \fIout-file\fR argument specifies where the output must be written. If omitted, the
output is written to \fBstdout\fR.
.PP
The format of the output is not explained here in detail, but it should be relatively easy
diff --git a/src/sieve-tools/sieve-filter.c b/src/sieve-tools/sieve-filter.c
index cbb1d559b..a48912631 100644
--- a/src/sieve-tools/sieve-filter.c
+++ b/src/sieve-tools/sieve-filter.c
@@ -32,8 +32,8 @@ static void print_help(void)
{
printf(
"Usage: sieve-filter [-m <mailbox>] [-x <extensions>]\n"
-" [-s <scriptfile>] [-c]\n"
-" <scriptfile> <mailstore>\n"
+" [-s <script-file>] [-c]\n"
+" <script-file> <mail-store>\n"
);
}
diff --git a/src/sieve-tools/sieve-test.c b/src/sieve-tools/sieve-test.c
index b6e6f2136..689840373 100644
--- a/src/sieve-tools/sieve-test.c
+++ b/src/sieve-tools/sieve-test.c
@@ -44,16 +44,11 @@
static void print_help(void)
{
-#ifdef SIEVE_RUNTIME_TRACE
-# define SVTRACE " [-t]"
-#else
-# define SVTRACE
-#endif
printf(
-"Usage: sieve-test [-r <recipient address>] [-f <envelope sender>]\n"
-" [-m <mailbox>] [-d <dump filename>] [-x <extensions>]\n"
-" [-s <scriptfile>] [-c]"SVTRACE"\n"
-" <scriptfile> <mailfile>\n"
+"Usage: sieve-test [-c] [-d <dump-filename>] [-e] [-f <envelope-sender>]\n"
+" [-l <mail-location>] [-m <default-mailbox>]\n"
+" [-r <recipient-address>] [-s <script-file>]\n"
+" [-t] [-x <extensions>] <script-file> <mail-file>\n"
);
}
@@ -201,14 +196,14 @@ int main(int argc, char **argv)
scriptfile = t_strdup(argv[optind++]);
} else {
print_help();
- i_fatal_status(EX_USAGE, "Missing <scriptfile> argument");
+ i_fatal_status(EX_USAGE, "Missing <script-file> argument");
}
if ( optind < argc ) {
mailfile = t_strdup(argv[optind++]);
} else {
print_help();
- i_fatal_status(EX_USAGE, "Missing <mailfile> argument");
+ i_fatal_status(EX_USAGE, "Missing <mail-file> argument");
}
if (optind != argc) {
diff --git a/src/sieve-tools/sievec.c b/src/sieve-tools/sievec.c
index b6bf4d1c8..b30c035a9 100644
--- a/src/sieve-tools/sievec.c
+++ b/src/sieve-tools/sievec.c
@@ -26,7 +26,7 @@
static void print_help(void)
{
printf(
-"Usage: sievec [-d] [-x <extensions>] <scriptfile> [<outfile>]\n"
+"Usage: sievec [-d] [-x <extensions>] <script-file> [<out-file>]\n"
);
}
@@ -51,8 +51,10 @@ int main(int argc, char **argv) {
} else if (strcmp(argv[i], "-x") == 0) {
/* extensions */
i++;
- if (i == argc)
+ if (i == argc) {
+ print_help();
i_fatal("Missing -x argument");
+ }
extensions = argv[i];
} else if ( scriptfile == NULL ) {
scriptfile = argv[i];
@@ -66,7 +68,7 @@ int main(int argc, char **argv) {
if ( scriptfile == NULL ) {
print_help();
- i_fatal("Missing <scriptfile> argument");
+ i_fatal("Missing <script-file> argument");
}
if ( outfile == NULL && dump )
diff --git a/src/sieve-tools/sieved.c b/src/sieve-tools/sieved.c
index 61d740275..6bb01788e 100644
--- a/src/sieve-tools/sieved.c
+++ b/src/sieve-tools/sieved.c
@@ -25,7 +25,7 @@
static void print_help(void)
{
printf(
-"Usage: sieved <binfile> [<outfile>]\n"
+"Usage: sieved [-x <extensions>] <sieve-binary> [<out-file>]\n"
);
}
@@ -45,8 +45,10 @@ int main(int argc, char **argv) {
if (strcmp(argv[i], "-x") == 0) {
/* extensions */
i++;
- if (i == argc)
+ if (i == argc) {
+ print_help();
i_fatal("Missing -x argument");
+ }
extensions = argv[i];
} else if ( binfile == NULL ) {
binfile = argv[i];
@@ -60,7 +62,7 @@ int main(int argc, char **argv) {
if ( binfile == NULL ) {
print_help();
- i_fatal("missing <binfile> argument");
+ i_fatal("missing <sieve-binary> argument");
}
if ( extensions != NULL ) {
--
GitLab