Commit | Line | Data |
---|---|---|
4009494e | 1 | \input texinfo @c -*-texinfo-*- |
7fbf7cae TZ |
2 | |
3 | @include gnus-overrides.texi | |
4 | ||
db78a8cb | 5 | @setfilename ../../info/sieve |
4009494e | 6 | @settitle Emacs Sieve Manual |
c6ab4664 | 7 | @documentencoding UTF-8 |
4009494e GM |
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 | ||
6bc383b1 | 15 | Copyright @copyright{} 2001--2014 Free Software Foundation, Inc. |
4009494e GM |
16 | |
17 | @quotation | |
18 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 19 | under the terms of the GNU Free Documentation License, Version 1.3 or |
4009494e | 20 | any later version published by the Free Software Foundation; with no |
debf4439 GM |
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''. | |
4009494e | 24 | |
6f093307 | 25 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
6bf430d1 | 26 | modify this GNU manual.'' |
4009494e GM |
27 | @end quotation |
28 | @end copying | |
29 | ||
0c973505 | 30 | @dircategory Emacs network features |
4009494e GM |
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 | |
7fbf7cae TZ |
40 | @ifset WEBHACKDEVEL |
41 | @title Emacs Sieve Manual (DEVELOPMENT VERSION) | |
42 | @end ifset | |
43 | @ifclear WEBHACKDEVEL | |
4009494e | 44 | @title Emacs Sieve Manual |
7fbf7cae | 45 | @end ifclear |
4009494e GM |
46 | |
47 | @author by Simon Josefsson | |
48 | @page | |
49 | @vskip 0pt plus 1filll | |
50 | @insertcopying | |
51 | @end titlepage | |
52 | ||
5dc584b5 KB |
53 | @summarycontents |
54 | @contents | |
4009494e GM |
55 | |
56 | @node Top | |
57 | @top Sieve Support for Emacs | |
58 | ||
5dc584b5 | 59 | This is intended as a users manual for Sieve Mode and Manage Sieve, and |
4009494e GM |
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 | ||
5dc584b5 KB |
67 | @ifnottex |
68 | @insertcopying | |
69 | @end ifnottex | |
4009494e GM |
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 | |
745b097b | 153 | Server : mailserver:sieve |
4009494e GM |
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 | |
65e7ca35 | 163 | commands (@kbd{<up>}, @kbd{<down>} etc.)@: can be used to navigate the |
4009494e GM |
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 | |
f99f1641 | 216 | Displays help in the minibuffer. |
4009494e | 217 | |
745b097b AK |
218 | @item Q |
219 | @kindex Q | |
220 | @findex sieve-manage-quit | |
221 | Quit Manage Sieve and close the connection. | |
222 | ||
4009494e GM |
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" @{ | |
b1fbbb32 | 242 | fileinto "INBOX.w3-beta"; |
4009494e GM |
243 | @} |
244 | @end example | |
245 | ||
01c52d31 MB |
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 | |
4009494e GM |
249 | required. |
250 | ||
251 | @example | |
252 | if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{ | |
b1fbbb32 | 253 | fileinto "INBOX.auc-tex"; |
4009494e GM |
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" @{ | |
b1fbbb32 | 264 | fileinto "INBOX.kerberos"; |
4009494e GM |
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 | ||
4009494e GM |
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 | ||
fd9ba500 JD |
307 | @item sieve-manage-authenticate |
308 | @findex sieve-manage-authenticate | |
309 | Authenticate to the server. | |
310 | ||
4009494e GM |
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 | ||
745b097b | 351 | @item RFC5804 |
4009494e GM |
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 | ||
4009494e GM |
364 | @bye |
365 | ||
366 | @c End: |