This is ../info/gnus, produced by makeinfo version 4.3 from gnus.texi. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Gnus: (gnus). The newsreader Gnus. END-INFO-DIR-ENTRY This file documents Gnus, the GNU Emacs newsreader. Copyright (C) 1995,96,97,98,99,2000,2001 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being none, with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License" in the Emacs manual. (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.  File: gnus, Node: Slashdot, Next: Ultimate, Prev: Web Searches, Up: Browsing the Web Slashdot -------- Slashdot (`http://slashdot.org/') is a popular news site, with lively discussion following the news articles. `nnslashdot' will let you read this forum in a convenient manner. The easiest way to read this source is to put something like the following in your `.gnus.el' file: (setq gnus-secondary-select-methods '((nnslashdot ""))) This will make Gnus query the `nnslashdot' back end for new comments and groups. The `F' command will subscribe each new news article as a new Gnus group, and you can read the comments by entering these groups. (Note that the default subscription method is to subscribe new groups as zombies. Other methods are available (*note Subscription Methods::). If you want to remove an old `nnslashdot' group, the `G ' command is the most handy tool (*note Foreign Groups::). When following up to `nnslashdot' comments (or posting new comments), some light HTMLizations will be performed. In particular, text quoted with `> ' will be quoted with `blockquote' instead, and signatures will have `br' added to the end of each line. Other than that, you can just write HTML directly into the message buffer. Note that Slashdot filters out some HTML forms. The following variables can be altered to change its behavior: `nnslashdot-threaded' Whether `nnslashdot' should display threaded groups or not. The default is `t'. To be able to display threads, `nnslashdot' has to retrieve absolutely all comments in a group upon entry. If a threaded display is not required, `nnslashdot' will only retrieve the comments that are actually wanted by the user. Threading is nicer, but much, much slower than untreaded. `nnslashdot-login-name' The login name to use when posting. `nnslashdot-password' The password to use when posting. `nnslashdot-directory' Where `nnslashdot' will store its files. The default is `~/News/slashdot/'. `nnslashdot-active-url' The URL format string that will be used to fetch the information on news articles and comments. Default: `http://slashdot.org/search.pl?section=&min=%d'. `nnslashdot-comments-url' The URL format string that will be used to fetch comments. The default is `http://slashdot.org/comments.pl?sid=%s&threshold=%d&commentsort=%d&mode=flat&startat=%d'. `nnslashdot-article-url' The URL format string that will be used to fetch the news article. The default is `http://slashdot.org/article.pl?sid=%s&mode=nocomment'. `nnslashdot-threshold' The score threshold. The default is -1. `nnslashdot-group-number' The number of old groups, in addition to the ten latest, to keep updated. The default is 0.  File: gnus, Node: Ultimate, Next: Web Archive, Prev: Slashdot, Up: Browsing the Web Ultimate -------- The Ultimate Bulletin Board (`http://www.ultimatebb.com/') is probably the most popular Web bulletin board system used. It has a quite regular and nice interface, and it's possible to get the information Gnus needs to keep groups updated. The easiest way to get started with `nnultimate' is to say something like the following in the group buffer: `B nnultimate http://www.tcj.com/messboard/ubbcgi/ '. (Substitute the URL (not including `Ultimate.cgi' or the like at the end) for a forum you're interested in; there's quite a list of them on the Ultimate web site.) Then subscribe to the groups you're interested in from the server buffer, and read them from the group buffer. The following `nnultimate' variables can be altered: `nnultimate-directory' The directory where `nnultimate' stores its files. The default is `~/News/ultimate/'.  File: gnus, Node: Web Archive, Next: Customizing w3, Prev: Ultimate, Up: Browsing the Web Web Archive ----------- Some mailing lists only have archives on Web servers, such as `http://www.egroups.com/' and `http://www.mail-archive.com/'. It has a quite regular and nice interface, and it's possible to get the information Gnus needs to keep groups updated. The easiest way to get started with `nnwarchive' is to say something like the following in the group buffer: `M-x gnus-group-make-warchive-group an_egroup egroups www.egroups.com your@email.address '. (Substitute the AN_EGROUP with the mailing list you subscribed, the YOUR@EMAIL.ADDRESS with your email address.), or to browse the back end by `B nnwarchive mail-archive '. The following `nnwarchive' variables can be altered: `nnwarchive-directory' The directory where `nnwarchive' stores its files. The default is `~/News/warchive/'. `nnwarchive-login' The account name on the web server. `nnwarchive-passwd' The password for your account on the web server.  File: gnus, Node: Customizing w3, Prev: Web Archive, Up: Browsing the Web Customizing w3 -------------- Gnus uses the url library to fetch web pages and Emacs/w3 to display web pages. Emacs/w3 is documented in its own manual, but there are some things that may be more relevant for Gnus users. For instance, a common question is how to make Emacs/w3 follow links using the `browse-url' functions (which will call some external web browser like Netscape). Here's one way: (eval-after-load "w3" '(progn (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) (defun w3-fetch (&optional url target) (interactive (list (w3-read-url-with-default))) (if (eq major-mode 'gnus-article-mode) (browse-url url) (w3-fetch-orig url target))))) Put that in your `.emacs' file, and hitting links in w3-rendered HTML in the Gnus article buffers will use `browse-url' to follow the link.  File: gnus, Node: Other Sources, Next: Combined Groups, Prev: Browsing the Web, Up: Select Methods Other Sources ============= Gnus can do more than just read news or mail. The methods described below allow Gnus to view directories and files as if they were newsgroups. * Menu: * Directory Groups:: You can read a directory as if it was a newsgroup. * Anything Groups:: Dired? Who needs dired? * Document Groups:: Single files can be the basis of a group. * SOUP:: Reading SOUP packets ``offline''. * Mail-To-News Gateways:: Posting articles via mail-to-news gateways. * IMAP:: Using Gnus as a IMAP client.  File: gnus, Node: Directory Groups, Next: Anything Groups, Up: Other Sources Directory Groups ---------------- If you have a directory that has lots of articles in separate files in it, you might treat it as a newsgroup. The files have to have numerical names, of course. This might be an opportune moment to mention `ange-ftp' (and its successor `efs'), that most wonderful of all wonderful Emacs packages. When I wrote `nndir', I didn't think much about it--a back end to read directories. Big deal. `ange-ftp' changes that picture dramatically. For instance, if you enter the `ange-ftp' file name `/ftp.hpc.uh.edu:/pub/emacs/ding-list/' as the directory name, `ange-ftp' or `efs' will actually allow you to read this directory over at `sina' as a newsgroup. Distributed news ahoy! `nndir' will use NOV files if they are present. `nndir' is a "read-only" back end--you can't delete or expire articles with this method. You can use `nnmh' or `nnml' for whatever you use `nndir' for, so you could switch to any of those methods if you feel the need to have a non-read-only `nndir'.  File: gnus, Node: Anything Groups, Next: Document Groups, Prev: Directory Groups, Up: Other Sources Anything Groups --------------- From the `nndir' back end (which reads a single spool-like directory), it's just a hop and a skip to `nneething', which pretends that any arbitrary directory is a newsgroup. Strange, but true. When `nneething' is presented with a directory, it will scan this directory and assign article numbers to each file. When you enter such a group, `nneething' must create "headers" that Gnus can use. After all, Gnus is a newsreader, in case you're forgetting. `nneething' does this in a two-step process. First, it snoops each file in question. If the file looks like an article (i.e., the first few lines look like headers), it will use this as the head. If this is just some arbitrary file without a head (e.g. a C source file), `nneething' will cobble up a header out of thin air. It will use file ownership, name and date and do whatever it can with these elements. All this should happen automatically for you, and you will be presented with something that looks very much like a newsgroup. Totally like a newsgroup, to be precise. If you select an article, it will be displayed in the article buffer, just as usual. If you select a line that represents a directory, Gnus will pop you into a new summary buffer for this `nneething' group. And so on. You can traverse the entire disk this way, if you feel like, but remember that Gnus is not dired, really, and does not intend to be, either. There are two overall modes to this action--ephemeral or solid. When doing the ephemeral thing (i.e., `G D' from the group buffer), Gnus will not store information on what files you have read, and what files are new, and so on. If you create a solid `nneething' group the normal way with `G m', Gnus will store a mapping table between article numbers and file names, and you can treat this group like any other groups. When you activate a solid `nneething' group, you will be told how many unread articles it contains, etc., etc. Some variables: `nneething-map-file-directory' All the mapping files for solid `nneething' groups will be stored in this directory, which defaults to `~/.nneething/'. `nneething-exclude-files' All files that match this regexp will be ignored. Nice to use to exclude auto-save files and the like, which is what it does by default. `nneething-include-files' Regexp saying what files to include in the group. If this variable is non-`nil', only files matching this regexp will be included. `nneething-map-file' Name of the map files.  File: gnus, Node: Document Groups, Next: SOUP, Prev: Anything Groups, Up: Other Sources Document Groups --------------- `nndoc' is a cute little thing that will let you read a single file as a newsgroup. Several files types are supported: `babyl' The babyl (rmail) mail box. `mbox' The standard Unix mbox file. `mmdf' The MMDF mail box format. `news' Several news articles appended into a file. `rnews' The rnews batch transport format. `forward' Forwarded articles. `nsmail' Netscape mail boxes. `mime-parts' MIME multipart messages. `standard-digest' The standard (RFC 1153) digest format. `slack-digest' Non-standard digest format--matches most things, but does it badly. You can also use the special "file type" `guess', which means that `nndoc' will try to guess what file type it is looking at. `digest' means that `nndoc' should guess what digest type the file is. `nndoc' will not try to change the file or insert any extra headers into it--it will simply, like, let you use the file as the basis for a group. And that's it. If you have some old archived articles that you want to insert into your new & spiffy Gnus mail back end, `nndoc' can probably help you with that. Say you have an old `RMAIL' file with mail that you now want to split into your new `nnml' groups. You look at that file using `nndoc' (using the `G f' command in the group buffer (*note Foreign Groups::)), set the process mark on all the articles in the buffer (`M P b', for instance), and then re-spool (`B r') using `nnml'. If all goes well, all the mail in the `RMAIL' file is now also stored in lots of `nnml' directories, and you can delete that pesky `RMAIL' file. If you have the guts! Virtual server variables: `nndoc-article-type' This should be one of `mbox', `babyl', `digest', `news', `rnews', `mmdf', `forward', `rfc934', `rfc822-forward', `mime-parts', `standard-digest', `slack-digest', `clari-briefs', `nsmail' or `guess'. `nndoc-post-type' This variable says whether Gnus is to consider the group a news group or a mail group. There are two valid values: `mail' (the default) and `news'. * Menu: * Document Server Internals:: How to add your own document types.  File: gnus, Node: Document Server Internals, Up: Document Groups Document Server Internals ......................... Adding new document types to be recognized by `nndoc' isn't difficult. You just have to whip up a definition of what the document looks like, write a predicate function to recognize that document type, and then hook into `nndoc'. First, here's an example document type definition: (mmdf (article-begin . "^\^A\^A\^A\^A\n") (body-end . "^\^A\^A\^A\^A\n")) The definition is simply a unique "name" followed by a series of regexp pseudo-variable settings. Below are the possible variables--don't be daunted by the number of variables; most document types can be defined with very few settings: `first-article' If present, `nndoc' will skip past all text until it finds something that match this regexp. All text before this will be totally ignored. `article-begin' This setting has to be present in all document type definitions. It says what the beginning of each article looks like. `head-begin-function' If present, this should be a function that moves point to the head of the article. `nndoc-head-begin' If present, this should be a regexp that matches the head of the article. `nndoc-head-end' This should match the end of the head of the article. It defaults to `^$'--the empty line. `body-begin-function' If present, this function should move point to the beginning of the body of the article. `body-begin' This should match the beginning of the body of the article. It defaults to `^\n'. `body-end-function' If present, this function should move point to the end of the body of the article. `body-end' If present, this should match the end of the body of the article. `file-end' If present, this should match the end of the file. All text after this regexp will be totally ignored. So, using these variables `nndoc' is able to dissect a document file into a series of articles, each with a head and a body. However, a few more variables are needed since not all document types are all that news-like--variables needed to transform the head or the body into something that's palatable for Gnus: `prepare-body-function' If present, this function will be called when requesting an article. It will be called with point at the start of the body, and is useful if the document has encoded some parts of its contents. `article-transform-function' If present, this function is called when requesting an article. It's meant to be used for more wide-ranging transformation of both head and body of the article. `generate-head-function' If present, this function is called to generate a head that Gnus can understand. It is called with the article number as a parameter, and is expected to generate a nice head for the article in question. It is called when requesting the headers of all articles. Let's look at the most complicated example I can come up with--standard digests: (standard-digest (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+")) (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+")) (prepare-body-function . nndoc-unquote-dashes) (body-end-function . nndoc-digest-body-end) (head-end . "^ ?$") (body-begin . "^ ?\n") (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$") (subtype digest guess)) We see that all text before a 70-width line of dashes is ignored; all text after a line that starts with that `^End of' is also ignored; each article begins with a 30-width line of dashes; the line separating the head from the body may contain a single space; and that the body is run through `nndoc-unquote-dashes' before being delivered. To hook your own document definition into `nndoc', use the `nndoc-add-type' function. It takes two parameters--the first is the definition itself and the second (optional) parameter says where in the document type definition alist to put this definition. The alist is traversed sequentially, and `nndoc-TYPE-type-p' is called for a given type `TYPE'. So `nndoc-mmdf-type-p' is called to see whether a document is of `mmdf' type, and so on. These type predicates should return `nil' if the document is not of the correct type; `t' if it is of the correct type; and a number if the document might be of the correct type. A high number means high probability; a low number means low probability with `0' being the lowest valid number.  File: gnus, Node: SOUP, Next: Mail-To-News Gateways, Prev: Document Groups, Up: Other Sources SOUP ---- In the PC world people often talk about "offline" newsreaders. These are thingies that are combined reader/news transport monstrosities. With built-in modem programs. Yecchh! Of course, us Unix Weenie types of human beans use things like `uucp' and, like, `nntpd' and set up proper news and mail transport things like Ghod intended. And then we just use normal newsreaders. However, it can sometimes be convenient to do something that's a bit easier on the brain if you have a very slow modem, and you're not really that interested in doing things properly. A file format called SOUP has been developed for transporting news and mail from servers to home machines and back again. It can be a bit fiddly. First some terminology: "server" This is the machine that is connected to the outside world and where you get news and/or mail from. "home machine" This is the machine that you want to do the actual reading and responding on. It is typically not connected to the rest of the world in any way. "packet" Something that contains messages and/or commands. There are two kinds of packets: "message packets" These are packets made at the server, and typically contain lots of messages for you to read. These are called `SoupoutX.tgz' by default, where X is a number. "response packets" These are packets made at the home machine, and typically contains replies that you've written. These are called `SoupinX.tgz' by default, where X is a number. 1. You log in on the server and create a SOUP packet. You can either use a dedicated SOUP thingie (like the `awk' program), or you can use Gnus to create the packet with its SOUP commands (`O s' and/or `G s b'; and then `G s p') (*note SOUP Commands::). 2. You transfer the packet home. Rail, boat, car or modem will do fine. 3. You put the packet in your home directory. 4. You fire up Gnus on your home machine using the `nnsoup' back end as the native or secondary server. 5. You read articles and mail and answer and followup to the things you want (*note SOUP Replies::). 6. You do the `G s r' command to pack these replies into a SOUP packet. 7. You transfer this packet to the server. 8. You use Gnus to mail this packet out with the `G s s' command. 9. You then repeat until you die. So you basically have a bipartite system--you use `nnsoup' for reading and Gnus for packing/sending these SOUP packets. * Menu: * SOUP Commands:: Commands for creating and sending SOUP packets * SOUP Groups:: A back end for reading SOUP packets. * SOUP Replies:: How to enable `nnsoup' to take over mail and news.  File: gnus, Node: SOUP Commands, Next: SOUP Groups, Up: SOUP SOUP Commands ............. These are commands for creating and manipulating SOUP packets. `G s b' Pack all unread articles in the current group (`gnus-group-brew-soup'). This command understands the process/prefix convention. `G s w' Save all SOUP data files (`gnus-soup-save-areas'). `G s s' Send all replies from the replies packet (`gnus-soup-send-replies'). `G s p' Pack all files into a SOUP packet (`gnus-soup-pack-packet'). `G s r' Pack all replies into a replies packet (`nnsoup-pack-replies'). `O s' This summary-mode command adds the current article to a SOUP packet (`gnus-soup-add-article'). It understands the process/prefix convention (*note Process/Prefix::). There are a few variables to customize where Gnus will put all these thingies: `gnus-soup-directory' Directory where Gnus will save intermediate files while composing SOUP packets. The default is `~/SoupBrew/'. `gnus-soup-replies-directory' This is what Gnus will use as a temporary directory while sending our reply packets. `~/SoupBrew/SoupReplies/' is the default. `gnus-soup-prefix-file' Name of the file where Gnus stores the last used prefix. The default is `gnus-prefix'. `gnus-soup-packer' A format string command for packing a SOUP packet. The default is `tar cf - %s | gzip > $HOME/Soupout%d.tgz'. `gnus-soup-unpacker' Format string command for unpacking a SOUP packet. The default is `gunzip -c %s | tar xvf -'. `gnus-soup-packet-directory' Where Gnus will look for reply packets. The default is `~/'. `gnus-soup-packet-regexp' Regular expression matching SOUP reply packets in `gnus-soup-packet-directory'.  File: gnus, Node: SOUP Groups, Next: SOUP Replies, Prev: SOUP Commands, Up: SOUP SOUP Groups ........... `nnsoup' is the back end for reading SOUP packets. It will read incoming packets, unpack them, and put them in a directory where you can read them at leisure. These are the variables you can use to customize its behavior: `nnsoup-tmp-directory' When `nnsoup' unpacks a SOUP packet, it does it in this directory. (`/tmp/' by default.) `nnsoup-directory' `nnsoup' then moves each message and index file to this directory. The default is `~/SOUP/'. `nnsoup-replies-directory' All replies will be stored in this directory before being packed into a reply packet. The default is `~/SOUP/replies/"'. `nnsoup-replies-format-type' The SOUP format of the replies packets. The default is `?n' (rnews), and I don't think you should touch that variable. I probably shouldn't even have documented it. Drats! Too late! `nnsoup-replies-index-type' The index type of the replies packet. The default is `?n', which means "none". Don't fiddle with this one either! `nnsoup-active-file' Where `nnsoup' stores lots of information. This is not an "active file" in the `nntp' sense; it's an Emacs Lisp file. If you lose this file or mess it up in any way, you're dead. The default is `~/SOUP/active'. `nnsoup-packer' Format string command for packing a reply SOUP packet. The default is `tar cf - %s | gzip > $HOME/Soupin%d.tgz'. `nnsoup-unpacker' Format string command for unpacking incoming SOUP packets. The default is `gunzip -c %s | tar xvf -'. `nnsoup-packet-directory' Where `nnsoup' will look for incoming packets. The default is `~/'. `nnsoup-packet-regexp' Regular expression matching incoming SOUP packets. The default is `Soupout'. `nnsoup-always-save' If non-`nil', save the replies buffer after each posted message.  File: gnus, Node: SOUP Replies, Prev: SOUP Groups, Up: SOUP SOUP Replies ............ Just using `nnsoup' won't mean that your postings and mailings end up in SOUP reply packets automagically. You have to work a bit more for that to happen. The `nnsoup-set-variables' command will set the appropriate variables to ensure that all your followups and replies end up in the SOUP system. In specific, this is what it does: (setq message-send-news-function 'nnsoup-request-post) (setq message-send-mail-function 'nnsoup-request-mail) And that's it, really. If you only want news to go into the SOUP system you just use the first line. If you only want mail to be SOUPed you use the second.  File: gnus, Node: Mail-To-News Gateways, Next: IMAP, Prev: SOUP, Up: Other Sources Mail-To-News Gateways --------------------- If your local `nntp' server doesn't allow posting, for some reason or other, you can post using one of the numerous mail-to-news gateways. The `nngateway' back end provides the interface. Note that you can't read anything from this back end--it can only be used to post with. Server variables: `nngateway-address' This is the address of the mail-to-news gateway. `nngateway-header-transformation' News headers often have to be transformed in some odd way or other for the mail-to-news gateway to accept it. This variable says what transformation should be called, and defaults to `nngateway-simple-header-transformation'. The function is called narrowed to the headers to be transformed and with one parameter--the gateway address. This default function just inserts a new `To' header based on the `Newsgroups' header and the gateway address. For instance, an article with this `Newsgroups' header: Newsgroups: alt.religion.emacs will get this `From' header inserted: To: alt-religion-emacs@GATEWAY The following pre-defined functions exist: `nngateway-simple-header-transformation' Creates a `To' header that looks like NEWSGROUP@`nngateway-address'. `nngateway-mail2news-header-transformation' Creates a `To' header that looks like `nngateway-address'. Here's an example: (setq gnus-post-method '(nngateway "mail2news@replay.com" (nngateway-header-transformation nngateway-mail2news-header-transformation))) So, to use this, simply say something like: (setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))  File: gnus, Node: IMAP, Prev: Mail-To-News Gateways, Up: Other Sources IMAP ---- IMAP is a network protocol for reading mail (or news, or...), think of it as a modernized NNTP. Connecting to a IMAP server is much similar to connecting to a news server, you just specify the network address of the server. IMAP has two properties. First, IMAP can do everything that POP can, it can hence be viewed as POP++. Secondly, IMAP is a mail storage protocol, similar to NNTP being a news storage protocol. (IMAP offers more features than NNTP because news is more or less read-only whereas mail is read-write.) If you want to use IMAP as POP++, use an imap entry in mail-sources. With this, Gnus will fetch mails from the IMAP server and store them on the local disk. This is not the usage described in this section. *Note Mail Sources::. If you want to use IMAP as a mail storage protocol, use an nnimap entry in gnus-secondary-select-methods. With this, Gnus will manipulate mails stored on the IMAP server. This is the kind of usage explained in this section. A server configuration in `~/.gnus' with a few IMAP servers might look something like the following. (Note that for SSL, you need external programs and libraries, see below.) (setq gnus-secondary-select-methods '((nnimap "simpleserver") ; no special configuration ; perhaps a ssh port forwarded server: (nnimap "dolk" (nnimap-address "localhost") (nnimap-server-port 1430)) ; a UW server running on localhost (nnimap "barbar" (nnimap-server-port 143) (nnimap-address "localhost") (nnimap-list-pattern ("INBOX" "mail/*"))) ; anonymous public cyrus server: (nnimap "cyrus.andrew.cmu.edu" (nnimap-authenticator anonymous) (nnimap-list-pattern "archive.*") (nnimap-stream network)) ; a ssl server on a non-standard port: (nnimap "vic20" (nnimap-address "vic20.somewhere.com") (nnimap-server-port 9930) (nnimap-stream ssl)))) The following variables can be used to create a virtual `nnimap' server: `nnimap-address' The address of the remote IMAP server. Defaults to the virtual server name if not specified. `nnimap-server-port' Port on server to contact. Defaults to port 143, or 993 for SSL. Note that this should be a integer, example server specification: (nnimap "mail.server.com" (nnimap-server-port 4711)) `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 IMAP, you'll probably want to limit the mailboxes to those in `~/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: (nnimap "mail.server.com" (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" ("~friend/Mail/" . "list/*")))) `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 SSL. (SSL is being replaced by STARTTLS, which can be automatically detected, but it's not widely deployed yet). Example server specification: (nnimap "mail.server.com" (nnimap-stream ssl)) Please note that the value of `nnimap-stream' is a symbol! * "gssapi:" Connect with GSSAPI (usually Kerberos 5). Requires the `imtest' program. * "kerberos4:" Connect with Kerberos 4. Requires the `imtest' program. * "starttls:" Connect via the STARTTLS extension (similar to SSL). Requires the library `starttls.el' and program `starttls'. * "ssl:" Connect through SSL. Requires OpenSSL (the program `openssl') or SSLeay (`s_client') as well as the external library `ssl.el'. * "shell:" Use a shell command to start an IMAP connection. * "network:" Plain, TCP/IP network connection. The `imtest' program is shipped with Cyrus IMAPD. Nnimap supports both `imtest' version 1.5.x and version 1.6.x. The variable `imap-kerberos4-program' contains parameters to pass to the `imtest' program. For SSL connections, the OpenSSL program is available from `http://www.openssl.org/'. OpenSSL was formerly known as SSLeay, and nnimap supports it too. However, 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 `imap-ssl-program' contains parameters to pass to OpenSSL/SSLeay. You also need `ssl.el' (from the W3 distribution, for instance). For IMAP connections using the `shell' stream, the variable `imap-shell-program' specifies what program to call. `nnimap-authenticator' The authenticator used to connect to the server. By default, nnimap will use the most secure authenticator your server supports. Example server specification: (nnimap "mail.server.com" (nnimap-authenticator anonymous)) Please note that the value of `nnimap-authenticator' is a symbol! * "gssapi:" GSSAPI (usually Kerberos 5) authentication. Requires the external program `imtest'. * "kerberos4:" Kerberos authentication. Requires the external program `imtest'. * "digest-md5:" Encrypted username/password via DIGEST-MD5. Requires external library `digest-md5.el'. * "cram-md5:" Encrypted username/password via CRAM-MD5. * "login:" Plain-text username/password via LOGIN. * "anonymous:" Login as `anonymous', supplying your email address as password. `nnimap-expunge-on-close' Unlike Parmenides, the IMAP designers decided that things that don't exist actually do exist. More specifically, IMAP has the concept of marking articles `Deleted' which doesn't actually delete them, and this (marking them `Deleted', that is) is what nnimap does when you delete a article in Gnus (with `G ' or similar). Since the articles aren't really removed when we mark them with the `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 `Deleted' when closing a mailbox but this is now configurable by this server variable. The possible options are: `always' The default behavior, delete all articles marked as "Deleted" when closing a mailbox. `never' Never actually delete articles. Currently there is no way of showing the articles marked for deletion in nnimap, but other IMAP clients may allow you to do this. If you ever want to run the EXPUNGE command manually, *Note Expunging mailboxes::. `ask' When closing mailboxes, nnimap will ask if you wish to expunge deleted articles or not. `nnimap-authinfo-file' A file containing credentials used to log in on servers. The format is (almost) the same as the `ftp' `~/.netrc' file. See `nntp-authinfo-file' for exact syntax. A file containing credentials used to log in on servers. The format is (almost) the same as the `ftp' `~/.netrc' file. See the variable `nntp-authinfo-file' for exact syntax; also see *Note NNTP::. * Menu: * Splitting in IMAP:: Splitting mail with nnimap. * Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. * Expunging mailboxes:: Equivalent of a "compress mailbox" button.  File: gnus, Node: Splitting in IMAP, Next: Editing IMAP ACLs, Up: IMAP Splitting in IMAP ................. 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 IMAP servers have server side splitting and those that have splitting seem to use some non-standard protocol. This means that IMAP support for Gnus has to do its own splitting. And it does. Here are the variables of interest: `nnimap-split-crosspost' If non-nil, do crossposting if several split methods match the mail. If nil, the first match in `nnimap-split-rule' found will be used. Nnmail equivalent: `nnmail-crosspost'. `nnimap-split-inbox' A string or a list of strings that gives the name(s) of IMAP mailboxes to split from. Defaults to `nil', which means that splitting is disabled! (setq nnimap-split-inbox '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap")) No nnmail equivalent. `nnimap-split-rule' New mail found in `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 IMAP mailbox to move articles matching the regexp in the second element in the sublist. Got that? Neither did I, we need examples. (setq nnimap-split-rule '(("INBOX.nnimap" "^Sender: owner-nnimap@vic20.globalcom.se") ("INBOX.junk" "^Subject:.*MAKE MONEY") ("INBOX.private" ""))) 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.spam and everything else in INBOX.private. The first string may contain `\\DIGIT' forms, like the ones used by replace-match to insert sub-expressions from the matched text. For instance: ("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@") 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-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 to where it thinks the article should be split. See `nnimap-split-fancy'. The splitting code tries to create mailboxes if it needs too. 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 has been extended along the lines of: (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))))) The virtual server name is in fact a regexp, so that the same rules may apply to several servers. In the example, the servers `my3server' and `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: `nnmail-split-methods'. `nnimap-split-predicate' Mail matching this predicate in `nnimap-split-inbox' will be split; it is a string and the default is `UNSEEN UNDELETED'. This might be useful if you use another 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 `UNDELETED'. `nnimap-split-fancy' It's possible to set `nnimap-split-rule' to `nnmail-split-fancy' if you want to use fancy splitting. *Note Fancy Mail Splitting::. However, to be able to have different fancy split rules for nnmail and nnimap back ends you can set `nnimap-split-rule' to `nnimap-split-fancy' and define the nnimap specific fancy split rule in `nnimap-split-fancy'. Example: (setq nnimap-split-rule 'nnimap-split-fancy nnimap-split-fancy ...) Nnmail equivalent: `nnmail-split-fancy'.  File: gnus, Node: Editing IMAP ACLs, Next: Expunging mailboxes, Prev: Splitting in IMAP, Up: IMAP Editing IMAP ACLs ................. ACL stands for Access Control List. ACLs are used in IMAP for limiting (or enabling) other users access to your mail boxes. Not all IMAP servers support this, this function will give an error if it doesn't. To edit a ACL for a mailbox, type `G l' (`gnus-group-edit-nnimap-acl') and you'll be presented with a ACL editing window with detailed instructions. Some possible uses: * 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. * 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 IMAP mailbox INBOX.mailbox).  File: gnus, Node: Expunging mailboxes, Prev: Editing IMAP ACLs, Up: IMAP Expunging mailboxes ................... If you're using the `never' setting of `nnimap-expunge-close', you may want the option of expunging all deleted articles in a mailbox manually. This is exactly what `G x' does. Currently there is no way of showing deleted articles, you can just delete them.  File: gnus, Node: Combined Groups, Next: Gnus Unplugged, Prev: Other Sources, Up: Select Methods Combined Groups =============== Gnus allows combining a mixture of all the other group types into bigger groups. * Menu: * Virtual Groups:: Combining articles from many groups. * Kibozed Groups:: Looking through parts of the newsfeed for articles.  File: gnus, Node: Virtual Groups, Next: Kibozed Groups, Up: Combined Groups Virtual Groups -------------- An "nnvirtual group" is really nothing more than a collection of other groups. For instance, if you are tired of reading many small groups, you can put them all in one big group, and then grow tired of reading one big, unwieldy group. The joys of computing! You specify `nnvirtual' as the method. The address should be a regexp to match component groups. All marks in the virtual group will stick to the articles in the component groups. So if you tick an article in a virtual group, the article will also be ticked in the component group from whence it came. (And vice versa--marks from the component groups will also be shown in the virtual group.) Here's an example `nnvirtual' method that collects all Andrea Dworkin newsgroups into one, big, happy newsgroup: (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") The component groups can be native or foreign; everything should work smoothly, but if your computer explodes, it was probably my fault. Collecting the same group from several servers might actually be a good idea if users have set the Distribution header to limit distribution. If you would like to read `soc.motss' both from a server in Japan and a server in Norway, you could use the following as the group regexp: "^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" (Remember, though, that if you're creating the group with `G m', you shouldn't double the backslashes, and you should leave off the quote characters at the beginning and the end of the string.) This should work kinda smoothly--all articles from both groups should end up in this one, and there should be no duplicates. Threading (and the rest) will still work as usual, but there might be problems with the sequence of articles. Sorting on date might be an option here (*note Selecting a Group::). One limitation, however--all groups included in a virtual group have to be alive (i.e., subscribed or unsubscribed). Killed or zombie groups can't be component groups for `nnvirtual' groups. If the `nnvirtual-always-rescan' is non-`nil', `nnvirtual' will always scan groups for unread articles when entering a virtual group. If this variable is `nil' (which is the default) and you read articles in a component group after the virtual group has been activated, the read articles from the component group will show up when you enter the virtual group. You'll also see this effect if you have two virtual groups that have a component group in common. If that's the case, you should set this variable to `t'. Or you can just tap `M-g' on the virtual group every time before you enter it--it'll have much the same effect. `nnvirtual' can have both mail and news groups as component groups. When responding to articles in `nnvirtual' groups, `nnvirtual' has to ask the back end of the component group the article comes from whether it is a news or mail back end. However, when you do a `^', there is typically no sure way for the component back end to know this, and in that case `nnvirtual' tells Gnus that the article came from a not-news back end. (Just to be on the safe side.) `C-c C-t' in the message buffer will insert the `Newsgroups' line from the article you respond to in these cases.  File: gnus, Node: Kibozed Groups, Prev: Virtual Groups, Up: Combined Groups Kibozed Groups -------------- "Kibozing" is defined by OED as "grepping through (parts of) the news feed". `nnkiboze' is a back end that will do this for you. Oh joy! Now you can grind any NNTP server down to a halt with useless requests! Oh happiness! To create a kibozed group, use the `G k' command in the group buffer. The address field of the `nnkiboze' method is, as with `nnvirtual', a regexp to match groups to be "included" in the `nnkiboze' group. That's where most similarities between `nnkiboze' and `nnvirtual' end. In addition to this regexp detailing component groups, an `nnkiboze' group must have a score file to say what articles are to be included in the group (*note Scoring::). You must run `M-x nnkiboze-generate-groups' after creating the `nnkiboze' groups you want to have. This command will take time. Lots of time. Oodles and oodles of time. Gnus has to fetch the headers from all the articles in all the component groups and run them through the scoring process to determine if there are any articles in the groups that are to be part of the `nnkiboze' groups. Please limit the number of component groups by using restrictive regexps. Otherwise your sysadmin may become annoyed with you, and the NNTP site may throw you off and never let you back in again. Stranger things have happened. `nnkiboze' component groups do not have to be alive--they can be dead, and they can be foreign. No restrictions. The generation of an `nnkiboze' group means writing two files in `nnkiboze-directory', which is `~/News/' by default. One contains the NOV header lines for all the articles in the group, and the other is an additional `.newsrc' file to store information on what groups have been searched through to find component articles. Articles marked as read in the `nnkiboze' group will have their NOV lines removed from the NOV file.  File: gnus, Node: Gnus Unplugged, Prev: Combined Groups, Up: Select Methods Gnus Unplugged ============== In olden times (ca. February '88), people used to run their newsreaders on big machines with permanent connections to the net. News transport was dealt with by news servers, and all the newsreaders had to do was to read news. Believe it or not. Nowadays most people read news and mail at home, and use some sort of modem to connect to the net. To avoid running up huge phone bills, it would be nice to have a way to slurp down all the news and mail, hang up the phone, read for several hours, and then upload any responses you have to make. And then you repeat the procedure. Of course, you can use news servers for doing this as well. I've used `inn' together with `slurp', `pop' and `sendmail' for some years, but doing that's a bore. Moving the news server functionality up to the newsreader makes sense if you're the only person reading news on a machine. Using Gnus as an "offline" newsreader is quite simple. * First, set up Gnus as you would do if you were running it on a machine that has full connection to the net. Go ahead. I'll still be waiting here. * Then, put the following magical incantation at the end of your `.gnus.el' file: (gnus-agentize) That's it. Gnus is now an "offline" newsreader. Of course, to use it as such, you have to learn a few new commands. * Menu: * Agent Basics:: How it all is supposed to work. * Agent Categories:: How to tell the Gnus Agent what to download. * Agent Commands:: New commands for all the buffers. * Agent Expiry:: How to make old articles go away. * Agent and IMAP:: How to use the Agent with IMAP. * Outgoing Messages:: What happens when you post/mail something? * Agent Variables:: Customizing is fun. * Example Setup:: An example `.gnus.el' file for offline people. * Batching Agents:: How to fetch news from a `cron' job. * Agent Caveats:: What you think it'll do and what it does.