From: Lars Magne Ingebrigtsen Date: Sat, 25 Sep 2010 21:24:11 +0000 (+0200) Subject: Document the new nnimap. X-Git-Url: https://cgit.sxemacs.org/?p=gnus;a=commitdiff_plain;h=bf264969f34075c75d182e5785358c7346dfd032 Document the new nnimap. --- diff --git a/lisp/nnimap.el b/lisp/nnimap.el index 44d9bab55..b55aacaef 100644 --- a/lisp/nnimap.el +++ b/lisp/nnimap.el @@ -62,6 +62,10 @@ Values are `ssl', `network', `starttls' or `shell'.") (defvoo nnimap-inbox nil "The mail box where incoming mail arrives and should be split out of.") +(defvoo nnimap-split-methods nil + "How mail is split. +Uses the same syntax as nnmail-split-methods") + (defvoo nnimap-authenticator nil "How nnimap authenticate itself to the server. Possible choices are nil (use default methods) or `anonymous'.") @@ -107,8 +111,6 @@ some servers.") (download "gnus-download") (forward "gnus-forward"))) -(defvar nnimap-split-methods nil) - (defun nnimap-buffer () (nnimap-find-process-buffer nntp-server-buffer)) diff --git a/texi/ChangeLog b/texi/ChangeLog index 92e9dca3d..33d715a6f 100644 --- a/texi/ChangeLog +++ b/texi/ChangeLog @@ -2,6 +2,7 @@ * gnus.texi (Article Commands): Document gnus-fetch-partial-articles. (Unavailable Servers): Document gnus-server-copy-server. + (Using IMAP): Document the new nnimap. 2010-09-25 Julien Danjou diff --git a/texi/gnus.texi b/texi/gnus.texi index d8204afbb..718720655 100644 --- a/texi/gnus.texi +++ b/texi/gnus.texi @@ -629,9 +629,9 @@ Select Methods * Server Buffer:: Making and editing virtual servers. * Getting News:: Reading USENET news with Gnus. +* Using @acronym{IMAP}:: Reading mail from @acronym{IMAP}. * Getting Mail:: Reading your personal mail with Gnus. * Browsing the Web:: Getting messages from a plethora of Web sources. -* IMAP:: Using Gnus as a @acronym{IMAP} client. * Other Sources:: Reading directories, files. * Combined Groups:: Combining groups into one group. * Email Based Diary:: Using mails to manage diary events in Gnus. @@ -698,15 +698,6 @@ Browsing the Web * RSS:: Reading RDF site summary. * Customizing W3:: Doing stuff to Emacs/W3 from Gnus. -@acronym{IMAP} - -* Splitting in IMAP:: Splitting mail with nnimap. -* Expiring in IMAP:: Expiring mail with nnimap. -* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. -* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. -* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus. -* Debugging IMAP:: What to do when things don't work. - Other Sources * Directory Groups:: You can read a directory as if it was a newsgroup. @@ -13736,9 +13727,9 @@ The different methods all have their peculiarities, of course. @menu * Server Buffer:: Making and editing virtual servers. * Getting News:: Reading USENET news with Gnus. +* Using @acronym{IMAP}:: Reading mail from @acronym{IMAP}. * Getting Mail:: Reading your personal mail with Gnus. * Browsing the Web:: Getting messages from a plethora of Web sources. -* IMAP:: Using Gnus as a @acronym{IMAP} client. * Other Sources:: Reading directories, files. * Combined Groups:: Combining groups into one group. * Email Based Diary:: Using mails to manage diary events in Gnus. @@ -14823,6 +14814,121 @@ there. @end table +@node Using @acronym{IMAP} +@section Using @acronym{IMAP} +@cindex imap + +The most popular mail backend is probably @code{nnimap}, which +provides access to @acronym{IMAP} servers. @acronym{IMAP} servers +store mail remotely, so the client doesn't store anything locally. +This means that it's a convenient choice when you're reading your mail +from different locations, or with different user agents. + +@menu +* Connecting to an @acronym{IMAP} Server:: Getting started with @acronym{IMAP}. +* Customizing the @acronym{IMAP} Connection:: Variables for @acronym{IMAP} connection. +* Client-Side @acronym{IMAP} Splitting:: Put mail in the correct mail box. +@end menu + + +@node Connecting to an @acronym{IMAP} Server +@subsection Connecting to an @acronym{IMAP} Server + +Connecting to an @acronym{IMAP} can be very easy. Type @kbd{B} in the +group buffer, or add something like the following to your secondary +select methods: + +@example +(setq gnus-secondary-select-methods + '((nnimap "imap.gmail.com"))) +@end example + +You'll be prompted for a user name and password. If you grow tired of +that, then add the following to your @file{~/.authinfo} file: + +@example +machine imap.gmail.com login password port imap +@end example + +That should basically be it for most users. + + +@node Customizing the @acronym{IMAP} Connection +@subsection Customizing the @acronym{IMAP} Connection + +Here's an example method that's more complex: + +@example +(nnimap "imap.gmail.com" + (nnimap-inbox "INBOX") + (nnimap-split-methods ,nnmail-split-methods) + (nnimap-expunge t) + (nnimap-stream 'ssl) + (nnir-search-engine imap) + (nnimap-expunge-inbox t)) +@end example + +@table @code +@item nnimap-address +The address of the server, like @samp{imap.gmail.com}. + +@item nnimap-server-port +If the server uses a non-standard port, that can be specified here. A +typical port would be @samp{imap} or @samp{imaps}. + +@item nnimap-stream +How @code{nnimap} should connect to the server. Possible values are: + +@table @code +@item ssl +This is the default, and this uses standard +@acronym{TLS}/@acronym{SSL} connection. + +@item network +Non-encrypted and unsafe straight socket connection. + +@item starttls +Encrypted @acronym{STARTTLS} over the normal @acronym{IMAP} port. + +@item shell +If you need to tunnel via other systems to connect to the server, you +can use this option, and customize @code{nnimap-shell-program} to be +what you need. + +@end table + +@item nnimap-authenticator +Some @acronym{IMAP} servers allow anonymous logins. In that case, +this should be set to @code{anonymous}. + +@item nnimap-streaming +Virtually all @code{IMAP} server support fast streaming of data. If +you have problems connecting to the server, try setting this to @code{nil}. + +@end table + + +@node Client-Side @acronym{IMAP} Splitting +@subsection Client-Side @acronym{IMAP} Splitting + +Many people prefer to do the sorting/splitting of mail into their mail +boxes on the @acronym{IMAP} server. That way they don't have to +download the mail they're not all that interested in. + +If you do want to do client-side mail splitting, then the following +variables are relevant: + +@table @code +@item nnimap-inbox +This is the @acronym{IMAP} mail box that will be scanned for new mail. + +@item nnimap-split-methods +Uses the same syntax as @code{nnmail-split-methods} (@pxref{Splitting +Mail}). + +@end table + + @node Getting Mail @section Getting Mail @cindex reading mail @@ -15381,10 +15487,7 @@ Get mail from a @acronym{IMAP} server. If you don't want to use @acronym{IMAP} as intended, as a network mail reading protocol (ie with nnimap), for some reason or other, Gnus let you treat it similar to a @acronym{POP} server and fetches articles from a given -@acronym{IMAP} mailbox. @xref{IMAP}, for more information. - -Note that for the Kerberos, GSSAPI, @acronym{TLS}/@acronym{SSL} and STARTTLS support you -may need external programs and libraries, @xref{IMAP}. +@acronym{IMAP} mailbox. @xref{Using @acronym{IMAP}}, for more information. Keywords: @@ -15853,7 +15956,7 @@ after @code{save-excursion} and @code{save-restriction} in the example above. Also note that with the nnimap backend, message bodies will not be downloaded by default. You need to set @code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Splitting in IMAP}). +(@pxref{Client-Side @acronym{IMAP} Splitting}). @item (! @var{func} @var{split}) If the split is a list, and the first element is @code{!}, then @@ -16617,6 +16720,7 @@ Spool}). @end menu + @node Unix Mail Box @subsubsection Unix Mail Box @cindex nnmbox @@ -17742,739 +17846,6 @@ Put that in your @file{.emacs} file, and hitting links in W3-rendered follow the link. -@node IMAP -@section IMAP -@cindex nnimap -@cindex @acronym{IMAP} - -@acronym{IMAP} is a network protocol for reading mail (or news, or @dots{}), -think of it as a modernized @acronym{NNTP}. Connecting to a @acronym{IMAP} -server is much similar to connecting to a news server, you just -specify the network address of the server. - -@acronym{IMAP} has two properties. First, @acronym{IMAP} can do -everything that @acronym{POP} can, it can hence be viewed as a -@acronym{POP++}. Secondly, @acronym{IMAP} is a mail storage protocol, -similar to @acronym{NNTP} being a news storage protocol---however, -@acronym{IMAP} offers more features than @acronym{NNTP} because news -is more or less read-only whereas mail is read-write. - -If you want to use @acronym{IMAP} as a @acronym{POP++}, use an imap -entry in @code{mail-sources}. With this, Gnus will fetch mails from -the @acronym{IMAP} server and store them on the local disk. This is -not the usage described in this section---@xref{Mail Sources}. - -If you want to use @acronym{IMAP} as a mail storage protocol, use an nnimap -entry in @code{gnus-secondary-select-methods}. With this, Gnus will -manipulate mails stored on the @acronym{IMAP} server. This is the kind of -usage explained in this section. - -A server configuration in @file{~/.gnus.el} with a few @acronym{IMAP} -servers might look something like the following. (Note that for -@acronym{TLS}/@acronym{SSL}, you need external programs and libraries, -see below.) - -@lisp -(setq gnus-secondary-select-methods - '((nnimap "simpleserver") ; @r{no special configuration} - ; @r{perhaps a ssh port forwarded server:} - (nnimap "dolk" - (nnimap-address "localhost") - (nnimap-server-port 1430)) - ; @r{a UW server running on localhost} - (nnimap "barbar" - (nnimap-server-port 143) - (nnimap-address "localhost") - (nnimap-list-pattern ("INBOX" "mail/*"))) - ; @r{anonymous public cyrus server:} - (nnimap "cyrus.andrew.cmu.edu" - (nnimap-authenticator anonymous) - (nnimap-list-pattern "archive.*") - (nnimap-stream network)) - ; @r{a ssl server on a non-standard port:} - (nnimap "vic20" - (nnimap-address "vic20.somewhere.com") - (nnimap-server-port 9930) - (nnimap-stream ssl)))) -@end lisp - -After defining the new server, you can subscribe to groups on the -server using normal Gnus commands such as @kbd{U} in the Group Buffer -(@pxref{Subscription Commands}) or via the Server Buffer -(@pxref{Server Buffer}). - -The following variables can be used to create a virtual @code{nnimap} -server: - -@table @code - -@item nnimap-address -@vindex nnimap-address - -The address of the remote @acronym{IMAP} server. Defaults to the virtual -server name if not specified. - -@item nnimap-server-port -@vindex nnimap-server-port -Port on server to contact. Defaults to port 143, or 993 for @acronym{TLS}/@acronym{SSL}. - -Note that this should be an integer, example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-server-port 4711)) -@end lisp - -@item nnimap-list-pattern -@vindex nnimap-list-pattern -String or list of strings of mailboxes to limit available groups to. -This is used when the server has very many mailboxes and you're only -interested in a few---some servers export your home directory via -@acronym{IMAP}, you'll probably want to limit the mailboxes to those in -@file{~/Mail/*} then. - -The string can also be a cons of REFERENCE and the string as above, what -REFERENCE is used for is server specific, but on the University of -Washington server it's a directory that will be concatenated with the -mailbox. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" - ("~friend/Mail/" . "list/*")))) -@end lisp - -@item nnimap-stream -@vindex nnimap-stream -The type of stream used to connect to your server. By default, nnimap -will detect and automatically use all of the below, with the exception -of @acronym{TLS}/@acronym{SSL}. (@acronym{IMAP} over -@acronym{TLS}/@acronym{SSL} is being replaced by STARTTLS, which can -be automatically detected, but it's not widely deployed yet.) - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-stream ssl)) -@end lisp - -Please note that the value of @code{nnimap-stream} is a symbol! - -@itemize @bullet -@item -@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the -@samp{gsasl} or @samp{imtest} program. -@item -@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program. -@item -@dfn{starttls:} Connect via the STARTTLS extension (similar to -@acronym{TLS}/@acronym{SSL}). Requires the external library @samp{starttls.el} and program -@samp{starttls}. -@item -@dfn{tls:} Connect through @acronym{TLS}. Requires GNUTLS (the program -@samp{gnutls-cli}). -@item -@dfn{ssl:} Connect through @acronym{SSL}. Requires OpenSSL (the program -@samp{openssl}) or SSLeay (@samp{s_client}). -@item -@dfn{shell:} Use a shell command to start @acronym{IMAP} connection. -@item -@dfn{network:} Plain, TCP/IP network connection. -@end itemize - -@vindex imap-kerberos4-program -The @samp{imtest} program is shipped with Cyrus IMAPD. If you're -using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version -1.5.x and 1.6.x) you need to frob @code{imap-process-connection-type} -to make @code{imap.el} use a pty instead of a pipe when communicating -with @samp{imtest}. You will then suffer from a line length -restrictions on @acronym{IMAP} commands, which might make Gnus seem to hang -indefinitely if you have many articles in a mailbox. The variable -@code{imap-kerberos4-program} contain parameters to pass to the imtest -program. - -For @acronym{TLS} connection, the @code{gnutls-cli} program from GNUTLS is -needed. It is available from -@uref{http://www.gnu.org/software/gnutls/}. - -@vindex imap-gssapi-program -This parameter specifies a list of command lines that invoke a GSSAPI -authenticated @acronym{IMAP} stream in a subshell. They are tried -sequentially until a connection is made, or the list has been -exhausted. By default, @samp{gsasl} from GNU SASL, available from -@uref{http://www.gnu.org/software/gsasl/}, and the @samp{imtest} -program from Cyrus IMAPD (see @code{imap-kerberos4-program}), are -tried. - -@vindex imap-ssl-program -For @acronym{SSL} connections, the OpenSSL program is available from -@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay, -and nnimap support it too---although the most recent versions of -SSLeay, 0.9.x, are known to have serious bugs making it -useless. Earlier versions, especially 0.8.x, of SSLeay are known to -work. The variable @code{imap-ssl-program} contain parameters to pass -to OpenSSL/SSLeay. - -@vindex imap-shell-program -@vindex imap-shell-host -For @acronym{IMAP} connections using the @code{shell} stream, the -variable @code{imap-shell-program} specify what program to call. Make -sure nothing is interfering with the output of the program, e.g., don't -forget to redirect the error output to the void. - -@item nnimap-authenticator -@vindex nnimap-authenticator - -The authenticator used to connect to the server. By default, nnimap -will use the most secure authenticator your server is capable of. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-authenticator anonymous)) -@end lisp - -Please note that the value of @code{nnimap-authenticator} is a symbol! - -@itemize @bullet -@item -@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires -external program @code{gsasl} or @code{imtest}. -@item -@dfn{kerberos4:} Kerberos 4 authentication. Requires external program -@code{imtest}. -@item -@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Requires -external library @code{digest-md5.el}. -@item -@dfn{cram-md5:} Encrypted username/password via CRAM-MD5. -@item -@dfn{login:} Plain-text username/password via LOGIN. -@item -@dfn{anonymous:} Login as ``anonymous'', supplying your email address as password. -@end itemize - -@item nnimap-expunge-on-close -@cindex expunging -@vindex nnimap-expunge-on-close -Unlike Parmenides the @acronym{IMAP} designers have decided things that -don't exist actually do exist. More specifically, @acronym{IMAP} has -this concept of marking articles @code{Deleted} which doesn't actually -delete them, and this (marking them @code{Deleted}, that is) is what -nnimap does when you delete an article in Gnus (with @kbd{B DEL} or -similar). - -Since the articles aren't really removed when we mark them with the -@code{Deleted} flag we'll need a way to actually delete them. Feel like -running in circles yet? - -Traditionally, nnimap has removed all articles marked as @code{Deleted} -when closing a mailbox but this is now configurable by this server -variable. - -The possible options are: - -@table @code - -@item always -The default behavior, delete all articles marked as ``Deleted'' when -closing a mailbox. -@item never -Never actually delete articles. Currently there is no way of showing -the articles marked for deletion in nnimap, but other @acronym{IMAP} clients -may allow you to do this. If you ever want to run the EXPUNGE command -manually, @xref{Expunging mailboxes}. -@item ask -When closing mailboxes, nnimap will ask if you wish to expunge deleted -articles or not. - -@end table - -@item nnimap-importantize-dormant -@vindex nnimap-importantize-dormant - -If non-@code{nil} (the default), marks dormant articles as ticked (as -well), for other @acronym{IMAP} clients. Within Gnus, dormant articles will -naturally still (only) be marked as dormant. This is to make dormant -articles stand out, just like ticked articles, in other @acronym{IMAP} -clients. (In other words, Gnus has two ``Tick'' marks and @acronym{IMAP} -has only one.) - -Probably the only reason for frobbing this would be if you're trying -enable per-user persistent dormant flags, using something like: - -@lisp -(setcdr (assq 'dormant nnimap-mark-to-flag-alist) - (format "gnus-dormant-%s" (user-login-name))) -(setcdr (assq 'dormant nnimap-mark-to-predicate-alist) - (format "KEYWORD gnus-dormant-%s" (user-login-name))) -@end lisp - -In this case, you would not want the per-user dormant flag showing up -as ticked for other users. - -@item nnimap-expunge-search-string -@cindex expunging -@vindex nnimap-expunge-search-string -@cindex expiring @acronym{IMAP} mail - -This variable contain the @acronym{IMAP} search command sent to server when -searching for articles eligible for expiring. The default is -@code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by -UID set and the second @code{%s} is replaced by a date. - -Probably the only useful value to change this to is -@code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in -messages instead of the internal article date. See section 6.4.4 of -RFC 2060 for more information on valid strings. - -However, if @code{nnimap-search-uids-not-since-is-evil} -is true, this variable has no effect since the search logic -is reversed, as described below. - -@item nnimap-authinfo-file -@vindex nnimap-authinfo-file - -A file containing credentials used to log in on servers. The format is -(almost) the same as the @code{ftp} @file{~/.netrc} file. See the -variable @code{nntp-authinfo-file} for exact syntax; also see -@ref{NNTP}. An example of an .authinfo line for an IMAP server, is: - -@example -machine students.uio.no login larsi password geheimnis port imap -@end example - -Note that it should be @code{port imap}, or @code{port 143}, if you -use a @code{nnimap-stream} of @code{tls} or @code{ssl}, even if the -actual port number used is port 993 for secured IMAP. For -convenience, Gnus will accept @code{port imaps} as a synonym of -@code{port imap}. - -@item nnimap-need-unselect-to-notice-new-mail -@vindex nnimap-need-unselect-to-notice-new-mail - -Unselect mailboxes before looking for new mail in them. Some servers -seem to need this under some circumstances; it was reported that -Courier 1.7.1 did. - -@item nnimap-nov-is-evil -@vindex nnimap-nov-is-evil -@cindex Courier @acronym{IMAP} server -@cindex @acronym{NOV} - -Never generate or use a local @acronym{NOV} database. Defaults to the -value of @code{gnus-agent}. - -Using a @acronym{NOV} database usually makes header fetching much -faster, but it uses the @code{UID SEARCH UID} command, which is very -slow on some servers (notably some versions of Courier). Since the Gnus -Agent caches the information in the @acronym{NOV} database without using -the slow command, this variable defaults to true if the Agent is in use, -and false otherwise. - -@item nnimap-search-uids-not-since-is-evil -@vindex nnimap-search-uids-not-since-is-evil -@cindex Courier @acronym{IMAP} server -@cindex expiring @acronym{IMAP} mail - -Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE -@var{date}} command, which is slow on some @acronym{IMAP} servers -(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE -@var{date}} and prune the list of expirable articles within Gnus. - -When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a -list of expirable articles and asks the IMAP server questions like ``Of -these articles, which ones are older than a week?'' While this seems -like a perfectly reasonable question, some IMAP servers take a long time -to answer it, since they seemingly go looking into every old article to -see if it is one of the expirable ones. Curiously, the question ``Of -@emph{all} articles, which ones are newer than a week?'' seems to be -much faster to answer, so setting this variable causes Gnus to ask this -question and figure out the answer to the real question itself. - -This problem can really sneak up on you: when you first configure Gnus, -everything works fine, but once you accumulate a couple thousand -messages, you start cursing Gnus for being so slow. On the other hand, -if you get a lot of email within a week, setting this variable will -cause a lot of network traffic between Gnus and the IMAP server. - -@item nnimap-logout-timeout -@vindex nnimap-logout-timeout - -There is a case where a connection to a @acronym{IMAP} server is unable -to close, when connecting to the server via a certain kind of network, -e.g. @acronym{VPN}. In that case, it will be observed that a connection -between Emacs and the local network looks alive even if the server has -closed a connection for some reason (typically, a timeout). -Consequently, Emacs continues waiting for a response from the server for -the @code{LOGOUT} command that Emacs sent, or hangs in other words. If -you are in such a network, setting this variable to a number of seconds -will be helpful. If it is set, a hung connection will be closed -forcibly, after this number of seconds from the time Emacs sends the -@code{LOGOUT} command. It should not be too small value but too large -value will be inconvenient too. Perhaps the value 1.0 will be a good -candidate but it might be worth trying some other values. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-logout-timeout 1.0)) -@end lisp - -@end table - -@menu -* Splitting in IMAP:: Splitting mail with nnimap. -* Expiring in IMAP:: Expiring mail with nnimap. -* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. -* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. -* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus. -* Debugging IMAP:: What to do when things don't work. -@end menu - - - -@node Splitting in IMAP -@subsection Splitting in IMAP -@cindex splitting imap mail - -Splitting is something Gnus users have loved and used for years, and now -the rest of the world is catching up. Yeah, dream on, not many -@acronym{IMAP} servers have server side splitting and those that have -splitting seem to use some non-standard protocol. This means that -@acronym{IMAP} support for Gnus has to do its own splitting. - -And it does. - -(Incidentally, people seem to have been dreaming on, and Sieve has -gaining a market share and is supported by several IMAP servers. -Fortunately, Gnus support it too, @xref{Sieve Commands}.) - -Here are the variables of interest: - -@table @code - -@item nnimap-split-crosspost -@cindex splitting, crosspost -@cindex crosspost -@vindex nnimap-split-crosspost - -If non-@code{nil}, do crossposting if several split methods match the -mail. If @code{nil}, the first match in @code{nnimap-split-rule} -found will be used. - -Nnmail equivalent: @code{nnmail-crosspost}. - -@item nnimap-split-inbox -@cindex splitting, inbox -@cindex inbox -@vindex nnimap-split-inbox - -A string or a list of strings that gives the name(s) of @acronym{IMAP} -mailboxes to split from. Defaults to @code{nil}, which means that -splitting is disabled! - -@lisp -(setq nnimap-split-inbox - '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap")) -@end lisp - -No nnmail equivalent. - -@item nnimap-split-rule -@cindex splitting, rules -@vindex nnimap-split-rule - -New mail found in @code{nnimap-split-inbox} will be split according to -this variable. - -This variable contains a list of lists, where the first element in the -sublist gives the name of the @acronym{IMAP} mailbox to move articles -matching the regexp in the second element in the sublist. Got that? -Neither did I, we need examples. - -@lisp -(setq nnimap-split-rule - '(("INBOX.nnimap" - "^Sender: owner-nnimap@@vic20.globalcom.se") - ("INBOX.junk" "^Subject:.*MAKE MONEY") - ("INBOX.private" ""))) -@end lisp - -This will put all articles from the nnimap mailing list into mailbox -INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line -into INBOX.junk and everything else in INBOX.private. - -The first string may contain @samp{\\1} forms, like the ones used by -replace-match to insert sub-expressions from the matched text. For -instance: - -@lisp -("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@") -@end lisp - -The first element can also be the symbol @code{junk} to indicate that -matching messages should simply be deleted. Use with care. - -The second element can also be a function. In that case, it will be -called with the first element of the rule as the argument, in a buffer -containing the headers of the article. It should return a -non-@code{nil} value if it thinks that the mail belongs in that group. - -Nnmail users might recollect that the last regexp had to be empty to -match all articles (like in the example above). This is not required in -nnimap. Articles not matching any of the regexps will not be moved out -of your inbox. (This might affect performance if you keep lots of -unread articles in your inbox, since the splitting code would go over -them every time you fetch new mail.) - -These rules are processed from the beginning of the alist toward the -end. The first rule to make a match will ``win'', unless you have -crossposting enabled. In that case, all matching rules will ``win''. - -This variable can also have a function as its value, the function will -be called with the headers narrowed and should return a group where it -thinks the article should be split to. See @code{nnimap-split-fancy}. - -The splitting code tries to create mailboxes if it needs to. - -To allow for different split rules on different virtual servers, and -even different split rules in different inboxes on the same server, -the syntax of this variable have been extended along the lines of: - -@lisp -(setq nnimap-split-rule - '(("my1server" (".*" (("ding" "ding@@gnus.org") - ("junk" "From:.*Simon")))) - ("my2server" ("INBOX" nnimap-split-fancy)) - ("my[34]server" (".*" (("private" "To:.*Simon") - ("junk" my-junk-func)))))) -@end lisp - -The virtual server name is in fact a regexp, so that the same rules -may apply to several servers. In the example, the servers -@code{my3server} and @code{my4server} both use the same rules. -Similarly, the inbox string is also a regexp. The actual splitting -rules are as before, either a function, or a list with group/regexp or -group/function elements. - -Nnmail equivalent: @code{nnmail-split-methods}. - -@item nnimap-split-predicate -@cindex splitting -@vindex nnimap-split-predicate - -Mail matching this predicate in @code{nnimap-split-inbox} will be -split, it is a string and the default is @samp{UNSEEN UNDELETED}. - -This might be useful if you use another @acronym{IMAP} client to read mail in -your inbox but would like Gnus to split all articles in the inbox -regardless of readedness. Then you might change this to -@samp{UNDELETED}. - -@item nnimap-split-fancy -@cindex splitting, fancy -@findex nnimap-split-fancy -@vindex nnimap-split-fancy - -It's possible to set @code{nnimap-split-rule} to -@code{nnmail-split-fancy} if you want to use fancy -splitting. @xref{Fancy Mail Splitting}. - -However, to be able to have different fancy split rules for nnmail and -nnimap back ends you can set @code{nnimap-split-rule} to -@code{nnimap-split-fancy} and define the nnimap specific fancy split -rule in @code{nnimap-split-fancy}. - -Example: - -@lisp -(setq nnimap-split-rule 'nnimap-split-fancy - nnimap-split-fancy ...) -@end lisp - -Nnmail equivalent: @code{nnmail-split-fancy}. - -@item nnimap-split-download-body -@findex nnimap-split-download-body -@vindex nnimap-split-download-body - -Set to non-@code{nil} to download entire articles during splitting. -This is generally not required, and will slow things down -considerably. You may need it if you want to use an advanced -splitting function that analyzes the body to split the article. - -@end table - -@node Expiring in IMAP -@subsection Expiring in IMAP -@cindex expiring @acronym{IMAP} mail - -Even though @code{nnimap} is not a proper @code{nnmail} derived back -end, it supports most features in regular expiring (@pxref{Expiring -Mail}). Unlike splitting in @acronym{IMAP} (@pxref{Splitting in -IMAP}) it does not clone the @code{nnmail} variables (i.e., creating -@var{nnimap-expiry-wait}) but reuse the @code{nnmail} variables. What -follows below are the variables used by the @code{nnimap} expiry -process. - -A note on how the expire mark is stored on the @acronym{IMAP} server is -appropriate here as well. The expire mark is translated into a -@code{imap} client specific mark, @code{gnus-expire}, and stored on the -message. This means that likely only Gnus will understand and treat -the @code{gnus-expire} mark properly, although other clients may allow -you to view client specific flags on the message. It also means that -your server must support permanent storage of client specific flags on -messages. Most do, fortunately. - -If expiring @acronym{IMAP} mail seems very slow, try setting the server -variable @code{nnimap-search-uids-not-since-is-evil}. - -@table @code - -@item nnmail-expiry-wait -@item nnmail-expiry-wait-function - -These variables are fully supported. The expire value can be a -number, the symbol @code{immediate} or @code{never}. - -@item nnmail-expiry-target - -This variable is supported, and internally implemented by calling the -@code{nnmail} functions that handle this. It contains an optimization -that if the destination is a @acronym{IMAP} group on the same server, the -article is copied instead of appended (that is, uploaded again). - -@end table - -@node Editing IMAP ACLs -@subsection Editing IMAP ACLs -@cindex editing imap acls -@cindex Access Control Lists -@cindex Editing @acronym{IMAP} ACLs -@kindex G l (Group) -@findex gnus-group-nnimap-edit-acl - -ACL stands for Access Control List. ACLs are used in @acronym{IMAP} for -limiting (or enabling) other users access to your mail boxes. Not all -@acronym{IMAP} servers support this, this function will give an error if it -doesn't. - -To edit an ACL for a mailbox, type @kbd{G l} -(@code{gnus-group-edit-nnimap-acl}) and you'll be presented with an ACL -editing window with detailed instructions. - -Some possible uses: - -@itemize @bullet -@item -Giving ``anyone'' the ``lrs'' rights (lookup, read, keep seen/unseen flags) -on your mailing list mailboxes enables other users on the same server to -follow the list without subscribing to it. -@item -At least with the Cyrus server, you are required to give the user -``anyone'' posting ("p") capabilities to have ``plussing'' work (that is, -mail sent to user+mailbox@@domain ending up in the @acronym{IMAP} mailbox -INBOX.mailbox). -@end itemize - -@node Expunging mailboxes -@subsection Expunging mailboxes -@cindex expunging - -@cindex expunge -@cindex manual expunging -@kindex G x (Group) -@findex gnus-group-expunge-group - -If you're using the @code{never} setting of @code{nnimap-expunge-on-close}, -you may want the option of expunging all deleted articles in a mailbox -manually. This is exactly what @kbd{G x} does. - -Currently there is no way of showing deleted articles, you can just -delete them. - -@node A note on namespaces -@subsection A note on namespaces -@cindex IMAP namespace -@cindex namespaces - -The @acronym{IMAP} protocol has a concept called namespaces, described -by the following text in the RFC2060: - -@display -5.1.2. Mailbox Namespace Naming Convention - - By convention, the first hierarchical element of any mailbox name - which begins with "#" identifies the "namespace" of the remainder of - the name. This makes it possible to disambiguate between different - types of mailbox stores, each of which have their own namespaces. - - For example, implementations which offer access to USENET - newsgroups MAY use the "#news" namespace to partition the USENET - newsgroup namespace from that of other mailboxes. Thus, the - comp.mail.misc newsgroup would have an mailbox name of - "#news.comp.mail.misc", and the name "comp.mail.misc" could refer - to a different object (e.g. a user's private mailbox). -@end display - -While there is nothing in this text that warrants concern for the -@acronym{IMAP} implementation in Gnus, some servers use namespace -prefixes in a way that does not work with how Gnus uses mailbox names. - -Specifically, University of Washington's @acronym{IMAP} server uses -mailbox names like @code{#driver.mbx/read-mail} which are valid only -in the @sc{create} and @sc{append} commands. After the mailbox is -created (or a messages is appended to a mailbox), it must be accessed -without the namespace prefix, i.e. @code{read-mail}. Since Gnus do -not make it possible for the user to guarantee that user entered -mailbox names will only be used with the CREATE and APPEND commands, -you should simply not use the namespace prefixed mailbox names in -Gnus. - -See the UoW IMAPD documentation for the @code{#driver.*/} prefix -for more information on how to use the prefixes. They are a power -tool and should be used only if you are sure what the effects are. - -@node Debugging IMAP -@subsection Debugging IMAP -@cindex IMAP debugging -@cindex protocol dump (IMAP) - -@acronym{IMAP} is a complex protocol, more so than @acronym{NNTP} or -@acronym{POP3}. Implementation bugs are not unlikely, and we do our -best to fix them right away. If you encounter odd behavior, chances -are that either the server or Gnus is buggy. - -If you are familiar with network protocols in general, you will -probably be able to extract some clues from the protocol dump of the -exchanges between Gnus and the server. Even if you are not familiar -with network protocols, when you include the protocol dump in -@acronym{IMAP}-related bug reports you are helping us with data -critical to solving the problem. Therefore, we strongly encourage you -to include the protocol dump when reporting IMAP bugs in Gnus. - - -@vindex imap-log -Because the protocol dump, when enabled, generates lots of data, it is -disabled by default. You can enable it by setting @code{imap-log} as -follows: - -@lisp -(setq imap-log t) -@end lisp - -This instructs the @code{imap.el} package to log any exchanges with -the server. The log is stored in the buffer @samp{*imap-log*}. Look -for error messages, which sometimes are tagged with the keyword -@code{BAD}---but when submitting a bug, make sure to include all the -data. - @node Other Sources @section Other Sources @@ -24416,7 +23787,7 @@ call the external tools during splitting. Example fancy split method: Note that with the nnimap back end, message bodies will not be downloaded by default. You need to set @code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Splitting in IMAP}). +(@pxref{Client-Side @acronym{IMAP} Splitting}). That is about it. As some spam is likely to get through anyway, you might want to have a nifty function to call when you happen to read @@ -24698,14 +24069,14 @@ the value @samp{spam} means @samp{nnimap+your-server:spam}. The value @vindex nnimap-split-download-body Note for IMAP users: if you use the @code{spam-check-bogofilter}, @code{spam-check-ifile}, and @code{spam-check-stat} spam back ends, -you should also set the variable @code{nnimap-split-download-body} -to @code{t}. These spam back ends are most useful when they can -``scan'' the full message body. By default, the nnimap back end only -retrieves the message headers; @code{nnimap-split-download-body} tells -it to retrieve the message bodies as well. We don't set this by -default because it will slow @acronym{IMAP} down, and that is not an -appropriate decision to make on behalf of the user. @xref{Splitting -in IMAP}. +you should also set the variable @code{nnimap-split-download-body} to +@code{t}. These spam back ends are most useful when they can ``scan'' +the full message body. By default, the nnimap back end only retrieves +the message headers; @code{nnimap-split-download-body} tells it to +retrieve the message bodies as well. We don't set this by default +because it will slow @acronym{IMAP} down, and that is not an +appropriate decision to make on behalf of the user. @xref{Client-Side +@acronym{IMAP} Splitting}. You have to specify one or more spam back ends for @code{spam-split} to use, by setting the @code{spam-use-*} variables. @xref{Spam Back