2007-09-06 05:07:05 +00:00
|
|
|
\input texinfo @c -*-texinfo-*-
|
2011-02-06 00:25:41 +00:00
|
|
|
|
2014-06-10 02:20:31 +00:00
|
|
|
@setfilename ../../info/sieve.info
|
2007-09-06 05:07:05 +00:00
|
|
|
@settitle Emacs Sieve Manual
|
Fix single-quoting style in PDF manuals
The PDF versions of the GNU manuals used curved single quotes to
represent grave accent and apostrophe, which made it a pain to cut
and paste code examples from them. Fix the PDF versions to use
grave accent and apostrophe for Lisp source code, keystrokes, etc.
This change does not affect the info files, nor does it affect
ordinary uses of curved single quotes in PDF.
* doc/emacs/docstyle.texi: New file, which specifies treatment for
grave accent and apostrophe, as well as the document encoding.
* doc/emacs/emacs-xtra.texi, doc/emacs/emacs.texi:
* doc/lispintro/emacs-lisp-intro.texi:
* doc/lispref/back.texi, doc/lispref/book-spine.texi:
* doc/lispref/elisp.texi, doc/lispref/lay-flat.texi:
* doc/misc/ada-mode.texi, doc/misc/auth.texi:
* doc/misc/autotype.texi, doc/misc/bovine.texi, doc/misc/calc.texi:
* doc/misc/cc-mode.texi, doc/misc/cl.texi, doc/misc/dbus.texi:
* doc/misc/dired-x.texi, doc/misc/ebrowse.texi, doc/misc/ede.texi:
* doc/misc/ediff.texi, doc/misc/edt.texi, doc/misc/efaq-w32.texi:
* doc/misc/efaq.texi, doc/misc/eieio.texi, doc/misc/emacs-gnutls.texi:
* doc/misc/emacs-mime.texi, doc/misc/epa.texi, doc/misc/erc.texi:
* doc/misc/ert.texi, doc/misc/eshell.texi, doc/misc/eudc.texi:
* doc/misc/eww.texi, doc/misc/flymake.texi, doc/misc/forms.texi:
* doc/misc/gnus-coding.texi, doc/misc/gnus-faq.texi:
* doc/misc/gnus.texi, doc/misc/htmlfontify.texi:
* doc/misc/idlwave.texi, doc/misc/ido.texi, doc/misc/info.texi:
* doc/misc/mairix-el.texi, doc/misc/message.texi, doc/misc/mh-e.texi:
* doc/misc/newsticker.texi, doc/misc/nxml-mode.texi:
* doc/misc/octave-mode.texi, doc/misc/org.texi, doc/misc/pcl-cvs.texi:
* doc/misc/pgg.texi, doc/misc/rcirc.texi, doc/misc/reftex.texi:
* doc/misc/remember.texi, doc/misc/sasl.texi, doc/misc/sc.texi:
* doc/misc/semantic.texi, doc/misc/ses.texi, doc/misc/sieve.texi:
* doc/misc/smtpmail.texi, doc/misc/speedbar.texi:
* doc/misc/srecode.texi, doc/misc/todo-mode.texi, doc/misc/tramp.texi:
* doc/misc/url.texi, doc/misc/vhdl-mode.texi, doc/misc/vip.texi:
* doc/misc/viper.texi, doc/misc/widget.texi, doc/misc/wisent.texi:
* doc/misc/woman.texi:
Use it instead of '@documentencoding UTF-8', to lessen the need for
global changes like this in the future.
* doc/emacs/Makefile.in (EMACS_XTRA):
* doc/lispintro/Makefile.in (srcs):
* doc/lispref/Makefile.in (srcs):
Add dependency on docstyle.texi.
* doc/misc/Makefile.in (style): New macro.
(${buildinfodir}/%.info, %.dvi, %.pdf, %.html)
(${buildinfodir}/ccmode.info, ${buildinfodir}/efaq%.info, gnus_deps):
Use it.
2015-05-01 19:05:53 +00:00
|
|
|
@include docstyle.texi
|
2007-09-06 05:07:05 +00:00
|
|
|
@synindex fn cp
|
|
|
|
@synindex vr cp
|
|
|
|
@synindex pg cp
|
|
|
|
|
|
|
|
@copying
|
|
|
|
This file documents the Emacs Sieve package, for server-side mail filtering.
|
|
|
|
|
2020-01-01 00:19:43 +00:00
|
|
|
Copyright @copyright{} 2001--2020 Free Software Foundation, Inc.
|
2007-09-06 05:07:05 +00:00
|
|
|
|
|
|
|
@quotation
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
2008-11-19 04:29:29 +00:00
|
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
2007-09-06 05:07:05 +00:00
|
|
|
any later version published by the Free Software Foundation; with no
|
2014-05-07 17:34:53 +00:00
|
|
|
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
|
2008-06-15 02:31:43 +00:00
|
|
|
and with the Back-Cover Texts as in (a) below. A copy of the license
|
|
|
|
is included in the section entitled ``GNU Free Documentation License''.
|
2007-09-06 05:07:05 +00:00
|
|
|
|
2008-06-13 04:20:28 +00:00
|
|
|
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
|
2012-12-21 18:36:41 +00:00
|
|
|
modify this GNU manual.''
|
2007-09-06 05:07:05 +00:00
|
|
|
@end quotation
|
|
|
|
@end copying
|
|
|
|
|
2011-02-18 13:57:53 +00:00
|
|
|
@dircategory Emacs network features
|
2007-09-06 05:07:05 +00:00
|
|
|
@direntry
|
|
|
|
* Sieve: (sieve). Managing Sieve scripts in Emacs.
|
|
|
|
@end direntry
|
|
|
|
@iftex
|
|
|
|
@finalout
|
|
|
|
@end iftex
|
|
|
|
@setchapternewpage odd
|
|
|
|
|
|
|
|
@titlepage
|
2011-02-06 00:25:41 +00:00
|
|
|
@ifset WEBHACKDEVEL
|
|
|
|
@title Emacs Sieve Manual (DEVELOPMENT VERSION)
|
|
|
|
@end ifset
|
|
|
|
@ifclear WEBHACKDEVEL
|
2007-09-06 05:07:05 +00:00
|
|
|
@title Emacs Sieve Manual
|
2011-02-06 00:25:41 +00:00
|
|
|
@end ifclear
|
2007-09-06 05:07:05 +00:00
|
|
|
|
|
|
|
@author by Simon Josefsson
|
|
|
|
@page
|
|
|
|
@vskip 0pt plus 1filll
|
|
|
|
@insertcopying
|
|
|
|
@end titlepage
|
|
|
|
|
2009-02-16 17:41:58 +00:00
|
|
|
@summarycontents
|
|
|
|
@contents
|
2007-09-06 05:07:05 +00:00
|
|
|
|
|
|
|
@node Top
|
|
|
|
@top Sieve Support for Emacs
|
|
|
|
|
2009-02-16 17:41:58 +00:00
|
|
|
This is intended as a users manual for Sieve Mode and Manage Sieve, and
|
2007-09-06 05:07:05 +00:00
|
|
|
as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp
|
|
|
|
API.
|
|
|
|
|
|
|
|
Sieve is a language for server-side filtering of mail. The language
|
|
|
|
is documented in RFC 3028. This manual does not attempt to document
|
|
|
|
the language, so keep RFC 3028 around.
|
|
|
|
|
2009-02-16 17:41:58 +00:00
|
|
|
@ifnottex
|
|
|
|
@insertcopying
|
|
|
|
@end ifnottex
|
2007-09-06 05:07:05 +00:00
|
|
|
|
|
|
|
@menu
|
|
|
|
* Installation:: Getting ready to use the package.
|
|
|
|
* Sieve Mode:: Editing Sieve scripts.
|
|
|
|
* Managing Sieve:: Managing Sieve scripts on a remote server.
|
|
|
|
* Examples :: A few Sieve code snippets.
|
|
|
|
* Manage Sieve API :: Interfacing to the Manage Sieve Protocol API.
|
|
|
|
* Standards:: A summary of RFCs and working documents used.
|
|
|
|
* GNU Free Documentation License:: The license for this documentation.
|
|
|
|
* Index:: Function and variable index.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
|
|
|
|
@node Installation
|
|
|
|
@chapter Installation
|
|
|
|
@cindex Install
|
|
|
|
@cindex Setup
|
|
|
|
|
|
|
|
The Sieve package should come with your Emacs version, and should be
|
|
|
|
ready for use directly.
|
|
|
|
|
|
|
|
However, to manually set up the package you can put the following
|
|
|
|
commands in your @code{~/.emacs}:
|
|
|
|
|
|
|
|
@lisp
|
|
|
|
(autoload 'sieve-mode "sieve-mode")
|
|
|
|
@end lisp
|
|
|
|
@lisp
|
|
|
|
(setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode)
|
|
|
|
auto-mode-alist))
|
|
|
|
@end lisp
|
|
|
|
|
|
|
|
|
|
|
|
@node Sieve Mode
|
|
|
|
@chapter Sieve Mode
|
|
|
|
|
|
|
|
Sieve mode provides syntax-based indentation, font-locking support and
|
|
|
|
other handy functions to make editing Sieve scripts easier.
|
|
|
|
|
|
|
|
Use @samp{M-x sieve-mode} to switch to this major mode. This command
|
|
|
|
runs the hook @code{sieve-mode-hook}.
|
|
|
|
|
|
|
|
@vindex sieve-mode-map
|
|
|
|
@vindex sieve-mode-syntax-table
|
|
|
|
Sieve mode is derived from @code{c-mode}, and is very similar except
|
|
|
|
for the syntax of comments. The keymap (@code{sieve-mode-map}) is
|
|
|
|
inherited from @code{c-mode}, as are the variables for customizing
|
|
|
|
indentation. Sieve mode has its own abbrev table
|
|
|
|
(@code{sieve-mode-abbrev-table}) and syntax table
|
|
|
|
(@code{sieve-mode-syntax-table}).
|
|
|
|
|
|
|
|
In addition to the editing utility functions, Sieve mode also contains
|
|
|
|
bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
|
|
|
|
|
|
|
|
@table @kbd
|
|
|
|
|
2018-02-26 12:53:37 +00:00
|
|
|
@item C-c @key{RET}
|
2018-02-26 08:24:39 +00:00
|
|
|
@kindex C-c RET
|
2007-09-06 05:07:05 +00:00
|
|
|
@findex sieve-manage
|
|
|
|
@cindex manage remote sieve script
|
2018-09-27 15:48:06 +00:00
|
|
|
Open a connection to a remote server using the Manage Sieve protocol.
|
2007-09-06 05:07:05 +00:00
|
|
|
|
|
|
|
@item C-c C-l
|
|
|
|
@kindex C-c C-l
|
|
|
|
@findex sieve-upload
|
|
|
|
@cindex upload sieve script
|
|
|
|
Upload the Sieve script to the currently open server.
|
|
|
|
|
|
|
|
@end table
|
|
|
|
|
|
|
|
|
|
|
|
@node Managing Sieve
|
|
|
|
@chapter Managing Sieve
|
|
|
|
|
|
|
|
Manage Sieve is a special mode used to display Sieve scripts available
|
|
|
|
on a remote server. It can be invoked with @kbd{M-x sieve-manage
|
|
|
|
RET}, which queries the user for a server and if necessary, user
|
|
|
|
credentials to use.
|
|
|
|
|
|
|
|
When a server has been successfully contacted, the Manage Sieve buffer
|
|
|
|
looks something like:
|
|
|
|
|
|
|
|
@example
|
2013-06-14 09:48:49 +00:00
|
|
|
Server : mailserver:sieve
|
2007-09-06 05:07:05 +00:00
|
|
|
|
|
|
|
2 scripts on server, press RET on a script name edits it, or
|
|
|
|
press RET on <new script> to create a new script.
|
|
|
|
<new script>
|
|
|
|
ACTIVE .sieve
|
|
|
|
template.siv
|
|
|
|
@end example
|
|
|
|
|
|
|
|
One of the scripts are highlighted, and standard point navigation
|
2018-02-26 12:53:37 +00:00
|
|
|
commands (@kbd{@key{UP}}, @kbd{@key{DOWN}} etc.)@: can be used to
|
|
|
|
navigate the list.
|
2007-09-06 05:07:05 +00:00
|
|
|
|
|
|
|
The following commands are available in the Manage Sieve buffer:
|
|
|
|
|
|
|
|
@table @kbd
|
|
|
|
|
|
|
|
@item m
|
|
|
|
@kindex m
|
|
|
|
@findex sieve-activate
|
|
|
|
Activates the currently highlighted script.
|
|
|
|
|
|
|
|
@item u
|
|
|
|
@kindex u
|
|
|
|
@findex sieve-deactivate
|
|
|
|
Deactivates the currently highlighted script.
|
|
|
|
|
|
|
|
@item C-M-?
|
|
|
|
@kindex C-M-?
|
|
|
|
@findex sieve-deactivate-all
|
|
|
|
Deactivates all scripts.
|
|
|
|
|
|
|
|
@item r
|
|
|
|
@kindex r
|
|
|
|
@findex sieve-remove
|
|
|
|
Remove currently highlighted script.
|
|
|
|
|
2018-02-26 12:53:37 +00:00
|
|
|
@item @key{RET}
|
2007-09-06 05:07:05 +00:00
|
|
|
@item mouse-2
|
|
|
|
@item f
|
2018-02-26 08:24:39 +00:00
|
|
|
@kindex RET
|
2007-09-06 05:07:05 +00:00
|
|
|
@kindex mouse-2
|
|
|
|
@kindex f
|
|
|
|
@findex sieve-edit-script
|
|
|
|
Bury the server buffer and download the currently highlighted script
|
|
|
|
into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).
|
|
|
|
|
|
|
|
@item o
|
|
|
|
@kindex o
|
|
|
|
@findex sieve-edit-script-other-window
|
|
|
|
Create a new buffer in another window containing the currently
|
|
|
|
highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).
|
|
|
|
|
|
|
|
@item q
|
|
|
|
@kindex q
|
|
|
|
@findex sieve-bury-buffer
|
|
|
|
Bury the Manage Sieve buffer without closing the connection.
|
|
|
|
|
|
|
|
@item ?
|
|
|
|
@item h
|
|
|
|
@kindex ?
|
|
|
|
@kindex h
|
|
|
|
@findex sieve-help
|
2012-12-22 16:25:40 +00:00
|
|
|
Displays help in the minibuffer.
|
2007-09-06 05:07:05 +00:00
|
|
|
|
2013-06-14 09:48:49 +00:00
|
|
|
@item Q
|
|
|
|
@kindex Q
|
|
|
|
@findex sieve-manage-quit
|
|
|
|
Quit Manage Sieve and close the connection.
|
|
|
|
|
2007-09-06 05:07:05 +00:00
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Examples
|
|
|
|
@chapter Examples
|
|
|
|
|
|
|
|
If you are not familiar with Sieve, this chapter contains a few simple
|
|
|
|
code snippets that you can cut'n'paste and modify at will, until you
|
|
|
|
feel more comfortable with the Sieve language to write the rules from
|
|
|
|
scratch.
|
|
|
|
|
|
|
|
The following complete Sieve script places all messages with a matching
|
|
|
|
@samp{Sender:} header into the given mailbox. Many mailing lists uses
|
|
|
|
this format. The first line makes sure your Sieve server understands
|
|
|
|
the @code{fileinto} command.
|
|
|
|
|
|
|
|
@example
|
|
|
|
require "fileinto";
|
|
|
|
|
2019-10-17 11:56:42 +00:00
|
|
|
if address "sender" "emacs-devel@@gnu.org" @{
|
|
|
|
fileinto "INBOX.emacs-devel";
|
2007-09-06 05:07:05 +00:00
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
2007-10-28 09:18:39 +00:00
|
|
|
A few mailing lists do not use the @samp{Sender:} header, but has a
|
|
|
|
unique identifier in some other header. The following is not a
|
|
|
|
complete script, it assumes that @code{fileinto} has already been
|
2007-09-06 05:07:05 +00:00
|
|
|
required.
|
|
|
|
|
|
|
|
@example
|
|
|
|
if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
|
2010-06-23 07:44:09 +00:00
|
|
|
fileinto "INBOX.auc-tex";
|
2007-09-06 05:07:05 +00:00
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
At last, we have the hopeless mailing lists that does not have any
|
|
|
|
unique identifier and you are forced to match on the @samp{To:} and
|
|
|
|
@samp{Cc} headers. As before, this snippet assumes that @code{fileinto}
|
|
|
|
has been required.
|
|
|
|
|
|
|
|
@example
|
|
|
|
if address ["to", "cc"] "kerberos@@mit.edu" @{
|
2010-06-23 07:44:09 +00:00
|
|
|
fileinto "INBOX.kerberos";
|
2007-09-06 05:07:05 +00:00
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@node Manage Sieve API
|
|
|
|
@chapter Manage Sieve API
|
|
|
|
|
|
|
|
The @file{sieve-manage.el} library contains low-level functionality
|
|
|
|
for talking to a server with the @sc{managesieve} protocol.
|
|
|
|
|
|
|
|
A number of user-visible variables exist, which all can be customized
|
2018-02-26 12:53:37 +00:00
|
|
|
in the @code{sieve} group (@kbd{M-x customize-group @key{RET} sieve @key{RET}}):
|
2007-09-06 05:07:05 +00:00
|
|
|
|
|
|
|
@table @code
|
|
|
|
|
|
|
|
@item sieve-manage-default-port
|
|
|
|
@vindex sieve-manage-default-port
|
|
|
|
Sets the default port to use, the suggested port number is @code{2000}.
|
|
|
|
|
|
|
|
@item sieve-manage-log
|
|
|
|
@vindex sieve-manage-log
|
|
|
|
If non-@code{nil}, should be a string naming a buffer where a protocol trace
|
|
|
|
is dumped (for debugging purposes).
|
|
|
|
|
|
|
|
@end table
|
|
|
|
|
|
|
|
The API functions include:
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
|
|
|
|
@item sieve-manage-open
|
|
|
|
@findex sieve-manage-open
|
|
|
|
Open connection to managesieve server, returning a buffer to be used
|
|
|
|
by all other API functions.
|
|
|
|
|
|
|
|
@item sieve-manage-opened
|
|
|
|
@findex sieve-manage-opened
|
|
|
|
Check if a server is open or not.
|
|
|
|
|
|
|
|
@item sieve-manage-close
|
|
|
|
@findex sieve-manage-close
|
|
|
|
Close a server connection.
|
|
|
|
|
2010-10-06 14:02:39 +00:00
|
|
|
@item sieve-manage-authenticate
|
|
|
|
@findex sieve-manage-authenticate
|
|
|
|
Authenticate to the server.
|
|
|
|
|
2007-09-06 05:07:05 +00:00
|
|
|
@item sieve-manage-capability
|
|
|
|
@findex sieve-manage-capability
|
|
|
|
Return a list of capabilities the server supports.
|
|
|
|
|
|
|
|
@item sieve-manage-listscripts
|
|
|
|
@findex sieve-manage-listscripts
|
|
|
|
List scripts on the server.
|
|
|
|
|
|
|
|
@item sieve-manage-havespace
|
|
|
|
@findex sieve-manage-havespace
|
|
|
|
Return non-@code{nil} if the server has room for a script of given
|
|
|
|
size.
|
|
|
|
|
|
|
|
@item sieve-manage-getscript
|
|
|
|
@findex sieve-manage-getscript
|
|
|
|
Download script from server.
|
|
|
|
|
|
|
|
@item sieve-manage-putscript
|
|
|
|
@findex sieve-manage-putscript
|
|
|
|
Upload script to server.
|
|
|
|
|
|
|
|
@item sieve-manage-setactive
|
|
|
|
@findex sieve-manage-setactive
|
|
|
|
Indicate which script on the server should be active.
|
|
|
|
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Standards
|
|
|
|
@chapter Standards
|
|
|
|
|
|
|
|
The Emacs Sieve package implements all or parts of a small but
|
|
|
|
hopefully growing number of RFCs and drafts documents. This chapter
|
|
|
|
lists the relevant ones. They can all be fetched from
|
|
|
|
@uref{http://quimby.gnus.org/notes/}.
|
|
|
|
|
|
|
|
@table @dfn
|
|
|
|
|
|
|
|
@item RFC3028
|
|
|
|
Sieve: A Mail Filtering Language.
|
|
|
|
|
2013-06-14 09:48:49 +00:00
|
|
|
@item RFC5804
|
2007-09-06 05:07:05 +00:00
|
|
|
A Protocol for Remotely Managing Sieve Scripts
|
|
|
|
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node GNU Free Documentation License
|
|
|
|
@appendix GNU Free Documentation License
|
|
|
|
@include doclicense.texi
|
|
|
|
|
|
|
|
@node Index
|
|
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
|
|
|
|
@bye
|
|
|
|
|
|
|
|
@c End:
|