man/sieve.texi

   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, 2002, 2003, 2004, 2005 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.2 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-@code{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-@code{nil} iff server have roam for a script of given
 317 size.
 318
 319 @item sieve-manage-getscript
 320 @findex sieve-manage-getscript
 321 Download script from server.
 322
 323 @item sieve-manage-putscript
 324 @findex sieve-manage-putscript
 325 Upload script to server.
 326
 327 @item sieve-manage-setactive
 328 @findex sieve-manage-setactive
 329 Indicate which script on the server should be active.
 330
 331 @end table
 332
 333 @node Standards
 334 @chapter Standards
 335
 336 The Emacs Sieve package implements all or parts of a small but
 337 hopefully growing number of RFCs and drafts documents.  This chapter
 338 lists the relevant ones.  They can all be fetched from
 339 @uref{http://quimby.gnus.org/notes/}.
 340
 341 @table @dfn
 342
 343 @item RFC3028
 344 Sieve: A Mail Filtering Language.
 345
 346 @item draft-martin-managesieve-03
 347 A Protocol for Remotely Managing Sieve Scripts
 348
 349 @end table
 350
 351
 352 @node Index
 353 @chapter Index
 354 @printindex cp
 355
 356 @summarycontents
 357 @contents
 358 @bye
 359
 360 @c End:
 361
 362 @ignore
 363    arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3
 364 @end ignore