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