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:sieve
 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 @item Q
 218 @kindex Q
 219 @findex sieve-manage-quit
 220 Quit Manage Sieve and close the connection.
 221
 222 @end table
 223
 224 @node Examples
 225 @chapter Examples
 226
 227 If you are not familiar with Sieve, this chapter contains a few simple
 228 code snippets that you can cut'n'paste and modify at will, until you
 229 feel more comfortable with the Sieve language to write the rules from
 230 scratch.
 231
 232 The following complete Sieve script places all messages with a matching
 233 @samp{Sender:} header into the given mailbox.  Many mailing lists uses
 234 this format.  The first line makes sure your Sieve server understands
 235 the @code{fileinto} command.
 236
 237 @example
 238 require "fileinto";
 239
 240 if address "sender" "owner-w3-beta@@xemacs.org" @{
 241         fileinto "INBOX.w3-beta";
 242 @}
 243 @end example
 244
 245 A few mailing lists do not use the @samp{Sender:} header, but has a
 246 unique identifier in some other header.  The following is not a
 247 complete script, it assumes that @code{fileinto} has already been
 248 required.
 249
 250 @example
 251 if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
 252         fileinto "INBOX.auc-tex";
 253 @}
 254 @end example
 255
 256 At last, we have the hopeless mailing lists that does not have any
 257 unique identifier and you are forced to match on the @samp{To:} and
 258 @samp{Cc} headers.  As before, this snippet assumes that @code{fileinto}
 259 has been required.
 260
 261 @example
 262 if address ["to", "cc"] "kerberos@@mit.edu" @{
 263         fileinto "INBOX.kerberos";
 264 @}
 265 @end example
 266
 267 @node Manage Sieve API
 268 @chapter Manage Sieve API
 269
 270 The @file{sieve-manage.el} library contains low-level functionality
 271 for talking to a server with the @sc{managesieve} protocol.
 272
 273 A number of user-visible variables exist, which all can be customized
 274 in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):
 275
 276 @table @code
 277
 278 @item sieve-manage-default-port
 279 @vindex sieve-manage-default-port
 280 Sets the default port to use, the suggested port number is @code{2000}.
 281
 282 @item sieve-manage-log
 283 @vindex sieve-manage-log
 284 If non-@code{nil}, should be a string naming a buffer where a protocol trace
 285 is dumped (for debugging purposes).
 286
 287 @end table
 288
 289 The API functions include:
 290
 291 @table @code
 292
 293 @item sieve-manage-open
 294 @findex sieve-manage-open
 295 Open connection to managesieve server, returning a buffer to be used
 296 by all other API functions.
 297
 298 @item sieve-manage-opened
 299 @findex sieve-manage-opened
 300 Check if a server is open or not.
 301
 302 @item sieve-manage-close
 303 @findex sieve-manage-close
 304 Close a server connection.
 305
 306 @item sieve-manage-authenticate
 307 @findex sieve-manage-authenticate
 308 Authenticate to the server.
 309
 310 @item sieve-manage-capability
 311 @findex sieve-manage-capability
 312 Return a list of capabilities the server supports.
 313
 314 @item sieve-manage-listscripts
 315 @findex sieve-manage-listscripts
 316 List scripts on the server.
 317
 318 @item sieve-manage-havespace
 319 @findex sieve-manage-havespace
 320 Return non-@code{nil} if the server has room for a script of given
 321 size.
 322
 323 @item sieve-manage-getscript
 324 @findex sieve-manage-getscript
 325 Download script from server.
 326
 327 @item sieve-manage-putscript
 328 @findex sieve-manage-putscript
 329 Upload script to server.
 330
 331 @item sieve-manage-setactive
 332 @findex sieve-manage-setactive
 333 Indicate which script on the server should be active.
 334
 335 @end table
 336
 337 @node Standards
 338 @chapter Standards
 339
 340 The Emacs Sieve package implements all or parts of a small but
 341 hopefully growing number of RFCs and drafts documents.  This chapter
 342 lists the relevant ones.  They can all be fetched from
 343 @uref{http://quimby.gnus.org/notes/}.
 344
 345 @table @dfn
 346
 347 @item RFC3028
 348 Sieve: A Mail Filtering Language.
 349
 350 @item RFC5804
 351 A Protocol for Remotely Managing Sieve Scripts
 352
 353 @end table
 354
 355 @node GNU Free Documentation License
 356 @appendix GNU Free Documentation License
 357 @include doclicense.texi
 358
 359 @node Index
 360 @unnumbered Index
 361 @printindex cp
 362
 363 @bye
 364
 365 @c End: