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