Implement mailto: urls in gnus-html and shr.

[gnus] / texi / gnus-faq.texi

@c \input texinfo @c -*-texinfo-*-
@c Uncomment 1st line before texing this file alone.
@c %**start of header
@c Copyright (C) 1995, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
@c   2009, 2010 Free Software Foundation, Inc.
@c
@setfilename gnus-faq.info
@settitle Frequently Asked Questions
@c %**end of header
@c

@node Frequently Asked Questions
@section Frequently Asked Questions

@menu
* FAQ - Changes::                           
* FAQ - Introduction::                       About Gnus and this FAQ.
* FAQ 1 - Installation FAQ::                 Installation of Gnus.
* FAQ 2 - Startup / Group buffer::           Start up questions and the
                                             first buffer Gnus shows you.
* FAQ 3 - Getting Messages::                 Making Gnus read your mail
                                             and news.
* FAQ 4 - Reading messages::                 How to efficiently read
                                             messages.
* FAQ 5 - Composing messages::               Composing mails or Usenet
                                             postings.
* FAQ 6 - Old messages::                     Importing, archiving,
                                             searching and deleting messages.
* FAQ 7 - Gnus in a dial-up environment::    Reading mail and news while
                                             offline.
* FAQ 8 - Getting help::                     When this FAQ isn't enough.
* FAQ 9 - Tuning Gnus::                      How to make Gnus faster.
* FAQ - Glossary::                           Terms used in the FAQ
                                             explained.
@end menu

@subheading Abstract

This is the new Gnus Frequently Asked Questions list.

Please submit features and suggestions to the 
@email{ding@@gnus.org, ding list}.

@node FAQ - Changes
@subheading Changes



@itemize @bullet

@item
2008-06-15: Adjust for message-fill-column.  Add x-face-file.
Clarify difference between ding and gnu.emacs.gnus.  Remove
reference to discontinued service.

@item
2006-04-15: Added tip on how to delete sent buffer on exit.
@end itemize

@node FAQ - Introduction
@subheading Introduction

This is the Gnus Frequently Asked Questions list.

Gnus is a Usenet Newsreader and Electronic Mail User Agent implemented
as a part of Emacs. It's been around in some form for almost a decade
now, and has been distributed as a standard part of Emacs for much of
that time. Gnus 5 is the latest (and greatest) incarnation. The
original version was called GNUS, and was written by Masanobu UMEDA.
When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and
decided to rewrite Gnus.

