sieve-ja.texi

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