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