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