aboutsummaryrefslogtreecommitdiffstats
path: root/doc/misc
diff options
context:
space:
mode:
authorGnus developers2010-09-26 04:03:19 +0000
committerKatsumi Yamaoka2010-09-26 04:03:19 +0000
commit8ccbef23ea624d892bada3c66ef2339ada342997 (patch)
treeb8baaa6929a0742ffd301529bcc27001dd08e031 /doc/misc
parent83e245c4906513429cb56629485deb5f04a240a3 (diff)
downloademacs-8ccbef23ea624d892bada3c66ef2339ada342997.tar.gz
emacs-8ccbef23ea624d892bada3c66ef2339ada342997.zip
Merge changes made in Gnus trunk.
nnimap.el: Implement partial IMAP article fetch. nnimap.el: Have nnimap not update the infos if it can't get info from the server. Implement functions for showing the complete articles. gnus-int.el (gnus-open-server): Don't query whether to go offline -- just do it. gnus-art.el (gnus-mime-delete-part): Fix plural for "byte" when there isn't a single byte. nndoc.el (nndoc-type-alist): Move mime-parts after mbox. Suggested by Jay Berkenbilt. mm-decode.el (mm-save-part): Allow saving to other directories the normal Emacs way. gnus-html.el (gnus-html-rescale-image): Use our defalias gnus-window-inside-pixel-edges. gnus-srvr.el (gnus-server-copy-server): Add documentation. gnus.texi (Using IMAP): Document the new nnimap. nnimap.el (nnimap-wait-for-response): Search further when we're not using streaming. gnus-int.el (gnus-check-server): Say what the error was when opening failed. nnheader.el (nnheader-get-report-string): New function. gnus-int.el (gnus-check-server): Use report-string. nnimap.el (nnimap-open-connection): Add more error reporting when nnimap fails early. gnus-start.el (gnus-get-unread-articles): Don't try to open failed servers twice. nnimap.el (nnimap-wait-for-response): Reversed logic in the nnimap-streaming test. gnus-art.el: Removed CTAN button stuff, which I don't think is very relevant any more. Remove NoCeM support, since nobody seems to use it any more. Remove earcon and gnus-audio. gnus.el (gnus): Silence gnus-load message. gnus-group.el (gnus-read-ephemeral-bug-group): Add the bug email address to the To list for easier response. gnus.texi (Connecting to an IMAP Server): Show how to use as primary method instead of secondary.
Diffstat (limited to 'doc/misc')
-rw-r--r--doc/misc/gnus-news.texi12
-rw-r--r--doc/misc/gnus.texi1107
2 files changed, 169 insertions, 950 deletions
diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi
index 8aa28dd89c8..bf7a685003f 100644
--- a/doc/misc/gnus-news.texi
+++ b/doc/misc/gnus-news.texi
@@ -246,6 +246,16 @@ of the "Whomever writes:" line. You need to set
246@code{message-insert-formatted-citation-line} as well. 246@code{message-insert-formatted-citation-line} as well.
247@end itemize 247@end itemize
248 248
249@item Changes in Browse Server mode
250
251@itemize @bullet
252@item Gnus' sophisticated subscription methods are now available in
253Browse Server buffers as well using the variable
254@code{gnus-browse-subscribe-newsgroup-method}.
255
256@end itemize
257
258
249@item Changes in back ends 259@item Changes in back ends
250 260
251@itemize @bullet 261@itemize @bullet
@@ -336,6 +346,8 @@ be unchanged except that the marks will be removed when copying or
336moving articles to a group that has not turned auto-expire on. 346moving articles to a group that has not turned auto-expire on.
337@xref{Expiring Mail}. 347@xref{Expiring Mail}.
338 348
349@item NoCeM support has been removed.
350
339@end itemize 351@end itemize
340 352
341@end itemize 353@end itemize
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index a22644f2f98..46a7d8fd7ef 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -629,9 +629,9 @@ Select Methods
629 629
630* Server Buffer:: Making and editing virtual servers. 630* Server Buffer:: Making and editing virtual servers.
631* Getting News:: Reading USENET news with Gnus. 631* Getting News:: Reading USENET news with Gnus.
632* Using @acronym{IMAP}:: Reading mail from @acronym{IMAP}.
632* Getting Mail:: Reading your personal mail with Gnus. 633* Getting Mail:: Reading your personal mail with Gnus.
633* Browsing the Web:: Getting messages from a plethora of Web sources. 634* Browsing the Web:: Getting messages from a plethora of Web sources.
634* IMAP:: Using Gnus as a @acronym{IMAP} client.
635* Other Sources:: Reading directories, files. 635* Other Sources:: Reading directories, files.
636* Combined Groups:: Combining groups into one group. 636* Combined Groups:: Combining groups into one group.
637* Email Based Diary:: Using mails to manage diary events in Gnus. 637* Email Based Diary:: Using mails to manage diary events in Gnus.
@@ -698,15 +698,6 @@ Browsing the Web
698* RSS:: Reading RDF site summary. 698* RSS:: Reading RDF site summary.
699* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. 699* Customizing W3:: Doing stuff to Emacs/W3 from Gnus.
700 700
701@acronym{IMAP}
702
703* Splitting in IMAP:: Splitting mail with nnimap.
704* Expiring in IMAP:: Expiring mail with nnimap.
705* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
706* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
707* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus.
708* Debugging IMAP:: What to do when things don't work.
709
710Other Sources 701Other Sources
711 702
712* Directory Groups:: You can read a directory as if it was a newsgroup. 703* Directory Groups:: You can read a directory as if it was a newsgroup.
@@ -808,7 +799,6 @@ Various
808* Highlighting and Menus:: Making buffers look all nice and cozy. 799* Highlighting and Menus:: Making buffers look all nice and cozy.
809* Buttons:: Get tendinitis in ten easy steps! 800* Buttons:: Get tendinitis in ten easy steps!
810* Daemons:: Gnus can do things behind your back. 801* Daemons:: Gnus can do things behind your back.
811* NoCeM:: How to avoid spam and other fatty foods.
812* Undo:: Some actions can be undone. 802* Undo:: Some actions can be undone.
813* Predicate Specifiers:: Specifying predicates. 803* Predicate Specifiers:: Specifying predicates.
814* Moderation:: What to do if you're a moderator. 804* Moderation:: What to do if you're a moderator.
@@ -1637,15 +1627,6 @@ of doing your job. Note that this variable is used before
1637@vindex gnus-no-groups-message 1627@vindex gnus-no-groups-message
1638Message displayed by Gnus when no groups are available. 1628Message displayed by Gnus when no groups are available.
1639 1629
1640@item gnus-play-startup-jingle
1641@vindex gnus-play-startup-jingle
1642If non-@code{nil}, play the Gnus jingle at startup.
1643
1644@item gnus-startup-jingle
1645@vindex gnus-startup-jingle
1646Jingle to be played if the above variable is non-@code{nil}. The
1647default is @samp{Tuxedomoon.Jingle4.au}.
1648
1649@item gnus-use-backend-marks 1630@item gnus-use-backend-marks
1650@vindex gnus-use-backend-marks 1631@vindex gnus-use-backend-marks
1651If non-@code{nil}, Gnus will store article marks both in the 1632If non-@code{nil}, Gnus will store article marks both in the
@@ -3617,8 +3598,12 @@ Enter the current group (@code{gnus-browse-select-group}).
3617@item u 3598@item u
3618@kindex u (Browse) 3599@kindex u (Browse)
3619@findex gnus-browse-unsubscribe-current-group 3600@findex gnus-browse-unsubscribe-current-group
3601@vindex gnus-browse-subscribe-newsgroup-method
3620Unsubscribe to the current group, or, as will be the case here, 3602Unsubscribe to the current group, or, as will be the case here,
3621subscribe to it (@code{gnus-browse-unsubscribe-current-group}). 3603subscribe to it (@code{gnus-browse-unsubscribe-current-group}). You
3604can affect the way the new group is entered into the Group buffer
3605using the variable @code{gnus-browse-subscribe-newsgroup-method}. See
3606@pxref{Subscription Methods} for available options.
3622 3607
3623@item l 3608@item l
3624@itemx q 3609@itemx q
@@ -10086,18 +10071,6 @@ string is invalid.
10086An alist of @code{(RATE . REGEXP)} pairs used by the function 10071An alist of @code{(RATE . REGEXP)} pairs used by the function
10087@code{gnus-button-mid-or-mail-heuristic}. 10072@code{gnus-button-mid-or-mail-heuristic}.
10088 10073
10089@c Stuff related to gnus-button-tex-level
10090
10091@item gnus-button-ctan-handler
10092@findex gnus-button-ctan-handler
10093The function to use for displaying CTAN links. It must take one
10094argument, the string naming the URL.
10095
10096@item gnus-ctan-url
10097@vindex gnus-ctan-url
10098Top directory of a CTAN (Comprehensive TeX Archive Network) archive used
10099by @code{gnus-button-ctan-handler}.
10100
10101@c Misc stuff 10074@c Misc stuff
10102 10075
10103@item gnus-article-button-face 10076@item gnus-article-button-face
@@ -10170,14 +10143,6 @@ Related variables and functions include
10170@code{gnus-button-mid-or-mail-heuristic}, and 10143@code{gnus-button-mid-or-mail-heuristic}, and
10171@code{gnus-button-mid-or-mail-heuristic-alist}. 10144@code{gnus-button-mid-or-mail-heuristic-alist}.
10172 10145
10173@item gnus-button-tex-level
10174@vindex gnus-button-tex-level
10175Controls the display of references to @TeX{} or LaTeX stuff, e.g. for CTAN
10176URLs. See the variables @code{gnus-ctan-url},
10177@code{gnus-button-ctan-handler},
10178@code{gnus-button-ctan-directory-regexp}, and
10179@code{gnus-button-handle-ctan-bogus-regexp}.
10180
10181@end table 10146@end table
10182 10147
10183 10148
@@ -10829,6 +10794,16 @@ Generate and print a PostScript image of the article buffer
10829be run just before printing the buffer. An alternative way to print 10794be run just before printing the buffer. An alternative way to print
10830article is to use Muttprint (@pxref{Saving Articles}). 10795article is to use Muttprint (@pxref{Saving Articles}).
10831 10796
10797@item A C
10798@vindex gnus-fetch-partial-articles
10799@findex gnus-summary-show-complete-article
10800If @code{gnus-fetch-partial-articles} is non-@code{nil}, Gnus will
10801fetch partial articles, if the backend it fetches them from supports
10802it. Currently only @code{nnimap} does. If you're looking at a
10803partial article, and want to see the complete article instead, then
10804the @kbd{A C} command (@code{gnus-summary-show-complete-article}) will
10805do so.
10806
10832@end table 10807@end table
10833 10808
10834 10809
@@ -11877,8 +11852,7 @@ read the same article more than once. Unless, of course, somebody has
11877posted it to several groups separately. Posting the same article to 11852posted it to several groups separately. Posting the same article to
11878several groups (not cross-posting) is called @dfn{spamming}, and you are 11853several groups (not cross-posting) is called @dfn{spamming}, and you are
11879by law required to send nasty-grams to anyone who perpetrates such a 11854by law required to send nasty-grams to anyone who perpetrates such a
11880heinous crime. You may want to try NoCeM handling to filter out spam 11855heinous crime.
11881(@pxref{NoCeM}).
11882 11856
11883Remember: Cross-posting is kinda ok, but posting the same article 11857Remember: Cross-posting is kinda ok, but posting the same article
11884separately to several groups is not. Massive cross-posting (aka. 11858separately to several groups is not. Massive cross-posting (aka.
@@ -12009,7 +11983,7 @@ To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to
12009install an OpenPGP implementation such as GnuPG. The Lisp interface 11983install an OpenPGP implementation such as GnuPG. The Lisp interface
12010to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG, 11984to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG,
12011epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg, 11985epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg,
12012PGG Manual}), Mailcrypt, and gpg.el are also supported. 11986PGG Manual}), and Mailcrypt are also supported.
12013 11987
12014@item 11988@item
12015To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6 11989To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6
@@ -12048,7 +12022,7 @@ public-key matching the @samp{From:} header as the recipient;
12048@vindex mml1991-use 12022@vindex mml1991-use
12049Symbol indicating elisp interface to OpenPGP implementation for 12023Symbol indicating elisp interface to OpenPGP implementation for
12050@acronym{PGP} messages. The default is @code{epg}, but @code{pgg}, 12024@acronym{PGP} messages. The default is @code{epg}, but @code{pgg},
12051@code{mailcrypt}, and @code{gpg} are also supported although 12025and @code{mailcrypt} are also supported although
12052deprecated. By default, Gnus uses the first available interface in 12026deprecated. By default, Gnus uses the first available interface in
12053this order. 12027this order.
12054 12028
@@ -12056,7 +12030,7 @@ this order.
12056@vindex mml2015-use 12030@vindex mml2015-use
12057Symbol indicating elisp interface to OpenPGP implementation for 12031Symbol indicating elisp interface to OpenPGP implementation for
12058@acronym{PGP/MIME} messages. The default is @code{epg}, but 12032@acronym{PGP/MIME} messages. The default is @code{epg}, but
12059@code{pgg}, @code{mailcrypt}, and @code{gpg} are also supported 12033@code{pgg}, and @code{mailcrypt} are also supported
12060although deprecated. By default, Gnus uses the first available 12034although deprecated. By default, Gnus uses the first available
12061interface in this order. 12035interface in this order.
12062 12036
@@ -13726,9 +13700,9 @@ The different methods all have their peculiarities, of course.
13726@menu 13700@menu
13727* Server Buffer:: Making and editing virtual servers. 13701* Server Buffer:: Making and editing virtual servers.
13728* Getting News:: Reading USENET news with Gnus. 13702* Getting News:: Reading USENET news with Gnus.
13703* Using @acronym{IMAP}:: Reading mail from @acronym{IMAP}.
13729* Getting Mail:: Reading your personal mail with Gnus. 13704* Getting Mail:: Reading your personal mail with Gnus.
13730* Browsing the Web:: Getting messages from a plethora of Web sources. 13705* Browsing the Web:: Getting messages from a plethora of Web sources.
13731* IMAP:: Using Gnus as a @acronym{IMAP} client.
13732* Other Sources:: Reading directories, files. 13706* Other Sources:: Reading directories, files.
13733* Combined Groups:: Combining groups into one group. 13707* Combined Groups:: Combining groups into one group.
13734* Email Based Diary:: Using mails to manage diary events in Gnus. 13708* Email Based Diary:: Using mails to manage diary events in Gnus.
@@ -14141,6 +14115,14 @@ Close the connections to all servers in the buffer
14141Remove all marks to whether Gnus was denied connection from any servers 14115Remove all marks to whether Gnus was denied connection from any servers
14142(@code{gnus-server-remove-denials}). 14116(@code{gnus-server-remove-denials}).
14143 14117
14118@item c
14119@kindex c (Server)
14120@findex gnus-server-copy-server
14121Copy a server and give it a new name
14122(@code{gnus-server-copy-server}). This can be useful if you have a
14123complex method definition, and want to use the same definition towards
14124a different (physical) server.
14125
14144@item L 14126@item L
14145@kindex L (Server) 14127@kindex L (Server)
14146@findex gnus-server-offline-server 14128@findex gnus-server-offline-server
@@ -14805,6 +14787,121 @@ there.
14805@end table 14787@end table
14806 14788
14807 14789
14790@node Using @acronym{IMAP}
14791@section Using @acronym{IMAP}
14792@cindex imap
14793
14794The most popular mail backend is probably @code{nnimap}, which
14795provides access to @acronym{IMAP} servers. @acronym{IMAP} servers
14796store mail remotely, so the client doesn't store anything locally.
14797This means that it's a convenient choice when you're reading your mail
14798from different locations, or with different user agents.
14799
14800@menu
14801* Connecting to an @acronym{IMAP} Server:: Getting started with @acronym{IMAP}.
14802* Customizing the @acronym{IMAP} Connection:: Variables for @acronym{IMAP} connection.
14803* Client-Side @acronym{IMAP} Splitting:: Put mail in the correct mail box.
14804@end menu
14805
14806
14807@node Connecting to an @acronym{IMAP} Server
14808@subsection Connecting to an @acronym{IMAP} Server
14809
14810Connecting to an @acronym{IMAP} can be very easy. Type @kbd{B} in the
14811group buffer, or (if your primary interest is reading email), say
14812something like:
14813
14814@example
14815(setq gnus-select-method
14816 '(nnimap "imap.gmail.com"))
14817@end example
14818
14819You'll be prompted for a user name and password. If you grow tired of
14820that, then add the following to your @file{~/.authinfo} file:
14821
14822@example
14823machine imap.gmail.com login <username> password <password> port imap
14824@end example
14825
14826That should basically be it for most users.
14827
14828
14829@node Customizing the @acronym{IMAP} Connection
14830@subsection Customizing the @acronym{IMAP} Connection
14831
14832Here's an example method that's more complex:
14833
14834@example
14835(nnimap "imap.gmail.com"
14836 (nnimap-inbox "INBOX")
14837 (nnimap-split-methods ,nnmail-split-methods)
14838 (nnimap-expunge t)
14839 (nnimap-stream 'ssl)
14840 (nnir-search-engine imap)
14841 (nnimap-expunge-inbox t))
14842@end example
14843
14844@table @code
14845@item nnimap-address
14846The address of the server, like @samp{imap.gmail.com}.
14847
14848@item nnimap-server-port
14849If the server uses a non-standard port, that can be specified here. A
14850typical port would be @samp{imap} or @samp{imaps}.
14851
14852@item nnimap-stream
14853How @code{nnimap} should connect to the server. Possible values are:
14854
14855@table @code
14856@item ssl
14857This is the default, and this uses standard
14858@acronym{TLS}/@acronym{SSL} connection.
14859
14860@item network
14861Non-encrypted and unsafe straight socket connection.
14862
14863@item starttls
14864Encrypted @acronym{STARTTLS} over the normal @acronym{IMAP} port.
14865
14866@item shell
14867If you need to tunnel via other systems to connect to the server, you
14868can use this option, and customize @code{nnimap-shell-program} to be
14869what you need.
14870
14871@end table
14872
14873@item nnimap-authenticator
14874Some @acronym{IMAP} servers allow anonymous logins. In that case,
14875this should be set to @code{anonymous}.
14876
14877@item nnimap-streaming
14878Virtually all @code{IMAP} server support fast streaming of data. If
14879you have problems connecting to the server, try setting this to @code{nil}.
14880
14881@end table
14882
14883
14884@node Client-Side @acronym{IMAP} Splitting
14885@subsection Client-Side @acronym{IMAP} Splitting
14886
14887Many people prefer to do the sorting/splitting of mail into their mail
14888boxes on the @acronym{IMAP} server. That way they don't have to
14889download the mail they're not all that interested in.
14890
14891If you do want to do client-side mail splitting, then the following
14892variables are relevant:
14893
14894@table @code
14895@item nnimap-inbox
14896This is the @acronym{IMAP} mail box that will be scanned for new mail.
14897
14898@item nnimap-split-methods
14899Uses the same syntax as @code{nnmail-split-methods} (@pxref{Splitting
14900Mail}).
14901
14902@end table
14903
14904
14808@node Getting Mail 14905@node Getting Mail
14809@section Getting Mail 14906@section Getting Mail
14810@cindex reading mail 14907@cindex reading mail
@@ -15363,10 +15460,7 @@ Get mail from a @acronym{IMAP} server. If you don't want to use
15363@acronym{IMAP} as intended, as a network mail reading protocol (ie 15460@acronym{IMAP} as intended, as a network mail reading protocol (ie
15364with nnimap), for some reason or other, Gnus let you treat it similar 15461with nnimap), for some reason or other, Gnus let you treat it similar
15365to a @acronym{POP} server and fetches articles from a given 15462to a @acronym{POP} server and fetches articles from a given
15366@acronym{IMAP} mailbox. @xref{IMAP}, for more information. 15463@acronym{IMAP} mailbox. @xref{Using @acronym{IMAP}}, for more information.
15367
15368Note that for the Kerberos, GSSAPI, @acronym{TLS}/@acronym{SSL} and STARTTLS support you
15369may need external programs and libraries, @xref{IMAP}.
15370 15464
15371Keywords: 15465Keywords:
15372 15466
@@ -15835,7 +15929,7 @@ after @code{save-excursion} and @code{save-restriction} in the example
15835above. Also note that with the nnimap backend, message bodies will 15929above. Also note that with the nnimap backend, message bodies will
15836not be downloaded by default. You need to set 15930not be downloaded by default. You need to set
15837@code{nnimap-split-download-body} to @code{t} to do that 15931@code{nnimap-split-download-body} to @code{t} to do that
15838(@pxref{Splitting in IMAP}). 15932(@pxref{Client-Side @acronym{IMAP} Splitting}).
15839 15933
15840@item (! @var{func} @var{split}) 15934@item (! @var{func} @var{split})
15841If the split is a list, and the first element is @code{!}, then 15935If the split is a list, and the first element is @code{!}, then
@@ -16599,6 +16693,7 @@ Spool}).
16599@end menu 16693@end menu
16600 16694
16601 16695
16696
16602@node Unix Mail Box 16697@node Unix Mail Box
16603@subsubsection Unix Mail Box 16698@subsubsection Unix Mail Box
16604@cindex nnmbox 16699@cindex nnmbox
@@ -17724,739 +17819,6 @@ Put that in your @file{.emacs} file, and hitting links in W3-rendered
17724follow the link. 17819follow the link.
17725 17820
17726 17821
17727@node IMAP
17728@section IMAP
17729@cindex nnimap
17730@cindex @acronym{IMAP}
17731
17732@acronym{IMAP} is a network protocol for reading mail (or news, or @dots{}),
17733think of it as a modernized @acronym{NNTP}. Connecting to a @acronym{IMAP}
17734server is much similar to connecting to a news server, you just
17735specify the network address of the server.
17736
17737@acronym{IMAP} has two properties. First, @acronym{IMAP} can do
17738everything that @acronym{POP} can, it can hence be viewed as a
17739@acronym{POP++}. Secondly, @acronym{IMAP} is a mail storage protocol,
17740similar to @acronym{NNTP} being a news storage protocol---however,
17741@acronym{IMAP} offers more features than @acronym{NNTP} because news
17742is more or less read-only whereas mail is read-write.
17743
17744If you want to use @acronym{IMAP} as a @acronym{POP++}, use an imap
17745entry in @code{mail-sources}. With this, Gnus will fetch mails from
17746the @acronym{IMAP} server and store them on the local disk. This is
17747not the usage described in this section---@xref{Mail Sources}.
17748
17749If you want to use @acronym{IMAP} as a mail storage protocol, use an nnimap
17750entry in @code{gnus-secondary-select-methods}. With this, Gnus will
17751manipulate mails stored on the @acronym{IMAP} server. This is the kind of
17752usage explained in this section.
17753
17754A server configuration in @file{~/.gnus.el} with a few @acronym{IMAP}
17755servers might look something like the following. (Note that for
17756@acronym{TLS}/@acronym{SSL}, you need external programs and libraries,
17757see below.)
17758
17759@lisp
17760(setq gnus-secondary-select-methods
17761 '((nnimap "simpleserver") ; @r{no special configuration}
17762 ; @r{perhaps a ssh port forwarded server:}
17763 (nnimap "dolk"
17764 (nnimap-address "localhost")
17765 (nnimap-server-port 1430))
17766 ; @r{a UW server running on localhost}
17767 (nnimap "barbar"
17768 (nnimap-server-port 143)
17769 (nnimap-address "localhost")
17770 (nnimap-list-pattern ("INBOX" "mail/*")))
17771 ; @r{anonymous public cyrus server:}
17772 (nnimap "cyrus.andrew.cmu.edu"
17773 (nnimap-authenticator anonymous)
17774 (nnimap-list-pattern "archive.*")
17775 (nnimap-stream network))
17776 ; @r{a ssl server on a non-standard port:}
17777 (nnimap "vic20"
17778 (nnimap-address "vic20.somewhere.com")
17779 (nnimap-server-port 9930)
17780 (nnimap-stream ssl))))
17781@end lisp
17782
17783After defining the new server, you can subscribe to groups on the
17784server using normal Gnus commands such as @kbd{U} in the Group Buffer
17785(@pxref{Subscription Commands}) or via the Server Buffer
17786(@pxref{Server Buffer}).
17787
17788The following variables can be used to create a virtual @code{nnimap}
17789server:
17790
17791@table @code
17792
17793@item nnimap-address
17794@vindex nnimap-address
17795
17796The address of the remote @acronym{IMAP} server. Defaults to the virtual
17797server name if not specified.
17798
17799@item nnimap-server-port
17800@vindex nnimap-server-port
17801Port on server to contact. Defaults to port 143, or 993 for @acronym{TLS}/@acronym{SSL}.
17802
17803Note that this should be an integer, example server specification:
17804
17805@lisp
17806(nnimap "mail.server.com"
17807 (nnimap-server-port 4711))
17808@end lisp
17809
17810@item nnimap-list-pattern
17811@vindex nnimap-list-pattern
17812String or list of strings of mailboxes to limit available groups to.
17813This is used when the server has very many mailboxes and you're only
17814interested in a few---some servers export your home directory via
17815@acronym{IMAP}, you'll probably want to limit the mailboxes to those in
17816@file{~/Mail/*} then.
17817
17818The string can also be a cons of REFERENCE and the string as above, what
17819REFERENCE is used for is server specific, but on the University of
17820Washington server it's a directory that will be concatenated with the
17821mailbox.
17822
17823Example server specification:
17824
17825@lisp
17826(nnimap "mail.server.com"
17827 (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*"
17828 ("~friend/Mail/" . "list/*"))))
17829@end lisp
17830
17831@item nnimap-stream
17832@vindex nnimap-stream
17833The type of stream used to connect to your server. By default, nnimap
17834will detect and automatically use all of the below, with the exception
17835of @acronym{TLS}/@acronym{SSL}. (@acronym{IMAP} over
17836@acronym{TLS}/@acronym{SSL} is being replaced by STARTTLS, which can
17837be automatically detected, but it's not widely deployed yet.)
17838
17839Example server specification:
17840
17841@lisp
17842(nnimap "mail.server.com"
17843 (nnimap-stream ssl))
17844@end lisp
17845
17846Please note that the value of @code{nnimap-stream} is a symbol!
17847
17848@itemize @bullet
17849@item
17850@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the
17851@samp{gsasl} or @samp{imtest} program.
17852@item
17853@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program.
17854@item
17855@dfn{starttls:} Connect via the STARTTLS extension (similar to
17856@acronym{TLS}/@acronym{SSL}). Requires the external library @samp{starttls.el} and program
17857@samp{starttls}.
17858@item
17859@dfn{tls:} Connect through @acronym{TLS}. Requires GNUTLS (the program
17860@samp{gnutls-cli}).
17861@item
17862@dfn{ssl:} Connect through @acronym{SSL}. Requires OpenSSL (the program
17863@samp{openssl}) or SSLeay (@samp{s_client}).
17864@item
17865@dfn{shell:} Use a shell command to start @acronym{IMAP} connection.
17866@item
17867@dfn{network:} Plain, TCP/IP network connection.
17868@end itemize
17869
17870@vindex imap-kerberos4-program
17871The @samp{imtest} program is shipped with Cyrus IMAPD. If you're
17872using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version
178731.5.x and 1.6.x) you need to frob @code{imap-process-connection-type}
17874to make @code{imap.el} use a pty instead of a pipe when communicating
17875with @samp{imtest}. You will then suffer from a line length
17876restrictions on @acronym{IMAP} commands, which might make Gnus seem to hang
17877indefinitely if you have many articles in a mailbox. The variable
17878@code{imap-kerberos4-program} contain parameters to pass to the imtest
17879program.
17880
17881For @acronym{TLS} connection, the @code{gnutls-cli} program from GNUTLS is
17882needed. It is available from
17883@uref{http://www.gnu.org/software/gnutls/}.
17884
17885@vindex imap-gssapi-program
17886This parameter specifies a list of command lines that invoke a GSSAPI
17887authenticated @acronym{IMAP} stream in a subshell. They are tried
17888sequentially until a connection is made, or the list has been
17889exhausted. By default, @samp{gsasl} from GNU SASL, available from
17890@uref{http://www.gnu.org/software/gsasl/}, and the @samp{imtest}
17891program from Cyrus IMAPD (see @code{imap-kerberos4-program}), are
17892tried.
17893
17894@vindex imap-ssl-program
17895For @acronym{SSL} connections, the OpenSSL program is available from
17896@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay,
17897and nnimap support it too---although the most recent versions of
17898SSLeay, 0.9.x, are known to have serious bugs making it
17899useless. Earlier versions, especially 0.8.x, of SSLeay are known to
17900work. The variable @code{imap-ssl-program} contain parameters to pass
17901to OpenSSL/SSLeay.
17902
17903@vindex imap-shell-program
17904@vindex imap-shell-host
17905For @acronym{IMAP} connections using the @code{shell} stream, the
17906variable @code{imap-shell-program} specify what program to call. Make
17907sure nothing is interfering with the output of the program, e.g., don't
17908forget to redirect the error output to the void.
17909
17910@item nnimap-authenticator
17911@vindex nnimap-authenticator
17912
17913The authenticator used to connect to the server. By default, nnimap
17914will use the most secure authenticator your server is capable of.
17915
17916Example server specification:
17917
17918@lisp
17919(nnimap "mail.server.com"
17920 (nnimap-authenticator anonymous))
17921@end lisp
17922
17923Please note that the value of @code{nnimap-authenticator} is a symbol!
17924
17925@itemize @bullet
17926@item
17927@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires
17928external program @code{gsasl} or @code{imtest}.
17929@item
17930@dfn{kerberos4:} Kerberos 4 authentication. Requires external program
17931@code{imtest}.
17932@item
17933@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Requires
17934external library @code{digest-md5.el}.
17935@item
17936@dfn{cram-md5:} Encrypted username/password via CRAM-MD5.
17937@item
17938@dfn{login:} Plain-text username/password via LOGIN.
17939@item
17940@dfn{anonymous:} Login as ``anonymous'', supplying your email address as password.
17941@end itemize
17942
17943@item nnimap-expunge-on-close
17944@cindex expunging
17945@vindex nnimap-expunge-on-close
17946Unlike Parmenides the @acronym{IMAP} designers have decided things that
17947don't exist actually do exist. More specifically, @acronym{IMAP} has
17948this concept of marking articles @code{Deleted} which doesn't actually
17949delete them, and this (marking them @code{Deleted}, that is) is what
17950nnimap does when you delete an article in Gnus (with @kbd{B DEL} or
17951similar).
17952
17953Since the articles aren't really removed when we mark them with the
17954@code{Deleted} flag we'll need a way to actually delete them. Feel like
17955running in circles yet?
17956
17957Traditionally, nnimap has removed all articles marked as @code{Deleted}
17958when closing a mailbox but this is now configurable by this server
17959variable.
17960
17961The possible options are:
17962
17963@table @code
17964
17965@item always
17966The default behavior, delete all articles marked as ``Deleted'' when
17967closing a mailbox.
17968@item never
17969Never actually delete articles. Currently there is no way of showing
17970the articles marked for deletion in nnimap, but other @acronym{IMAP} clients
17971may allow you to do this. If you ever want to run the EXPUNGE command
17972manually, @xref{Expunging mailboxes}.
17973@item ask
17974When closing mailboxes, nnimap will ask if you wish to expunge deleted
17975articles or not.
17976
17977@end table
17978
17979@item nnimap-importantize-dormant
17980@vindex nnimap-importantize-dormant
17981
17982If non-@code{nil} (the default), marks dormant articles as ticked (as
17983well), for other @acronym{IMAP} clients. Within Gnus, dormant articles will
17984naturally still (only) be marked as dormant. This is to make dormant
17985articles stand out, just like ticked articles, in other @acronym{IMAP}
17986clients. (In other words, Gnus has two ``Tick'' marks and @acronym{IMAP}
17987has only one.)
17988
17989Probably the only reason for frobbing this would be if you're trying
17990enable per-user persistent dormant flags, using something like:
17991
17992@lisp
17993(setcdr (assq 'dormant nnimap-mark-to-flag-alist)
17994 (format "gnus-dormant-%s" (user-login-name)))
17995(setcdr (assq 'dormant nnimap-mark-to-predicate-alist)
17996 (format "KEYWORD gnus-dormant-%s" (user-login-name)))
17997@end lisp
17998
17999In this case, you would not want the per-user dormant flag showing up
18000as ticked for other users.
18001
18002@item nnimap-expunge-search-string
18003@cindex expunging
18004@vindex nnimap-expunge-search-string
18005@cindex expiring @acronym{IMAP} mail
18006
18007This variable contain the @acronym{IMAP} search command sent to server when
18008searching for articles eligible for expiring. The default is
18009@code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by
18010UID set and the second @code{%s} is replaced by a date.
18011
18012Probably the only useful value to change this to is
18013@code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in
18014messages instead of the internal article date. See section 6.4.4 of
18015RFC 2060 for more information on valid strings.
18016
18017However, if @code{nnimap-search-uids-not-since-is-evil}
18018is true, this variable has no effect since the search logic
18019is reversed, as described below.
18020
18021@item nnimap-authinfo-file
18022@vindex nnimap-authinfo-file
18023
18024A file containing credentials used to log in on servers. The format is
18025(almost) the same as the @code{ftp} @file{~/.netrc} file. See the
18026variable @code{nntp-authinfo-file} for exact syntax; also see
18027@ref{NNTP}. An example of an .authinfo line for an IMAP server, is:
18028
18029@example
18030machine students.uio.no login larsi password geheimnis port imap
18031@end example
18032
18033Note that it should be @code{port imap}, or @code{port 143}, if you
18034use a @code{nnimap-stream} of @code{tls} or @code{ssl}, even if the
18035actual port number used is port 993 for secured IMAP. For
18036convenience, Gnus will accept @code{port imaps} as a synonym of
18037@code{port imap}.
18038
18039@item nnimap-need-unselect-to-notice-new-mail
18040@vindex nnimap-need-unselect-to-notice-new-mail
18041
18042Unselect mailboxes before looking for new mail in them. Some servers
18043seem to need this under some circumstances; it was reported that
18044Courier 1.7.1 did.
18045
18046@item nnimap-nov-is-evil
18047@vindex nnimap-nov-is-evil
18048@cindex Courier @acronym{IMAP} server
18049@cindex @acronym{NOV}
18050
18051Never generate or use a local @acronym{NOV} database. Defaults to the
18052value of @code{gnus-agent}.
18053
18054Using a @acronym{NOV} database usually makes header fetching much
18055faster, but it uses the @code{UID SEARCH UID} command, which is very
18056slow on some servers (notably some versions of Courier). Since the Gnus
18057Agent caches the information in the @acronym{NOV} database without using
18058the slow command, this variable defaults to true if the Agent is in use,
18059and false otherwise.
18060
18061@item nnimap-search-uids-not-since-is-evil
18062@vindex nnimap-search-uids-not-since-is-evil
18063@cindex Courier @acronym{IMAP} server
18064@cindex expiring @acronym{IMAP} mail
18065
18066Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE
18067@var{date}} command, which is slow on some @acronym{IMAP} servers
18068(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE
18069@var{date}} and prune the list of expirable articles within Gnus.
18070
18071When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a
18072list of expirable articles and asks the IMAP server questions like ``Of
18073these articles, which ones are older than a week?'' While this seems
18074like a perfectly reasonable question, some IMAP servers take a long time
18075to answer it, since they seemingly go looking into every old article to
18076see if it is one of the expirable ones. Curiously, the question ``Of
18077@emph{all} articles, which ones are newer than a week?'' seems to be
18078much faster to answer, so setting this variable causes Gnus to ask this
18079question and figure out the answer to the real question itself.
18080
18081This problem can really sneak up on you: when you first configure Gnus,
18082everything works fine, but once you accumulate a couple thousand
18083messages, you start cursing Gnus for being so slow. On the other hand,
18084if you get a lot of email within a week, setting this variable will
18085cause a lot of network traffic between Gnus and the IMAP server.
18086
18087@item nnimap-logout-timeout
18088@vindex nnimap-logout-timeout
18089
18090There is a case where a connection to a @acronym{IMAP} server is unable
18091to close, when connecting to the server via a certain kind of network,
18092e.g. @acronym{VPN}. In that case, it will be observed that a connection
18093between Emacs and the local network looks alive even if the server has
18094closed a connection for some reason (typically, a timeout).
18095Consequently, Emacs continues waiting for a response from the server for
18096the @code{LOGOUT} command that Emacs sent, or hangs in other words. If
18097you are in such a network, setting this variable to a number of seconds
18098will be helpful. If it is set, a hung connection will be closed
18099forcibly, after this number of seconds from the time Emacs sends the
18100@code{LOGOUT} command. It should not be too small value but too large
18101value will be inconvenient too. Perhaps the value 1.0 will be a good
18102candidate but it might be worth trying some other values.
18103
18104Example server specification:
18105
18106@lisp
18107(nnimap "mail.server.com"
18108 (nnimap-logout-timeout 1.0))
18109@end lisp
18110
18111@end table
18112
18113@menu
18114* Splitting in IMAP:: Splitting mail with nnimap.
18115* Expiring in IMAP:: Expiring mail with nnimap.
18116* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
18117* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
18118* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus.
18119* Debugging IMAP:: What to do when things don't work.
18120@end menu
18121
18122
18123
18124@node Splitting in IMAP
18125@subsection Splitting in IMAP
18126@cindex splitting imap mail
18127
18128Splitting is something Gnus users have loved and used for years, and now
18129the rest of the world is catching up. Yeah, dream on, not many
18130@acronym{IMAP} servers have server side splitting and those that have
18131splitting seem to use some non-standard protocol. This means that
18132@acronym{IMAP} support for Gnus has to do its own splitting.
18133
18134And it does.
18135
18136(Incidentally, people seem to have been dreaming on, and Sieve has
18137gaining a market share and is supported by several IMAP servers.
18138Fortunately, Gnus support it too, @xref{Sieve Commands}.)
18139
18140Here are the variables of interest:
18141
18142@table @code
18143
18144@item nnimap-split-crosspost
18145@cindex splitting, crosspost
18146@cindex crosspost
18147@vindex nnimap-split-crosspost
18148
18149If non-@code{nil}, do crossposting if several split methods match the
18150mail. If @code{nil}, the first match in @code{nnimap-split-rule}
18151found will be used.
18152
18153Nnmail equivalent: @code{nnmail-crosspost}.
18154
18155@item nnimap-split-inbox
18156@cindex splitting, inbox
18157@cindex inbox
18158@vindex nnimap-split-inbox
18159
18160A string or a list of strings that gives the name(s) of @acronym{IMAP}
18161mailboxes to split from. Defaults to @code{nil}, which means that
18162splitting is disabled!
18163
18164@lisp
18165(setq nnimap-split-inbox
18166 '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))
18167@end lisp
18168
18169No nnmail equivalent.
18170
18171@item nnimap-split-rule
18172@cindex splitting, rules
18173@vindex nnimap-split-rule
18174
18175New mail found in @code{nnimap-split-inbox} will be split according to
18176this variable.
18177
18178This variable contains a list of lists, where the first element in the
18179sublist gives the name of the @acronym{IMAP} mailbox to move articles
18180matching the regexp in the second element in the sublist. Got that?
18181Neither did I, we need examples.
18182
18183@lisp
18184(setq nnimap-split-rule
18185 '(("INBOX.nnimap"
18186 "^Sender: owner-nnimap@@vic20.globalcom.se")
18187 ("INBOX.junk" "^Subject:.*MAKE MONEY")
18188 ("INBOX.private" "")))
18189@end lisp
18190
18191This will put all articles from the nnimap mailing list into mailbox
18192INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line
18193into INBOX.junk and everything else in INBOX.private.
18194
18195The first string may contain @samp{\\1} forms, like the ones used by
18196replace-match to insert sub-expressions from the matched text. For
18197instance:
18198
18199@lisp
18200("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@")
18201@end lisp
18202
18203The first element can also be the symbol @code{junk} to indicate that
18204matching messages should simply be deleted. Use with care.
18205
18206The second element can also be a function. In that case, it will be
18207called with the first element of the rule as the argument, in a buffer
18208containing the headers of the article. It should return a
18209non-@code{nil} value if it thinks that the mail belongs in that group.
18210
18211Nnmail users might recollect that the last regexp had to be empty to
18212match all articles (like in the example above). This is not required in
18213nnimap. Articles not matching any of the regexps will not be moved out
18214of your inbox. (This might affect performance if you keep lots of
18215unread articles in your inbox, since the splitting code would go over
18216them every time you fetch new mail.)
18217
18218These rules are processed from the beginning of the alist toward the
18219end. The first rule to make a match will ``win'', unless you have
18220crossposting enabled. In that case, all matching rules will ``win''.
18221
18222This variable can also have a function as its value, the function will
18223be called with the headers narrowed and should return a group where it
18224thinks the article should be split to. See @code{nnimap-split-fancy}.
18225
18226The splitting code tries to create mailboxes if it needs to.
18227
18228To allow for different split rules on different virtual servers, and
18229even different split rules in different inboxes on the same server,
18230the syntax of this variable have been extended along the lines of:
18231
18232@lisp
18233(setq nnimap-split-rule
18234 '(("my1server" (".*" (("ding" "ding@@gnus.org")
18235 ("junk" "From:.*Simon"))))
18236 ("my2server" ("INBOX" nnimap-split-fancy))
18237 ("my[34]server" (".*" (("private" "To:.*Simon")
18238 ("junk" my-junk-func))))))
18239@end lisp
18240
18241The virtual server name is in fact a regexp, so that the same rules
18242may apply to several servers. In the example, the servers
18243@code{my3server} and @code{my4server} both use the same rules.
18244Similarly, the inbox string is also a regexp. The actual splitting
18245rules are as before, either a function, or a list with group/regexp or
18246group/function elements.
18247
18248Nnmail equivalent: @code{nnmail-split-methods}.
18249
18250@item nnimap-split-predicate
18251@cindex splitting
18252@vindex nnimap-split-predicate
18253
18254Mail matching this predicate in @code{nnimap-split-inbox} will be
18255split, it is a string and the default is @samp{UNSEEN UNDELETED}.
18256
18257This might be useful if you use another @acronym{IMAP} client to read mail in
18258your inbox but would like Gnus to split all articles in the inbox
18259regardless of readedness. Then you might change this to
18260@samp{UNDELETED}.
18261
18262@item nnimap-split-fancy
18263@cindex splitting, fancy
18264@findex nnimap-split-fancy
18265@vindex nnimap-split-fancy
18266
18267It's possible to set @code{nnimap-split-rule} to
18268@code{nnmail-split-fancy} if you want to use fancy
18269splitting. @xref{Fancy Mail Splitting}.
18270
18271However, to be able to have different fancy split rules for nnmail and
18272nnimap back ends you can set @code{nnimap-split-rule} to
18273@code{nnimap-split-fancy} and define the nnimap specific fancy split
18274rule in @code{nnimap-split-fancy}.
18275
18276Example:
18277
18278@lisp
18279(setq nnimap-split-rule 'nnimap-split-fancy
18280 nnimap-split-fancy ...)
18281@end lisp
18282
18283Nnmail equivalent: @code{nnmail-split-fancy}.
18284
18285@item nnimap-split-download-body
18286@findex nnimap-split-download-body
18287@vindex nnimap-split-download-body
18288
18289Set to non-@code{nil} to download entire articles during splitting.
18290This is generally not required, and will slow things down
18291considerably. You may need it if you want to use an advanced
18292splitting function that analyzes the body to split the article.
18293
18294@end table
18295
18296@node Expiring in IMAP
18297@subsection Expiring in IMAP
18298@cindex expiring @acronym{IMAP} mail
18299
18300Even though @code{nnimap} is not a proper @code{nnmail} derived back
18301end, it supports most features in regular expiring (@pxref{Expiring
18302Mail}). Unlike splitting in @acronym{IMAP} (@pxref{Splitting in
18303IMAP}) it does not clone the @code{nnmail} variables (i.e., creating
18304@var{nnimap-expiry-wait}) but reuse the @code{nnmail} variables. What
18305follows below are the variables used by the @code{nnimap} expiry
18306process.
18307
18308A note on how the expire mark is stored on the @acronym{IMAP} server is
18309appropriate here as well. The expire mark is translated into a
18310@code{imap} client specific mark, @code{gnus-expire}, and stored on the
18311message. This means that likely only Gnus will understand and treat
18312the @code{gnus-expire} mark properly, although other clients may allow
18313you to view client specific flags on the message. It also means that
18314your server must support permanent storage of client specific flags on
18315messages. Most do, fortunately.
18316
18317If expiring @acronym{IMAP} mail seems very slow, try setting the server
18318variable @code{nnimap-search-uids-not-since-is-evil}.
18319
18320@table @code
18321
18322@item nnmail-expiry-wait
18323@item nnmail-expiry-wait-function
18324
18325These variables are fully supported. The expire value can be a
18326number, the symbol @code{immediate} or @code{never}.
18327
18328@item nnmail-expiry-target
18329
18330This variable is supported, and internally implemented by calling the
18331@code{nnmail} functions that handle this. It contains an optimization
18332that if the destination is a @acronym{IMAP} group on the same server, the
18333article is copied instead of appended (that is, uploaded again).
18334
18335@end table
18336
18337@node Editing IMAP ACLs
18338@subsection Editing IMAP ACLs
18339@cindex editing imap acls
18340@cindex Access Control Lists
18341@cindex Editing @acronym{IMAP} ACLs
18342@kindex G l (Group)
18343@findex gnus-group-nnimap-edit-acl
18344
18345ACL stands for Access Control List. ACLs are used in @acronym{IMAP} for
18346limiting (or enabling) other users access to your mail boxes. Not all
18347@acronym{IMAP} servers support this, this function will give an error if it
18348doesn't.
18349
18350To edit an ACL for a mailbox, type @kbd{G l}
18351(@code{gnus-group-edit-nnimap-acl}) and you'll be presented with an ACL
18352editing window with detailed instructions.
18353
18354Some possible uses:
18355
18356@itemize @bullet
18357@item
18358Giving ``anyone'' the ``lrs'' rights (lookup, read, keep seen/unseen flags)
18359on your mailing list mailboxes enables other users on the same server to
18360follow the list without subscribing to it.
18361@item
18362At least with the Cyrus server, you are required to give the user
18363``anyone'' posting ("p") capabilities to have ``plussing'' work (that is,
18364mail sent to user+mailbox@@domain ending up in the @acronym{IMAP} mailbox
18365INBOX.mailbox).
18366@end itemize
18367
18368@node Expunging mailboxes
18369@subsection Expunging mailboxes
18370@cindex expunging
18371
18372@cindex expunge
18373@cindex manual expunging
18374@kindex G x (Group)
18375@findex gnus-group-expunge-group
18376
18377If you're using the @code{never} setting of @code{nnimap-expunge-on-close},
18378you may want the option of expunging all deleted articles in a mailbox
18379manually. This is exactly what @kbd{G x} does.
18380
18381Currently there is no way of showing deleted articles, you can just
18382delete them.
18383
18384@node A note on namespaces
18385@subsection A note on namespaces
18386@cindex IMAP namespace
18387@cindex namespaces
18388
18389The @acronym{IMAP} protocol has a concept called namespaces, described
18390by the following text in the RFC2060:
18391
18392@display
183935.1.2. Mailbox Namespace Naming Convention
18394
18395 By convention, the first hierarchical element of any mailbox name
18396 which begins with "#" identifies the "namespace" of the remainder of
18397 the name. This makes it possible to disambiguate between different
18398 types of mailbox stores, each of which have their own namespaces.
18399
18400 For example, implementations which offer access to USENET
18401 newsgroups MAY use the "#news" namespace to partition the USENET
18402 newsgroup namespace from that of other mailboxes. Thus, the
18403 comp.mail.misc newsgroup would have an mailbox name of
18404 "#news.comp.mail.misc", and the name "comp.mail.misc" could refer
18405 to a different object (e.g. a user's private mailbox).
18406@end display
18407
18408While there is nothing in this text that warrants concern for the
18409@acronym{IMAP} implementation in Gnus, some servers use namespace
18410prefixes in a way that does not work with how Gnus uses mailbox names.
18411
18412Specifically, University of Washington's @acronym{IMAP} server uses
18413mailbox names like @code{#driver.mbx/read-mail} which are valid only
18414in the @sc{create} and @sc{append} commands. After the mailbox is
18415created (or a messages is appended to a mailbox), it must be accessed
18416without the namespace prefix, i.e. @code{read-mail}. Since Gnus do
18417not make it possible for the user to guarantee that user entered
18418mailbox names will only be used with the CREATE and APPEND commands,
18419you should simply not use the namespace prefixed mailbox names in
18420Gnus.
18421
18422See the UoW IMAPD documentation for the @code{#driver.*/} prefix
18423for more information on how to use the prefixes. They are a power
18424tool and should be used only if you are sure what the effects are.
18425
18426@node Debugging IMAP
18427@subsection Debugging IMAP
18428@cindex IMAP debugging
18429@cindex protocol dump (IMAP)
18430
18431@acronym{IMAP} is a complex protocol, more so than @acronym{NNTP} or
18432@acronym{POP3}. Implementation bugs are not unlikely, and we do our
18433best to fix them right away. If you encounter odd behavior, chances
18434are that either the server or Gnus is buggy.
18435
18436If you are familiar with network protocols in general, you will
18437probably be able to extract some clues from the protocol dump of the
18438exchanges between Gnus and the server. Even if you are not familiar
18439with network protocols, when you include the protocol dump in
18440@acronym{IMAP}-related bug reports you are helping us with data
18441critical to solving the problem. Therefore, we strongly encourage you
18442to include the protocol dump when reporting IMAP bugs in Gnus.
18443
18444
18445@vindex imap-log
18446Because the protocol dump, when enabled, generates lots of data, it is
18447disabled by default. You can enable it by setting @code{imap-log} as
18448follows:
18449
18450@lisp
18451(setq imap-log t)
18452@end lisp
18453
18454This instructs the @code{imap.el} package to log any exchanges with
18455the server. The log is stored in the buffer @samp{*imap-log*}. Look
18456for error messages, which sometimes are tagged with the keyword
18457@code{BAD}---but when submitting a bug, make sure to include all the
18458data.
18459
18460@node Other Sources 17822@node Other Sources
18461@section Other Sources 17823@section Other Sources
18462 17824
@@ -22369,7 +21731,6 @@ four days, Gnus will decay the scores four times, for instance.
22369* Highlighting and Menus:: Making buffers look all nice and cozy. 21731* Highlighting and Menus:: Making buffers look all nice and cozy.
22370* Buttons:: Get tendinitis in ten easy steps! 21732* Buttons:: Get tendinitis in ten easy steps!
22371* Daemons:: Gnus can do things behind your back. 21733* Daemons:: Gnus can do things behind your back.
22372* NoCeM:: How to avoid spam and other fatty foods.
22373* Undo:: Some actions can be undone. 21734* Undo:: Some actions can be undone.
22374* Predicate Specifiers:: Specifying predicates. 21735* Predicate Specifiers:: Specifying predicates.
22375* Moderation:: What to do if you're a moderator. 21736* Moderation:: What to do if you're a moderator.
@@ -23388,13 +22749,12 @@ your @file{~/.gnus.el} file:
23388(gnus-demon-add-handler 'gnus-demon-close-connections 30 t) 22749(gnus-demon-add-handler 'gnus-demon-close-connections 30 t)
23389@end lisp 22750@end lisp
23390 22751
23391@findex gnus-demon-add-nocem
23392@findex gnus-demon-add-scanmail 22752@findex gnus-demon-add-scanmail
23393@findex gnus-demon-add-rescan 22753@findex gnus-demon-add-rescan
23394@findex gnus-demon-add-scan-timestamps 22754@findex gnus-demon-add-scan-timestamps
23395@findex gnus-demon-add-disconnection 22755@findex gnus-demon-add-disconnection
23396Some ready-made functions to do this have been created: 22756Some ready-made functions to do this have been created:
23397@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, 22757@code{gnus-demon-add-disconnection},
23398@code{gnus-demon-add-nntp-close-connection}, 22758@code{gnus-demon-add-nntp-close-connection},
23399@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and 22759@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and
23400@code{gnus-demon-add-scanmail}. Just put those functions in your 22760@code{gnus-demon-add-scanmail}. Just put those functions in your
@@ -23413,152 +22773,6 @@ is a sure-fire way of getting booted off any respectable system. So
23413behave. 22773behave.
23414 22774
23415 22775
23416@node NoCeM
23417@section NoCeM
23418@cindex nocem
23419@cindex spam
23420
23421@dfn{Spamming} is posting the same article lots and lots of times.
23422Spamming is bad. Spamming is evil.
23423
23424Spamming is usually canceled within a day or so by various anti-spamming
23425agencies. These agencies usually also send out @dfn{NoCeM} messages.
23426NoCeM is pronounced ``no see-'em'', and means what the name
23427implies---these are messages that make the offending articles, like, go
23428away.
23429
23430What use are these NoCeM messages if the articles are canceled anyway?
23431Some sites do not honor cancel messages and some sites just honor cancels
23432from a select few people. Then you may wish to make use of the NoCeM
23433messages, which are distributed in the newsgroups
23434@samp{news.lists.filters}, @samp{alt.nocem.misc}, etc.
23435
23436Gnus can read and parse the messages in this group automatically, and
23437this will make spam disappear.
23438
23439There are some variables to customize, of course:
23440
23441@table @code
23442@item gnus-use-nocem
23443@vindex gnus-use-nocem
23444Set this variable to @code{t} to set the ball rolling. It is @code{nil}
23445by default.
23446
23447You can also set this variable to a positive number as a group level.
23448In that case, Gnus scans NoCeM messages when checking new news if this
23449value is not exceeding a group level that you specify as the prefix
23450argument to some commands, e.g. @code{gnus},
23451@code{gnus-group-get-new-news}, etc. Otherwise, Gnus does not scan
23452NoCeM messages if you specify a group level that is smaller than this
23453value to those commands. For example, if you use 1 or 2 on the mail
23454groups and the levels on the news groups remain the default, 3 is the
23455best choice.
23456
23457@item gnus-nocem-groups
23458@vindex gnus-nocem-groups
23459Gnus will look for NoCeM messages in the groups in this list. The
23460default is
23461@lisp
23462("news.lists.filters" "alt.nocem.misc")
23463@end lisp
23464
23465@item gnus-nocem-issuers
23466@vindex gnus-nocem-issuers
23467There are many people issuing NoCeM messages. This list says what
23468people you want to listen to. The default is:
23469
23470@lisp
23471("Adri Verhoef"
23472 "alba-nocem@@albasani.net"
23473 "bleachbot@@httrack.com"
23474 "news@@arcor-online.net"
23475 "news@@uni-berlin.de"
23476 "nocem@@arcor.de"
23477 "pgpmoose@@killfile.org"
23478 "xjsppl@@gmx.de")
23479@end lisp
23480
23481Known despammers that you can put in this list are listed at@*
23482@uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}.
23483
23484You do not have to heed NoCeM messages from all these people---just the
23485ones you want to listen to. You also don't have to accept all NoCeM
23486messages from the people you like. Each NoCeM message has a @dfn{type}
23487header that gives the message a (more or less, usually less) rigorous
23488definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf},
23489@samp{binary}, and @samp{troll}. To specify this, you have to use
23490@code{(@var{issuer} @var{conditions} @dots{})} elements in the list.
23491Each condition is either a string (which is a regexp that matches types
23492you want to use) or a list on the form @code{(not @var{string})}, where
23493@var{string} is a regexp that matches types you don't want to use.
23494
23495For instance, if you want all NoCeM messages from Chris Lewis except his
23496@samp{troll} messages, you'd say:
23497
23498@lisp
23499("clewis@@ferret.ocunix.on.ca" ".*" (not "troll"))
23500@end lisp
23501
23502On the other hand, if you just want nothing but his @samp{spam} and
23503@samp{spew} messages, you'd say:
23504
23505@lisp
23506("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam")
23507@end lisp
23508
23509The specs are applied left-to-right.
23510
23511
23512@item gnus-nocem-verifyer
23513@vindex gnus-nocem-verifyer
23514@findex gnus-nocem-epg-verify
23515@findex pgg-verify
23516This should be a function for verifying that the NoCeM issuer is who she
23517says she is. This variable defaults to @code{gnus-nocem-epg-verify} if
23518EasyPG is available, otherwise defaults to @code{pgg-verify}. The
23519function should return non-@code{nil} if the verification is successful,
23520otherwise (including the case the NoCeM message was not signed) should
23521return @code{nil}. If this is too slow and you don't care for
23522verification (which may be dangerous), you can set this variable to
23523@code{nil}.
23524
23525Formerly the default was @code{mc-verify}, which is a Mailcrypt
23526function. While you can still use it, you can change it into
23527@code{gnus-nocem-epg-verify} or @code{pgg-verify} running with GnuPG if
23528you are willing to add the @acronym{PGP} public keys to GnuPG's keyring.
23529
23530@item gnus-nocem-directory
23531@vindex gnus-nocem-directory
23532This is where Gnus will store its NoCeM cache files. The default is@*
23533@file{~/News/NoCeM/}.
23534
23535@item gnus-nocem-expiry-wait
23536@vindex gnus-nocem-expiry-wait
23537The number of days before removing old NoCeM entries from the cache.
23538The default is 15. If you make it shorter Gnus will be faster, but you
23539might then see old spam.
23540
23541@item gnus-nocem-check-from
23542@vindex gnus-nocem-check-from
23543Non-@code{nil} means check for valid issuers in message bodies.
23544Otherwise don't bother fetching articles unless their author matches a
23545valid issuer; that is much faster if you are selective about the
23546issuers.
23547
23548@item gnus-nocem-check-article-limit
23549@vindex gnus-nocem-check-article-limit
23550If non-@code{nil}, the maximum number of articles to check in any NoCeM
23551group. @code{nil} means no restriction. NoCeM groups can be huge and
23552very slow to process.
23553
23554@end table
23555
23556Using NoCeM could potentially be a memory hog. If you have many living
23557(i. e., subscribed or unsubscribed groups), your Emacs process will grow
23558big. If this is a problem, you should kill off all (or most) of your
23559unsubscribed groups (@pxref{Subscription Commands}).
23560
23561
23562@node Undo 22776@node Undo
23563@section Undo 22777@section Undo
23564@cindex undo 22778@cindex undo
@@ -24398,7 +23612,7 @@ call the external tools during splitting. Example fancy split method:
24398Note that with the nnimap back end, message bodies will not be 23612Note that with the nnimap back end, message bodies will not be
24399downloaded by default. You need to set 23613downloaded by default. You need to set
24400@code{nnimap-split-download-body} to @code{t} to do that 23614@code{nnimap-split-download-body} to @code{t} to do that
24401(@pxref{Splitting in IMAP}). 23615(@pxref{Client-Side @acronym{IMAP} Splitting}).
24402 23616
24403That is about it. As some spam is likely to get through anyway, you 23617That is about it. As some spam is likely to get through anyway, you
24404might want to have a nifty function to call when you happen to read 23618might want to have a nifty function to call when you happen to read
@@ -24680,14 +23894,14 @@ the value @samp{spam} means @samp{nnimap+your-server:spam}. The value
24680@vindex nnimap-split-download-body 23894@vindex nnimap-split-download-body
24681Note for IMAP users: if you use the @code{spam-check-bogofilter}, 23895Note for IMAP users: if you use the @code{spam-check-bogofilter},
24682@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends, 23896@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends,
24683you should also set the variable @code{nnimap-split-download-body} 23897you should also set the variable @code{nnimap-split-download-body} to
24684to @code{t}. These spam back ends are most useful when they can 23898@code{t}. These spam back ends are most useful when they can ``scan''
24685``scan'' the full message body. By default, the nnimap back end only 23899the full message body. By default, the nnimap back end only retrieves
24686retrieves the message headers; @code{nnimap-split-download-body} tells 23900the message headers; @code{nnimap-split-download-body} tells it to
24687it to retrieve the message bodies as well. We don't set this by 23901retrieve the message bodies as well. We don't set this by default
24688default because it will slow @acronym{IMAP} down, and that is not an 23902because it will slow @acronym{IMAP} down, and that is not an
24689appropriate decision to make on behalf of the user. @xref{Splitting 23903appropriate decision to make on behalf of the user. @xref{Client-Side
24690in IMAP}. 23904@acronym{IMAP} Splitting}.
24691 23905
24692You have to specify one or more spam back ends for @code{spam-split} 23906You have to specify one or more spam back ends for @code{spam-split}
24693to use, by setting the @code{spam-use-*} variables. @xref{Spam Back 23907to use, by setting the @code{spam-use-*} variables. @xref{Spam Back
@@ -27604,13 +26818,6 @@ Mail can be re-scanned by a daemonic process (@pxref{Daemons}).
27604@end iftex 26818@end iftex
27605 26819
27606@item 26820@item
27607Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}).
27608
27609@lisp
27610(setq gnus-use-nocem t)
27611@end lisp
27612
27613@item
27614Groups can be made permanently visible (@pxref{Listing Groups}). 26821Groups can be made permanently visible (@pxref{Listing Groups}).
27615 26822
27616@lisp 26823@lisp