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