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 |
280 |
|
If non-nil, should be a string naming a buffer where a protocol trace |
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 |
316 |
|
Returns non-nil iff server have roam for a script of given size. |
317 |
|
|
318 |
|
@item sieve-manage-getscript |
319 |
|
@findex sieve-manage-getscript |
320 |
|
Download script from server. |
321 |
|
|
322 |
|
@item sieve-manage-putscript |
323 |
|
@findex sieve-manage-putscript |
324 |
|
Upload script to server. |
325 |
|
|
326 |
|
@item sieve-manage-setactive |
327 |
|
@findex sieve-manage-setactive |
328 |
|
Indicate which script on the server should be active. |
329 |
|
|
330 |
|
@end table |
331 |
|
|
332 |
|
@node Standards |
333 |
|
@chapter Standards |
334 |
|
|
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/}. |
339 |
|
|
340 |
|
@table @dfn |
341 |
|
|
342 |
|
@item RFC3028 |
343 |
|
Sieve: A Mail Filtering Language. |
344 |
|
|
345 |
|
@item draft-martin-managesieve-03 |
346 |
|
A Protocol for Remotely Managing Sieve Scripts |
347 |
|
|
348 |
|
@end table |
349 |
|
|
350 |
|
|
351 |
|
@node Index |
352 |
|
@chapter Index |
353 |
|
@printindex cp |
354 |
|
|
355 |
|
@summarycontents |
356 |
|
@contents |
357 |
|
@bye |
358 |
|
|
359 |
|
@c End: |
360 |
|
|
361 |
|
@ignore |
362 |
|
arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3 |
363 |
|
@end ignore |