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