1 files changed, 96 insertions, 2 deletions

diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 731c4ae1..95c6741f 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -223,2 +223,3 @@ Built-in and Library Functions
 * System functions::
+* Sieve Interface::
 * Interfaces to Third-Party Programs::
@@ -987,3 +988,2 @@ the corresponding section below.
 @cindex Upgrading from 4.1 to 4.2
-@UNREVISED{}
   Upgrading to this version does not require any special efforts.  You
@@ -5260,2 +5260,3 @@ in version @value{VERSION}.
 * System functions::
+* Sieve Interface::
 * Interfaces to Third-Party Programs::
@@ -6479,4 +6480,97 @@ the return status of the command otherwise.
 @end deftypefn
-          
 
+@node Sieve Interface
+@subsubsection Sieve Interface
+@cindex Sieve
+@UNREVISED{}
+  @samp{Sieve} is a powerful mail filtering language, defined in
+@acronym{RFC} 3028.  @command{Mailfromd} supports an extended form
+of this language.  For description of the language and available
+extensions, @xref{Sieve Language, Sieve Language, Sieve Language,
+mailutils, GNU Mailutils Manual}.
+
+@deftypefn {Built-in Function} boolean sieve (string @var{script} @
+                                              [, number @var{flags}])
+Compile the Sieve source file @var{script} and execute it over the
+collected message.  This function can be used only in @code{eom}
+handler.
+
+@findex sieve.mfh
+Optional @var{flags} define additional debugging and verbosity
+settings.  It is a bit-mask field, consisting of a bitwise @code{or}
+of one or more of the following flags, defined in @file{sieve.mfh}:
+
+@table @code
+@item MF_SIEVE_LOG
+Log every executed @samp{Sieve} action.
+
+@item MF_SIEVE_DEBUG_TRACE  
+Trace execution of @samp{Sieve} tests.
+
+@item MF_SIEVE_DEBUG_INSTR
+Log every instruction, executed in the compiled @samp{Sieve} code.
+This produces huge amounts of output and is rarely useful, unless you
+suspect some bug in @samp{Sieve} implementation and wish to trace it.
+
+@item MF_SIEVE_DEBUG_MAILUTILS
+Log debugging information about the underlying Mailutils calls.
+
+@item MF_SIEVE_DEBUG_PROT
+Trace networking protocols.
+@end table
+
+For example, @code{MF_SIEVE_LOG|MF_SIEVE_DEBUG_TRACE} enables logging
+@samp{Sieve} actions and tests.
+
+The @code{sieve} function returns @code{true} if the message was
+accepted by the @var{script} program, and @code{false} otherwise.
+Here, the word @dfn{accepted} means that some form of @samp{KEEP}
+action (@pxref{Actions, keep, Actions, mailutils, GNU Mailutils
+Manual}) was executed over the message.
+@end deftypefn
+
+The following example discards each message not accepted by the
+@samp{Sieve} program @file{/etc/mail/filter.siv}:
+
+@smallexample
+#include_once <sieve.mfh>
+group eom
+do
+  if not sieve("/etc/mail/filter.siv", MF_SIEVE_LOG)
+     discard
+  fi
+done
+@end smallexample
+
+The example below illustrates how one can adjust logging flags
+depending on the current debugging level:
+
+@smallexample
+#include_once <sieve.mfh>
+prog eom
+do
+  number flags 0
+  number level debug_level("bi_sieve")
+  if %level >= 1
+    set flags %flags | MF_SIEVE_LOG
+  fi
+  if %level >= 2
+    set flags %flags | MF_SIEVE_DEBUG_TRACE
+  fi
+  if %level > 9
+    set flags %flags | MF_SIEVE_DEBUG_INSTR
+  fi
+  if %level > 19
+    set flags %flags | MF_SIEVE_DEBUG_MAILUTILS
+  fi
+  if %level > 20
+    set flags %flags | MF_SIEVE_DEBUG_PROT
+  fi          
+
+  if not sieve("/etc/mail/filter.siv", %flags)
+     discard
+  fi
+done
+@end smallexample
+  
 @node Interfaces to Third-Party Programs