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