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