6. 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 (see section 6.1 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.

6.1 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.

gnus-server-mode-hook is run when creating the server buffer.

6.1.1 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.

`a'

Whether this server is agentized.

The mode line can also be customized by using the gnus-server-mode-line-format variable (see section 8.4.2 Mode Line Formatting). The following specs are understood:

`S'

Server name.

`M'

Server method.

Also see section 8.4 Formatting Variables.

6.1.2 Server Commands

v

The key v is reserved for users. You can bind it key to some function or better use it as a prefix key.

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 back end that has gotten out of sync.

6.1.3 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-open-connection-function nntp-open-via-rlogin-and-telnet)
      (nntp-via-address "the.firewall.machine")
      (nntp-address "the.real.nntp.host")
      (nntp-end-of-line "\n"))

If you want to use the wonderful ssh program to provide a compressed connection over the modem line, you could add the following configuration to the example above:

      (nntp-via-rlogin-command "ssh")

See also nntp-via-rlogin-command-switches.

If you're behind a firewall, but have direct access to the outside world through a wrapper command like "runsocks", you could open a socksified telnet connection to the news server as follows:

(nntp "outside"
      (nntp-pre-command "runsocks")
      (nntp-open-connection-function nntp-open-via-telnet)
      (nntp-address "the.news.server")
      (nntp-end-of-line "\n"))

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.

6.1.4 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 nnml to read the cache. You could also use nnspool or nnmh, though.

Type a nnml RET cache RET.

You should now have a brand new nnml 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:

(nnml "cache")

Change that to:

(nnml "cache"
         (nnml-directory "~/News/cache/")
         (nnml-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.

6.1.5 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"))

Server variables are often called server parameters.

6.1.6 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.

6.1.7 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 (see section 6.1 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).

L

Set server status to offline (gnus-server-offline-server).

6.2 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.

6.2.1 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 (see section 2.9 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-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-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.

nntp-open-connection-function

It is possible to customize how the connection to the nntp server will be opened. If you specify an nntp-open-connection-function parameter, Gnus will use that function to establish the connection. Six pre-made functions are supplied. These functions can be grouped in two categories: direct connection functions (four pre-made), and indirect ones (two pre-made).

nntp-prepare-post-hook

A hook run just before posting an article. If there is no Message-ID header in the article and the news server provides the recommended ID, it will be added to the article before running this hook. It is useful to make Cancel-Lock headers even if you inhibit Gnus to add a Message-ID header, you could say:

(add-hook 'nntp-prepare-post-hook 'canlock-insert-header)

Note that not all servers support the recommended ID. This works for INN versions 2.3.0 and later, for instance.

6.2.1.1 Direct Functions

These functions are called direct because they open a direct connection between your machine and the NNTP server. The behavior of these functions is also affected by commonly understood variables (see section 6.2.1.3 Common Variables).

nntp-open-network-stream

This is the default, and simply connects to some port or other on the remote system.

nntp-open-tls-stream

Opens a connection to a server over a secure channel. To use this you must have GNUTLS installed. You then define a server as follows:

;; "nntps" is port 563 and is predefined in our `/etc/services' ;; however, `gnutls-cli -p' doesn't like named ports. ;; (nntp "snews.bar.com" (nntp-open-connection-function nntp-open-tls-stream) (nntp-port-number ) (nntp-address "snews.bar.com"))

nntp-open-ssl-stream

Opens a connection to a server over a secure channel. To use this you must have OpenSSL or SSLeay installed. You then define a server as follows:

;; "snews" is port 563 and is predefined in our `/etc/services' ;; however, `openssl s_client -port' doesn't like named ports. ;; (nntp "snews.bar.com" (nntp-open-connection-function nntp-open-ssl-stream) (nntp-port-number 563) (nntp-address "snews.bar.com"))

nntp-open-telnet-stream

Opens a connection to an NNTP server by simply `telnet''ing it. You might wonder why this function exists, since we have the default nntp-open-network-stream which would do the job. (One of) the reason(s) is that if you are behind a firewall but have direct connections to the outside world thanks to a command wrapper like runsocks, you can use it like this:

(nntp "socksified" (nntp-pre-command "runsocks") (nntp-open-connection-function nntp-open-telnet-stream) (nntp-address "the.news.server"))

With the default method, you would need to wrap your whole Emacs session, which is not a good idea.

6.2.1.2 Indirect Functions

These functions are called indirect because they connect to an intermediate host before actually connecting to the NNTP server. All of these functions and related variables are also said to belong to the "via" family of connection: they're all prefixed with "via" to make things cleaner. The behavior of these functions is also affected by commonly understood variables (see section 6.2.1.3 Common Variables).

nntp-open-via-rlogin-and-telnet

Does an `rlogin' on a remote system, and then does a `telnet' to the real NNTP server from there. This is useful for instance if you need to connect to a firewall machine first.

nntp-open-via-rlogin-and-telnet-specific variables:

nntp-via-rlogin-command

Command used to log in on the intermediate host. The default is `rsh', but `ssh' is a popular alternative.

nntp-via-rlogin-command-switches

List of strings to be used as the switches to nntp-via-rlogin-command. The default is nil. If you use `ssh' for nntp-via-rlogin-command, you may set this to `("-C")' in order to compress all data connections, otherwise set this to `("-t" "-e" "none")' or `("-C" "-t" "-e" "none")' if the telnet command requires a pseudo-tty allocation on an intermediate host.

nntp-open-via-telnet-and-telnet

Does essentially the same, but uses `telnet' instead of `rlogin' to connect to the intermediate host.

nntp-open-via-telnet-and-telnet-specific variables:

nntp-via-telnet-command

Command used to telnet the intermediate host. The default is `telnet'.

nntp-via-telnet-switches

List of strings to be used as the switches to the nntp-via-telnet-command command. The default is `("-8")'.

nntp-via-user-password

Password to use when logging in on the intermediate host.

nntp-via-envuser

If non-nil, the intermediate 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-via-shell-prompt

Regexp matching the shell prompt on the intermediate host. The default is `bash\\|\$ *\r?$\\|> *\r?'.

Here are some additional variables that are understood by all the above functions:

nntp-via-user-name

User name to use when connecting to the intermediate host.

nntp-via-address

Address of the intermediate host to connect to.

6.2.1.3 Common Variables

The following variables affect the behavior of all, or several of the pre-made connection functions. When not specified, all functions are affected (the values of the following variables will be used as the default if each virtual nntp server doesn't specify those server variables individually).

nntp-pre-command

A command wrapper to use when connecting through a non native connection function (all except nntp-open-network-stream, nntp-open-tls-stream, and nntp-open-ssl-stream). This is where you would put a `SOCKS' wrapper for instance.

nntp-address

The address of the NNTP server.

nntp-port-number

Port number to connect to the NNTP server. The default is `nntp'. If you use NNTP over TLS/SSL, you may want to use integer ports rather than named ports (i.e, use `563' instead of `snews' or `nntps'), because external TLS/SSL tools may not work with named ports.

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 a non native connection function.

nntp-telnet-command

Command to use when connecting to the NNTP server through `telnet'. This is not for an intermediate host. This is just for the real NNTP server. The default is `telnet'.

nntp-telnet-switches

A list of switches to pass to nntp-telnet-command. The default is `("-8")'.

6.2.2 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 (see section 1.1 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 name of the active file.

nnspool-newsgroups-file

The name of the group descriptions file.

nnspool-history-file

The name of the news history file.

nnspool-active-times-file

The name of 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.

6.3 Getting Mail

Reading mail with a newsreader--isn't that just plain WeIrD? But of course.

6.3.1 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 6.3.9 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.)

6.3.2 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.el' file:

(setq gnus-secondary-select-methods '((nnml "")))

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 see section 6.3.13 Choosing a Mail Back End and see section 6.3.9 Expiring Mail.

6.3.3 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")

In that case, nnmail-split-lowercase-expanded controls whether the inserted text should be made lowercase. See section 6.3.6 Fancy Mail Splitting.

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 no rule matched, the mail will end up in the `bogus' group. When new groups are created by splitting mail, you may want to run gnus-group-find-new-groups to see the new groups. This also applies to the `bogus' group.

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<SPACE> 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 (see section 3.25 Mail Group Commands).

Header lines longer than the value of nnmail-split-header-length-limit are excluded from the split function.

By default the splitting codes MIME decodes headers so you can match on non-ASCII strings. The nnmail-mail-splitting-charset variable specifies the default charset for decoding. The behavior can be turned off completely by binding nnmail-mail-splitting-decodes to nil, which is useful if you want to match articles based on the raw header data.

By default, splitting is performed on all incoming messages. If you specify a directory entry for the variable mail-sources (see section 6.3.4.1 Mail Source Specifiers), however, then splitting does not happen by default. You can set the variable nnmail-resplit-incoming to a non-nil value to make splitting happen even in this case. (This variable has no effect on other kinds of entries.)

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.

6.3.4 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.

6.3.4.1 Mail Source Specifiers

You tell Gnus how to fetch mail by setting mail-sources (see section 6.3.4.4 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 file name. Defaults to the value of the MAIL environment variable or the value of rmail-spool-directory (usually something like `/usr/mail/spool/user-name').

:prescript

:postscript

Script run before/after fetching mail.

An example file mail source:

(file :path "/usr/spool/mail/user-name")

Or using the default file name:

(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. That is, there is a one-to-one correspondence between files in that directory and groups, so that mail from the file `foo.bar.spool' will be put in the group foo.bar. (You can change the suffix to be used instead of .spool.) Setting nnmail-scan-directory-mail-source-once to non-nil forces Gnus to scan the mail source only once. This is particularly useful if you want to scan mail groups at a specified level.

There is also the variable nnmail-resplit-incoming, if you set that to a non-nil value, then the normal splitting process is applied to all the files from the directory, 6.3.3 Splitting Mail.

Keywords:

:path

The name 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 (eg, `:port 1234') or a string (eg, `: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. If the pop3-leave-mail-on-server is non-nil the mail is to be left on the POP server after fetching when using pop3-movemail. Note that POP servers maintain no state information between sessions, so what the client believes is there and what is actually there may not match up. If they do not, then the whole thing can fall apart and leave you with a corrupt mailbox.

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 name 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. See section 6.5 IMAP, for more information.

Note that for the Kerberos, GSSAPI, TLS/SSL and STARTTLS support you may need external programs and libraries, See section 6.5 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 TLS/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 `gssapi', `kerberos4', `starttls', `tls', `ssl', `shell' 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 `gssapi', `kerberos4', `digest-md5', `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 `1:*'. Then all articles in the mailbox is fetched, no matter what. For a complete list of predicates, see RFC 2060 section 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 section 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 http://www.hotmail.com/, http://webmail.netscape.com/, http://www.netaddress.com/, http://mail.yahoo.com/.

NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is required for url "4.0pre.46".

WARNING: Mails may be 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.

6.3.4.2 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.

6.3.4.3 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. If t, delete the files immediately, if nil, never delete any files. If a positive number, delete files older than number of days (This will only happen, when receiving new mail). You may also set mail-source-delete-incoming to nil and call mail-source-delete-old-incoming from a hook or interactively.

mail-source-delete-old-incoming-confirm

If non-nil, ask for for confirmation before deleting old incoming files. This variable only applies when mail-source-delete-incoming is a positive number.

mail-source-ignore-errors

If non-nil, ignore errors when reading mail from a mail source.

mail-source-directory

Directory where incoming mail source 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 variable mail-source-delete-incoming is nil or a number.

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 or a number.

mail-source-default-file-modes

All new mail files will get this file mode. The default is 384.

mail-source-movemail-program

If non-nil, name of program for fetching new mail. If nil, movemail in exec-directory.

6.3.4.4 Fetching Mail

The way to actually tell Gnus where to get new mail from is to set mail-sources to a list of mail source specifiers (see section 6.3.4.1 Mail Source Specifiers).

If this variable (and the obsolescent nnmail-spool-file) is nil, the mail back ends will never attempt to fetch mail by themselves.

If you want to fetch mail both from your local spool as well as a POP mail server, you'd say something like:

(setq mail-sources
      '((file)
        (pop :server "pop3.mail.server"
             :password "secret")))

Or, if you don't want to use any of the keyword defaults:

(setq mail-sources
      '((file :path "/var/spool/mail/user-name")
        (pop :server "pop3.mail.server"
             :user "user-name"
             :port "pop3"
             :password "secret")))

When you use a mail back end, 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 back end--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.

6.3.5 Mail Back End Variables

These variables are (for the most part) pertinent to all the various mail back ends.

nnmail-read-incoming-hook

The mail back ends all call this hook after reading new mail. You can use this hook to notify any mail watch programs, if you want to.

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-encoded-words 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 'nnmail-pre-get-new-mail-hook (lambda () (set-default-file-modes 511))) (add-hook 'nnmail-post-get-new-mail-hook (lambda () (set-default-file-modes 551)))

nnmail-use-long-file-names

If non-nil, the mail back ends will use long file and directory names. Groups like `mail.misc' will end up in directories (assuming use of nnml back end) or files (assuming use of nnfolder back end) 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-IDs of articles imported into the back end (via Gcc, for instance) into the mail duplication discovery cache. The default is nil.

nnmail-cache-ignore-groups

This can be a regular expression or a list of regular expressions. Group names that match any of the regular expressions will never be recorded in the Message-ID cache.

This can be useful, for example, when using Fancy Splitting (see section 6.3.6 Fancy Mail Splitting) together with the function nnmail-split-fancy-with-parent.

6.3.6 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")
      ;; Both lists below have the same suffix, so prevent
      ;; cross-posting to mkpkg.list of messages posted only to
      ;; the bugs- list, but allow cross-posting when the
      ;; message was really cross-posted.
      (any "bugs-mypackage@somewhere" "mypkg.bugs")
      (any "mypackage@somewhere" - "bugs-mypackage" "mypkg.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 possible split syntaxes:

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.

(field value [- restrict [...] ] split [invert-partial])

The split can be a list containing at least three elements. If the first element field (a regexp matching a header) contains value (also a regexp) then store the message as specified by split.

If restrict (yet another regexp) matches some string after field and before the end of the matched value, the split is ignored. If none of the restrict clauses match, split is processed.

The last element invert-partial is optional. If it is non-nil, the match-partial-words behavior controlled by the variable nnmail-split-fancy-match-partial-words (see below) is be inverted. (New in Gnus 5.10.7)

(| 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.

(& split ...)

If the split is a list, and the first element is &, then process all splits in the list.

junk

If the split is the symbol junk, then don't save (i.e., delete) this message. Use with extreme caution.

(: 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.

For instance, the following function could be used to split based on the body of the messages:

(defun split-on-body () (save-excursion (save-restriction (widen) (goto-char (point-min)) (when (re-search-forward "Some.*string" nil t) "string.group"))))

The buffer is narrowed to the message in question when function is run. That's why (widen) needs to be called after save-excursion and save-restriction in the example above. Also note that with the nnimap backend, message bodies will not be downloaded by default. You need to set nnimap-split-download-body to t to do that (see section 6.5.1 Splitting in IMAP).

(! func split)

If the split is a list, and the first element is !, then split will be processed, and func will be called as a function with the result of split as argument. func should return a split.

nil

If the split is nil, it is ignored.

In these splits, field must match a complete field name.

Normally, value in these splits must match a complete word according to the fundamental mode syntax table. In other words, all value's will be implicitly surrounded by \<...\> markers, which are word delimiters. Therefore, if you use the following split, for example,

(any "joe" "joemail")

messages sent from `joedavis@foo.org' will normally not be filed in `joemail'. If you want to alter this behavior, you can use any of the following three ways:

1. You can set the nnmail-split-fancy-match-partial-words variable to non-nil in order to ignore word boundaries and instead the match becomes more like a grep. This variable controls whether partial words are matched during fancy splitting. The default value is nil.

   Note that it influences all value's in your split rules.

2. value beginning with .* ignores word boundaries in front of a word. Similarly, if value ends with .*, word boundaries in the rear of a word will be ignored. For example, the value "@example\\.com" does not match `foo@example.com' but ".*@example\\.com" does.

3. You can set the invert-partial flag in your split rules of the `(field value ...)' types, aforementioned in this section. If the flag is set, word boundaries on both sides of a word are ignored even if nnmail-split-fancy-match-partial-words is nil. Contrarily, if the flag is set, word boundaries are not ignored even if nnmail-split-fancy-match-partial-words is non-nil. (New in Gnus 5.10.7)

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. Predefined entries in nnmail-split-abbrev-alist include:

from

Matches the `From', `Sender' and `Resent-From' fields.

to

Matches the `To', `Cc', `Apparently-To', `Resent-To' and `Resent-Cc' fields.

any

Is the union of the from and to entries.

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")

In this example, messages sent to `debian-foo@lists.debian.org' will be filed in `mail.debian.foo'.

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.

Where nnmail-split-lowercase-expanded controls whether the lowercase of the matched string should be used for the substitution. Setting it as non-nil is useful to avoid the creation of multiple groups when users send to an address using different case (i.e. mailing-list@domain vs Mailing-List@Domain). The default value is t.

nnmail-split-fancy-with-parent is a function which allows you to split followups into the same groups their parents are in. Sometimes you can't make splitting rules for all your mail. For example, your boss might send you personal mail regarding different projects you are working on, and as you can't tell your boss to put a distinguishing string into the subject line, you have to resort to manually moving the messages into the right group. With this function, you only have to do it once per thread.

To use this feature, you have to set nnmail-treat-duplicates and nnmail-cache-accepted-message-ids to a non-nil value. And then you can include nnmail-split-fancy-with-parent using the colon feature, like so:

(setq nnmail-treat-duplicates 'warn     ; or delete
      nnmail-cache-accepted-message-ids t
      nnmail-split-fancy
      '(| (: nnmail-split-fancy-with-parent)
          ;; other splits go here
        ))

