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