doc/misc/sieve.texi

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