* lisp/doc-view.el (doc-view-scale-internally): New var.
[emacs.git] / doc / misc / sieve.texi
blobcbcd6a61f3927547b2f83f7fb5ead3c98fd4c5dd
1 \input texinfo                  @c -*-texinfo-*-
3 @include gnus-overrides.texi
5 @setfilename ../../info/sieve
6 @settitle Emacs Sieve Manual
7 @synindex fn cp
8 @synindex vr cp
9 @synindex pg cp
11 @copying
12 This file documents the Emacs Sieve package, for server-side mail filtering.
14 Copyright @copyright{} 2001--2013 Free Software Foundation, Inc.
16 @quotation
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
21 and with the Back-Cover Texts as in (a) below.  A copy of the license
22 is included in the section entitled ``GNU Free Documentation License''.
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual.''
26 @end quotation
27 @end copying
29 @dircategory Emacs network features
30 @direntry
31 * Sieve: (sieve).               Managing Sieve scripts in Emacs.
32 @end direntry
33 @iftex
34 @finalout
35 @end iftex
36 @setchapternewpage odd
38 @titlepage
39 @ifset WEBHACKDEVEL
40 @title Emacs Sieve Manual (DEVELOPMENT VERSION)
41 @end ifset
42 @ifclear WEBHACKDEVEL
43 @title Emacs Sieve Manual
44 @end ifclear
46 @author by Simon Josefsson
47 @page
48 @vskip 0pt plus 1filll
49 @insertcopying
50 @end titlepage
52 @summarycontents
53 @contents
55 @node Top
56 @top Sieve Support for Emacs
58 This is intended as a users manual for Sieve Mode and Manage Sieve, and
59 as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp
60 API.
62 Sieve is a language for server-side filtering of mail.  The language
63 is documented in RFC 3028.  This manual does not attempt to document
64 the language, so keep RFC 3028 around.
66 @ifnottex
67 @insertcopying
68 @end ifnottex
70 @menu
71 * Installation::          Getting ready to use the package.
72 * Sieve Mode::            Editing Sieve scripts.
73 * Managing Sieve::        Managing Sieve scripts on a remote server.
74 * Examples ::             A few Sieve code snippets.
75 * Manage Sieve API ::     Interfacing to the Manage Sieve Protocol API.
76 * Standards::             A summary of RFCs and working documents used.
77 * GNU Free Documentation License:: The license for this documentation.
78 * Index::                 Function and variable index.
79 @end menu
82 @node Installation
83 @chapter Installation
84 @cindex Install
85 @cindex Setup
87 The Sieve package should come with your Emacs version, and should be
88 ready for use directly.
90 However, to manually set up the package you can put the following
91 commands in your @code{~/.emacs}:
93 @lisp
94 (autoload 'sieve-mode "sieve-mode")
95 @end lisp
96 @lisp
97 (setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode)
98                             auto-mode-alist))
99 @end lisp
102 @node Sieve Mode
103 @chapter Sieve Mode
105 Sieve mode provides syntax-based indentation, font-locking support and
106 other handy functions to make editing Sieve scripts easier.
108 Use @samp{M-x sieve-mode} to switch to this major mode.  This command
109 runs the hook @code{sieve-mode-hook}.
111 @vindex sieve-mode-map
112 @vindex sieve-mode-syntax-table
113 Sieve mode is derived from @code{c-mode}, and is very similar except
114 for the syntax of comments.  The keymap (@code{sieve-mode-map}) is
115 inherited from @code{c-mode}, as are the variables for customizing
116 indentation.  Sieve mode has its own abbrev table
117 (@code{sieve-mode-abbrev-table}) and syntax table
118 (@code{sieve-mode-syntax-table}).
120 In addition to the editing utility functions, Sieve mode also contains
121 bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
123 @table @kbd
125 @item C-c RET
126 @kindex C-c RET
127 @findex sieve-manage
128 @cindex manage remote sieve script
129 Open a connection to a remote server using the Managesieve protocol.
131 @item C-c C-l
132 @kindex C-c C-l
133 @findex sieve-upload
134 @cindex upload sieve script
135 Upload the Sieve script to the currently open server.
137 @end table
140 @node Managing Sieve
141 @chapter Managing Sieve
143 Manage Sieve is a special mode used to display Sieve scripts available
144 on a remote server.  It can be invoked with @kbd{M-x sieve-manage
145 RET}, which queries the user for a server and if necessary, user
146 credentials to use.
148 When a server has been successfully contacted, the Manage Sieve buffer
149 looks something like:
151 @example
152 Server  : mailserver:2000
154 2 scripts on server, press RET on a script name edits it, or
155 press RET on <new script> to create a new script.
156         <new script>
157  ACTIVE .sieve
158         template.siv
159 @end example
161 One of the scripts are highlighted, and standard point navigation
162 commands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate the
163 list.
165 The following commands are available in the Manage Sieve buffer:
167 @table @kbd
169 @item m
170 @kindex m
171 @findex sieve-activate
172 Activates the currently highlighted script.
174 @item u
175 @kindex u
176 @findex sieve-deactivate
177 Deactivates the currently highlighted script.
179 @item C-M-?
180 @kindex C-M-?
181 @findex sieve-deactivate-all
182 Deactivates all scripts.
184 @item r
185 @kindex r
186 @findex sieve-remove
187 Remove currently highlighted script.
189 @item RET
190 @item mouse-2
191 @item f
192 @kindex RET
193 @kindex mouse-2
194 @kindex f
195 @findex sieve-edit-script
196 Bury the server buffer and download the currently highlighted script
197 into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).
199 @item o
200 @kindex o
201 @findex sieve-edit-script-other-window
202 Create a new buffer in another window containing the currently
203 highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).
205 @item q
206 @kindex q
207 @findex sieve-bury-buffer
208 Bury the Manage Sieve buffer without closing the connection.
210 @item ?
211 @item h
212 @kindex ?
213 @kindex h
214 @findex sieve-help
215 Displays help in the minibuffer.
217 @end table
219 @node Examples
220 @chapter Examples
222 If you are not familiar with Sieve, this chapter contains a few simple
223 code snippets that you can cut'n'paste and modify at will, until you
224 feel more comfortable with the Sieve language to write the rules from
225 scratch.
227 The following complete Sieve script places all messages with a matching
228 @samp{Sender:} header into the given mailbox.  Many mailing lists uses
229 this format.  The first line makes sure your Sieve server understands
230 the @code{fileinto} command.
232 @example
233 require "fileinto";
235 if address "sender" "owner-w3-beta@@xemacs.org" @{
236         fileinto "INBOX.w3-beta";
238 @end example
240 A few mailing lists do not use the @samp{Sender:} header, but has a
241 unique identifier in some other header.  The following is not a
242 complete script, it assumes that @code{fileinto} has already been
243 required.
245 @example
246 if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
247         fileinto "INBOX.auc-tex";
249 @end example
251 At last, we have the hopeless mailing lists that does not have any
252 unique identifier and you are forced to match on the @samp{To:} and
253 @samp{Cc} headers.  As before, this snippet assumes that @code{fileinto}
254 has been required.
256 @example
257 if address ["to", "cc"] "kerberos@@mit.edu" @{
258         fileinto "INBOX.kerberos";
260 @end example
262 @node Manage Sieve API
263 @chapter Manage Sieve API
265 The @file{sieve-manage.el} library contains low-level functionality
266 for talking to a server with the @sc{managesieve} protocol.
268 A number of user-visible variables exist, which all can be customized
269 in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):
271 @table @code
273 @item sieve-manage-default-port
274 @vindex sieve-manage-default-port
275 Sets the default port to use, the suggested port number is @code{2000}.
277 @item sieve-manage-log
278 @vindex sieve-manage-log
279 If non-@code{nil}, should be a string naming a buffer where a protocol trace
280 is dumped (for debugging purposes).
282 @end table
284 The API functions include:
286 @table @code
288 @item sieve-manage-open
289 @findex sieve-manage-open
290 Open connection to managesieve server, returning a buffer to be used
291 by all other API functions.
293 @item sieve-manage-opened
294 @findex sieve-manage-opened
295 Check if a server is open or not.
297 @item sieve-manage-close
298 @findex sieve-manage-close
299 Close a server connection.
301 @item sieve-manage-authenticate
302 @findex sieve-manage-authenticate
303 Authenticate to the server.
305 @item sieve-manage-capability
306 @findex sieve-manage-capability
307 Return a list of capabilities the server supports.
309 @item sieve-manage-listscripts
310 @findex sieve-manage-listscripts
311 List scripts on the server.
313 @item sieve-manage-havespace
314 @findex sieve-manage-havespace
315 Return non-@code{nil} if the server has room for a script of given
316 size.
318 @item sieve-manage-getscript
319 @findex sieve-manage-getscript
320 Download script from server.
322 @item sieve-manage-putscript
323 @findex sieve-manage-putscript
324 Upload script to server.
326 @item sieve-manage-setactive
327 @findex sieve-manage-setactive
328 Indicate which script on the server should be active.
330 @end table
332 @node Standards
333 @chapter Standards
335 The Emacs Sieve package implements all or parts of a small but
336 hopefully growing number of RFCs and drafts documents.  This chapter
337 lists the relevant ones.  They can all be fetched from
338 @uref{http://quimby.gnus.org/notes/}.
340 @table @dfn
342 @item RFC3028
343 Sieve: A Mail Filtering Language.
345 @item draft-martin-managesieve-03
346 A Protocol for Remotely Managing Sieve Scripts
348 @end table
350 @node GNU Free Documentation License
351 @appendix GNU Free Documentation License
352 @include doclicense.texi
354 @node Index
355 @unnumbered Index
356 @printindex cp
358 @bye
360 @c End: