2001-11-07 Simon Josefsson <jas@extundo.com>

[gnus] / texi / sieve.texi

\input texinfo                  @c -*-texinfo-*-

@setfilename sieve
@settitle Emacs Sieve Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@dircategory Emacs
@direntry
* Sieve: (sieve).               Managing Sieve scripts in Emacs.
@end direntry
@iftex
@finalout
@end iftex
@setchapternewpage odd

@ifnottex

This file documents the Emacs Sieve package.

Copyright (C) 2001 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end ifnottex

@tex

@titlepage
@title Emacs Sieve Manual

@author by Simon Josefsson
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 2001 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being none, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end titlepage
@page

@end tex

@node Top
@top Sieve Support for Emacs

This manual documents the Emacs Sieve package.

It is intended as a users manual for Sieve Mode and Manage Sieve, and
as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp
API.

Sieve is a language for server-side filtering of mail.  The language
is documented in RFC 3028.  This manual does not attempt to document
the language, so keep RFC 3028 around.

@menu
* Installation::          Getting ready to use the package.
* Sieve Mode::            Editing Sieve scripts.
* Managing Sieve::        Managing Sieve scripts on a remote server.
* Examples ::             A few Sieve code snippets.
* Manage Sieve API ::     Interfacing to the Manage Sieve Protocol API.
* Standards::             A summary of RFCs and working documents used.
* Index::                 Function and variable index.
@end menu


@node Installation
@chapter Installation
@cindex Install
@cindex Setup

The Sieve package should come with your Emacs version, and should be
ready for use directly.

However, to manually set up the package you can put the following
commands in your @code{~/.emacs}:

@lisp
(autoload 'sieve-mode "sieve-mode")
@end lisp
@lisp
(setq auto-mode-alist (cons '("\\.si\\(v\\|eve\\)\\'" . sieve-mode)
                            auto-mode-alist))
@end lisp


@node Sieve Mode
@chapter Sieve Mode

Sieve mode provides syntax-based indentation, font-locking support and
other handy functions to make editing Sieve scripts easier.

Use @samp{M-x sieve-mode} to switch to this major mode.  This command
runs the hook @code{sieve-mode-hook}.

@vindex sieve-mode-map
@vindex sieve-mode-syntax-table
Sieve mode is derived from @code{c-mode}, and is very similar except
for the syntax of comments.  The keymap (@code{sieve-mode-map}) is
inherited from @code{c-mode}, as are the the variables for customizing
indentation.  Sieve mode has its own abbrev table
(@code{sieve-mode-abbrev-table}) and syntax table
(@code{sieve-mode-syntax-table}).

In addition to the editing utility functions, Sieve mode also contains
bindings to manage Sieve scripts remotely. @pxref{Managing Sieve}.

@table @kbd

@item C-c RET
@kindex C-c RET
@findex sieve-manage
@cindex manage remote sieve script
Open a connection to a remote server using the Managesieve protocol.

@item C-c C-l
@kindex C-c C-l
@findex sieve-upload
@cindex upload sieve script
Upload the Sieve script to the currently open server.

@end table


@node Managing Sieve
@chapter Managing Sieve

Manage Sieve is a special mode used to display Sieve scripts available
on a remote server.  It can be invoked with @kbd{M-x sieve-manage
RET}, which queries the user for a server and if necessary, user
credentials to use.

When a server has been succesfully contacted, the Manage Sieve buffer
looks something like:

@example
Server  : mailserver:2000

2 scripts on server, press RET on a script name edits it, or
press RET on <new script> to create a new script.
        <new script>
 ACTIVE .sieve
        template.siv
@end example

One of the scripts are highlighted, and standard point navigation
commands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate the
list.

The following commands are available in the Manage Sieve buffer:

@table @kbd

@item m
@kindex m
@findex sieve-activate
Activates the currently highlighted script.

@item u
@kindex u
@findex sieve-deactivate
Deactivates the currently highlighted script.

@item C-M-?
@kindex C-M-?
@findex sieve-deactivate-all
Deactivates all scripts.

@item r
@kindex r
@findex sieve-remove
Remove currently highlighted script.

@item RET
@item mouse-2
@item f
@kindex RET
@kindex mouse-2
@kindex f
@findex sieve-edit-script
Bury the server buffer and download the currently highlighted script
into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).