Its biggest strength is the fact that it is extremely
customizable. It is somewhat intimidating at first glance, but
most of the complexity can be ignored until you're ready to take
advantage of it. If you receive a reasonable volume of e-mail
(you're on various mailing lists), or you would like to read
high-volume mailing lists but cannot keep up with them, or read
high volume newsgroups or are just bored, then Gnus is what you
want.

This FAQ was maintained by Justin Sheehy until March 2002. He
would like to thank Steve Baur and Per Abrahamsen for doing a wonderful
job with this FAQ before him. We would like to do the same - thanks,
Justin!

This version is much nicer than the unofficial hypertext
versions that are archived at Utrecht, Oxford, Smart Pages, Ohio
State, and other FAQ archives. See the resources question below
if you want information on obtaining it in another format.

The information contained here was compiled with the assistance
of the Gnus development mailing list, and any errors or
misprints are the Gnus team's fault, sorry.

@node FAQ 1 - Installation FAQ
@subsection Installation FAQ

@menu
* FAQ 1-1::    What is the latest version of Gnus?
* FAQ 1-2::    What's new in 5.10?
* FAQ 1-3::    Where and how to get Gnus?
* FAQ 1-4::    What to do with the tarball now?
* FAQ 1-5::    I sometimes read references to No Gnus and Oort Gnus,
               what are those?
* FAQ 1-6::    Which version of Emacs do I need?
* FAQ 1-7::    How do I run Gnus on both Emacs and XEmacs?
@end menu

@node FAQ 1-1
@subsubheading Question 1.1

What is the latest version of Gnus?

@subsubheading Answer

Jingle please: Gnus 5.10 is released, get it while it's
hot! As well as the step in version number is rather
small, Gnus 5.10 has tons of new features which you
shouldn't miss. The current release (5.13) should be at
least as stable as the latest release of the 5.8 series.

@node FAQ 1-2
@subsubheading Question 1.2

What's new in 5.10?

@subsubheading Answer

First of all, you should have a look into the file
GNUS-NEWS in the toplevel directory of the Gnus tarball,
there the most important changes are listed. Here's a
short list of the changes I find especially
important/interesting:

@itemize @bullet

@item
Major rewrite of the Gnus agent, Gnus agent is now
active by default.

@item
Many new article washing functions for dealing with
ugly formatted articles.

@item
Anti Spam features.

@item
Message-utils now included in Gnus.

@item
New format specifiers for summary lines, e.g. %B for
a complex trn-style thread tree.
@end itemize

@node FAQ 1-3
@subsubheading Question 1.3

Where and how to get Gnus?

@subsubheading Answer

Gnus is released independent from releases of Emacs and XEmacs.
Therefore, the version bundled with Emacs or the version in XEmacs'
package system might not be up to date (e.g. Gnus 5.9 bundled with Emacs
21 is outdated).
You can get the latest released version of Gnus from
@uref{http://www.gnus.org/dist/gnus.tar.gz}
or via anonymous FTP from 
@uref{ftp://ftp.gnus.org/pub/gnus/gnus.tar.gz}.

@node FAQ 1-4
@subsubheading Question 1.4

What to do with the tarball now?

@subsubheading Answer

Untar it via @samp{tar xvzf gnus.tar.gz} and do the common 
@samp{./configure; make; make install} circle.
(under MS-Windows either get the Cygwin environment from
@uref{http://www.cygwin.com}
which allows you to do what's described above or unpack the
tarball with some packer (e.g. Winace from
@uref{http://www.winace.com})
and use the batch-file make.bat included in the tarball to install
Gnus.) If you don't want to (or aren't allowed to) install Gnus
system-wide, you can install it in your home directory and add the
following lines to your ~/.xemacs/init.el or ~/.emacs:

@example
(add-to-list 'load-path "/path/to/gnus/lisp")
(if (featurep 'xemacs)
    (add-to-list 'Info-directory-list "/path/to/gnus/texi/")
  (add-to-list 'Info-default-directory-list "/path/to/gnus/texi/"))
@end example
@noindent

Make sure that you don't have any Gnus related stuff
before this line, on MS Windows use something like
"C:/path/to/lisp" (yes, "/").

@node FAQ 1-5
@subsubheading Question 1.5

I sometimes read references to No Gnus and Oort Gnus,
what are those?

@subsubheading Answer

Oort Gnus was the name of the development version of
Gnus, which became Gnus 5.10 in autumn 2003. No Gnus is
the name of the current development version which will
once become Gnus 5.12 or Gnus 6. (If you're wondering why
not 5.11, the odd version numbers are normally used for
the Gnus versions bundled with Emacs)

@node FAQ 1-6
@subsubheading Question 1.6

Which version of Emacs do I need?

@subsubheading Answer

Gnus 5.10 requires an Emacs version that is greater than or equal
to Emacs 20.7 or XEmacs 21.1.
The development versions of Gnus (aka No Gnus) requires Emacs 21
or XEmacs 21.4.

@node FAQ 1-7
@subsubheading Question 1.7

How do I run Gnus on both Emacs and XEmacs?

@subsubheading Answer

You can't use the same copy of Gnus in both as the Lisp
files are byte-compiled to a format which is different
depending on which Emacs did the compilation. Get one copy
of Gnus for Emacs and one for XEmacs.

@node FAQ 2 - Startup / Group buffer
@subsection Startup / Group buffer

@menu
* FAQ 2-1::    Every time I start Gnus I get a message "Gnus auto-save
               file exists. Do you want to read it?", what does this mean and
               how to prevent it?
* FAQ 2-2::    Gnus doesn't remember which groups I'm subscribed to,
               what's this?
* FAQ 2-3::    How to change the format of the lines in Group buffer?
* FAQ 2-4::    My group buffer becomes a bit crowded, is there a way to
               sort my groups into categories so I can easier browse through
               them?
* FAQ 2-5::    How to manually sort the groups in Group buffer? How to
               sort the groups in a topic?
@end menu

@node FAQ 2-1
@subsubheading Question 2.1

Every time I start Gnus I get a message "Gnus auto-save
file exists. Do you want to read it?", what does this mean
and how to prevent it?

@subsubheading Answer

This message means that the last time you used Gnus, it
wasn't properly exited and therefor couldn't write its
informations to disk (e.g. which messages you read), you
are now asked if you want to restore those informations
from the auto-save file.

To prevent this message make sure you exit Gnus
via @samp{q} in group buffer instead of
just killing Emacs.

@node FAQ 2-2
@subsubheading Question 2.2

Gnus doesn't remember which groups I'm subscribed to,
what's this?

@subsubheading Answer

You get the message described in the q/a pair above while
starting Gnus, right? It's an other symptom for the same
problem, so read the answer above.

@node FAQ 2-3
@subsubheading Question 2.3

How to change the format of the lines in Group buffer?

@subsubheading Answer

You've got to tweak the value of the variable
gnus-group-line-format. See the manual node "Group Line
Specification" for information on how to do this. An
example for this (guess from whose .gnus :-)):

@example
(setq gnus-group-line-format "%P%M%S[%5t]%5y : %(%g%)\n")
@end example
@noindent

@node FAQ 2-4
@subsubheading Question 2.4

My group buffer becomes a bit crowded, is there a way to
sort my groups into categories so I can easier browse
through them?

@subsubheading Answer

Gnus offers the topic mode, it allows you to sort your
groups in, well, topics, e.g. all groups dealing with
Linux under the topic linux, all dealing with music under
the topic music and all dealing with scottish music under
the topic scottish which is a subtopic of music.

To enter topic mode, just hit t while in Group buffer. Now
you can use @samp{T n} to create a topic
at point and @samp{T m} to move a group to
a specific topic. For more commands see the manual or the
menu. You might want to include the %P specifier at the
beginning of your gnus-group-line-format variable to have
the groups nicely indented.

@node FAQ 2-5
@subsubheading Question 2.5

How to manually sort the groups in Group buffer? How to
sort the groups in a topic?

@subsubheading Answer

Move point over the group you want to move and
hit @samp{C-k}, now move point to the
place where you want the group to be and
hit @samp{C-y}.

@node FAQ 3 - Getting Messages
@subsection Getting Messages

@menu
* FAQ 3-1::     I just installed Gnus, started it via  @samp{M-x gnus} 
                but it only says "nntp (news) open error", what to do?
* FAQ 3-2::     I'm working under Windows and have no idea what
                ~/.gnus.el means.
* FAQ 3-3::     My news server requires authentication, how to store
                user name and password on disk?
* FAQ 3-4::     Gnus seems to start up OK, but I can't find out how to
                subscribe to a group.
* FAQ 3-5::     Gnus doesn't show all groups / Gnus says I'm not allowed
                to post on this server as well as I am, what's that?
* FAQ 3-6::     I want Gnus to fetch news from several servers, is this
                possible?
* FAQ 3-7::     And how about local spool files?
* FAQ 3-8::     OK, reading news works now, but I want to be able to
                read my mail with Gnus, too. How to do it?
* FAQ 3-9::     And what about IMAP?
* FAQ 3-10::    At the office we use one of those MS Exchange servers,
                can I use Gnus to read my mail from it?
* FAQ 3-11::    Can I tell Gnus not to delete the mails on the server it
                retrieves via POP3?
@end menu

@node FAQ 3-1
@subsubheading Question 3.1

I just installed Gnus, started it via 
@samp{M-x gnus} 
but it only says "nntp (news) open error", what to do?

@subsubheading Answer

You've got to tell Gnus where to fetch the news from. Read
the documentation for information on how to do this. As a
first start, put those lines in ~/.gnus.el:

@example
(setq gnus-select-method '(nntp "news.yourprovider.net"))
(setq user-mail-address "you@@yourprovider.net")
(setq user-full-name "Your Name")
@end example
@noindent

@node FAQ 3-2
@subsubheading Question 3.2

I'm working under Windows and have no idea what ~/.gnus.el means.

@subsubheading Answer

The ~/ means the home directory where Gnus and Emacs look
for the configuration files.  However, you don't really
need to know what this means, it suffices that Emacs knows
what it means :-) You can type 
@samp{C-x C-f ~/.gnus.el RET } 
(yes, with the forward slash, even on Windows), and
Emacs will open the right file for you.  (It will most
likely be new, and thus empty.)
However, I'd discourage you from doing so, since the
directory Emacs chooses will most certainly not be what
you want, so let's do it the correct way. 
The first thing you've got to do is to
create a suitable directory (no blanks in directory name
please) e.g. c:\myhome. Then you must set the environment
variable HOME to this directory.  To do this under Win9x
or Me include the line

@example
SET HOME=C:\myhome
@end example
@noindent

in your autoexec.bat and reboot.  Under NT, 2000 and XP, hit
Winkey+Pause/Break to enter system options (if it doesn't work, go
to Control Panel -> System -> Advanced). There you'll find the
possibility to set environment variables.  Create a new one with
name HOME and value C:\myhome.  Rebooting is not necessary.

Now to create ~/.gnus.el, say
@samp{C-x C-f ~/.gnus.el RET C-x C-s}.
in Emacs.

@node FAQ 3-3
@subsubheading Question 3.3

My news server requires authentication, how to store
user name and password on disk?

@subsubheading Answer

Create a file ~/.authinfo which includes for each server a line like this

@example
machine news.yourprovider.net login YourUserName password YourPassword
@end example
@noindent
.
Make sure that the file isn't readable to others if you
work on a OS which is capable of doing so.  (Under Unix
say 
@example
chmod 600 ~/.authinfo
@end example
@noindent

in a shell.)

@node FAQ 3-4
@subsubheading Question 3.4

Gnus seems to start up OK, but I can't find out how to
subscribe to a group.

@subsubheading Answer

If you know the name of the group say @samp{U
name.of.group RET} in group buffer (use the
tab-completion Luke). Otherwise hit ^ in group buffer,
this brings you to the server buffer. Now place point (the
cursor) over the server which carries the group you want,
hit @samp{RET}, move point to the group
you want to subscribe to and say @samp{u}
to subscribe to it.

@node FAQ 3-5
@subsubheading Question 3.5

Gnus doesn't show all groups / Gnus says I'm not allowed to
post on this server as well as I am, what's that?

@subsubheading Answer

Some providers allow restricted anonymous access and full
access only after authorization. To make Gnus send authinfo
to those servers append 

@example
force yes
@end example
@noindent
 
to the line for those servers in ~/.authinfo.

@node FAQ 3-6
@subsubheading Question 3.6

I want Gnus to fetch news from several servers, is this possible?

@subsubheading Answer

Of course. You can specify more sources for articles in the
variable gnus-secondary-select-methods. Add something like
this in ~/.gnus.el:

@example
(add-to-list 'gnus-secondary-select-methods
             '(nntp "news.yourSecondProvider.net"))
(add-to-list 'gnus-secondary-select-methods
             '(nntp "news.yourThirdProvider.net"))
@end example
@noindent

@node FAQ 3-7
@subsubheading Question 3.7

And how about local spool files?

@subsubheading Answer

No problem, this is just one more select method called
nnspool, so you want this:

@example
(add-to-list 'gnus-secondary-select-methods '(nnspool ""))
@end example
@noindent

Or this if you don't want an NNTP Server as primary news source:

@example
(setq gnus-select-method '(nnspool ""))
@end example
@noindent

Gnus will look for the spool file in /usr/spool/news, if you
want something different, change the line above to something like this:

@example
(add-to-list 'gnus-secondary-select-methods
             '(nnspool ""
                       (nnspool-directory "/usr/local/myspoolddir")))
@end example
@noindent

This sets the spool directory for this server only.
You might have to specify more stuff like the program used
to post articles, see the Gnus manual on how to do this.

@node FAQ 3-8
@subsubheading Question 3.8

OK, reading news works now, but I want to be able to read my mail
with Gnus, too. How to do it?

@subsubheading Answer

That's a bit harder since there are many possible sources
for mail, many possible ways for storing mail and many
different ways for sending mail. The most common cases are
these: 1: You want to read your mail from a pop3 server and
send them directly to a SMTP Server 2: Some program like
fetchmail retrieves your mail and stores it on disk from
where Gnus shall read it. Outgoing mail is sent by
Sendmail, Postfix or some other MTA. Sometimes, you even
need a combination of the above cases.

However, the first thing to do is to tell Gnus in which way
it should store the mail, in Gnus terminology which back end
to use. Gnus supports many different back ends, the most
commonly used one is nnml. It stores every mail in one file
and is therefor quite fast. However you might prefer a one
file per group approach if your file system has problems with
many small files, the nnfolder back end is then probably the
choice for you.  To use nnml add the following to ~/.gnus.el:

@example
(add-to-list 'gnus-secondary-select-methods '(nnml ""))
@end example
@noindent

As you might have guessed, if you want nnfolder, it's

@example
(add-to-list 'gnus-secondary-select-methods '(nnfolder ""))
@end example
@noindent

Now we need to tell Gnus, where to get it's mail from. If
it's a POP3 server, then you need something like this:

@example
(eval-after-load "mail-source"
  '(add-to-list 'mail-sources '(pop :server "pop.YourProvider.net"
                                    :user "yourUserName"
                                    :password "yourPassword")))
@end example
@noindent

Make sure ~/.gnus.el isn't readable to others if you store
your password there. If you want to read your mail from a
traditional spool file on your local machine, it's

@example
(eval-after-load "mail-source"
  '(add-to-list 'mail-sources '(file :path "/path/to/spool/file"))
@end example
@noindent

If it's a Maildir, with one file per message as used by
postfix, Qmail and (optionally) fetchmail it's

@example
(eval-after-load "mail-source"
  '(add-to-list 'mail-sources '(maildir :path "/path/to/Maildir/"
                                        :subdirs ("cur" "new")))
@end example
@noindent

And finally if you want to read your mail from several files
in one directory, for example because procmail already split your
mail, it's

@example
(eval-after-load "mail-source"
  '(add-to-list 'mail-sources
                '(directory :path "/path/to/procmail-dir/"
                            :suffix ".prcml")))
@end example
@noindent

Where :suffix ".prcml" tells Gnus only to use files with the
suffix .prcml.

OK, now you only need to tell Gnus how to send mail. If you
want to send mail via sendmail (or whichever MTA is playing
the role of sendmail on your system), you don't need to do
anything. However, if you want to send your mail to an
SMTP Server you need the following in your ~/.gnus.el

@example
(setq send-mail-function 'smtpmail-send-it)
(setq message-send-mail-function 'smtpmail-send-it)
(setq smtpmail-default-smtp-server "smtp.yourProvider.net")
@end example
@noindent

@node FAQ 3-9
@subsubheading Question 3.9

And what about IMAP?

@subsubheading Answer

There are two ways of using IMAP with Gnus. The first one is
to use IMAP like POP3, that means Gnus fetches the mail from
the IMAP server and stores it on disk. If you want to do
this (you don't really want to do this) add the following to
~/.gnus.el

@example
(add-to-list 'mail-sources '(imap :server "mail.mycorp.com"
                                  :user "username"
                                  :pass "password"
                                  :stream network
                                  :authentication login
                                  :mailbox "INBOX"
                                  :fetchflag "\\Seen"))
@end example
@noindent

You might have to tweak the values for stream and/or
authentication, see the Gnus manual node "Mail Source
Specifiers" for possible values.

If you want to use IMAP the way it's intended, you've got to
follow a different approach.  You've got to add the nnimap
back end to your select method and give the information
about the server there.

@example
(add-to-list 'gnus-secondary-select-methods
             '(nnimap "Give the baby a name"
                      (nnimap-address "imap.yourProvider.net")
                      (nnimap-port 143)
                      (nnimap-list-pattern "archive.*")))
@end example
@noindent

Again, you might have to specify how to authenticate to the
server if Gnus can't guess the correct way, see the Manual
Node "IMAP" for detailed information.

@node FAQ 3-10
@subsubheading Question 3.10

At the office we use one of those MS Exchange servers, can I use
Gnus to read my mail from it?

@subsubheading Answer

Offer your administrator a pair of new running shoes for
activating IMAP on the server and follow the instructions
above.

@node FAQ 3-11
@subsubheading Question 3.11

Can I tell Gnus not to delete the mails on the server it
retrieves via POP3?

@subsubheading Answer

First of all, that's not the way POP3 is intended to work,
if you have the possibility, you should use the IMAP
Protocol if you want your messages to stay on the
server. Nevertheless there might be situations where you
need the feature, but sadly Gnus itself has no predefined
functionality to do so.

However this is Gnus county so there are possibilities to
achieve what you want. The easiest way is to get an external
program which retrieves copies of the mail and stores them
on disk, so Gnus can read it from there. On Unix systems you
could use e.g. fetchmail for this, on MS Windows you can use
Hamster, an excellent local news and mail server.

The other solution would be, to replace the method Gnus
uses to get mail from POP3 servers by one which is capable