[gnus] / texi / gnus.texi

\input texinfo                  @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename gnus.info
@settitle (ding) Gnus 0.84 Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@iftex
@finalout
@end iftex
@setchapternewpage odd
@c      @smallbook
@comment %**end of header (This is for running Texinfo on a region.)
@tex
\overfullrule=0pt
%\global\baselineskip 30pt      % For printing in double spaces
@end tex

@ifinfo

This file documents Gnus, the GNU Emacs newsreader.

Copyright (C) 1995 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.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@iftex

@titlepage
@title (ding) Gnus Manual

@author by Lars Magne Ingebrigtsen
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995 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 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.

Cover art by Etienne Suvasa.
@end titlepage
@page

@end iftex

@node Top
@top The Gnus Newsreader

You can read news (and mail) from within Emacs by using Gnus.  The news
can be gotten by any nefarious means you can think of - @sc{nntp}, local
spool or your mbox file.  All at the same time, if you want to push your
luck.

@menu
* History::                 How Gnus got where it is today.
* Terminology::             We use really difficult, like, words here.
* Starting Up::             Finding news can be a pain.
* The Group Buffer::        Selecting, subscribing and killing groups.
* The Summary Buffer::      Reading, saving and posting articles.
* The Article Buffer::      Displaying and handling articles.
* The Server Buffer::       Making and editing virtual servers.
* Various::                 General purpose settings.
* Customization::           Tailoring Gnus to your needs.
* Troubleshooting::         What you might try if things do not work.
* The End::                 Farewell, and goodbye.
* Index::                   Variable, function and concept index.
* Key Index::               Key Index.
@end menu

@node History
@chapter History

@cindex history
@sc{gnus} was written by Masanobu UMEDA.  When autumn crept up in '94,
Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.

The recommended pronunciation of the name this program is "ding
guh-noose", with "ding" being half-sung in a loud, high-pitched voice,
and "guh-noose" being grumbled and a disaffected fashion.  Any
irritation and/or damage this name may cause you is not the
responsibility of the author, even though you might like to strangle him
for the stupid idea.

