\input texinfo @c -*-texinfo-*-@setfilename ../info/sieve@settitle Emacs Sieve Manual@synindex fn cp@synindex vr cp@synindex pg cp@copyingThis file documents the Emacs Sieve package, for server-side mail filtering.Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006 FreeSoftware Foundation, Inc.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.2 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNUManual'', and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense'' in the Emacs manual.(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.@end quotation@end copying@dircategory Emacs@direntry* Sieve: (sieve). Managing Sieve scripts in Emacs.@end direntry@iftex@finalout@end iftex@setchapternewpage odd@titlepage@title Emacs Sieve Manual@author by Simon Josefsson@page@vskip 0pt plus 1filll@insertcopying@end titlepage@node Top@top Sieve Support for EmacsThis manual documents the Emacs Sieve package.It is intended as a users manual for Sieve Mode and Manage Sieve, andas a reference manual for the @samp{sieve-manage} protocol Emacs LispAPI.Sieve is a language for server-side filtering of mail. The languageis documented in RFC 3028. This manual does not attempt to documentthe language, so keep RFC 3028 around.A good online Sieve resources is @uref{http://www.cyrusoft.com/sieve/}.@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.* Index:: Function and variable index.@end menu@node Installation@chapter Installation@cindex Install@cindex SetupThe Sieve package should come with your Emacs version, and should beready for use directly.However, to manually set up the package you can put the followingcommands 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 ModeSieve mode provides syntax-based indentation, font-locking support andother handy functions to make editing Sieve scripts easier.Use @samp{M-x sieve-mode} to switch to this major mode. This commandruns the hook @code{sieve-mode-hook}.@vindex sieve-mode-map@vindex sieve-mode-syntax-tableSieve mode is derived from @code{c-mode}, and is very similar exceptfor the syntax of comments. The keymap (@code{sieve-mode-map}) isinherited from @code{c-mode}, as are the variables for customizingindentation. 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 containsbindings to manage Sieve scripts remotely. @xref{Managing Sieve}.@table @kbd@item C-c RET@kindex C-c RET@findex sieve-manage@cindex manage remote sieve scriptOpen a connection to a remote server using the Managesieve protocol.@item C-c C-l@kindex C-c C-l@findex sieve-upload@cindex upload sieve scriptUpload the Sieve script to the currently open server.@end table@node Managing Sieve@chapter Managing SieveManage Sieve is a special mode used to display Sieve scripts availableon a remote server. It can be invoked with @kbd{M-x sieve-manageRET}, which queries the user for a server and if necessary, usercredentials to use.When a server has been successfully contacted, the Manage Sieve bufferlooks something like:@exampleServer : mailserver:20002 scripts on server, press RET on a script name edits it, orpress RET on <new script> to create a new script. <new script> ACTIVE .sieve template.siv@end exampleOne of the scripts are highlighted, and standard point navigationcommands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate thelist.The following commands are available in the Manage Sieve buffer:@table @kbd@item m@kindex m@findex sieve-activateActivates the currently highlighted script.@item u@kindex u@findex sieve-deactivateDeactivates the currently highlighted script.@item C-M-?@kindex C-M-?@findex sieve-deactivate-allDeactivates all scripts.@item r@kindex r@findex sieve-removeRemove currently highlighted script.@item RET@item mouse-2@item f@kindex RET@kindex mouse-2@kindex f@findex sieve-edit-scriptBury the server buffer and download the currently highlighted scriptinto a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).@item o@kindex o@findex sieve-edit-script-other-windowCreate a new buffer in another window containing the currentlyhighlighted script for editing in Sieve mode (@pxref{Sieve Mode}).@item q@kindex q@findex sieve-bury-bufferBury the Manage Sieve buffer without closing the connection.@item ?@item h@kindex ?@kindex h@findex sieve-helpDisplays help in the minibuffer. @end table@node Examples@chapter ExamplesIf you are not familiar with Sieve, this chapter contains a few simplecode snippets that you can cut'n'paste and modify at will, until youfeel more comfortable with the Sieve language to write the rules fromscratch.The following complete Sieve script places all messages with a matching@samp{Sender:} header into the given mailbox. Many mailing lists usesthis format. The first line makes sure your Sieve server understandsthe @code{fileinto} command.@examplerequire "fileinto";if address "sender" "owner-w3-beta@@xemacs.org" @{ fileinto "INBOX.w3-beta";@}@end exampleA few mailing lists do not use the @samp{Sender:} header, but doescontain some unique identifier in some other header. The following isnot a complete script, it assumes that @code{fileinto} has already beenrequired.@exampleif header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{ fileinto "INBOX.auc-tex";@}@end exampleAt last, we have the hopeless mailing lists that does not have anyunique 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.@exampleif address ["to", "cc"] "kerberos@@mit.edu" @{ fileinto "INBOX.kerberos";@}@end example@node Manage Sieve API@chapter Manage Sieve APIThe @file{sieve-manage.el} library contains low-level functionalityfor talking to a server with the @sc{managesieve} protocol.A number of user-visible variables exist, which all can be customizedin the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):@table @code@item sieve-manage-default-user@vindex sieve-manage-default-userSets the default username.@item sieve-manage-default-port@vindex sieve-manage-default-portSets the default port to use, the suggested port number is @code{2000}.@item sieve-manage-log@vindex sieve-manage-logIf non-@code{nil}, should be a string naming a buffer where a protocol traceis dumped (for debugging purposes).@end tableThe API functions include:@table @code@item sieve-manage-open@findex sieve-manage-openOpen connection to managesieve server, returning a buffer to be usedby all other API functions.@item sieve-manage-opened@findex sieve-manage-openedCheck if a server is open or not.@item sieve-manage-close@findex sieve-manage-closeClose a server connection.@item sieve-manage-authenticate@findex sieve-manage-authenticateAuthenticate to the server.@item sieve-manage-capability@findex sieve-manage-capabilityReturn a list of capabilities the server support.@item sieve-manage-listscripts@findex sieve-manage-listscriptsList scripts on the server.@item sieve-manage-havespace@findex sieve-manage-havespaceReturns non-@code{nil} iff server have roam for a script of givensize.@item sieve-manage-getscript@findex sieve-manage-getscriptDownload script from server.@item sieve-manage-putscript@findex sieve-manage-putscriptUpload script to server.@item sieve-manage-setactive@findex sieve-manage-setactiveIndicate which script on the server should be active.@end table@node Standards@chapter StandardsThe Emacs Sieve package implements all or parts of a small buthopefully growing number of RFCs and drafts documents. This chapterlists the relevant ones. They can all be fetched from@uref{http://quimby.gnus.org/notes/}.@table @dfn@item RFC3028Sieve: A Mail Filtering Language.@item draft-martin-managesieve-03A Protocol for Remotely Managing Sieve Scripts@end table@node Index@chapter Index@printindex cp@summarycontents@contents@bye@c End:@ignore arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3@end ignore