doc/misc/sieve.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @include gnus-overrides.texi
   4
   5 @setfilename ../../info/sieve
   6 @settitle Emacs Sieve Manual
   7 @synindex fn cp
   8 @synindex vr cp
   9 @synindex pg cp
  10
  11 @copying
  12 This file documents the Emacs Sieve package, for server-side mail filtering.
  13
  14 Copyright @copyright{} 2001-2011  Free Software Foundation, Inc.
  15
  16 @quotation
  17 Permission is granted to copy, distribute and/or modify this document
  18 under the terms of the GNU Free Documentation License, Version 1.3 or
  19 any later version published by the Free Software Foundation; with no
  20 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
  21 and with the Back-Cover Texts as in (a) below.  A copy of the license
  22 is included in the section entitled ``GNU Free Documentation License''.
  23
  24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  25 modify this GNU manual.  Buying copies from the FSF supports it in
  26 developing GNU and promoting software freedom.''
  27 @end quotation
  28 @end copying
  29
  30 @dircategory Emacs network features
  31 @direntry
  32 * Sieve: (sieve).               Managing Sieve scripts in Emacs.
  33 @end direntry
  34 @iftex
  35 @finalout
  36 @end iftex
  37 @setchapternewpage odd
  38
  39 @titlepage
  40 @ifset WEBHACKDEVEL
  41 @title Emacs Sieve Manual (DEVELOPMENT VERSION)
  42 @end ifset
  43 @ifclear WEBHACKDEVEL
  44 @title Emacs Sieve Manual
  45 @end ifclear
  46
  47 @author by Simon Josefsson
  48 @page
  49 @vskip 0pt plus 1filll
  50 @insertcopying
  51 @end titlepage
  52
  53 @summarycontents
  54 @contents
  55
  56 @node Top
  57 @top Sieve Support for Emacs
  58
  59 This 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 @ifnottex
  68 @insertcopying
  69 @end ifnottex
  70
  71 @menu
  72 * Installation::          Getting ready to use the package.
  73 * Sieve Mode::            Editing Sieve scripts.
  74 * Managing Sieve::        Managing Sieve scripts on a remote server.
  75 * Examples ::             A few Sieve code snippets.
  76 * Manage Sieve API ::     Interfacing to the Manage Sieve Protocol API.
  77 * Standards::             A summary of RFCs and working documents used.
  78 * GNU Free Documentation License:: The license for this documentation.
  79 * Index::                 Function and variable index.
  80 @end menu
  81
  82
  83 @node Installation
  84 @chapter Installation
  85 @cindex Install
  86 @cindex Setup
  87
  88 The Sieve package should come with your Emacs version, and should be
  89 ready for use directly.
  90
  91 However, to manually set up the package you can put the following
  92 commands in your @code{~/.emacs}:
  93
  94 @lisp
  95 (autoload 'sieve-mode "sieve-mode")
  96 @end lisp
  97 @lisp
  98 (setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode)
  99                             auto-mode-alist))
 100 @end lisp
 101
 102
 103 @node Sieve Mode
 104 @chapter Sieve Mode
 105
 106 Sieve mode provides syntax-based indentation, font-locking support and
 107 other handy functions to make editing Sieve scripts easier.
 108
 109 Use @samp{M-x sieve-mode} to switch to this major mode.  This command
 110 runs the hook @code{sieve-mode-hook}.
 111
 112 @vindex sieve-mode-map
 113 @vindex sieve-mode-syntax-table
 114 Sieve mode is derived from @code{c-mode}, and is very similar except
 115 for the syntax of comments.  The keymap (@code{sieve-mode-map}) is
 116 inherited from @code{c-mode}, as are the variables for customizing
 117 indentation.  Sieve mode has its own abbrev table
 118 (@code{sieve-mode-abbrev-table}) and syntax table
 119 (@code{sieve-mode-syntax-table}).
 120
 121 In addition to the editing utility functions, Sieve mode also contains
 122 bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
 123
 124 @table @kbd
 125
 126 @item C-c RET
 127 @kindex C-c RET
 128 @findex sieve-manage
 129 @cindex manage remote sieve script
 130 Open a connection to a remote server using the Managesieve protocol.
 131
 132 @item C-c C-l
 133 @kindex C-c C-l
 134 @findex sieve-upload
 135 @cindex upload sieve script
 136 Upload the Sieve script to the currently open server.
 137
 138 @end table
 139
 140
 141 @node Managing Sieve
 142 @chapter Managing Sieve
 143
 144 Manage Sieve is a special mode used to display Sieve scripts available
 145 on a remote server.  It can be invoked with @kbd{M-x sieve-manage
 146 RET}, which queries the user for a server and if necessary, user
 147 credentials to use.
 148
 149 When a server has been successfully contacted, the Manage Sieve buffer
 150 looks something like:
 151
 152 @example
 153 Server  : mailserver:2000
 154
 155 2 scripts on server, press RET on a script name edits it, or
 156 press RET on <new script> to create a new script.
 157         <new script>
 158  ACTIVE .sieve
 159         template.siv
 160 @end example
 161
 162 One of the scripts are highlighted, and standard point navigation
 163 commands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate the
 164 list.
 165
 166 The following commands are available in the Manage Sieve buffer:
 167
 168 @table @kbd
 169
 170 @item m
 171 @kindex m
 172 @findex sieve-activate
 173 Activates the currently highlighted script.
 174
 175 @item u
 176 @kindex u
 177 @findex sieve-deactivate
 178 Deactivates the currently highlighted script.
 179
 180 @item C-M-?
 181 @kindex C-M-?
 182 @findex sieve-deactivate-all
 183 Deactivates all scripts.
 184
 185 @item r
 186 @kindex r
 187 @findex sieve-remove
 188 Remove currently highlighted script.
 189
 190 @item RET
 191 @item mouse-2
 192 @item f
 193 @kindex RET
 194 @kindex mouse-2
 195 @kindex f
 196 @findex sieve-edit-script
 197 Bury the server buffer and download the currently highlighted script
 198 into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).
 199
 200 @item o
 201 @kindex o
 202 @findex sieve-edit-script-other-window
 203 Create a new buffer in another window containing the currently
 204 highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).
 205
 206 @item q
 207 @kindex q
 208 @findex sieve-bury-buffer
 209 Bury the Manage Sieve buffer without closing the connection.
 210
 211 @item ?
 212 @item h
 213 @kindex ?
 214 @kindex h
 215 @findex sieve-help
 216 Displays help in the minibuffer.
 217
 218 @end table
 219
 220 @node Examples
 221 @chapter Examples
 222
 223 If you are not familiar with Sieve, this chapter contains a few simple
 224 code snippets that you can cut'n'paste and modify at will, until you
 225 feel more comfortable with the Sieve language to write the rules from
 226 scratch.
 227
 228 The following complete Sieve script places all messages with a matching
 229 @samp{Sender:} header into the given mailbox.  Many mailing lists uses
 230 this format.  The first line makes sure your Sieve server understands
 231 the @code{fileinto} command.
 232
 233 @example
 234 require "fileinto";
 235
 236 if address "sender" "owner-w3-beta@@xemacs.org" @{
 237         fileinto "INBOX.w3-beta";
 238 @}
 239 @end example
 240
 241 A few mailing lists do not use the @samp{Sender:} header, but has a
 242 unique identifier in some other header.  The following is not a
 243 complete script, it assumes that @code{fileinto} has already been
 244 required.
 245
 246 @example
 247 if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
 248         fileinto "INBOX.auc-tex";
 249 @}
 250 @end example
 251
 252 At last, we have the hopeless mailing lists that does not have any
 253 unique identifier and you are forced to match on the @samp{To:} and
 254 @samp{Cc} headers.  As before, this snippet assumes that @code{fileinto}
 255 has been required.
 256
 257 @example
 258 if address ["to", "cc"] "kerberos@@mit.edu" @{
 259         fileinto "INBOX.kerberos";
 260 @}
 261 @end example
 262
 263 @node Manage Sieve API
 264 @chapter Manage Sieve API
 265
 266 The @file{sieve-manage.el} library contains low-level functionality
 267 for talking to a server with the @sc{managesieve} protocol.
 268
 269 A number of user-visible variables exist, which all can be customized
 270 in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):
 271
 272 @table @code
 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 supports.
 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 Return non-@code{nil} if the server has room 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 @node GNU Free Documentation License
 352 @appendix GNU Free Documentation License
 353 @include doclicense.texi
 354
 355 @node Index
 356 @unnumbered Index
 357 @printindex cp
 358
 359 @bye
 360
 361 @c End: