/[emacs]/emacs/man/sieve.texi
ViewVC logotype

Diff of /emacs/man/sieve.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1 by rsteib, Mon Aug 2 13:28:45 2004 UTC revision 1.2 by miles, Sat Sep 4 13:13:44 2004 UTC
# Line 0  Line 1 
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

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26