This feature works as follows: when nnmail-treat-duplicates is non-nil, Gnus records the message id of every message it sees in the file specified by the variable nnmail-message-id-cache-file, together with the group it is in (the group is omitted for non-mail messages). When mail splitting is invoked, the function nnmail-split-fancy-with-parent then looks at the References (and In-Reply-To) header of each message to split and searches the file specified by nnmail-message-id-cache-file for the message ids. When it has found a parent, it returns the corresponding group name unless the group name matches the regexp nnmail-split-fancy-with-parent-ignore-groups. It is recommended that you set nnmail-message-id-cache-length to a somewhat higher number than the default so that the message ids are still in the cache. (A value of 5000 appears to create a file some 300 kBytes in size.) When nnmail-cache-accepted-message-ids is non-nil, Gnus also records the message ids of moved articles, so that the followup messages goes into the new group.

Also see the variable nnmail-cache-ignore-groups if you don't want certain groups to be recorded in the cache. For example, if all outgoing messages are written to an "outgoing" group, you could set nnmail-cache-ignore-groups to match that group name. Otherwise, answers to all your messages would end up in the "outgoing" group.

6.3.7 Group Mail Splitting

If you subscribe to dozens of mailing lists but you don't want to maintain mail splitting rules manually, group mail splitting is for you. You just have to set to-list and/or to-address in group parameters or group customization and set nnmail-split-methods to gnus-group-split. This splitting function will scan all groups for those parameters and split mail accordingly, i.e., messages posted from or to the addresses specified in the parameters to-list or to-address of a mail group will be stored in that group.

Sometimes, mailing lists have multiple addresses, and you may want mail splitting to recognize them all: just set the extra-aliases group parameter to the list of additional addresses and it's done. If you'd rather use a regular expression, set split-regexp.

All these parameters in a group will be used to create an nnmail-split-fancy split, in which the field is `any', the value is a single regular expression that matches to-list, to-address, all of extra-aliases and all matches of split-regexp, and the split is the name of the group. restricts are also supported: just set the split-exclude parameter to a list of regular expressions.

If you can't get the right split to be generated using all these parameters, or you just need something fancier, you can set the parameter split-spec to an nnmail-split-fancy split. In this case, all other aforementioned parameters will be ignored by gnus-group-split. In particular, split-spec may be set to nil, in which case the group will be ignored by gnus-group-split.

gnus-group-split will do cross-posting on all groups that match, by defining a single & fancy split containing one split for each group. If a message doesn't match any split, it will be stored in the group named in gnus-group-split-default-catch-all-group, unless some group has split-spec set to catch-all, in which case that group is used as the catch-all group. Even though this variable is often used just to name a group, it may also be set to an arbitrarily complex fancy split (after all, a group name is a fancy split), and this may be useful to split mail that doesn't go to any mailing list to personal mail folders. Note that this fancy split is added as the last element of a | split list that also contains a & split with the rules extracted from group parameters.

It's time for an example. Assume the following group parameters have been defined:

nnml:mail.bar:
((to-address . "bar@femail.com")
 (split-regexp . ".*@femail\\.com"))
nnml:mail.foo:
((to-list . "foo@nowhere.gov")
 (extra-aliases "foo@localhost" "foo-redist@home")
 (split-exclude "bugs-foo" "rambling-foo")
 (admin-address . "foo-request@nowhere.gov"))
nnml:mail.others:
((split-spec . catch-all))

Setting nnmail-split-methods to gnus-group-split will behave as if nnmail-split-fancy had been selected and variable nnmail-split-fancy had been set as follows:

(| (& (any "\\(bar@femail\\.com\\|.*@femail\\.com\\)" "mail.bar")
      (any "\\(foo@nowhere\\.gov\\|foo@localhost\\|foo-redist@home\\)"
           - "bugs-foo" - "rambling-foo" "mail.foo"))
   "mail.others")

If you'd rather not use group splitting for all your mail groups, you may use it for only some of them, by using nnmail-split-fancy splits like this:

(: gnus-group-split-fancy groups no-crosspost catch-all)

groups may be a regular expression or a list of group names whose parameters will be scanned to generate the output split. no-crosspost can be used to disable cross-posting; in this case, a single | split will be output. catch-all is the fall back fancy split, used like gnus-group-split-default-catch-all-group. If catch-all is nil, or if split-regexp matches the empty string in any selected group, no catch-all split will be issued. Otherwise, if some group has split-spec set to catch-all, this group will override the value of the catch-all argument.

Unfortunately, scanning all groups and their parameters can be quite slow, especially considering that it has to be done for every message. But don't despair! The function gnus-group-split-setup can be used to enable gnus-group-split in a much more efficient way. It sets nnmail-split-methods to nnmail-split-fancy and sets nnmail-split-fancy to the split produced by gnus-group-split-fancy. Thus, the group parameters are only scanned once, no matter how many messages are split.

However, if you change group parameters, you'd have to update nnmail-split-fancy manually. You can do it by running gnus-group-split-update. If you'd rather have it updated automatically, just tell gnus-group-split-setup to do it for you. For example, add to your `~/.gnus.el':

(gnus-group-split-setup auto-update catch-all)

If auto-update is non-nil, gnus-group-split-update will be added to nnmail-pre-get-new-mail-hook, so you won't ever have to worry about updating nnmail-split-fancy again. If you don't omit catch-all (it's optional, equivalent to nil), gnus-group-split-default-catch-all-group will be set to its value.

Because you may want to change nnmail-split-fancy after it is set by gnus-group-split-update, this function will run gnus-group-split-updated-hook just before finishing.

6.3.8 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 back ends, 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 (see section 6.3.13.3 Mail Spool), and have set nnmail-split-methods to a satisfactory value (see section 6.3.3 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 file name to the mbox file when prompted to create an nndoc group from the mbox file (see section 2.9 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 (see section 3.7.6 Setting Process Marks).

5. Type B r to respool all the process-marked articles, and answer `nnml' when prompted (see section 3.25 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 back end to another. Just respool all the mail in the old mail groups using the new mail back end.