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: Rejected Articles, Prev: Drafts, Up: Composing Messages Rejected Articles ================= Sometimes a news server will reject an article. Perhaps the server doesn't like your face. Perhaps it just feels miserable. Perhaps _there be demons_. Perhaps you have included too much cited text. Perhaps the disk is full. Perhaps the server is down. These situations are, of course, totally beyond the control of Gnus. (Gnus, of course, loves the way you look, always feels great, has angels fluttering around inside of it, doesn't care about how much cited text you include, never runs full and never goes down.) So Gnus saves these articles until some later time when the server feels better. The rejected articles will automatically be put in a special draft group (*note Drafts::). When the server comes back up again, you'd then typically enter that group and send all the articles off.  File: gnus, Node: Select Methods, Next: Scoring, Prev: Composing Messages, Up: Top Select Methods ************** A "foreign group" is a group not read by the usual (or default) means. It could be, for instance, a group from a different NNTP server, it could be a virtual group, or it could be your own personal mail group. A foreign group (or any group, really) is specified by a "name" and a "select method". To take the latter first, a select method is a list where the first element says what back end to use (e.g. `nntp', `nnspool', `nnml') and the second element is the "server name". There may be additional elements in the select method, where the value may have special meaning for the back end in question. One could say that a select method defines a "virtual server"--so we do just that (*note The Server Buffer::). The "name" of the group is the name the back end will recognize the group as. For instance, the group `soc.motss' on the NNTP server `some.where.edu' will have the name `soc.motss' and select method `(nntp "some.where.edu")'. Gnus will call this group `nntp+some.where.edu:soc.motss', even though the `nntp' back end just knows this group as `soc.motss'. The different methods all have their peculiarities, of course. * Menu: * The Server Buffer:: Making and editing virtual servers. * Getting News:: Reading USENET news with Gnus. * Getting Mail:: Reading your personal mail with Gnus. * Browsing the Web:: Getting messages from a plethora of Web sources. * Other Sources:: Reading directories, files, SOUP packets. * Combined Groups:: Combining groups into one group. * Gnus Unplugged:: Reading news and mail offline.  File: gnus, Node: The Server Buffer, Next: Getting News, Up: Select Methods The Server Buffer ================= Traditionally, a "server" is a machine or a piece of software that one connects to, and then requests information from. Gnus does not connect directly to any real servers, but does all transactions through one back end or other. But that's just putting one layer more between the actual media and Gnus, so we might just as well say that each back end represents a virtual server. For instance, the `nntp' back end may be used to connect to several different actual NNTP servers, or, perhaps, to many different ports on the same actual NNTP server. You tell Gnus which back end to use, and what parameters to set by specifying a "select method". These select method specifications can sometimes become quite complicated--say, for instance, that you want to read from the NNTP server `news.funet.fi' on port number 13, which hangs if queried for NOV headers and has a buggy select. Ahem. Anyway, if you had to specify that for each group that used this server, that would be too much work, so Gnus offers a way of naming select methods, which is what you do in the server buffer. To enter the server buffer, use the `^' (`gnus-group-enter-server-mode') command in the group buffer. * Menu: * Server Buffer Format:: You can customize the look of this buffer. * Server Commands:: Commands to manipulate servers. * Example Methods:: Examples server specifications. * Creating a Virtual Server:: An example session. * Server Variables:: Which variables to set. * Servers and Methods:: You can use server names as select methods. * Unavailable Servers:: Some servers you try to contact may be down. `gnus-server-mode-hook' is run when creating the server buffer.  File: gnus, Node: Server Buffer Format, Next: Server Commands, Up: The Server Buffer Server Buffer Format -------------------- You can change the look of the server buffer lines by changing the `gnus-server-line-format' variable. This is a `format'-like variable, with some simple extensions: `h' How the news is fetched--the back end name. `n' The name of this server. `w' Where the news is to be fetched from--the address. `s' The opened/closed/denied status of the server. The mode line can also be customized by using the `gnus-server-mode-line-format' variable (*note Mode Line Formatting::). The following specs are understood: `S' Server name. `M' Server method. Also *note Formatting Variables::.  File: gnus, Node: Server Commands, Next: Example Methods, Prev: Server Buffer Format, Up: The Server Buffer Server Commands --------------- `a' Add a new server (`gnus-server-add-server'). `e' Edit a server (`gnus-server-edit-server'). `' Browse the current server (`gnus-server-read-server'). `q' Return to the group buffer (`gnus-server-exit'). `k' Kill the current server (`gnus-server-kill-server'). `y' Yank the previously killed server (`gnus-server-yank-server'). `c' Copy the current server (`gnus-server-copy-server'). `l' List all servers (`gnus-server-list-servers'). `s' Request that the server scan its sources for new articles (`gnus-server-scan-server'). This is mainly sensible with mail servers. `g' Request that the server regenerate all its data structures (`gnus-server-regenerate-server'). This can be useful if you have a mail back end that has gotten out of sync.  File: gnus, Node: Example Methods, Next: Creating a Virtual Server, Prev: Server Commands, Up: The Server Buffer Example Methods --------------- Most select methods are pretty simple and self-explanatory: (nntp "news.funet.fi") Reading directly from the spool is even simpler: (nnspool "") As you can see, the first element in a select method is the name of the back end, and the second is the "address", or "name", if you will. After these two elements, there may be an arbitrary number of `(VARIABLE FORM)' pairs. To go back to the first example--imagine that you want to read from port 15 on that machine. This is what the select method should look like then: (nntp "news.funet.fi" (nntp-port-number 15)) You should read the documentation to each back end to find out what variables are relevant, but here's an `nnmh' example: `nnmh' is a mail back end that reads a spool-like structure. Say you have two structures that you wish to access: One is your private mail spool, and the other is a public one. Here's the possible spec for your private mail: (nnmh "private" (nnmh-directory "~/private/mail/")) (This server is then called `private', but you may have guessed that.) Here's the method for a public spool: (nnmh "public" (nnmh-directory "/usr/information/spool/") (nnmh-get-new-mail nil)) If you are behind a firewall and only have access to the NNTP server from the firewall machine, you can instruct Gnus to `rlogin' on the firewall machine and telnet from there to the NNTP server. Doing this can be rather fiddly, but your virtual server definition should probably look something like this: (nntp "firewall" (nntp-address "the.firewall.machine") (nntp-open-connection-function nntp-open-rlogin) (nntp-end-of-line "\n") (nntp-rlogin-parameters ("telnet" "the.real.nntp.host" "nntp"))) If you want to use the wonderful `ssh' program to provide a compressed connection over the modem line, you could create a virtual server that would look something like this: (nntp "news" (nntp-address "copper.uio.no") (nntp-rlogin-program "ssh") (nntp-open-connection-function nntp-open-rlogin) (nntp-end-of-line "\n") (nntp-rlogin-parameters ("telnet" "news.uio.no" "nntp"))) This means that you have to have set up `ssh-agent' correctly to provide automatic authorization, of course. And to get a compressed connection, you have to have the `Compression' option in the `ssh' `config' file.  File: gnus, Node: Creating a Virtual Server, Next: Server Variables, Prev: Example Methods, Up: The Server Buffer Creating a Virtual Server ------------------------- If you're saving lots of articles in the cache by using persistent articles, you may want to create a virtual server to read the cache. First you need to add a new server. The `a' command does that. It would probably be best to use `nnspool' to read the cache. You could also use `nnml' or `nnmh', though. Type `a nnspool cache '. You should now have a brand new `nnspool' virtual server called `cache'. You now need to edit it to have the right definitions. Type `e' to edit the server. You'll be entered into a buffer that will contain the following: (nnspool "cache") Change that to: (nnspool "cache" (nnspool-spool-directory "~/News/cache/") (nnspool-nov-directory "~/News/cache/") (nnspool-active-file "~/News/cache/active")) Type `C-c C-c' to return to the server buffer. If you now press over this virtual server, you should be entered into a browse buffer, and you should be able to enter any of the groups displayed.  File: gnus, Node: Server Variables, Next: Servers and Methods, Prev: Creating a Virtual Server, Up: The Server Buffer Server Variables ---------------- One sticky point when defining variables (both on back ends and in Emacs in general) is that some variables are typically initialized from other variables when the definition of the variables is being loaded. If you change the "base" variable after the variables have been loaded, you won't change the "derived" variables. This typically affects directory and file variables. For instance, `nnml-directory' is `~/Mail/' by default, and all `nnml' directory variables are initialized from that variable, so `nnml-active-file' will be `~/Mail/active'. If you define a new virtual `nnml' server, it will _not_ suffice to set just `nnml-directory'--you have to explicitly set all the file variables to be what you want them to be. For a complete list of variables for each back end, see each back end's section later in this manual, but here's an example `nnml' definition: (nnml "public" (nnml-directory "~/my-mail/") (nnml-active-file "~/my-mail/active") (nnml-newsgroups-file "~/my-mail/newsgroups"))  File: gnus, Node: Servers and Methods, Next: Unavailable Servers, Prev: Server Variables, Up: The Server Buffer Servers and Methods ------------------- Wherever you would normally use a select method (e.g. `gnus-secondary-select-method', in the group select method, when browsing a foreign server) you can use a virtual server name instead. This could potentially save lots of typing. And it's nice all over.  File: gnus, Node: Unavailable Servers, Prev: Servers and Methods, Up: The Server Buffer Unavailable Servers ------------------- If a server seems to be unreachable, Gnus will mark that server as `denied'. That means that any subsequent attempt to make contact with that server will just be ignored. "It can't be opened," Gnus will tell you, without making the least effort to see whether that is actually the case or not. That might seem quite naughty, but it does make sense most of the time. Let's say you have 10 groups subscribed to on server `nephelococcygia.com'. This server is located somewhere quite far away from you and the machine is quite slow, so it takes 1 minute just to find out that it refuses connection to you today. If Gnus were to attempt to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do that. Once it has gotten a single "connection refused", it will regard that server as "down". So, what happens if the machine was only feeling unwell temporarily? How do you test to see whether the machine has come up again? You jump to the server buffer (*note The Server Buffer::) and poke it with the following commands: `O' Try to establish connection to the server on the current line (`gnus-server-open-server'). `C' Close the connection (if any) to the server (`gnus-server-close-server'). `D' Mark the current server as unreachable (`gnus-server-deny-server'). `M-o' Open the connections to all servers in the buffer (`gnus-server-open-all-servers'). `M-c' Close the connections to all servers in the buffer (`gnus-server-close-all-servers'). `R' Remove all marks to whether Gnus was denied connection from any servers (`gnus-server-remove-denials').  File: gnus, Node: Getting News, Next: Getting Mail, Prev: The Server Buffer, Up: Select Methods Getting News ============ A newsreader is normally used for reading news. Gnus currently provides only two methods of getting news--it can read from an NNTP server, or it can read from a local spool. * Menu: * NNTP:: Reading news from an NNTP server. * News Spool:: Reading news from the local spool.  File: gnus, Node: NNTP, Next: News Spool, Up: Getting News NNTP ---- Subscribing to a foreign group from an NNTP server is rather easy. You just specify `nntp' as method and the address of the NNTP server as the, uhm, address. If the NNTP server is located at a non-standard port, setting the third element of the select method to this port number should allow you to connect to the right port. You'll have to edit the group info for that (*note Foreign Groups::). The name of the foreign group can be the same as a native group. In fact, you can subscribe to the same group from as many different servers you feel like. There will be no name collisions. The following variables can be used to create a virtual `nntp' server: `nntp-server-opened-hook' is run after a connection has been made. It can be used to send commands to the NNTP server after it has been contacted. By default it sends the command `MODE READER' to the server with the `nntp-send-mode-reader' function. This function should always be present in this hook. `nntp-authinfo-function' This function will be used to send `AUTHINFO' to the NNTP server. The default function is `nntp-send-authinfo', which looks through your `~/.authinfo' (or whatever you've set the `nntp-authinfo-file' variable to) for applicable entries. If none are found, it will prompt you for a login name and a password. The format of the `~/.authinfo' file is (almost) the same as the `ftp' `~/.netrc' file, which is defined in the `ftp' manual page, but here are the salient facts: 1. The file contains one or more line, each of which define one server. 2. Each line may contain an arbitrary number of token/value pairs. The valid tokens include `machine', `login', `password', `default'. In addition Gnus introduces two new tokens, not present in the original `.netrc'/`ftp' syntax, namely `port' and `force'. (This is the only way the `.authinfo' file format deviates from the `.netrc' file format.) `port' is used to indicate what port on the server the credentials apply to and `force' is explained below. Here's an example file: machine news.uio.no login larsi password geheimnis machine nntp.ifi.uio.no login larsi force yes The token/value pairs may appear in any order; `machine' doesn't have to be first, for instance. In this example, both login name and password have been supplied for the former server, while the latter has only the login name listed, and the user will be prompted for the password. The latter also has the `force' tag, which means that the authinfo will be sent to the NNTP server upon connection; the default (i.e., when there is not `force' tag) is to not send authinfo to the NNTP server until the NNTP server asks for it. You can also add `default' lines that will apply to all servers that don't have matching `machine' lines. default force yes This will force sending `AUTHINFO' commands to all servers not previously mentioned. Remember to not leave the `~/.authinfo' file world-readable. `nntp-server-action-alist' This is a list of regexps to match on server types and actions to be taken when matches are made. For instance, if you want Gnus to beep every time you connect to innd, you could say something like: (setq nntp-server-action-alist '(("innd" (ding)))) You probably don't want to do that, though. The default value is '(("nntpd 1\\.5\\.11t" (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader))) This ensures that Gnus doesn't send the `MODE READER' command to nntpd 1.5.11t, since that command chokes that server, I've been told. `nntp-maximum-request' If the NNTP server doesn't support NOV headers, this back end will collect headers by sending a series of `head' commands. To speed things up, the back end sends lots of these commands without waiting for reply, and then reads all the replies. This is controlled by the `nntp-maximum-request' variable, and is 400 by default. If your network is buggy, you should set this to 1. `nntp-connection-timeout' If you have lots of foreign `nntp' groups that you connect to regularly, you're sure to have problems with NNTP servers not responding properly, or being too loaded to reply within reasonable time. This is can lead to awkward problems, which can be helped somewhat by setting `nntp-connection-timeout'. This is an integer that says how many seconds the `nntp' back end should wait for a connection before giving up. If it is `nil', which is the default, no timeouts are done. `nntp-server-hook' This hook is run as the last step when connecting to an NNTP server. `nntp-open-connection-function' This function is used to connect to the remote system. Four pre-made functions are supplied: `nntp-open-network-stream' This is the default, and simply connects to some port or other on the remote system. `nntp-open-rlogin' Does an `rlogin' on the remote system, and then does a `telnet' to the NNTP server available there. `nntp-open-rlogin'-related variables: `nntp-rlogin-program' Program used to log in on remote machines. The default is `rsh', but `ssh' is a popular alternative. `nntp-rlogin-parameters' This list will be used as the parameter list given to `rsh'. `nntp-rlogin-user-name' User name on the remote system. `nntp-open-telnet' Does a `telnet' to the remote system and then another `telnet' to get to the NNTP server. `nntp-open-telnet'-related variables: `nntp-telnet-command' Command used to start `telnet'. `nntp-telnet-switches' List of strings to be used as the switches to the `telnet' command. `nntp-telnet-user-name' User name for log in on the remote system. `nntp-telnet-passwd' Password to use when logging in. `nntp-telnet-parameters' A list of strings executed as a command after logging in via `telnet'. `nntp-telnet-shell-prompt' Regexp matching the shell prompt on the remote machine. The default is `bash\\|\$ *\r?$\\|> *\r?'. `nntp-open-telnet-envuser' If non-`nil', the `telnet' session (client and server both) will support the `ENVIRON' option and not prompt for login name. This works for Solaris `telnet', for instance. `nntp-open-ssl-stream' Opens a connection to a server over a "secure" channel. To use this you must have SSLay installed (`ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL', and you also need `ssl.el' (from the W3 distribution, for instance). You then define a server as follows: ;; Type `C-c C-c' after you've finished editing. ;; ;; "snews" is port 563 and is predefined ;; in our /etc/services ;; (nntp "snews.bar.com" (nntp-open-connection-function nntp-open-ssl-stream) (nntp-port-number "snews") (nntp-address "snews.bar.com")) `nntp-end-of-line' String to use as end-of-line marker when talking to the NNTP server. This is `\r\n' by default, but should be `\n' when using `rlogin' to talk to the server. `nntp-rlogin-user-name' User name on the remote system when using the `rlogin' connect function. `nntp-address' The address of the remote system running the NNTP server. `nntp-port-number' Port number to connect to when using the `nntp-open-network-stream' connect function. `nntp-buggy-select' Set this to non-`nil' if your select routine is buggy. `nntp-nov-is-evil' If the NNTP server does not support NOV, you could set this variable to `t', but `nntp' usually checks automatically whether NOV can be used. `nntp-xover-commands' List of strings used as commands to fetch NOV lines from a server. The default value of this variable is `("XOVER" "XOVERVIEW")'. `nntp-nov-gap' `nntp' normally sends just one big request for NOV lines to the server. The server responds with one huge list of lines. However, if you have read articles 2-5000 in the group, and only want to read article 1 and 5001, that means that `nntp' will fetch 4999 NOV lines that you will not need. This variable says how big a gap between two consecutive articles is allowed to be before the `XOVER' request is split into several request. Note that if your network is fast, setting this variable to a really small number means that fetching will probably be slower. If this variable is `nil', `nntp' will never split requests. The default is 5. `nntp-prepare-server-hook' A hook run before attempting to connect to an NNTP server. `nntp-warn-about-losing-connection' If this variable is non-`nil', some noise will be made when a server closes connection. `nntp-record-commands' If non-`nil', `nntp' will log all commands it sends to the NNTP server (along with a timestamp) in the `*nntp-log*' buffer. This is useful if you are debugging a Gnus/NNTP connection that doesn't seem to work.  File: gnus, Node: News Spool, Prev: NNTP, Up: Getting News News Spool ---------- Subscribing to a foreign group from the local spool is extremely easy, and might be useful, for instance, to speed up reading groups that contain very big articles--`alt.binaries.pictures.furniture', for instance. Anyway, you just specify `nnspool' as the method and `""' (or anything else) as the address. If you have access to a local spool, you should probably use that as the native select method (*note Finding the News::). It is normally faster than using an `nntp' select method, but might not be. It depends. You just have to try to find out what's best at your site. `nnspool-inews-program' Program used to post an article. `nnspool-inews-switches' Parameters given to the inews program when posting an article. `nnspool-spool-directory' Where `nnspool' looks for the articles. This is normally `/usr/spool/news/'. `nnspool-nov-directory' Where `nnspool' will look for NOV files. This is normally `/usr/spool/news/over.view/'. `nnspool-lib-dir' Where the news lib dir is (`/usr/lib/news/' by default). `nnspool-active-file' The path to the active file. `nnspool-newsgroups-file' The path to the group descriptions file. `nnspool-history-file' The path to the news history file. `nnspool-active-times-file' The path to the active date file. `nnspool-nov-is-evil' If non-`nil', `nnspool' won't try to use any NOV files that it finds. `nnspool-sift-nov-with-sed' If non-`nil', which is the default, use `sed' to get the relevant portion from the overview file. If nil, `nnspool' will load the entire file into a buffer and process it there.  File: gnus, Node: Getting Mail, Next: Browsing the Web, Prev: Getting News, Up: Select Methods Getting Mail ============ Reading mail with a newsreader--isn't that just plain WeIrD? But of course. * Menu: * Mail in a Newsreader:: Important introductory notes. * Getting Started Reading Mail:: A simple cookbook example. * Splitting Mail:: How to create mail groups. * Mail Sources:: How to tell Gnus where to get mail from. * Mail Back End Variables:: Variables for customizing mail handling. * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. * Group Mail Splitting:: Use group customize to drive mail splitting. * Incorporating Old Mail:: What about the old mail you have? * Expiring Mail:: Getting rid of unwanted mail. * Washing Mail:: Removing gruft from the mail you get. * Duplicates:: Dealing with duplicated mail. * Not Reading Mail:: Using mail back ends for reading other files. * Choosing a Mail Back End:: Gnus can read a variety of mail formats.  File: gnus, Node: Mail in a Newsreader, Next: Getting Started Reading Mail, Up: Getting Mail Mail in a Newsreader -------------------- If you are used to traditional mail readers, but have decided to switch to reading mail with Gnus, you may find yourself experiencing something of a culture shock. Gnus does not behave like traditional mail readers. If you want to make it behave that way, you can, but it's an uphill battle. Gnus, by default, handles all its groups using the same approach. This approach is very newsreaderly--you enter a group, see the new/unread messages, and when you read the messages, they get marked as read, and you don't see them any more. (Unless you explicitly ask for them.) In particular, you do not do anything explicitly to delete messages. Does this mean that all the messages that have been marked as read are deleted? How awful! But, no, it means that old messages are "expired" according to some scheme or other. For news messages, the expire process is controlled by the news administrator; for mail, the expire process is controlled by you. The expire process for mail is covered in depth in *note Expiring Mail::. What many Gnus users find, after using it a while for both news and mail, is that the transport mechanism has very little to do with how they want to treat a message. Many people subscribe to several mailing lists. These are transported via SMTP, and are therefore mail. But we might go for weeks without answering, or even reading these messages very carefully. We may not need to save them because if we should need to read one again, they are archived somewhere else. Some people have local news groups which have only a handful of readers. These are transported via NNTP, and are therefore news. But we may need to read and answer a large fraction of the messages very carefully in order to do our work. And there may not be an archive, so we may need to save the interesting messages the same way we would personal mail. The important distinction turns out to be not the transport mechanism, but other factors such as how interested we are in the subject matter, or how easy it is to retrieve the message if we need to read it again. Gnus provides many options for sorting mail into "groups" which behave like newsgroups, and for treating each group (whether mail or news) differently. Some users never get comfortable using the Gnus (ahem) paradigm and wish that Gnus should grow up and be a male, er, mail reader. It is possible to whip Gnus into a more mailreaderly being, but, as said before, it's not easy. People who prefer proper mail readers should try VM instead, which is an excellent, and proper, mail reader. I don't mean to scare anybody off, but I want to make it clear that you may be required to learn a new way of thinking about messages. After you've been subjected to The Gnus Way, you will come to love it. I can guarantee it. (At least the guy who sold me the Emacs Subliminal Brain-Washing Functions that I've put into Gnus did guarantee it. You Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way. You Do.)  File: gnus, Node: Getting Started Reading Mail, Next: Splitting Mail, Prev: Mail in a Newsreader, Up: Getting Mail Getting Started Reading Mail ---------------------------- It's quite easy to use Gnus to read your new mail. You just plonk the mail back end of your choice into `gnus-secondary-select-methods', and things will happen automatically. For instance, if you want to use `nnml' (which is a "one file per mail" back end), you could put the following in your `.gnus' file: (setq gnus-secondary-select-methods '((nnml "private"))) Now, the next time you start Gnus, this back end will be queried for new articles, and it will move all the messages in your spool file to its directory, which is `~/Mail/' by default. The new group that will be created (`mail.misc') will be subscribed, and you can read it like any other group. You will probably want to split the mail into several groups, though: (setq nnmail-split-methods '(("junk" "^From:.*Lars Ingebrigtsen") ("crazy" "^Subject:.*die\\|^Organization:.*flabby") ("other" ""))) This will result in three new `nnml' mail groups being created: `nnml:junk', `nnml:crazy', and `nnml:other'. All the mail that doesn't fit into the first two groups will be placed in the last group. This should be sufficient for reading mail with Gnus. You might want to give the other sections in this part of the manual a perusal, though. Especially *note Choosing a Mail Back End:: and *note Expiring Mail::.  File: gnus, Node: Splitting Mail, Next: Mail Sources, Prev: Getting Started Reading Mail, Up: Getting Mail Splitting Mail -------------- The `nnmail-split-methods' variable says how the incoming mail is to be split into groups. (setq nnmail-split-methods '(("mail.junk" "^From:.*Lars Ingebrigtsen") ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") ("mail.other" ""))) This variable is a list of lists, where the first element of each of these lists is the name of the mail group (they do not have to be called something beginning with `mail', by the way), and the second element is a regular expression used on the header of each mail to determine if it belongs in this mail group. The first string may contain `\\1' forms, like the ones used by `replace-match' to insert sub-expressions from the matched text. For instance: ("list.\\1" "From:.* \\(.*\\)-list@majordomo.com") The second element can also be a function. In that case, it will be called narrowed to the headers with the first element of the rule as the argument. It should return a non-`nil' value if it thinks that the mail belongs in that group. The last of these groups should always be a general one, and the regular expression should _always_ be `' so that it matches any mails that haven't been matched by any of the other regexps. (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".) If you like to tinker with this yourself, you can set this variable to a function of your choice. This function will be called without any arguments in a buffer narrowed to the headers of an incoming mail message. The function should return a list of group names that it thinks should carry this mail message. Note that the mail back ends are free to maul the poor, innocent, incoming headers all they want to. They all add `Lines' headers; some add `X-Gnus-Group' headers; most rename the Unix mbox `From ' line to something else. The mail back ends all support cross-posting. If several regexps match, the mail will be "cross-posted" to all those groups. `nnmail-crosspost' says whether to use this mechanism or not. Note that no articles are crossposted to the general (`') group. `nnmh' and `nnml' makes crossposts by creating hard links to the crossposted articles. However, not all file systems support hard links. If that's the case for you, set `nnmail-crosspost-link-function' to `copy-file'. (This variable is `add-name-to-file' by default.) If you wish to see where the previous mail split put the messages, you can use the `M-x nnmail-split-history' command. If you wish to see where re-spooling messages would put the messages, you can use `gnus-summary-respool-trace' and related commands (*note Mail Group Commands::). Gnus gives you all the opportunity you could possibly want for shooting yourself in the foot. Let's say you create a group that will contain all the mail you get from your boss. And then you accidentally unsubscribe from the group. Gnus will still put all the mail from your boss in the unsubscribed group, and so, when your boss mails you "Have that report ready by Monday or you're fired!", you'll never see it and, come Tuesday, you'll still believe that you're gainfully employed while you really should be out collecting empty bottles to save up for next month's rent money.  File: gnus, Node: Mail Sources, Next: Mail Back End Variables, Prev: Splitting Mail, Up: Getting Mail Mail Sources ------------ Mail can be gotten from many different sources--the mail spool, from a POP mail server, from a procmail directory, or from a maildir, for instance. * Menu: * Mail Source Specifiers:: How to specify what a mail source is. * Mail Source Customization:: Some variables that influence things. * Fetching Mail:: Using the mail source specifiers.  File: gnus, Node: Mail Source Specifiers, Next: Mail Source Customization, Up: Mail Sources Mail Source Specifiers ...................... You tell Gnus how to fetch mail by setting `mail-sources' (*note Fetching Mail::) to a "mail source specifier". Here's an example: (pop :server "pop3.mailserver.com" :user "myname") As can be observed, a mail source specifier is a list where the first element is a "mail source type", followed by an arbitrary number of "keywords". Keywords that are not explicitly specified are given default values. The following mail source types are available: `file' Get mail from a single file; typically from the mail spool. Keywords: `:path' The path of the file. Defaults to the value of the `MAIL' environment variable or `/usr/mail/spool/user-name'. An example file mail source: (file :path "/usr/spool/mail/user-name") Or using the default path: (file) If the mail spool file is not located on the local machine, it's best to use POP or IMAP or the like to fetch the mail. You can not use ange-ftp file names here--it has no way to lock the mail spool while moving the mail. If it's impossible to set up a proper server, you can use ssh instead. (setq mail-sources '((file :prescript "ssh host bin/getmail >%t"))) The `getmail' script would look something like the following: #!/bin/sh # getmail - move mail from spool to stdout # flu@iki.fi MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail TMP=$HOME/Mail/tmp rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP Alter this script to fit find the `movemail' you want to use. `directory' Get mail from several files in a directory. This is typically used when you have procmail split the incoming mail into several files. Setting `nnmail-scan-directory-mail-source-once' to non-nil force Gnus to scan the mail source only once. Keywords: `:path' The path of the directory where the files are. There is no default value. `:suffix' Only files ending with this suffix are used. The default is `.spool'. `:predicate' Only files that have this predicate return non-`nil' are returned. The default is `identity'. This is used as an additional filter--only files that have the right suffix _and_ satisfy this predicate are considered. `:prescript' `:postscript' Script run before/after fetching mail. An example directory mail source: (directory :path "/home/user-name/procmail-dir/" :suffix ".prcml") `pop' Get mail from a POP server. Keywords: `:server' The name of the POP server. The default is taken from the `MAILHOST' environment variable. `:port' The port number of the POP server. This can be a number (e.g. `:port 110') or a string (e.g. `:port "pop3"'). If it is a string, it should be a service name as listed in `/etc/services' on Unix systems. The default is `"pop3"'. On some systems you might need to specify it as `"pop-3"' instead. `:user' The user name to give to the POP server. The default is the login name. `:password' The password to give to the POP server. If not specified, the user is prompted. `:program' The program to use to fetch mail from the POP server. This should be a `format'-like string. Here's an example: fetchmail %u@%s -P %p %t The valid format specifier characters are: `t' The name of the file the mail is to be moved to. This must always be included in this string. `s' The name of the server. `P' The port number of the server. `u' The user name to use. `p' The password to use. The values used for these specs are taken from the values you give the corresponding keywords. `:prescript' A script to be run before fetching the mail. The syntax is the same as the `:program' keyword. This can also be a function to be run. `:postscript' A script to be run after fetching the mail. The syntax is the same as the `:program' keyword. This can also be a function to be run. `:function' The function to use to fetch mail from the POP server. The function is called with one parameter--the name of the file where the mail should be moved to. `:authentication' This can be either the symbol `password' or the symbol `apop' and says what authentication scheme to use. The default is `password'. If the `:program' and `:function' keywords aren't specified, `pop3-movemail' will be used. Here are some examples. Fetch from the default POP server, using the default user name, and default fetcher: (pop) Fetch from a named server with a named user and password: (pop :server "my.pop.server" :user "user-name" :password "secret") Use `movemail' to move the mail: (pop :program "movemail po:%u %t %p") `maildir' Get mail from a maildir. This is a type of mailbox that is supported by at least qmail and postfix, where each file in a special directory contains exactly one mail. Keywords: `:path' The path of the directory where the mails are stored. The default is taken from the `MAILDIR' environment variable or `~/Maildir/'. `:subdirs' The subdirectories of the Maildir. The default is `("new" "cur")'. You can also get mails from remote hosts (because maildirs don't suffer from locking problems). Two example maildir mail sources: (maildir :path "/home/user-name/Maildir/" :subdirs ("cur" "new")) (maildir :path "/user@remotehost.org:~/Maildir/" :subdirs ("new")) `imap' Get mail from a IMAP server. If you don't want to use IMAP as intended, as a network mail reading protocol (ie with nnimap), for some reason or other, Gnus let you treat it similar to a POP server and fetches articles from a given IMAP mailbox. *Note IMAP::, for more information. Note that for SSL support you may need external programs and libraries, *Note IMAP::. Keywords: `:server' The name of the IMAP server. The default is taken from the `MAILHOST' environment variable. `:port' The port number of the IMAP server. The default is `143', or `993' for SSL connections. `:user' The user name to give to the IMAP server. The default is the login name. `:password' The password to give to the IMAP server. If not specified, the user is prompted. `:stream' What stream to use for connecting to the server, this is one of the symbols in `imap-stream-alist'. Right now, this means `kerberos4', `ssl' or the default `network'. `:authentication' Which authenticator to use for authenticating to the server, this is one of the symbols in `imap-authenticator-alist'. Right now, this means `kerberos4', `cram-md5', `anonymous' or the default `login'. `:program' When using the `shell' :stream, the contents of this variable is mapped into the `imap-shell-program' variable. This should be a `format'-like string (or list of strings). Here's an example: ssh %s imapd The valid format specifier characters are: `s' The name of the server. `l' User name from `imap-default-user'. `p' The port number of the server. The values used for these specs are taken from the values you give the corresponding keywords. `:mailbox' The name of the mailbox to get mail from. The default is `INBOX' which normally is the mailbox which receive incoming mail. `:predicate' The predicate used to find articles to fetch. The default, `UNSEEN UNDELETED', is probably the best choice for most people, but if you sometimes peek in your mailbox with a IMAP client and mark some articles as read (or; SEEN) you might want to set this to `nil'. Then all articles in the mailbox is fetched, no matter what. For a complete list of predicates, see RFC 2060 §6.4.4. `:fetchflag' How to flag fetched articles on the server, the default `\Deleted' will mark them as deleted, an alternative would be `\Seen' which would simply mark them as read. These are the two most likely choices, but more flags are defined in RFC 2060 §2.3.2. `:dontexpunge' If non-nil, don't remove all articles marked as deleted in the mailbox after finishing the fetch. An example IMAP mail source: (imap :server "mail.mycorp.com" :stream kerberos4 :fetchflag "\\Seen") `webmail' Get mail from a webmail server, such as www.hotmail.com, webmail.netscape.com, www.netaddress.com, www.my-deja.com. NOTE: Now mail.yahoo.com provides POP3 service, so POP mail source is suggested. NOTE: Webmail largely depends cookies. A "one-line-cookie" patch is required for url "4.0pre.46". WARNING: Mails may lost. NO WARRANTY. Keywords: `:subtype' The type of the webmail server. The default is `hotmail'. The alternatives are `netscape', `netaddress', `my-deja'. `:user' The user name to give to the webmail server. The default is the login name. `:password' The password to give to the webmail server. If not specified, the user is prompted. `:dontexpunge' If non-nil, only fetch unread articles and don't move them to trash folder after finishing the fetch. An example webmail source: (webmail :subtype 'hotmail :user "user-name" :password "secret") "Common Keywords" Common keywords can be used in any type of mail source. Keywords: `:plugged' If non-nil, fetch the mail even when Gnus is unplugged. If you use directory source to get mail, you can specify it as in this example: (setq mail-sources '((directory :path "/home/pavel/.Spool/" :suffix "" :plugged t))) Gnus will then fetch your mail even when you are unplugged. This is useful when you use local mail and news. Function Interface .................. Some of the above keywords specify a Lisp function to be executed. For each keyword `:foo', the Lisp variable `foo' is bound to the value of the keyword while the function is executing. For example, consider the following mail-source setting: (setq mail-sources '((pop :user "jrl" :server "pophost" :function fetchfunc))) While the function `fetchfunc' is executing, the symbol `user' is bound to `"jrl"', and the symbol `server' is bound to `"pophost"'. The symbols `port', `password', `program', `prescript', `postscript', `function', and `authentication' are also bound (to their default values). See above for a list of keywords for each type of mail source.  File: gnus, Node: Mail Source Customization, Next: Fetching Mail, Prev: Mail Source Specifiers, Up: Mail Sources Mail Source Customization ......................... The following is a list of variables that influence how the mail is fetched. You would normally not need to set or change any of these variables. `mail-source-crash-box' File where mail will be stored while processing it. The default is `~/.emacs-mail-crash-box'. `mail-source-delete-incoming' If non-`nil', delete incoming files after handling them. `mail-source-directory' Directory where files (if any) will be stored. The default is `~/Mail/'. At present, the only thing this is used for is to say where the incoming files will be stored if the previous variable is `nil'. `mail-source-incoming-file-prefix' Prefix for file name for storing incoming mail. The default is `Incoming', in which case files will end up with names like `Incoming30630D_' or `Incoming298602ZD'. This is really only relevant if `mail-source-delete-incoming' is `nil'. `mail-source-default-file-modes' All new mail files will get this file mode. The default is 384.