This is ../info/gnus, produced by makeinfo version 4.0 from 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<SPACE>'
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.