@item o
@kindex o
@findex sieve-edit-script-other-window
Create a new buffer in another window containing the currently
highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).

@item q
@kindex q
@findex sieve-bury-buffer
Bury the Manage Sieve buffer without closing the connection.

@item ?
@item h
@kindex ?
@kindex h
@findex sieve-help
Displays help in the minibuffer. 

@end table

@node Examples
@chapter Examples

If you are not familiar with Sieve, this chapter contains a few simple
code snippets that you can cut'n'paste and modify at will, until you
feel more comfortable with the Sieve language to write the rules from
scratch.

The following complete Sieve script places all messages with a matching
@samp{Sender:} header into the given mailbox.  Many mailing lists uses
this format.  The first line makes sure your Sieve server understands
the @code{fileinto} command.

@example
require "fileinto";

if address "sender" "owner-w3-beta@@xemacs.org" @{
        fileinto "INBOX.w3-beta";
@}
@end example

A few mailing lists do not use the @samp{Sender:} header, but does
contain some unique identifier in some other header.  The following is
not a complete script, it assumes that @code{fileinto} has already been
required.

@example
if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
        fileinto "INBOX.auc-tex";
@}
@end example

At last, we have the hopeless mailing lists that does not have any
unique identifier and you are forced to match on the @samp{To:} and
@samp{Cc} headers.  As before, this snippet assumes that @code{fileinto}
has been required.

@example
if address ["to", "cc"] "kerberos@@mit.edu" @{
        fileinto "INBOX.kerberos";
@}
@end example

@node Manage Sieve API
@chapter Manage Sieve API

The @file{sieve-manage.el} library contains low-level functionality
for talking to a server with the @sc{managesieve} protocol.

A number of user-visible variables exist, which all can be customized
in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):

@table @code

@item sieve-manage-default-user
@vindex sieve-manage-default-user
Sets the default username.

@item sieve-manage-default-port
@vindex sieve-manage-default-port
Sets the default port to use, the suggested port number is @code{2000}.

@item sieve-manage-log
@vindex sieve-manage-log
If non-nil, should be a string naming a buffer where a protocol trace
is dumped (for debugging purposes).

@end table

The API functions include:

@table @code

@item sieve-manage-open
@findex sieve-manage-open
Open connection to managesieve server, returning a buffer to be used
by all other API functions.

@item sieve-manage-opened
@findex sieve-manage-opened
Check if a server is open or not.

@item sieve-manage-close
@findex sieve-manage-close
Close a server connection.

@item sieve-manage-authenticate
@findex sieve-manage-authenticate
Authenticate to the server.

@item sieve-manage-capability
@findex sieve-manage-capability
Return a list of capabilities the server support.

@item sieve-manage-listscripts
@findex sieve-manage-listscripts
List scripts on the server.

@item sieve-manage-havespace
@findex sieve-manage-havespace
Returns non-nil iff server have roam for a script of given size.

@item sieve-manage-getscript
@findex sieve-manage-getscript
Download script from server.

@item sieve-manage-putscript
@findex sieve-manage-putscript
Upload script to server.

@item sieve-manage-setactive
@findex sieve-manage-setactive
Indicate which script on the server should be active.

@end table

@node Standards
@chapter Standards

The Emacs Sieve package implements all or parts of a small but
hopefully growing number of RFCs and drafts documents.  This chapter
lists the relevant ones.  They can all be fetched from
@samp{http://quimby.gnus.org/notes/}.

@table @dfn

@item RFC3028
Sieve: A Mail Filtering Language.

@item draft-martin-managesieve-03
A Protocol for Remotely Managing Sieve Scripts

@end table


@node Index
@chapter Index
@printindex cp

@summarycontents
@contents
@bye

@c End: