This is Info file ../info/gnus, produced by Makeinfo version 1.68 from the input file gnus.texi. 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 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.  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 backend 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 backend 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 backend 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' backend 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. * 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 backend 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 backend represents a virtual server. For instance, the `nntp' backend 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 backend 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. Anyways, 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 backend 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'). `SPACE' 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 backend that has gotten out of synch.  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 backend, 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 backend to find out what variables are relevant, but here's an `nnmh' example: `nnmh' is a mail backend 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 RET cache RET'. 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 `RET' 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 backends 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 backend, see each backend'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' and `force'. (The latter is not a valid `.netrc'/`ftp' token, which is the only way the `.authinfo' file format deviates from the `.netrc' file format.) 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 backend will collect headers by sending a series of `head' commands. To speed things up, the backend 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' backend 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 distributeion, 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 timestep) 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. Anyways, 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: Other Sources, Prev: Getting News, Up: Select Methods Getting Mail ============ Reading mail with a newsreader--isn't that just plain WeIrD? But of course. * Menu: * Getting Started Reading Mail:: A simple cookbook example. * Splitting Mail:: How to create mail groups. * Mail Backend Variables:: Variables for customizing mail handling. * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. * Mail and Procmail:: Reading mail groups that procmail create. * 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 backends for reading other files. * Choosing a Mail Backend:: Gnus can read a variety of mail formats.  File: gnus, Node: Getting Started Reading Mail, Next: Splitting Mail, Up: Getting Mail Getting Started Reading Mail ---------------------------- It's quite easy to use Gnus to read your new mail. You just plonk the mail backend 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" backend), you could put the following in your `.gnus' file: (setq gnus-secondary-select-methods '((nnml "private"))) Now, the next time you start Gnus, this backend 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 Backend::. and *note Expiring Mail::..  File: gnus, Node: Splitting Mail, Next: Mail Backend Variables, 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 backends 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 backends 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. 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 Backend Variables, Next: Fancy Mail Splitting, Prev: Splitting Mail, Up: Getting Mail Mail Backend Variables ---------------------- These variables are (for the most part) pertinent to all the various mail backends. `nnmail-read-incoming-hook' The mail backends all call this hook after reading new mail. You can use this hook to notify any mail watch programs, if you want to. `nnmail-spool-file' The backends will look for new mail in this file. If this variable is `nil', the mail backends will never attempt to fetch mail by themselves. If you are using a POP mail server and your name is `larsi', you should set this variable to `po:larsi'. If your name is not `larsi', you should probably modify that slightly, but you may have guessed that already, you smart & handsome devil! You can also set this variable to `pop', and Gnus will try to figure out the POP mail string by itself. In any case, Gnus will call `movemail' which will contact the POP server named in the `MAILHOST' environment variable. If the POP server needs a password, you can either set `nnmail-pop-password-required' to `t' and be prompted for the password, or set `nnmail-pop-password' to the password itself. `nnmail-spool-file' can also be a list of mailboxes. Your Emacs has to have been configured with `--with-pop' before compilation. This is the default, but some installations have it switched off. When you use a mail backend, Gnus will slurp all your mail from your inbox and plonk it down in your home directory. Gnus doesn't move any mail if you're not using a mail backend--you have to do a lot of magic invocations first. At the time when you have finished drawing the pentagram, lightened the candles, and sacrificed the goat, you really shouldn't be too surprised when Gnus moves your mail. `nnmail-use-procmail' If non-`nil', the mail backends will look in `nnmail-procmail-directory' for incoming mail. All the files in that directory that have names ending in `nnmail-procmail-suffix' will be considered incoming mailboxes, and will be searched for new mail. `nnmail-crash-box' When a mail backend reads a spool file, mail is first moved to this file, which is `~/.gnus-crash-box' by default. If this file already exists, it will always be read (and incorporated) before any other spool files. `nnmail-prepare-incoming-hook' This is run in a buffer that holds all the new incoming mail, and can be used for, well, anything, really. `nnmail-split-hook' Hook run in the buffer where the mail headers of each message is kept just before the splitting based on these headers is done. The hook is free to modify the buffer contents in any way it sees fit--the buffer is discarded after the splitting has been done, and no changes performed in the buffer will show up in any files. `gnus-article-decode-rfc1522' is one likely function to add to this hook. `nnmail-pre-get-new-mail-hook' `nnmail-post-get-new-mail-hook' These are two useful hooks executed when treating new incoming mail--`nnmail-pre-get-new-mail-hook' (is called just before starting to handle the new mail) and `nnmail-post-get-new-mail-hook' (is called when the mail handling is done). Here's and example of using these two hooks to change the default file modes the new mail files get: (add-hook 'gnus-pre-get-new-mail-hook (lambda () (set-default-file-modes 511))) (add-hook 'gnus-post-get-new-mail-hook (lambda () (set-default-file-modes 551))) `nnmail-tmp-directory' This variable says where to move incoming mail to - while processing it. This is usually done in the same directory that the mail backend inhabits (e.g., `~/Mail/'), but if this variable is non-`nil', it will be used instead. `nnmail-movemail-program' This program is executed to move mail from the user's inbox to her home directory. The default is `movemail'. This can also be a function. In that case, the function will be called with two parameters - the name of the inbox, and the file to be moved to. `nnmail-delete-incoming' If non-`nil', the mail backends will delete the temporary incoming file after splitting mail into the proper groups. This is `t' by default. (No Gnus release since (ding) Gnus 0.10 (or something like that) have lost mail, I think, but that's not the point. (Except certain versions of Red Gnus.)) By not deleting the Incoming* files, one can be sure not to lose mail - if Gnus totally whacks out, one can always recover what was lost. You may delete the `Incoming*' files at will. `nnmail-use-long-file-names' If non-`nil', the mail backends will use long file and directory names. Groups like `mail.misc' will end up in directories (assuming use of `nnml' backend) or files (assuming use of `nnfolder' backend) like `mail.misc'. If it is `nil', the same group will end up in `mail/misc'. `nnmail-delete-file-function' Function called to delete files. It is `delete-file' by default. `nnmail-cache-accepted-message-ids' If non-`nil', put the `Message-ID's of articles imported into the backend (via `Gcc', for instance) into the mail duplication discovery cache. The default is `nil'.  File: gnus, Node: Fancy Mail Splitting, Next: Mail and Procmail, Prev: Mail Backend Variables, Up: Getting Mail Fancy Mail Splitting -------------------- If the rather simple, standard method for specifying how to split mail doesn't allow you to do what you want, you can set `nnmail-split-methods' to `nnmail-split-fancy'. Then you can play with the `nnmail-split-fancy' variable. Let's look at an example value of this variable first: ;; Messages from the mailer daemon are not crossposted to any of ;; the ordinary groups. Warnings are put in a separate group ;; from real errors. (| ("from" mail (| ("subject" "warn.*" "mail.warning") "mail.misc")) ;; Non-error messages are crossposted to all relevant ;; groups, but we don't crosspost between the group for the ;; (ding) list and the group for other (ding) related mail. (& (| (any "ding@ifi\\.uio\\.no" "ding.list") ("subject" "ding" "ding.misc")) ;; Other mailing lists... (any "procmail@informatik\\.rwth-aachen\\.de" "procmail.list") (any "SmartList@informatik\\.rwth-aachen\\.de" "SmartList.list") ;; People... (any "larsi@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) ;; Unmatched mail goes to the catch all group. "misc.misc") This variable has the format of a "split". A split is a (possibly) recursive structure where each split may contain other splits. Here are the five possible split syntaxes: 1. `group': If the split is a string, that will be taken as a group name. Normal regexp match expansion will be done. See below for examples. 2. (FIELD VALUE SPLIT): If the split is a list, the first element of which is a string, then store the message as specified by SPLIT, if header FIELD (a regexp) contains VALUE (also a regexp). 3. (| SPLIT...): If the split is a list, and the first element is `|' (vertical bar), then process each SPLIT until one of them matches. A SPLIT is said to match if it will cause the mail message to be stored in one or more groups. 4. (& SPLIT...): If the split is a list, and the first element is `&', then process all SPLITs in the list. 5. `junk': If the split is the symbol `junk', then don't save this message. Use with extreme caution. 6. (: FUNCTION ARG1 ARG2 ...): If the split is a list, and the first element is `:', then the second element will be called as a function with ARGS given as arguments. The function should return a SPLIT. 7. `nil': If the split is `nil', it is ignored. In these splits, FIELD must match a complete field name. VALUE must match a complete word according to the fundamental mode syntax table. You can use `.*' in the regexps to match partial field names or words. In other words, all VALUE's are wrapped in `\<' and `\>' pairs. FIELD and VALUE can also be lisp symbols, in that case they are expanded as specified by the variable `nnmail-split-abbrev-alist'. This is an alist of cons cells, where the `car' of a cell contains the key, and the `cdr' contains the associated value. `nnmail-split-fancy-syntax-table' is the syntax table in effect when all this splitting is performed. If you want to have Gnus create groups dynamically based on some information in the headers (i.e., do `replace-match'-like substitutions in the group names), you can say things like: (any "debian-\\b\\(\\w+\\)@lists.debian.org" "mail.debian.\\1") If the string contains the element `\&', then the previously matched string will be substituted. Similarly, the elements `\\1' up to `\\9' will be substituted with the text matched by the groupings 1 through 9.  File: gnus, Node: Mail and Procmail, Next: Incorporating Old Mail, Prev: Fancy Mail Splitting, Up: Getting Mail Mail and Procmail ----------------- Many people use `procmail' (or some other mail filter program or external delivery agent--`slocal', `elm', etc) to split incoming mail into groups. If you do that, you should set `nnmail-spool-file' to `procmail' to ensure that the mail backends never ever try to fetch mail by themselves. If you have a combined `procmail'/POP/mailbox setup, you can do something like the following: (setq nnmail-use-procmail t) (setq nnmail-spool-file '("/usr/spool/mail/my-name" "po:my-name")) This also means that you probably don't want to set `nnmail-split-methods' either, which has some, perhaps, unexpected side effects. When a mail backend is queried for what groups it carries, it replies with the contents of that variable, along with any groups it has figured out that it carries by other means. None of the backends, except `nnmh', actually go out to the disk and check what groups actually exist. (It's not trivial to distinguish between what the user thinks is a basis for a newsgroup and what is just a plain old file or directory.) This means that you have to tell Gnus (and the backends) by hand what groups exist. Let's take the `nnmh' backend as an example: The folders are located in `nnmh-directory', say, `~/Mail/'. There are three folders, `foo', `bar' and `mail.baz'. Go to the group buffer and type `G m'. When prompted, answer `foo' for the name and `nnmh' for the method. Repeat twice for the two other groups, `bar' and `mail.baz'. Be sure to include all your mail groups. That's it. You are now set to read your mail. An active file for this method will be created automatically. If you use `nnfolder' or any other backend that store more than a single article in each file, you should never have procmail add mails to the file that Gnus sees. Instead, procmail should put all incoming mail in `nnmail-procmail-directory'. To arrive at the file name to put the incoming mail in, append `nnmail-procmail-suffix' to the group name. The mail backends will read the mail from these files. When Gnus reads a file called `mail.misc.spool', this mail will be put in the `mail.misc', as one would expect. However, if you want Gnus to split the mail the normal way, you could set `nnmail-resplit-incoming' to `t'. If you use `procmail' to split things directly into an `nnmh' directory (which you shouldn't do), you should set `nnmail-keep-last-article' to non-`nil' to prevent Gnus from ever expiring the final article (i.e., the article with the highest article number) in a mail newsgroup. This is quite, quite important. Here's an example setup: The incoming spools are located in `~/incoming/' and have `""' as suffixes (i.e., the incoming spool files have the same names as the equivalent groups). The `nnfolder' backend is to be used as the mail interface, and the `nnfolder' directory is `~/fMail/'. (setq nnfolder-directory "~/fMail/") (setq nnmail-spool-file 'procmail) (setq nnmail-procmail-directory "~/incoming/") (setq gnus-secondary-select-methods '((nnfolder ""))) (setq nnmail-procmail-suffix "")  File: gnus, Node: Incorporating Old Mail, Next: Expiring Mail, Prev: Mail and Procmail, Up: Getting Mail Incorporating Old Mail ---------------------- Most people have lots of old mail stored in various file formats. If you have set up Gnus to read mail using one of the spiffy Gnus mail backends, you'll probably wish to have that old mail incorporated into your mail groups. Doing so can be quite easy. To take an example: You're reading mail using `nnml' (*note Mail Spool::.), and have set `nnmail-split-methods' to a satisfactory value (*note Splitting Mail::.). You have an old Unix mbox file filled with important, but old, mail. You want to move it into your `nnml' groups. Here's how: 1. Go to the group buffer. 2. Type `G f' and give the path to the mbox file when prompted to create an `nndoc' group from the mbox file (*note Foreign Groups::.). 3. Type `SPACE' to enter the newly created group. 4. Type `M P b' to process-mark all articles in this group's buffer (*note Setting Process Marks::.). 5. Type `B r' to respool all the process-marked articles, and answer `nnml' when prompted (*note Mail Group Commands::.). All the mail messages in the mbox file will now also be spread out over all your `nnml' groups. Try entering them and check whether things have gone without a glitch. If things look ok, you may consider deleting the mbox file, but I wouldn't do that unless I was absolutely sure that all the mail has ended up where it should be. Respooling is also a handy thing to do if you're switching from one mail backend to another. Just respool all the mail in the old mail groups using the new mail backend.  File: gnus, Node: Expiring Mail, Next: Washing Mail, Prev: Incorporating Old Mail, Up: Getting Mail Expiring Mail ------------- Traditional mail readers have a tendency to remove mail articles when you mark them as read, in some way. Gnus takes a fundamentally different approach to mail reading. Gnus basically considers mail just to be news that has been received in a rather peculiar manner. It does not think that it has the power to actually change the mail, or delete any mail messages. If you enter a mail group, and mark articles as "read", or kill them in some other fashion, the mail articles will still exist on the system. I repeat: Gnus will not delete your old, read mail. Unless you ask it to, of course. To make Gnus get rid of your unwanted mail, you have to mark the articles as "expirable". This does not mean that the articles will disappear right away, however. In general, a mail article will be deleted from your system if, 1) it is marked as expirable, AND 2) it is more than one week old. If you do not mark an article as expirable, it will remain on your system until hell freezes over. This bears repeating one more time, with some spurious capitalizations: IF you do NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. You do not have to mark articles as expirable by hand. Groups that match the regular expression `gnus-auto-expirable-newsgroups' will have all articles that you read marked as expirable automatically. All articles marked as expirable have an `E' in the first column in the summary buffer. By default, if you have auto expiry switched on, Gnus will mark all the articles you read as expirable, no matter if they were read or unread before. To avoid having articles marked as read marked as expirable automatically, you can put something like the following in your `.gnus' file: (remove-hook 'gnus-mark-article-hook 'gnus-summary-mark-read-and-unread-as-read) (add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) Note that making a group auto-expirable doesn't mean that all read articles are expired--only the articles marked as expirable will be expired. Also note that using the `d' command won't make groups expirable--only semi-automatic marking of articles as read will mark the articles as expirable in auto-expirable groups. Let's say you subscribe to a couple of mailing lists, and you want the articles you have read to disappear after a while: (setq gnus-auto-expirable-newsgroups "mail.nonsense-list\\|mail.nice-list") Another way to have auto-expiry happen is to have the element `auto-expire' in the group parameters of the group. If you use adaptive scoring (*note Adaptive Scoring::.) and auto-expiring, you'll have problems. Auto-expiring and adaptive scoring don't really mix very well. The `nnmail-expiry-wait' variable supplies the default time an expirable article has to live. Gnus starts counting days from when the message *arrived*, not from when it was sent. The default is seven days. Gnus also supplies a function that lets you fine-tune how long articles are to live, based on what group they are in. Let's say you want to have one month expiry period in the `mail.private' group, a one day expiry period in the `mail.junk' group, and a six day expiry period everywhere else: (setq nnmail-expiry-wait-function (lambda (group) (cond ((string= group "mail.private") 31) ((string= group "mail.junk") 1) ((string= group "important") 'never) (t 6)))) The group names this function is fed are "unadorned" group names--no `nnml:' prefixes and the like. The `nnmail-expiry-wait' variable and `nnmail-expiry-wait-function' function can either be a number (not necessarily an integer) or one of the symbols `immediate' or `never'. You can also use the `expiry-wait' group parameter to selectively change the expiry period (*note Group Parameters::.). If `nnmail-keep-last-article' is non-`nil', Gnus will never expire the final article in a mail newsgroup. This is to make life easier for procmail users. By the way: That line up there, about Gnus never expiring non-expirable articles, is a lie. If you put `total-expire' in the group parameters, articles will not be marked as expirable, but all read articles will be put through the expiry process. Use with extreme caution. Even more dangerous is the `gnus-total-expirable-newsgroups' variable. All groups that match this regexp will have all read articles put through the expiry process, which means that *all* old mail articles in the groups in question will be deleted after a while. Use with extreme caution, and don't come crying to me when you discover that the regexp you used matched the wrong group and all your important mail has disappeared. Be a *man*! Or a *woman*! Whatever you feel more comfortable with! So there! Most people make most of their mail groups total-expirable, though.