doc/misc/sieve.texi

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