# HG changeset patch # User Glenn Morris # Date 1189053630 0 # Node ID 0941d6bec17e5656745c785b597bb79380ed62ce # Parent 0c15c259faf58d070ee807e0ebf7859637f71753 Move to ../doc/emacs/, misc/ diff -r 0c15c259faf5 -r 0941d6bec17e man/sieve.texi --- a/man/sieve.texi Thu Sep 06 04:40:24 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,369 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@setfilename ../info/sieve -@settitle Emacs Sieve Manual -@synindex fn cp -@synindex vr cp -@synindex pg cp - -@copying -This file documents the Emacs Sieve package, for server-side mail filtering. - -Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 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 quotation -@end copying - -@dircategory Emacs -@direntry -* Sieve: (sieve). Managing Sieve scripts in Emacs. -@end direntry -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@titlepage -@title Emacs Sieve Manual - -@author by Simon Josefsson -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@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. - -A good online Sieve resources is @uref{http://www.cyrusoft.com/sieve/}. - -@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. -* GNU Free Documentation License:: The license for this documentation. -* 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 '("\\.s\\(v\\|iv\\|ieve\\)\\'" . 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 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. @xref{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 successfully 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 to create a new script. - - ACTIVE .sieve - template.siv -@end example - -One of the scripts are highlighted, and standard point navigation -commands (@kbd{}, @kbd{} 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-@code{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 supports. - -@item sieve-manage-listscripts -@findex sieve-manage-listscripts -List scripts on the server. - -@item sieve-manage-havespace -@findex sieve-manage-havespace -Return non-@code{nil} if the server has room 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 -@uref{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 GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@summarycontents -@contents -@bye - -@c End: - -@ignore - arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3 -@end ignore