texi/sieve.texi

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