If you want to investigate the person responsible for this outrage, you
can point your (feh!) web browser to
@file{http://www.ifi.uio.no/~larsi/}.  This is also the primary
distribution point for the new and spiffy versions of Gnus, also know as
The Site That Destroys Newsrcs And Drives People Mad.

@dfn{(ding)}, is, of course, short for @dfn{ding is not Gnus}, which is
a total and utter lie, but who cares? (Besides, the "Gnus" in this
abbreviation should probably be pronounced "news" as UMEDA intended,
which makes it a more appropriate name, don't you think?)

@menu
* Why?::                What's the point of Gnus?
* Compatibility::       Just how compatible is (ding) Gnus with @sc{gnus}?
* Contributors::        Oodles of people.  
* New Features::        A short description of all the new stuff in Gnus.
* Newest Features::     Features so new that they haven't been written yet.
@end menu

@node Why?
@section Why?

What's the point of Gnus?  

I want to provide a "rad", "happening", "way cool" and "hep" newsreader,
that lets you do anything you can think of.  That was my original
motivation, but while working on Gnus, it has become clear to me that
this generation of newsreaders really belong in the stone age.
Newsreaders haven't developed much since the infancy of the net.  If the
volume continues to rise with the current rate of increase, all current
newsreaders will be pretty much useless.  How do you deal with
newsgroups that have hundreds (or thousands) of new articles each day? 

(ding) Gnus offer no real solutions to these questions, but I would very
much like to see Gnus being used as a testing ground for new methods of
reading and fetching news.  Expanding on Umeda-san's wise decision to
separate the newsreader from the backends, (ding) Gnus now offers a
simple interface for anybody who wants to write new backends for
fetching mail and news from different sources.  I have added hooks for
customizations everywhere I can imagine useful.  By doing so, I'm
inviting every one of you to explore and invent new ways of reading
news. 

May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}. 

@node Compatibility
@section Compatibility

@cindex compatibility
(ding) Gnus was designed to be fully compatible with @sc{gnus}.  Almost
all key bindings have been kept.  More key bindings have been added, of
course, but only in one or two obscure cases have old bindings been
changed.

Our motto is:
@quotation
@cartouche
@center In a cloud bones of steel.
@end cartouche
@end quotation

All commands have kept their names.  Some internal functions have changed
their names.

The @code{gnus-uu} package has changed drastically. @xref{Decoding
Articles}. 

One major compatibility question if the presence of several summary
buffers.  All variables that are relevant while reading a group are
buffer-local to the summary buffer they belong in.  Although most
important variables have their values copied into their global
counterparts whenever a command is executed in the summary buffer, this
change might lead to incorrect values being used unless you are careful.

All code that relies on knowledge of @sc{gnus} internals will probably
fail.  To take two examples: Sorting @code{gnus-newsrc-assoc} (or
changing it in any way, as a matter of fact) is strictly verboten.  Gnus
maintains a hash table that points to the entries in this assoc (which
speeds up many functions), and changing the assoc directly will lead to
peculiar results.

@cindex hilit19
@cindex highlighting
Old hilit19 code does not work at all.  In fact, you should probably
remove all hilit code from all Gnus hooks
(@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
@code{gnus-summary-article-hook}).  (Well, at the very least the first
two.)  Gnus provides various integrated functions for highlighting.
These are faster and more accurate.  To make life easier for everybody,
Gnus will by default remove all hilit calls from all hilit hooks.
Uncleanliness!  Away!

Packages like @code{expire-kill} will no longer work.  As a matter of
fact, you should probably remove all old @sc{gnus} packages (and other
code) when you start using (ding) Gnus.  More likely than not, (ding)
Gnus already does what you have written code to make @sc{gnus} do.
(Snicker.)

Even though old methods of doing things are still supported, only the
new methods are documented in this manual.  If you detect a new method of
doing something while reading this manual, that does not mean you have
to stop doing it the old way.

(ding) Gnus understands all @sc{gnus} startup files.

@kindex M-x gnus-bug
Overall, a casual user who hasn't written much code that depends on
@sc{gnus} internals should suffer no problems.  If problems occur,
please let me know (@kbd{M-x gnus-bug}).

Problems specific to GNU XEmacs can be reported to popineau@@ese-metz.fr
(Fabrice Popineau).  I will just forward any such questions to him,
anyway, so you might have to wait longer if you mail XEmacs questions to
me.

@node Contributors
@section Contributors
@cindex contributors

The new Gnus version couldn't have been done without the help of all the
people on the (ding) mailing list.  Every day for months I have gotten
tens of nice bug reports from them, filling me with joy, every single
one of them.  Smooches.  The people on the list have been tried beyond
endurance, what with my "oh, that's a neat idea <type type>, yup, I'll
release it right away <ship off> no wait, that doesn't work at all <type
type>, yup, I'll ship that one off right away <ship off> no, wait, that
absolutely does not work" policy for releases.  Microsoft - bah.  I'm
@emph{much} worse.

I would like to take this opportunity to thank the Academy for...  oops,
wrong show.

@itemize @bullet
@item
Of course, GNUS was written by Masanobu UMEDA.
@item 
Many excellent functions, especially dealing with scoring and
highlighting (as well as the soon-to-come @sc{soup} support) was written
by Per Abrahamsen.
@item
Innumerable bug fixes were written by Sudish Joseph.
@item
I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
@item 
nnfolder has been much enhanced by Scott Byer.
@item
The orphan scoring was written by Peter Mutsaers.
@item 
GNU XEmacs support has been added by Fabrice Popineau. 
@item 
Various bits and pieces, especially dealing with .newsrc files, was
suggested and added by Hallvard B Furuseth.
@item 
Brian Edmonds has written @code{gnus-bbdb}, as well as other bits and
pieces. 
@item 
Ricardo Nassif did the proof-reading.
@item
Kevin Davidson came up with the name @dfn{ding}, so blame him.
@item 
Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel Quinlan, Ilja
Weis, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
all contributed code and suggestions.
@end itemize


@node New Features
@section New Features
@cindex new features

The look of all buffers can be changed by setting format-like variables.
 
Local spool and several @sc{nntp} servers can be used at once.  Virtual
groups and private mail groups are featured.

Gnus can use various strategies for gathering threads that have lost
their roots (thereby gathering loose sub-threads in one thread) or it
can go back and retrieve enough headers to build a complete thread.

Killed groups can be displayed in the group buffer, and you can read
them as well.

Gnus can do partial group updates - you do not have to retrieve the
entire active file just to check for new articles in a few groups.

Gnus implements a sliding scale of subscribedness to groups.

The approach to killing has been changed.  Instead of simply killing or
not, you can score articles for easier reading.

@node Newest Features
@section Newest Features
@cindex todo

Also known as the @dfn{todo list}.  Sure to be implemented before the
next millennium.

@itemize @bullet
@item
Native @sc{mime} support is something that should be done.  I was hoping
I could steal code from @code{Mew}, the @sc{mime} mail reader for Emacs,
but I'm not quite sure what the status of that project is.  (ding) might
support @sc{mime} quite soon, and it might not.
@item
When the user references the parent of an article, some sort of
re-threading should be done to build a proper tree.  The same goes for
article expunging.  However, as it stands, it's not a trivial issue to
re-generate parts of the summary buffer.  Generating the entire buffer
is very easy, but slow.
@end itemize

@node Terminology
@chapter Terminology

@cindex terminology
@table @dfn
@item news
@cindex news
This is what you are supposed to use this thing for - reading news.
News is generally fetched from a nearby @sc{nntp} server, and is
generally publicly available to everybody.  If you post news, the entire
world is likely to read just what you have written, and they'll all
snigger mischievously.  Behind your back.
@item mail
@cindex mail
Everything that's delivered to you personally is mail.  Some news/mail
readers (like Gnus) blur the distinction between mail and news, but
there is a difference.  Mail is private.  News is public.  Mailing is
not posting, and replying is not following up.
@item reply
Send a mail to the person who has written what you are reading.
@item follow up
Post an article to the current newsgroup responding to the article you
are reading.
@item backend
Gnus gets fed articles from a number of backends, both news and mail
backends.  Gnus does not handle the underlying media, so to speak - this
is all done by the backends.
@item native
Gnus will always use one method (and backend) as the @dfn{native}, or
default, way of getting news.
@item foreign
You can also have any number of foreign groups at the same time.  These
are groups that use different backends for getting news.
@item head
@cindex head
The top part of an article, where administration information (etc.) is
put. 
@item body
@cindex body
The rest of an article. Everything that is not in the head is in the
body. 
@item header
@cindex header
A line from the head of an article. 
@item headers
@cindex headers
A collection of such lines, or a collection of heads.  Or even a
collection of @sc{nov} lines.
@item @sc{nov}
@cindex nov
When Gnus enters a group, it asks the backend for the headers for all
the unread articles in the group.  Most servers support the News OverView
format, which is much smaller and much faster to read than the normal
HEAD format. 
@item level
@cindex levels
Each group is subscribed at some @dfn{level} or other (1-9).  The ones
that have a lower level are "more" subscribed than the groups with a
higher level.  In fact, groups on levels 1-5 are considered
@dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
are @dfn{killed}.  Commands for listing groups and scanning for new
articles will all use the numeric prefix as @dfn{working level}.
@item killed groups
@cindex killed groups
No information on killed groups is stored or updated, which makes killed
groups much easier to handle than subscribed groups.
@item zombie groups
@cindex zombie groups
Just like killed groups, only slightly less dead.
@item active file
@cindex active file
The news server has to keep track of what articles it carries, and what
groups exist.  All this information in stored in the active file, which
is rather large, as you might surmise.
@end table

@node Starting Up
@chapter Starting Gnus
@cindex starting up

@kindex M-x gnus
If your system administrator has set things up properly, starting Gnus
and reading news is extremely easy - you just type @kbd{M-x gnus}.

If things do not go smoothly at startup, you have to twiddle some
variables. 

@menu
* Finding the News::    Choosing a method for getting news.
* The First Time::      What does Gnus do the first time you start it?
* The Server is Down::  How can I read my mail then?
* New Groups::          What is Gnus supposed to do with new groups?
* Startup Files::       Those pesky startup files - @file{.newsrc}.
* Auto Save::           Recovering from a crash.
* The Active File::     Reading the active file over a slow line Takes Time.
* Startup Variables::   Other variables you might change.
@end menu

@node Finding the News
@section Finding the News

@vindex gnus-select-method
The @code{gnus-select-method} variable controls how Gnus finds news.
This variable should be a list where the first element says @dfn{how}
and the second element says @dfn{where}.  This method is is your native
method.  All groups that are not fetched with this method are foreign
groups.

For instance, if you want to get your daily dosage of news from the
@samp{news.somewhere.edu} @sc{nntp} server, you'd say:

@lisp
(setq gnus-select-method '(nntp "news.somewhere.edu"))
@end lisp

If you want to read directly from the local spool, say:

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

If you can use a local spool, you probably should, as it will almost
certainly be much faster.

If this variable is not set, Gnus will take a look at the
@code{NNTPSERVER} environment variable.  If that isn't set either, it
will try to use the machine that is running Emacs as an @sc{nntp}
server.

@vindex gnus-nntp-server
If @code{gnus-nntp-server} is set, this variable will override
@code{gnus-select-method}.  You should therefore set
@code{gnus-nntp-server} to @code{nil}, which is what it is by default.

@vindex gnus-secondary-servers
You can also make Gnus prompt you interactively for the name of an
@sc{nntp} server.  If you give a non-numerical prefix to @code{gnus}
(i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
in the @code{gnus-secondary-servers} list (if any).  You can also just
type in the name of any server you feel like visiting.

However, if you use one @sc{nntp} server regularly, and are just
interested in a couple of groups from a different server, you would be
better served by using the @code{gnus-group-browse-foreign-server}
command from the group buffer.  It will let you have a look at what
groups are available, and you can subscribe to any of the groups you
want to.  This also makes @file{.newsrc} maintenance much tidier.
@xref{Foreign Groups}.

@vindex gnus-secondary-select-methods
A slightly different approach to foreign groups is to set the
@code{gnus-secondary-select-methods} variable.  The select methods
listed in this variable are in many ways just as native as the
@code{gnus-select-method} server.  They will also be queried for active
files during startup (if that's required), and new newsgroups that
appear on these servers will be subscribed (or not) just as native
groups are.

For instance, if you use the @code{nnmbox} backend to read you mail, you
would typically set this variable to

@lisp
(setq gnus-secondary-select-methods '((nnmbox "")))
@end lisp

@node The First Time
@section The First Time
@cindex first time usage

If no startup files exist, Gnus will try to determine what groups should
be subscribed by default.

@vindex gnus-default-subscribed-newsgroups
If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
will subscribe you to just those groups in that list, leaving the rest
killed.  Your system administrator should have set this variable to
something useful.

Since she hasn't, Gnus will just subscribe you to a few randomly picked
groups (i.e., @samp{*.newusers}).  (@dfn{Random} is here defined as
"whatever Lars thinks you should read".)

You'll also be subscribed to the Gnus documentation group, which should
help you with most common problems.  

If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
use the normal functions for handling new groups, and not do anything
special.

@node The Server is Down
@section The Server is Down
@cindex server errors

If the default server is down, Gnus will understandably have some
problems starting.  However, if you have some mail groups in addition to
the news groups, you may want to start Gnus anyway.

Gnus, being the trusting sort of program, will ask whether to proceed
without a native select method if that server can't be contacted.  This
will happen whether the server doesn't actually exist (i.e., you have
given the wrong address) or the server has just momentarily taken ill
for some reason or other.  

If Gnus says "nntp server on <your server> can't be opened. Continue?",
you do not want to continue unless you have some foreign groups that you
want to read.  Even if you don't, Gnus will let you continue, but you'll
find it difficult to actually do anything in the group buffer.  But,
hey, that's your problem.  Blllrph!

@node New Groups
@section New Groups
@cindex new groups

@vindex gnus-subscribe-newsgroup-method
What Gnus does when it encounters a new group is determined by the
@code{gnus-subscribe-newsgroup-method} variable.

This variable should contain a function.  Some handy pre-fab values
are:

@table @code
@item gnus-subscribe-randomly
@vindex gnus-subscribe-randomly
Subscribe all new groups randomly.
@item gnus-subscribe-alphabetically
@vindex gnus-subscribe-alphabetically
Subscribe all new groups alphabetically.
@item gnus-subscribe-hierarchically
@vindex gnus-subscribe-hierarchically
Subscribe all new groups hierarchically.
@item gnus-subscribe-interactively
@vindex gnus-subscribe-interactively
Subscribe new groups interactively.  This means that Gnus will ask
you about @strong{all} new groups.
@item gnus-subscribe-zombies
@vindex gnus-subscribe-zombies
Make all new groups zombies.  You can browse the zombies later and
either kill them all off properly, or subscribe to them.  This is the
default.
@end table

@vindex gnus-subscribe-hierarchical-interactive
A closely related variable is
@code{gnus-subscribe-hierarchical-interactive}.  (That's quite a
mouthful.)  If this variable is non-@code{nil}, Gnus will ask you in a
hierarchical fashion whether to subscribe to new groups or not.  Gnus
will ask you for each sub-hierarchy whether you want to descend the
hierarchy or not.

One common way to control which new newsgroups should be subscribed or
ignored is to put an @dfn{options} line at the start of the
@file{.newsrc} file.  Here's an example:

@example
options -n !alt.all !rec.all sci.all
@end example

@vindex gnus-subscribe-options-newsgroup-method
This line obviously belongs to a serious-minded intellectual scientific
person (or she may just be plain old boring), because it says that all
groups that have names beginning with @samp{alt} and @samp{rec} should
be ignored, and all groups with names beginning with @samp{sci} should
be subscribed.  Gnus will not use the normal subscription method for
subscribing these groups.
@code{gnus-subscribe-options-newsgroup-method} is used instead.  This
variable defaults to @code{gnus-subscribe-alphabetically}.

@vindex gnus-options-not-subscribe
@vindex gnus-options-subscribe
If you don't want to mess with your @file{.newsrc} file, you can just
set the two variables @code{gnus-options-subscribe} and
@code{gnus-options-not-subscribe}.  These two variables do exactly the
same as the @file{.newsrc} options -n trick.  Both are regexps, and if
the the new group matches the first, it will be unconditionally
subscribed, and if it matches the latter, it will be ignored.

@vindex gnus-check-new-newsgroups
If you are satisfied that you really never want to see any new groups,
you could set @code{gnus-check-new-newsgroups} to @code{nil}.  This will
also save you some time at startup.  Even if this variable is
@code{nil}, you can always subscribe to the new groups just by pressing
@kbd{U} in the group buffer (@pxref{Group Maintenance}).

Gnus normally determines whether a group is new or not by comparing the
list of groups from the active file(s) with the lists of subscribed and
dead groups.  This isn't a particularly fast method.  If
@code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
server for new groups since the last time.  This is both faster &
cheaper.  This also means that you can get rid of the list of killed
groups altogether, so you may set @code{gnus-save-killed-list} to
@code{nil}, which will save time both at startup, at exit, and all over.
Saves disk space, too.  Why isn't this the default, then?
Unfortunately, not all servers support this function.

This variable can also be a list of select methods.  If so, Gnus will
issue an @code{ask-server} command to each of the select methods, and
subscribe them (or not) using the normal methods.  This might be handy
if you are monitoring a few servers for new groups.  A side effect is
that startup will take much longer, so you can meditate while waiting.
Use the mantra "dingnusdingnusdingnus" to achieve permanent happiness.

@node Startup Files
@section Startup Files
@cindex startup files
@cindex .newsrc

Now, you all know about the @file{.newsrc} file.  All subscription
information is traditionally stored in this file.

Things got a bit more complicated with @sc{gnus}.  In addition to
keeping the @file{.newsrc} file updated, it also used a file called
@file{.newsrc.el} for storing all the information that didn't fit into
the @file{.newsrc} file.  (Actually, it duplicated everything in the
@file{.newsrc} file.)  @sc{gnus} would read whichever one of these files
that were the most recently saved, which enabled people to swap between
@sc{gnus} and other newsreaders.

That was kinda silly, so (ding) Gnus went one better: In addition to the
@file{.newsrc} and @file{.newsrc.el} files, (ding) Gnus also has a file
called @file{.newsrc.eld}.  It will read whichever of these files that
are most recent, but it will never write a @file{.newsrc.el} file.

@vindex gnus-save-newsrc-file
You can also turn off writing the @file{.newsrc} file by setting
@code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
the file and save some space, as well as making exit from Gnus faster.
However, this will make it impossible to use other newsreaders than
Gnus.  But hey, who would want to, right?

@vindex gnus-save-killed-list
If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
list of killed groups to the startup file.  This will save both time
(when starting and quitting) and space (on disk).  It will also means
that Gnus has no record of what groups are new or old, so the automatic
new groups subscription methods become meaningless.  You should always
set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
if you set this variable to @code{nil} (@pxref{New Groups}).

@vindex gnus-startup-file
The @code{gnus-startup-file} variable says where the startup files are.
The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
file being whatever that one is with a @samp{.eld} appended.

@vindex gnus-save-newsrc-hook
@code{gnus-save-newsrc-hook} is called before saving the @file{.newsrc}
file.

@node Auto Save
@section Auto Save
@cindex dribble file
@cindex auto-save

Whenever you do something that changes the Gnus data (reading articles,
catching up, killing/subscribing groups), the change is added to a
special @dfn{dribble buffer}.  This buffer is auto-saved the normal
Emacs way.  If your Emacs should crash before you have saved the
@file{.newsrc} files, all changes you have made can be recovered from
this file.

If Gnus detects this file at startup, it will ask the user whether to
read it. The auto save file is deleted whenever the real startup file is
saved.

@vindex gnus-use-dribble-file
If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
maintain a dribble buffer.

@node The Active File
@section The Active File
@cindex active file
@cindex ignored groups

When Gnus starts, or indeed whenever it tries to determine whether new
articles have arrived, it reads the active file.  This is a very large
file that lists all the active groups and articles on the @sc{nntp}
server.

@vindex gnus-ignored-newsgroups
Before examining the active file, Gnus deletes all lines that match the
regexp @code{gnus-ignored-newsgroups}.  This is done primarily to reject
any groups with bogus names, but you can use this variable to make Gnus
ignore hierarchies you aren't ever interested in.  This variable is
@code{nil} by default, and will slow down active file handling somewhat
if you set it to anything else.

@vindex gnus-read-active-file
The active file can be rather Huge, so if you have a slow network, you
can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
reading the active file.

Gnus will try to make do by just getting information on the groups
that you actually subscribe to.

Note that if you subscribe to lots and lots of groups, setting this
variable to @code{nil} will probably make Gnus slower, not faster.  At
present, having this variable @code{nil} will slow Gnus down
considerably, unless you read news over a 2400 baud modem.  

This variable can also have the value @code{some}.  Gnus will then
attempt to read active info only on the subscribed groups.  On some
servers this is quite fast (on sparkling, brand new INN servers that
support the @samp{LIST ACTIVE group} command), on others this is not
fast at all.  In any case, @code{some} should be faster than @code{nil},
and is certainly faster than @code{t} over slow lines.

If this variable is @code{nil}, Gnus will as for group info in total
lock-step, which isn't very fast.  If it is @code{some} and you use an
NNTP server, Gnus will pump out commands as fast as it can, and read all
the replies in one swoop.  This will normally result in better
performance, but if the server does not support the aforementioned
@samp{LIST ACTIVE group} command, this isn't very nice to the server. 

In any case, if you use @code{some} or @code{nil}, you should kill all
groups that you aren't interested in.

@node Startup Variables
@section Startup Variables

@table @code
@item gnus-check-bogus-newsgroups
@vindex gnus-check-bogus-newsgroups
If non-@code{nil}, Gnus will check for and delete all bogus groups at
startup.  A @dfn{bogus group} is a group that you have in your
@file{.newsrc} file, but doesn't exist on the news server.  Checking for
bogus groups isn't very quick, so to save time and resources, it's best
to leave this option off, and instead do the checking for bogus groups
once in a while from the group buffer (@pxref{Group Maintenance}).
@item gnus-inhibit-startup-message
@vindex gnus-inhibit-startup-message
If non-@code{nil}, the startup message won't be displayed.  That way,
your boss might not notice that you are reading news instead of doing
your job.
@item gnus-no-groups-message
@vindex gnus-no-groups-message
Message displayed by Gnus when no groups are available.
@end table

@node The Group Buffer
@chapter The Group Buffer
@cindex group buffer

The @dfn{group buffer} lists all (or parts) of the available groups.  It
is the first buffer shown when Gnus starts, and will never be killed as
long as Gnus is active.

@menu
* Group Buffer Format::    Information listed and how you can change it.
* Group Maneuvering::      Commands for moving in the group buffer.
* Selecting a Group::      Actually reading news.
* Group Subscribing::      Unsubscribing, killing, subscribing.
* Group Levels::           Levels? What are those, then?
* Marking Groups::         You can mark groups for later processing.
* Foreign Groups::         How to create foreign groups.
* Group Parameters::       Each group may have different parameters set.
* Listing Groups::         Gnus can list various subsets of the groups.
* Group Maintenance::      Maintaining a tidy @file{.newsrc} file.
* Browse Foreign Server::  You can browse a server.  See what if has to offer.
* Exiting Gnus::           Stop reading news and get some work done.
* Misc Group Stuff::       Other stuff that you can to do.
@end menu

@node Group Buffer Format
@section Group Buffer Format
@cindex group buffer format

The default format of the group buffer is nice and dull, but you can
make it as exciting and ugly as you feel like.

Here's a couple of example group lines:

@example
     25: news.announce.newusers
 *    0: alt.fan.andrea-dworkin
@end example

Quite simple, huh?

You can see that there are 25 unread articles in
@samp{news.announce.newusers}.  There are no unread articles, but some
ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
asterisk at the beginning of the line?)

@vindex gnus-group-line-format
You can fuck that up to your heart's delight by fiddling with the
@code{gnus-group-line-format} variable.  This variable works along the
lines of a @code{format} specification, which is pretty much the same as
a @code{printf} specifications, for those of you who use (feh!) C.

In addition to the normal "padding" specs that @code{format} supports
(eg. @samp{%7d}), specifications like @samp{%7,12s} are allowed.  A spec
of this type means that the field will be at least 7 characters long,
and never more that 12 characters long.

The default value that produced those lines above is 
@samp{"%M%S%5y: %(%g%)\n"}.

There should always be a colon on the line; the cursor always moves to
the colon after performing an operation.  Nothing else is required - not
even the group name.  All displayed text is just window dressing, and is
never examined by Gnus.  Gnus stores all real information it needs using
text properties.

(Note that if you make a really strange, wonderful, spreadsheet-like
layout, everybody will believe you are hard at work with the accounting
instead of wasting time reading news.)

Here's a list of all available format characters:

@table @samp
@item M    
Only marked articles.
@item S
Whether the group is subscribed.
@item L    
Level of subscribedness.
@item N
Number of unread articles.
@item I
Number of dormant articles.
@item T
Number of ticked articles.
@item R
Number of read articles.
@item t
Total number of articles.
@item y
Number of unread, unticked, non-dormant articles.
@item i
Number of ticked and dormant articles.
@item g
Full group name.
@item G
Group name.
@item D
Newsgroup description.
@item o
Moderated.
@item O
Moderated.
@item s
Select method.
@item n
Select from where.
@item z
A string that looks like @samp{<%s:%n>} if a foreign select method is
used.
@item u
User defined specifier.  The next character in the format string should
be a letter.  @sc{gnus} will call the function
@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
following @samp{%u}.  The function will be passed the current headers as
argument.  The function should return a string, which will be inserted
into the buffer just like information from any other specifier.
@end table

@cindex *
All the "number-of" specs will be filled with an asterisk (@samp{*}) if
no info is available - for instance, if it is a non-activated foreign
group, or a bogus (or semi-bogus) native group.

@vindex gnus-group-mode-line-format
The mode line can be changed by setting
(@code{gnus-group-mode-line-format}).  It doesn't understand that many
format specifiers:

@table @samp
@item S
Default news server.
@item M
Default select method.
@end table

@node Group Maneuvering
@section Group Maneuvering
@cindex group movement

All movement commands understand the numeric prefix and will behave as
expected, hopefully. 

@table @kbd
@item n
@kindex n (Group)
@findex gnus-group-next-unread-group
Go to the next group that has unread articles
(@code{gnus-group-next-unread-group}).
@item p
@itemx DEL
@kindex DEL (Group)
@kindex p (Group)
@findex gnus-group-prev-unread-group
Go to the previous group group that has unread articles
(@code{gnus-group-prev-unread-group}).
@item N
@kindex N (Group)
@findex gnus-group-next-group
Go to the next group (@code{gnus-group-next-group}).
@item P
@kindex P (Group)
@findex gnus-group-prev-group
Go to the previous group (@code{gnus-group-prev-group}).
@item M-p
@kindex M-p (Group)
@findex gnus-group-next-unread-group-same-level
Go to the next unread group on the same level (or lower)
(@code{gnus-group-next-unread-group-same-level}). 
@item M-n
@kindex M-n (Group)
@findex gnus-group-prev-unread-group-same-level
Go to the previous unread group on the same level (or lower)
(@code{gnus-group-prev-unread-group-same-level}). 
@end table

Three commands for jumping to groups:

@table @kbd
@item j
@kindex j (Group)
@findex gnus-group-jump-to-group
Jump to a group (and make it visible if it isn't already)
(@code{gnus-group-jump-to-group}).  Killed groups can be jumped to, just
like living groups.
@item ,
@kindex , (Group)
@findex gnus-group-best-unread-group
Jump to the unread group with the lowest level
(@code{gnus-group-best-unread-group}). 
@item .
@kindex . (Group)
@findex gnus-group-first-unread-group
Jump to the first group with unread articles
(@code{gnus-group-first-unread-group}).  
@end table

@vindex gnus-group-goto-unread
If @code{gnus-group-goto-unread} is @code{nil}, all the movement
commands will move to the next group, not the next unread group.  Even
the commands that say they move to the next unread group. 

@node Selecting a Group
@section Selecting a Group
@cindex group selection

@table @kbd
@item SPACE
@kindex SPACE (Group)
@findex gnus-group-read-group
Select the current group, switch to the summary buffer and display the
first unread article (@code{gnus-group-read-group}).  If there are no
unread articles in the group, or if you give a non-numerical prefix to
this command, Gnus will offer to fetch all the old articles in this
group from the server.  If you give a numerical prefix @var{N}, Gnus
will fetch @var{N} number of articles.  If @var{N} is positive, fetch
the @var{N} newest articles, if @var{N} is negative, fetch the
@var{abs(N)} oldest articles.
@item RET
@kindex RET (Group)
@findex gnus-group-select-group
Select the current group and switch to the summary buffer
(@code{gnus-group-select-group}).  Takes the same arguments as
@code{gnus-group-read-group} - the only difference is that this command
does not display the first unread article automatically upon group
entry. 
@item c
@kindex c (Group)
@findex gnus-group-catchup-current
Mark all unticked articles in this group as read
(@code{gnus-group-catchup-current}). 
@item C
@kindex C (Group)
@findex gnus-group-catchup-current-all
Mark all articles in this group, even the ticked ones, as read
(@code{gnus-group-catchup-current-all}). 
@end table

@vindex gnus-large-newsgroup
The @code{gnus-large-newsgroup} variable says what Gnus should consider
to be a big group.  If the group has more unread articles than this,
Gnus will query the user before entering the group.  The user can then
specify how many articles should be fetched from the server.  If the
user specifies a negative number (@samp{-n}), the @samp{n} oldest
articles will be fetched.  If it is positive, the @samp{n} articles that
have arrived most recently will be fetched.

@vindex gnus-select-group-hook
@vindex gnus-auto-select-newsgroup
If @code{gnus-auto-select-newsgroup} is non-@code{nil}, the first unread
article in the group will be displayed when you enter the group.  If you
want to prevent automatic selection in some group (say, in a binary
group with Huge articles) you can set this variable to @code{nil} in
@code{gnus-select-group-hook}, which is called when a group is selected.

@findex gnus-thread-sort-by-total-score
@findex gnus-thread-sort-by-date
@findex gnus-thread-sort-by-score
@findex gnus-thread-sort-by-subject
@findex gnus-thread-sort-by-author
@findex gnus-thread-sort-by-number
@vindex gnus-thread-sort-functions
If you are using a threaded summary display, you can sort the threads by
setting @code{gnus-thread-sort-functions}, which is a list of functions.
By default, sorting is done on article numbers.  Ready-made sorting
functions include @code{gnus-thread-sort-by-number},
@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
@code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score},
@code{gnus-thread-sort-by-total-score}.

Each function takes two threads and return non-@code{nil} if the first
thread should be sorted before the other.  If you use more than one
function, the primary sort key should be the last function in the list.

If you would like to sort by score, then by subject, and finally by
date, you could do something like:

@lisp
(setq gnus-thread-sort-functions 
      '(gnus-thread-sort-by-date
        gnus-thread-sort-by-subject
        gnus-thread-sort-by-score))
@end lisp

@vindex gnus-thread-score-function
The function in the @code{gnus-thread-score-function} variable (default
@code{+}) is used for calculating the total score of a thread.  Useful
functions might be @code{max}, @code{min}, or squared means, or whatever
tickles you fancy.

@node Group Subscribing
@section Group Subscribing
@cindex subscribing

@table @kbd
@item S t
@itemx u
@kindex S t (Group)
@kindex u (Group)
@findex gnus-group-unsubscribe-current-group
Toggle subscription to the current group
(@code{gnus-group-unsubscribe-current-group}).  
@item S s
@itemx U
@kindex S s (Group)
@kindex U (Group)
@findex gnus-group-unsubscribe-group
Prompt for a group to subscribe, and then subscribe it.  If it was
subscribed already, unsubscribe it instead
(@code{gnus-group-unsubscribe-group}).
@item S k
@itemx C-k
@kindex S k (Group)
@kindex C-k (Group)
@findex gnus-group-kill-group
Kill the current group (@code{gnus-group-kill-group}).
@item S y
@itemx C-y
@kindex S y (Group)
@kindex C-y (Group)
@findex gnus-group-yank-group
Yank the last killed group (@code{gnus-group-yank-group}).
@item S w
@itemx C-w
@kindex S w (Group)
@kindex C-w (Group)
@findex gnus-group-kill-region
Kill all groups in the region (@code{gnus-group-kill-region}). 
@item S z
@kindex S z (Group)
@findex gnus-group-kill-all-zombies
Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
@end table

@node Group Levels
@section Group Levels
@cindex group level

All groups have a level of @dfn{subscribedness}.  For instance, if a
group is on level 2, it is more subscribed than a group on level 5.  You
can ask Gnus to just list groups on a given level or lower
(@pxref{Listing Groups}), or to just check for new articles in groups on
a given level or lower (@pxref{Misc Group Stuff}).

@table @kbd
@item S l
@kindex S l (Group)
@findex gnus-group-set-current-level
Set the level of the current group.  If a numeric prefix is given, the
next @var{n} groups will have their levels set.  The user will be
prompted for a level.
@end table

@vindex gnus-level-killed
@vindex gnus-level-zombie
@vindex gnus-level-unsubscribed
@vindex gnus-level-subscribed
Gnus considers groups on between levels 1 and
@code{gnus-level-subscribed} (inclusive) to be subscribed,
@code{gnus-level-subscribed} (exclusive) and
@code{gnus-level-unsubscribed} (inclusive) to be unsubscribed,
@code{gnus-level-zombie} to be zombies (walking dead) and
@code{gnus-level-killed} to be killed, completely dead.  Gnus treats
subscribed and unsubscribed groups exactly the same, but zombie and
killed groups have no information on what articles you have read, etc,
stored.  This distinction between dead and living groups isn't done
because it is nice or clever, it is done purely for reasons of
efficiency. 

It is recommended that you keep all your mail groups (if any) on quite
low levels (eg. 1 or 2).

If you want to play with the level variables, you should show some care.
Set them once, and don't touch them ever again.  

@vindex gnus-level-default-unsubscribed
@vindex gnus-level-default-subscribed
Two closely related variables are @code{gnus-level-default-subscribed}
and @code{gnus-level-default-unsubscribed}, which are the levels that new
groups will be put on if they are (un)subscribed.  These two variables
should, of course, be inside the relevant legal ranges.

@vindex gnus-keep-same-level
If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
will only move to groups that are of the same level (or lower).  In
particular, going from the last article in one group to the next group
will go to the next group of the same level (or lower).  This might be
handy if you want to read the most important groups before you read the
rest.

@vindex gnus-group-default-list-level
All groups with a level less than or equal to
@code{gnus-group-default-list-level} will be listed in the group buffer
by default.

@vindex gnus-group-use-permament-levels
If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
use this level as the "work" level.

@node Marking Groups
@section Marking Groups
@cindex marking groups

If you want to perform some action on several groups, and they appear
subsequently in the group buffer, you would normally just give a
numerical prefix to the command.  Most group commands will then do your
bidding on those groups.

However, if the groups are not in sequential order, you can still
perform an action on several groups.  You simply mark the groups first,
and then execute the command.  

@table @kbd
@item #
@kindex # (Group)
@item G m
@kindex G m (Group)
@findex gnus-group-mark-group
Set the mark on the current group (@code{gnus-group-mark-group}). 
@item M-#
@kindex M-# (Group)
@item G u
@kindex G u (Group)
@findex gnus-group-unmark-group
Remove the mark from the current group
(@code{gnus-group-unmark-group}). 
@item G w
@kindex G w (Group)
@findex gnus-group-mark-region
Mark all groups between point and mark (@code{gnus-group-mark-region}). 
@end table

@node Foreign Groups
@section Foreign Groups
@cindex foreign groups

A @dfn{foreign group} is a group that is not read by the usual (or
default) means.  It could be, for instance, a group from a different
@sc{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 @dfn{name} and
a @dfn{select method}.  To take the latter first, a select method is a
list where the first element says what backend to use (eg. @code{nntp},
@code{nnspool}, @code{nnml}) and the second element is the @dfn{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 @dfn{virtual server} - so
we do just that (@pxref{The Server Buffer}).

The @dfn{name} of the group is the name the backend will recognize the
group as.

For instance, the group @samp{soc.motss} on the @sc{nntp} server
@samp{some.where.edu} will have the name @samp{soc.motss} and select
method @code{(nntp "some.where.edu")}.  Gnus will call this group, in
all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
nntp backend just knows this group as @samp{soc.motss}.

Here are some commands for making and editing general foreign groups,
and some commands to ease the creation of some special-purpose groups:

@table @kbd
@item G m
@kindex G m (Group)
@findex gnus-group-make-group
Make a new group (@code{gnus-group-make-group}).  Gnus will prompt you
for a name, a method and possibly an @dfn{address}.  For an easier way
to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.

@item G e
@kindex G e (Group)
@findex gnus-group-edit-group-method
Enter a buffer where you can edit the select method of the current
group (@code{gnus-group-edit-group-method}).

@item G p
@kindex G p (Group)
@findex gnus-group-edit-group-parameters
Enter a buffer where you can edit the group parameters
(@code{gnus-group-edit-group-parameters}). 

@item G E
@kindex G E (Group)
@findex gnus-group-edit-group
Enter a buffer where you can edit the group info
(@code{gnus-group-edit-group}).

@item G d
@kindex G d (Group)
@findex gnus-group-make-directory-group
Make a directory group.  You will be prompted for a directory name
(@code{gnus-group-make-directory-group}).  

@item G h 
@kindex G h (Group)
@findex gnus-group-make-help-group
Make the (ding) Gnus help group (@code{gnus-group-make-help-group}).

@item G a
@kindex G a (Group)
@findex gnus-group-make-archive-group
@vindex gnus-group-archive-directory
Make the (ding) Gnus archive group
(@code{gnus-group-make-archive-group}).  The archive group will be
fetched from @code{gnus-group-archive-directory}.

@item G k
@kindex G k (Group)
@findex gnus-group-make-kiboze-group
Make a kiboze group.  You will be prompted for a name, for a regexp to
match groups to be "included" in the kiboze group, and a series of
strings to match on headers (@code{gnus-group-make-kiboze-group}).

@item G D
@kindex G D (Group)
@findex gnus-group-enter-directory
Read a random directory as if with were a newsgroup with the
@code{nneething} backend (@code{gnus-group-enter-directory}).

@item G f
@kindex G f (Group)
@findex gnus-group-make-doc-group
Make a group based on some file or other
(@code{gnus-group-make-doc-group}).  You will be prompted for a file
name and a file type.  Currently supported types are @code{babyl},
@code{mbox} and @code{digest}.

@item G V
@kindex G V (Group)
@findex gnus-group-make-empty-virtual
Make a new, fresh, empty @code{nnvirtual} group
(@code{gnus-group-make-empty-virtual}).

@item G v
@kindex G v (Group)
@findex gnus-group-add-to-virtual
Add the current group to an @code{nnvirtual} group
(@code{gnus-group-add-to-virtual}).  Uses the process/prefix convention.
@end table

The different methods all have their peculiarities, of course.

@menu
* nntp::             Reading news from a different @sc{nntp} server.
* nnspool::          Reading news from the local spool.
* nnvirtual::        Combining articles from many groups.
* nnkiboze::         Looking through parts of the newsfeed for articles.
* nndir::            You can read a directory as if it was a newsgroup.
* nneething::          Dired? Who needs dired?
* nndoc::            Single files can be the basis of a group.
* Reading Mail::     Reading your personal mail with Gnus.
@end menu

@vindex gnus-activate-foreign-newsgroups
If the @code{gnus-activate-foreign-newsgroups} is a positive number,
Gnus will check all foreign groups with this level or lower at startup.
This might take quite a while, especially if you subscribe to lots of
groups from different @sc{nntp} servers.  It is @code{nil} by default,
which means that you won't be told whether there are new articles in
these groups.  How many unread articles there are will be determined
when, or if, you decide to enter them.  You can also activate any group
with @kbd{M-g} to see how many unread articles there are.

@node nntp
@subsection nntp
@cindex @sc{nntp}

Subscribing to a foreign group from an @sc{nntp} server is rather easy.
You just specify @code{nntp} as method and the address of the @sc{nntp}
server as the, uhm, address.

If the @sc{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 (@pxref{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 @code{nntp}
server: 

@table @code
@item nntp-server-opened-hook
@vindex nntp-server-opened-hook
@cindex @sc{mode reader}
@cindex authinfo
@findex nntp-send-authinfo
@findex nntp-send-mode-reader
@code{nntp-server-opened-hook} is run after a connection has been made.
It can be used to send commands to the @sc{nntp} server after it has
been contacted.  By default is sends the command @samp{MODE READER} to
the server with the @code{nntp-send-mode-reader} function.  Another
popular function is @code{nntp-send-authinfo}, which will prompt you for
an @sc{nntp} password and stuff.

@item nntp-maximum-request
@vindex nntp-maximum-request
If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
will collect headers by sending a series of @code{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 @code{nntp-maximum-request} variable, and is 400 by default.  If
your network is buggy, you should set this to 1.

@item nntp-connection-timeout
@vindex nntp-connection-timeout
If you have lots of foreign @code{nntp} groups that you connect to
regularly, you're sure to have problems with @sc{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 @code{nntp-connection-timeout}.  This is an integer
that says how many seconds the @code{nntp} backend should wait for a
connection before giving up.  If it is @code{nil}, which is the default,
no timeouts are done.

@item nntp-server-hook
@vindex nntp-server-hook
This hook is run as the last step when connecting to an @sc{nntp}
server.

@findex nntp-open-rlogin
@findex nntp-open-network-stream
@item nntp-open-server-function
@vindex nntp-open-server-function
This function is used to connect to the remote system.  Two pre-made
functions are @code{nntp-open-network-stream}, which is the default, and
simply connects to some port or other on the remote system.  The other
is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
and then does a telnet to the @sc{nntp} server available there.

@item nntp-rlogin-parameters
@vindex nntp-rlogin-parameters
If you use @code{nntp-open-rlogin} as the
@code{nntp-open-server-function}, this list will be used as the
parameter list given to @code{rsh}.

@item nntp-rlogin-user-name
@vindex nntp-rlogin-user-name
User name on the remote system when using the @code{rlogin} connect
function. 

@item nntp-address
@vindex nntp-address
The address of the remote system running the @sc{nntp} server.

@item nntp-port-number
@vindex nntp-port-number
Port number to connect to when using the @code{nntp-open-network-stream}
connect function.

@item nntp-buggy-select
@vindex nntp-buggy-select
Set this to non-@code{nil} if your select routine is buggy.

@item nntp-nov-is-evil 
@vindex nntp-nov-is-evil 
If the @sc{nntp} server does not support @sc{nov}, you could set this
variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
can be used automatically.

@item nntp-xover-commands
@vindex nntp-xover-commands
List of strings that are used as commands to fetch @sc{nov} lines from a
server.  The default value of this variable is @code{("XOVER"
"XOVERVIEW")}. 

@item nntp-nov-gap
@vindex nntp-nov-gap
@code{nntp} normally sends just one big request for @sc{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 @code{nntp} will fetch 4999 @sc{nov}
lines that you do not want, and will not use.  This variable says how
big a gap between two consecutive articles is allowed to be before the
@code{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 @code{nil},
@code{nntp} will never split requests.

@item nntp-prepare-server-hook
@vindex nntp-prepare-server-hook
A hook run before attempting to connect to an @sc{nntp} server.

@item nntp-async-number
@vindex nntp-async-number
How many articles should be pre-fetched when in asynchronous mode.  If
this variable is @code{t}, @code{nntp} will pre-fetch all the articles
that it can without bound.  If it is @code{nil}, no pre-fetching will be
made.

@end table

@node nnspool
@subsection nnspool
@cindex nnspool
@cindex 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 like
@samp{alt.binaries.pictures.furniture}.

Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
anything else) as the address.

If you have access to a local spool, you should probably use that as the
native select method (@pxref{Finding the News}).

@table @code
@item nnspool-inews-program
@vindex nnspool-inews-program
Program used to post an article.

@item nnspool-inews-switches
@vindex nnspool-inews-switches
Parameters given to the inews program when posting an article. 

@item nnspool-spool-directory
@vindex nnspool-spool-directory
Where nnspool looks for the articles.  This is normally
@file{/usr/spool/news/}.

@item nnspool-nov-directory 
@vindex nnspool-nov-directory 
Where nnspool will look for @sc{nov} files.  This is normally
@file{/usr/spool/news/over.view/}.

@item nnspool-lib-dir
@vindex nnspool-lib-dir
Where the news lib dir is (@file{/usr/lib/news/} by default).

@item nnspool-active-file
@vindex nnspool-active-file
The path of the active file.

@item nnspool-newsgroups-file
@vindex nnspool-newsgroups-file
The path of the group description file.

@item nnspool-history-file
@vindex nnspool-history-file
The path of the news history file.

@item nnspool-active-times-file
@vindex nnspool-active-times-file
The path of the active date file.

@item nnspool-nov-is-evil
@vindex nnspool-nov-is-evil
If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
that it finds.

@item nnspool-sift-nov-with-sed
@vindex nnspool-sift-nov-with-sed
If non-@code{nil}, which is the default, use @code{sed} to get the
relevant portion from the overview file.  If nil, @code{nnspool} will
load the entire file into a buffer and process it there.

@end table

@node nnvirtual
@subsection nnvirtual
@cindex nnvirtual
@cindex virtual groups

An @dfn{nnvirtual group} is really nothing more than a collection of
other groups.

For instance, if you are tired of reading many small group, you can
put them all in one big group, and then grow tired of reading one
big, unwieldy group.  The joys of computing!

You specify @code{nnvirtual} as the method.  The address should be a
regexp to match component groups.

All marks in the virtual group will stick to the articles in the
component groups.  So if you tick an article in a virtual group, the
article will also be ticked in the component group from whence it came.
(And vice versa - marks from the component groups will also be shown in
the virtual group.)

Here's an example nnvirtual method that collects all Andrea Dworkin
newsgroups into one, big, happy newsgroup:

@lisp
(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
@end lisp

The component groups can be native or foreign; everything should work
smoothly, but if your computer explodes, it was probably my fault.

Collecting the same group from several servers might actually be a good
idea if users have set the Distribution header to limit distribution.
If you would like to read @samp{soc.motss} both from a server in Japan
and a server in Norway, you could use the following as the group regexp:

@example
"^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
@end example

This should work kinda smoothly - all articles from both groups should
end up in this one, and there should be no duplicates.  Threading (and
the rest) will still work as usual, but there might be problems with the
sequence of articles.  Sorting on date might be an option here
(@pxref{Selecting a Group}.

One limitation, however - all groups that are included in a virtual
group has to be alive (i.e., subscribed or unsubscribed).  Killed or
zombie groups can't be component groups for nnvirtual groups.

@node nnkiboze
@subsection nnkiboze
@cindex nnkiboze
@cindex kibozing

@dfn{Kibozing} is defined by OED as "grepping through (parts of) the
news feed".  nnkiboze is a backend that will do this for you.  Oh joy!
Now you can grind any @sc{nntp} server down to a halt with useless
requests!  Oh happiness!

The address field of the nnkiboze method is, as with nnvirtual, a regexp
to match groups to be "included" in the nnkiboze group.  There most
similarities between nnkiboze and nnvirtual ends.

In addition to this regexp detailing component groups, an nnkiboze group
must have a score file to say what articles that are to be included in
the group (@pxref{Score Files}).

@kindex M-x nnkiboze-generate-groups
@findex nnkiboze-generate-groups
You must run @kbd{M-x nnkiboze-generate-groups} after creating the
nnkiboze groups you want to have.  This command will take time.  Lots of
time.  Oodles and oodles of time.  Gnus has to fetch the headers from
all the articles in all the components groups and run them through the
scoring process to determine if there are any articles in the groups
that are to be part of the nnkiboze groups.

Please limit the number of component groups by using restrictive
regexps.  Otherwise your sysadmin may become annoyed with you, and the
@sc{nntp} site may throw you off and never let you back in again.
Stranger things have happened.

nnkiboze component groups do not have to be alive - they can be dead,
and they can be foreign.  No restrictions.

@vindex nnkiboze-directory
The generation of an nnkiboze group means writing two files in
@code{nnkiboze-directory}, which is @file{~/News/} by default.  One
contains the @sc{nov} header lines for all the articles in the group,
and the other is an additional @file{.newsrc} file to store information
on what groups that have been searched through to find component
articles.

Articles that are marked as read in the nnkiboze group will have their
@sc{nov} lines removed from the @sc{nov} file.

@node nndir
@subsection nndir
@cindex nndir
@cindex directory groups

If you have a directory that has lots of articles in separate files in
it, you might treat it as a newsgroup.  The files have to have numerical
names, of course.

This might be an opportune moment to mention @code{ange-ftp}, that most
wonderful of all wonderful Emacs packages.  When I wrote @code{nndir}, I
didn't think much about it - a backend to read directories.  Big deal.

@code{ange-ftp} changes that picture dramatically.  For instance, if you
enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
directory name, ange-ftp will actually allow you to read this directory
over at @samp{sina} as a newsgroup.  Distributed news ahoy!

@code{nndir} will use @sc{nov} files if they are present.

@code{nndir} is a "read-only" backend - you can't delete or expire
articles with this method.  You can use @code{nnmh} or @code{nnml} for
whatever you use @code{nndir} for, so you could switch to any of those
methods if you feel the need to have a non-read-only @code{nndir}.

@node nneething
@subsection nneething
@cindex nneething

From the @code{nndir} backend (which reads a single spool-like
directory), it's just a hop and a skip to @code{nneething}, which
pretends that any random directory is a newsgroup. Strange, but true.

When @code{nneething} is presented with a directory, it will scan this
directory and assign article numbers to each file. When you enter such a
group, @code{nneething} must create "headers" that Gnus can use. After
all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
does this in a two-step process. First, it snoops each file in question.
If the file looks like an article (i.e., the first few lines look like
headers), it will use this as the head. If this is just some random file
without a head (eg. a C source file), @code{nneething} will cobble up a
header out of thin air. It will use file ownership, name and date and do
whatever it can with these elements.

All this should happen automatically for you, and you will be presented
with something that looks very much like a newsgroup. Totally like a
newsgroup, to be precise. If you select an article, it will be displayed
in the article buffer, just as usual.

If you select a line that represents a directory, Gnus will pop you into
a new summary buffer for this @code{nneething} group. And so on. You can
traverse the entire disk this way, if you feel like, but remember that
Gnus is not dired, really, and does not intend to be, either.

There are two overall modes to this action - ephemeral or solid. When
doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
will not store information on what files you have read, and what files
are new, and so on. If you create a solid @code{nneething} group the
normal way with @kbd{G m}, Gnus will store a mapping table between
article numbers and file names, and you can treat this group like any
other groups. When you activate a solid @code{nneething} group, you will
be told how many unread articles it contains, etc., etc.

Some variables:

@table @code
@item nneething-map-file-directory
@vindex nneething-map-file-directory
All the mapping files for solid @code{nneething} groups will be stored
in this directory, which defaults to @file{~/.nneething/}.

@item nneething-exclude-files
@vindex nneething-exclude-files
All files that match this regexp will be ignored. Nice to use to exclude
auto-save files and the like, which is what it does by default.

@item nneething-map-file
@vindex nneething-map-file
Name of the map files.
@end table


@node nndoc
@subsection nndoc
@cindex nndoc
@cindex documentation group
@cindex help group

nndoc is a cute little thing that will let you read a single file as a
newsgroup.  Currently supported file types are @code{babyl}, @code{mbox}
and @code{digest}. 

nndoc will not try to change the file or insert any extra headers into
it - it will simply, like, let you use the file as the basis for a
group.  And that's it.

Virtual server variables:

@table @code
@item nndoc-article-type
@vindex nndoc-article-type
This should be one of @code{mbox}, @code{babyl} or @code{digest}. 
@end table

@node Reading Mail
@subsection Reading Mail
@cindex reading mail
@cindex mail

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

@menu
* Creating Mail Groups::         How to create mail groups.
* Fancy Mail Splitting::         Gnus can do hairy splitting of incoming mail.
* Mail & Procmail::              Reading mail groups that procmail create.
* Expiring Old Mail Articles::   Getting rid of unwanted mail.
* Not Reading Mail::             Using mail backends for reading other files.
@end menu

Gnus will read the mail spool when you activate a mail group.  The mail
file is first copied to your home directory.  What happens after that
depends on what format you want to store your mail in.

@menu
* nnmbox::    Using the (quite) standard Un*x mbox.
* nnbabyl::   Many Emacs programs use the rmail babyl format.
* nnml::      Store your mail in a private spool?
* nnmh::      An mhspool-like backend useful for procmail people.
* nnfolder::  Having one file for each group.
@end menu

@vindex nnmail-read-incoming-hook
The mail backends all call @code{nnmail-read-incoming-hook} after
reading new mail.  You can use this hook to notify any mail watch
programs, if you want to.

@vindex nnmail-spool-file
@code{nnmail-spool-file} says where to look for new mail.  If this
variable is @code{nil}, the mail backends will never attempt to fetch
mail by themselves.  It is quite likely that Gnus supports POP-mail.
Set this variable to begin with the string @samp{po:}, and everything
should go smoothly, even though I have never tested this.

@vindex nnmail-use-procmail
If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
look in @code{nnmail-procmail-directory} for incoming mail.  All the
files in that directory that have names ending in
@code{gnus-procmail-suffix} will be considered incoming mailboxes, and
will be searched for new mail.

@vindex nnmail-prepare-incoming-hook
@code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
the new incoming mail, and can be used for, well, anything, really.

@vindex nnmail-tmp-directory
@code{nnmail-tmp-directory} says where to move the incoming mail to
while processing it.  This is usually done in the same directory that
the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
non-@code{nil}, it will be used instead.

@vindex nnmail-delete-incoming
If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
will delete the temporary incoming file after splitting mail into the
proper groups.  This is @code{nil} by default for reasons of security. 

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.

@node Creating Mail Groups
@subsubsection Creating Mail Groups
@cindex creating mail groups

You can make Gnus read your personal, private, secret mail.

You should first set @code{gnus-secondary-select-methods} to, for
instance, @code{((nnmbox ""))}.  When you start up Gnus, Gnus will ask
this backend for what groups it carries (@samp{mail.misc} by default)
and subscribe it the normal way.  (Which means you may have to look for
it among the zombie groups, I guess, all depending on your
@code{gnus-subscribe-newsgroup-method} variable.)

@vindex nnmail-split-methods
Then you should set the variable @code{nnmail-split-methods} to specify
how the incoming mail is to be split into groups.

@lisp
(setq nnmail-split-methods
  '(("mail.junk" "^From:.*Lars Ingebrigtsen")
    ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
    ("mail.other" "")))
@end lisp

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 @samp{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 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-@code{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 @emph{always} be @samp{""} so that it matches any
mails that haven't been matched by any of the other regexps.

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 groups names that it
thinks should carry this mail message.

@vindex nnmail-crosspost
The mail backends all support cross-posting.  If several regexps match,
the mail will be "cross-posted" to all those groups.
@code{nnmail-crosspost} says whether to use this mechanism or not.  Note
that no articles are crossposted to the general (@samp{""}) group. 

@node Fancy Mail Splitting
@subsubsection Fancy Mail Splitting
@cindex mail splitting
@cindex fancy mail splitting

@vindex nnmail-split-fancy
@findex nnmail-split-fancy
If the rather simple, standard method for specifying how to split mail
doesn't allow you to do what you want, you can set
@code{nnmail-split-methods} to @code{nnmail-split-fancy}.  Then you can
play with the @code{nnmail-split-fancy} variable. 

Let's look at an example value of this variable first:

@lisp
;; 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"))")
@end lisp

This variable has the format of a @dfn{split}.  A split is a (possibly)
recursive structure where each split may contain other splits.  Here are
the four possible split syntaxes:

@table @dfn
@item GROUP 
If the split is a string, that will be taken as a group name. 
@item (FIELD VALUE SPLIT)
If the split is a list, and the first element is a string, then that
means that if header FIELD (a regexp) contains VALUE (also a regexp),
then store the message as specified by SPLIT.
@item (| SPLIT...)
If the split is a list, and the first element is @code{|} (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.
@item (& SPLIT...)
If the split is a list, and the first element is @code{&}, then process
all SPLITs in the list.
@end table

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 @code{.*} in the regexps to match partial field names or
words.

@vindex nnmail-split-abbrev-alist
FIELD and VALUE can also be lisp symbols, in that case they are expanded
as specified by the variable @code{nnmail-split-abbrev-alist}.  This is
an alist of cons cells, where the car of the cells contains the key, and
the cdr contains a string.

@node Mail & Procmail
@subsubsection Mail & Procmail
@cindex procmail

Many people use @code{procmail} to split incoming mail into groups.  If
you do that, you should set @code{nnmail-spool-file} to @code{procmail}
to ensure that the mail backends never ever try to fetch mail by
themselves.

This also means that you probably don't want to set
@code{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
@code{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) what groups
exist by hand.

Let's take the @code{nnmh} backend as an example. 

The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.

Go to the group buffer and type @kbd{G m}.  When prompted, answer
@samp{foo} for the name and @samp{nnmh} for the method.  Repeat
twice for the two other groups, @samp{bar} and @samp{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.

@vindex nnmail-procmail-suffix
@vindex nnmail-procmail-directory
If you use @code{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 @code{nnmail-procmail-directory}.  To arrive at the file name to put
the incoming mail in, append @code{nnmail-procmail-suffix} to the group
name.  The mail backends will read the mail from these files.

@vindex nnmail-resplit-incoming
When Gnus reads a file called @file{mail.misc.spool}, this mail will be
put in the @code{mail.misc}, as one would expect.  However, if you want
Gnus to split the mail the normal way, you could set
@code{nnmail-resplit-incoming} to @code{t}.

@vindex nnmail-keep-last-article
If you use @code{procmail}, you should set
@code{nnmail-keep-last-article} to non-@code{nil}, to prevent Gnus from
ever expiring the final article in a mail newsgroup. This is quite,
quite important.


@node Expiring Old Mail Articles
@subsubsection Expiring Old Mail Articles
@cindex article expiry

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 @dfn{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.

@vindex gnus-auto-expirable-newsgroups
You do not have to mark articles as expirable by hand.  Groups that
match the regular expression @code{gnus-auto-expirable-newsgroups} will
have all articles that you read marked as expirable automatically.  All
articles that are marked as expirable have an @samp{E} in the first
column in the summary buffer.

Let's say you subscribe to a couple of mailing lists, and you want the
articles you have read to disappear after a while:

@lisp
(setq gnus-auto-expirable-newsgroups 
      "mail.nonsense-list\\|mail.nice-list")
@end lisp

Another way to have auto-expiry happen is to have the element
@code{auto-expire} in the select method of the group. 

@vindex nnmail-expiry-wait
The @code{nnmail-expiry-wait} variable supplies the default time an
expirable article has to live.  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 @samp{mail.private} group, a one day
expiry period in the @samp{mail.junk} group, and a six day expiry period
everywhere else:

@lisp
(setq nnmail-expiry-wait-function
      (lambda (group)
       (cond ((string= group "mail.private")
               31)
             ((string= group "mail.junk")
               1)
             (t
               6))))
@end lisp

@vindex nnmail-keep-last-article
If @code{nnmail-keep-last-article} is non-@code{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 @code{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. 

Note that at present, Gnus will not actually delete any expirable
articles automatically.  You have to enter one of the expiry functions
(eg. `C-c M-c-x' in the group buffer) to actually run articles through
the expiry process.  Or you can add a call to the expiry function in the
group exit hook.  Gnus will probably do all this automatically in the
future. 

@node Not Reading Mail
@subsubsection Not Reading Mail

If you start using any of the mail backends, they have the annoying
habit of assuming that you want to read mail with them.  This might not
be unreasonable, but it might not be what you want.

If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
will ever attempt to read incoming mail, which should help.

@vindex nnbabyl-get-new-mail
@vindex nnmbox-get-new-mail
@vindex nnml-get-new-mail
@vindex nnmh-get-new-mail
@vindex nnfolder-get-new-mail
This might be too much, if, for instance, you are reading mail quite
happily with @code{nnml} and just want to peek at some old @sc{rmail}
file you have stashed away with @code{nnbabyl}.  All backends have
variables called backend-@code{get-new-mail}.  If you want to disable
the @code{nnbabyl} mail reading, you edit the virtual server for the
group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.

All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
narrowed to the article to be saved before saving it when reading
incoming mail.

@node nnmbox
@subsubsection nnmbox
@cindex nnmbox
@cindex unix mail box

@vindex nnmbox-active-file
@vindex nnmbox-mbox-file
The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
mail.  @code{nnmbox} will add extra headers to each mail article to say
which group it belongs in.

Virtual server settings:

@table @code
@item nnmbox-mbox-file
@vindex nnmbox-mbox-file
The name of the mail box in the user's home directory. 

@item nnmbox-active-file
@vindex nnmbox-active-file
The name of the active file for the mail box.

@item nnmbox-get-new-mail
@vindex nnmbox-get-new-mail
If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
into groups.
@end table

@node nnbabyl
@subsubsection nnbabyl
@cindex nnbabyl
@cindex rmail mbox

@vindex nnbabyl-active-file
@vindex nnbabyl-mbox-file
The @dfn{nnbabyl} backend will use a babyl mail box to store mail.
@code{nnbabyl} will add extra headers to each mail article to say which
group it belongs in.

Virtual server settings:

@table @code
@item nnbabyl-mbox-file
@vindex nnbabyl-mbox-file
The name of the rmail mbox file.

@item nnbabyl-active-file
@vindex nnbabyl-active-file
The name of the active file for the rmail box.

@item nnbabyl-get-new-mail
@vindex nnbabyl-get-new-mail
If non-@code{nil}, @code{nnbabyl} will read incoming mail. 
@end table

@node nnml
@subsubsection nnml
@cindex nnml
@cindex mail @sc{nov} spool

The @dfn{nnml} spool mail format isn't compatible with any other known
format.  It should be used with some caution.

@vindex nnml-directory
If you use this backend, Gnus will split all incoming mail into files;
one file for each mail, and put the articles into the correct
directories under the directory specified by the @code{nnml-directory}
variable.  The default value is @file{~/Mail/}.

You do not have to create any directories beforehand; Gnus will take
care of all that.

If you have a strict limit as to how many files you are allowed to store
in your account, you should not use this backend.  As each mail gets its
own file, you might very well occupy thousands of inodes within a few
weeks.  If this is no problem for you, and it isn't a problem for you
having your friendly systems administrator walking around, madly,
shouting "Who is eating all my inodes?! Who? Who!?!", then you should
know that this is probably the fastest format to use.  You do not have
to trudge through a big mbox file just to read your new mail.

@code{nnml} is probably the slowest backend when it comes to article
splitting.  It has to create lots of files, and it also generates
@sc{nov} databases for the incoming mails.  This makes is the fastest
backend when it comes to reading mail.

Virtual server settings:

@table @code
@item nnml-directory
@vindex nnml-directory
All @code{nnml} directories will be placed under this directory. 

@item nnml-active-file
@vindex nnml-active-file
The active file for the @code{nnml} server.

@item nnml-newsgroups-file
@vindex nnml-newsgroups-file
The @code{nnml} group description file.

@item nnml-get-new-mail
@vindex nnml-get-new-mail
If non-@code{nil}, @code{nnml} will read incoming mail.

@item nnml-nov-is-evil
@vindex nnml-nov-is-evil
If non-@code{nil}, this backend will ignore any @sc{nov} files.  

@item nnml-nov-file-name
@vindex nnml-nov-file-name
The name of the @sc{nov} files.  The default is @file{.overview}. 

@end table

@findex nnml-generate-nov-databases
If your @code{nnml} groups and @sc{nov} files get totally out of whack,
you can do a complete update by typing @kbd{M-x
nnml-generate-nov-databases}.  This command will trawl through the
entire @code{nnml} hierarchy, looking at each and every article, so it
might take a while to complete.

@node nnmh
@subsubsection nnmh
@cindex nnmh
@cindex mh-e mail spool

@code{nnmh} is just like @code{nnml}, except that is doesn't generate
@sc{nov} databases and it doesn't keep an active file.  This makes
@code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
makes it easier to write procmail scripts for.

Virtual server settings:

@table @code
@item nnmh-directory
@vindex nnmh-directory
All @code{nnmh} directories will be located under this directory.

@item nnmh-get-new-mail
@vindex nnmh-get-new-mail
If non-@code{nil}, @code{nnmh} will read incoming mail.

@item nnmh-be-safe
@vindex nnmh-be-safe
If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
sure that the articles in the folder is actually what Gnus think they
are.  It will check date stamps, and stat everything in sight, so
setting this to @code{t} will mean a serious slow-down.  If you never
use anything by Gnus to read the nnmh articles, you do not have to set
this variable to @code{t}. 
@end table

@node nnfolder
@subsubsection nnfolder
@cindex nnfolder
@cindex mbox folders

@code{nnfolder} is a backend for storing each mail group in a separate
file.  Each file is in the standard Un*x mbox format.  @code{nnfolder}
will add extra headers to keep track of article numbers and arrival
dates.

Virtual server settings:

@table @code
@item nnfolder-directory
@vindex nnfolder-directory
All the @code{nnfolder} mail boxes will be stored under this directory. 

@item nnfolder-active-file
@vindex nnfolder-active-file
The name of the active file.

@item nnfolder-newsgroups-file
@vindex nnfolder-newsgroups-file
The name of the group description file.

@item nnfolder-get-new-mail
@vindex nnfolder-get-new-mail
If non-@code{nil}, @code{nnfolder} will read incoming mail.
@end table

@node Group Parameters
@section Group Parameters
@cindex group parameters

Gnus stores all information on a group in a list that is usually known
as the @dfn{group info}.  This list has from three to six elements.
Here's an example info.

@lisp
("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
                  (nnml "private") ((to-address . "ding@@ifi.uio.no")))
@end lisp

The first element is the @dfn{group name}, as Gnus knows the group,
anyway.  The second element is the @dfn{subscription level}, which
normally is a small integer.  The third element is a list of ranges of
read articles.  The fourth element is a list of lists of article marks
of various kinds.  The fifth element is the select method (or virtual
server, if you like).  The sixth element is a list of @dfn{group
parameters}, which is what this section is about.

Any of the last three elements may be missing if they are not required.
In fact, the vast majority of groups will normally only have the first
three elements, which saves quite a lot of cons cells.

At present, there's not much you can put in the group parameters list: 

@table @code
@item to-address
@cindex to-address
If the group parameter list contains an element that looks like
@samp{(to-address .  "some@@where.com")}, that address will be used by
the backend when doing followups and posts.  This is primarily useful in
mail groups that represent mailing lists.  You just set this address to
whatever the list address is.

This trick will actually work whether the group is foreign or not.
Let's say there's a group on the server that is called @samp{fa.4ad-l}.
This is a real newsgroup, but the server has gotten the articles from a
mail-to-news gateway.  Posting directly to this group is therefore
impossible - you have to send mail to the mailing list address instead.

@item to-group
@cindex to-group
IF the group parameter list contains an element like @code{(to-group
. "some.group.name")}, all posts will be sent to that groups.

@item auto-expire
@cindex auto-expire
If this symbol is present in the group parameter list, all articles that
are read will be marked as expirable.  For an alternative approach,
@xref{Expiring Old Mail Articles}.

@item total-expire
@cindex total-expire
If this symbol is present, all read articles will be put through the
expiry process, even if they are not marked as expirable.  Use with
caution. 
@end table

If you want to change the group parameters (or anything else of the
group info) you can use the @kbd{G E} to edit enter a buffer where you
can edit the group info.

You usually don't want to edit the entire group info, so you'd be better
off using the @kbd{G p} command to just edit the group parameters.

@node Listing Groups
@section Listing Groups
@cindex group listing

These commands all list various slices of the groups that are available.

@table @kbd
@item l
@itemx A s
@kindex A s (Group)
@kindex l (Group)
@findex gnus-group-list-groups
List all groups that have unread articles
(@code{gnus-group-list-groups}).  If the numeric prefix is used, this
command will list only groups of level ARG and lower.  By default, it
only lists groups of level five or lower (i.e., just subscribed groups).
@item L
@itemx A u
@kindex A u (Group)
@kindex L (Group)
@findex gnus-group-list-all-groups
List all groups, whether they have unread articles or not
(@code{gnus-group-list-all-groups}).  If the numeric prefix is used,
this command will list only groups of level ARG and lower.  By default,
it lists groups of level seven or lower (i.e., just subscribed and
unsubscribed groups).
@item A k
@kindex A k (Group)
@findex gnus-group-list-killed