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.

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.

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---NNTP, local spool or your mbox file.  All at the same time, if you want to push your luck.

History
*******

GNUS was written by Masanobu UMEDA.  When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.

If you want to investigate the person responsible for this outrage, you can point your (feh!) web browser to 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.

During the first extended alpha period of develpment, the new Gnus was called "(ding) Gnus".  (ding), is, of course, short for 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?)

In any case, after spending all that energy with coming up with a new and spiffy name, we decided that the name was too spiffy, so we renamamed it back again to "Gnus".  But in mixed case.  "Gnus" vs. "GNUS".  New vs. old.

Incidentally, the next Gnus generation will be called "September Gnus", and won't be released until February.  Confused?  You will be.

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?

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, 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. C-u 100 M-x hail-emacs.

Compatibility
=============

Gnus was designed to be fully compatible with 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:

     In a cloud bones of steel.

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

The gnus-uu package has changed drastically. See 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 GNUS internals will probably fail.  To take two examples: Sorting 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.

Old hilit19 code does not work at all.  In fact, you should probably remove all hilit code from all Gnus hooks (gnus-group-prepare-hook, gnus-summary-prepare-hook and 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 expire-kill will no longer work.  As a matter of fact, you should probably remove all old GNUS packages (and other code) when you start using Gnus.  More likely than not, Gnus already does what you have written code to make 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.

Gnus understands all GNUS startup files.

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

Conformity
==========

No rebels without a clue here, ma'am.  We conform to all standards known to (wo)man.  Except for those standards and/or conventions we disagree with, of course.

RFC 822
     There are no known breaches of this standard.

RFC 1036
     There are no known breaches of this standard, either.

Usenet Seal of Approval
     Gnus hasn't been formally through the Seal process, but I have read through the Seal text and I think Gnus would pass.

Son-of-RFC 1036
     We do have some breaches to this one.

     MIME
          Gnus does no MIME handling, and this standard-to-be seems to think that MIME is the bees' knees, so we have major breakage here.

     X-Newsreader
          This is considered to be a "vanity header", while I consider it to be consumer information.  After seeing so many badly formatted articles coming from tin and Netscape I know not to use either of those for posting articles.  I would not have known that if it wasn't for the X-Newsreader header.

     References
          Gnus breaks lines if this header is long.  I infer from RFC1036 that being conservative in what you output is not creating 5000-character lines, so it seems like a good idea to me.  However, this standard-to-be says that whitespace in the References header is to be preserved, so...  It doesn't matter one way or the other to Gnus, so if somebody tells me what The Way is, I'll change it.  Or not.

If you ever see Gnus act noncompliantly to the texts mentioned above, don't hesitate to drop a note to Gnus Towers and let us know.

Emacsen
=======

Gnus should work on :

  * Emacs 19.26 and up.

  * XEmacs 19.12 and up.

  * Mule versions based on Emacs 19.26 and up.

Gnus will absolutely not work on any Emacsen older than that.  Not reliably, at least.

There are some vague differences in what Gnus does, though:

  * The mouse-face on Gnus lines under Emacs and Mule is delimited to certain parts of the lines while they cover the entire line under XEmacs.

  * The same with current-article marking---XEmacs puts an underline under the entire summary line while Emacs and Mule are nicer and kinder.

  * XEmacs features more graphics---a logo and a toolbar.

  * Citation highlighting us better under Emacs and Mule than under XEmacs.

  * Emacs 19.26-19.28 have tangible hidden headers, which can be a bit confusing.

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.  Micro$oft---bah. Amateurs.  I'm much worse.  (Or is that "worser"? "much worser"? "worsest"?)

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

  * Of course, GNUS was written by Masanobu UMEDA.

  * Many excellent functions, especially dealing with scoring and highlighting (as well as the soon-to-come SOUP support) was written by Per Abrahamsen.

  * Innumerable bug fixes were written by Sudish Joseph.

  * gnus-topic was written by Ilja Weis.

  * The refcard was written by Vladimir Alexiev.

  * I stole some pieces from the XGnus distribution by Felix Lee and JWZ.

  * nnfolder has been much enhanced by Scott Byer.

  * The orphan scoring was written by Peter Mutsaers.

  * GNU XEmacs support has been added by Fabrice Popineau.

  * Various bits and pieces, especially dealing with .newsrc files, were suggested and added by Hallvard B Furuseth.

  * Brian Edmonds has written gnus-bbdb.

  * Ricardo Nassif did the proof-reading.

  * Kevin Davidson came up with the name ding, so blame him.

  * Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel Quinlan, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have all contributed code and suggestions.

New Features
============

  * The look of all buffers can be changed by setting format-like variables (see Group Buffer Format and see Summary Buffer Format).

  * Local spool and several NNTP servers can be used at once (see Foreign Groups).

  * You can combine groups into virtual groups (see nnvirtual).

  * You can read a number of different mail formats (see Reading Mail). All the mail backends implement a convenient mail expiry scheme (see Expiring Old Mail Articles).

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

  * 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 (see The Active File).

  * Gnus implements a sliding scale of subscribedness to groups (see Group Levels).

  * You can score articles according to any number of criteria (see Scoring).  You can even get Gnus to find out how to score articles for you (see Adaptive Scoring).

  * Gnus maintains a dribble buffer that is auto-saved the normal Emacs manner, so it should be difficult to lose much data on what you have read if your machine should go down (see Auto Save).

  * Gnus now has its own startup file to avoid cluttering up the .emacs file.

  * You can set the process mark on both groups and articles and perform operations on all the marked items (see Process/Prefix).

  * You can grep through a subset of groups and create a group from the results (see nnkiboze).

  * You can list subsets of groups according to, well, anything (see Listing Groups).

  * You can browse foreign servers and subscribe to groups from those servers (see Browse Foreign Server).

  * Gnus can fetch articles asynchronously on a second connection to the server (see Asynchronous Fetching).

  * You can cache articles locally (see Article Caching).

  * The uudecode functions have been expanded and generalized (see Decoding Articles).

  * You can still post uuencoded articles, which was a little-known feature of GNUS past (see Uuencoding & Posting).

  * Fetching parents (and other articles) now actually works without glitches (see Finding the Parent).

  * Gnus can fetch FAQs and group descriptions (see Group Information).

  * Digests (and other files) can be used as the basis for groups (see nndoc).

  * Articles can be highlighted and customized (see Customizing Articles).

  * URLs and other external references can be buttonized (see Article Buttons).

  * All Gnus buffers can be customized in a difficult fashion (see Windows Configuration).

  * You can click on buttons instead of using the keyboard (see Buttons).

This is, of course, just a short overview of the most important new features.  No, really.  There are tons more.  Yes, we have feeping creaturism in full effect, but nothing too gratuitous, I would hope.

Newest Features
===============

Also known as the todo list.  Sure to be implemented before the next millennium.

Be afraid.  Be very afraid.

  * Native MIME support is something that should be done.

  * trn-like trees.

  * nn-like pick-and-read summary interface.

  * NoCeM support.

  * Frame configuration.

  * Floating point group levels and group bubbling.

  * Automatic re-scan of incoming mail.

  * Buttonize more stuff in the article buffer.

  * A better and simpler method for specifying mail composing methods.

  * Marks for saved, forwarded, etc articles.

  * Speed up caching and adaptive scoring.

  * Gather thread by filling in missing Message-IDs.

  * PGP support.

  * Allow posting through mail-to-news gateways.

  * Speed up massive group massacres.

  * jka-compr isn't fully supported.

  * Create better digests.

  * Do better word-wrap on cited text.

  * Better X-Face support with X-Face databases and stuff.

  * Support SELF-DISCIPLINE pins.

  * Really do unbinhexing.

  * Listing of all active groups.

  * XEmacs toolbar.

  * Do the X-Receipt-To thing.

  * Don't kill summary buffers upon exit from the groups.

  * Allow adaption on secondary marks.

And much, much, much more.  There is more to come than has already been implemented.  (But that's always true, isn't it?)

<URL:http://www.ifi.uio.no/~larsi/sgnus/todo> is where the actual up-to-the-second todo list is located, so if you're really curious, you could point your Web browser over that-a-way.

Terminology
***********

news
     This is what you are supposed to use this thing for---reading news. News is generally fetched from a nearby 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.

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.

reply
     Send a mail to the person who has written what you are reading.

follow up
     Post an article to the current newsgroup responding to the article you are reading.

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.

native
     Gnus will always use one method (and backend) as the native, or default, way of getting news.

foreign
     You can also have any number of foreign groups at the same time.  These are groups that use different backends for getting news.

head
     The top part of an article, where administration information (etc.) is put.

body
     The rest of an article. Everything that is not in the head is in the body.

header
     A line from the head of an article.

headers
     A collection of such lines, or a collection of heads.  Or even a collection of NOV lines.

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.

level
     Each group is subscribed at some 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 subscribed; 6-7 are unsubscribed; 8 are zombies; and 9 are killed.  Commands for listing groups and scanning for new articles will all use the numeric prefix as working level.

killed groups
     No information on killed groups is stored or updated, which makes killed groups much easier to handle than subscribed groups.

zombie groups
     Just like killed groups, only slightly less dead.

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.

bogus groups
     A group that exists in the .newsrc file, but isn't known to the server (i. e.,  it isn't in the active file), is a bogus group. This means that the group probably doesn't exist (any more).

Starting Gnus
*************

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

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

Finding the News
================

The gnus-select-method variable controls how Gnus finds news. This variable should be a list where the first element says how and the second element says 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 news.somewhere.edu NNTP server, you'd say:

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

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

     (setq gnus-select-method '(nnspool ""))

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 NNTPSERVER environment variable.  If that variable isn't set, Gnus will see whether gnus-nntpserver-file (default /etc/nntpserver) has any opinions in the matter.  It that fails as well, Gnus will will try to use the machine that is running Emacs as an NNTP server.  That's a longshot, though.

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

You can also make Gnus prompt you interactively for the name of an NNTP server.  If you give a non-numerical prefix to gnus (i.e., C-u M-x gnus), Gnus will let you choose between the servers in the 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 NNTP server regularly, and are just interested in a couple of groups from a different server, you would be better served by using the 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 .newsrc maintenance much tidier. See Foreign Groups.

A slightly different approach to foreign groups is to set the gnus-secondary-select-methods variable.  The select methods listed in this variable are in many ways just as native as the 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 nnmbox backend to read you mail, you would typically set this variable to

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

The First Time
==============

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

If the variable 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., *.newusers).  (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 gnus-default-subscribed-newsgroups is t, Gnus will just use the normal functions for handling new groups, and not do anything special.

The Server is Down
==================

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!

If you know that the server is definitely down, or you just want to read your mail without bothering with the server at all, you can use the gnus-no-server command to start Gnus.  That might come in handy if you're in a hurry as well.

Slave Gnusii
============

You might want to run more than one Emacs with more than one Gnus at the same time.  If you are using different .newsrc files (eg., if you are using the two different Gnusii to read from two different servers), that is no problem whatsoever.  You just do it.

The problem appears when you want to run two Gnusii that use the same .newsrc file.

To work around that problem some, we here at the Think-Tank at the Gnus Towers have come up with a new concept: Masters and servants.  (We have applied for a patent on this concept, and have taken out a copyright on those words.  If you wish to use those words in conjunction with each other, you have to send $1 per usage instance to me.  Usage of the patent (Master/Slave Relationships In Computer Applications) will be much more expensive, of course.)

Anyways, you start one Gnus up the normal way with M-x gnus (or however you do it).  Each subsequent slave Gnusii should be started with M-x gnus-slave.  These slaves won't save normal .newsrc files, but some slave files that contains information only on what groups have been read in the slave session.  When a master Gnus starts, it will read (and delete) these slave files, incorporating all information from all of them.  (The slave files will be read in the sequence they were created, so the latest changes will have precedence.)

Information from the slave files has, of course, presedence over the information in the normal (i. e., master) .newsrc file.

Fetching a Group
================

It it sometime convenient to be able to just say "I want to read this group and I don't care whether Gnus has been started or not".  This is perhaps more useful for people who write code than for users, but the command gnus-fetch-group provides this functionality in any case.  It takes the group name as a paramenter.

New Groups
==========

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

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

gnus-subscribe-randomly
     Subscribe all new groups randomly.

gnus-subscribe-alphabetically
     Subscribe all new groups alphabetically.

gnus-subscribe-hierarchically
     Subscribe all new groups hierarchically.

gnus-subscribe-interactively
     Subscribe new groups interactively.  This means that Gnus will ask you about all new groups.

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.

A closely related variable is gnus-subscribe-hierarchical-interactive.  (That's quite a mouthful.)  If this variable is non-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 options line at the start of the .newsrc file.  Here's an example:

     options -n !alt.all !rec.all sci.all

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 alt and rec should be ignored, and all groups with names beginning with sci should be subscribed.  Gnus will not use the normal subscription method for subscribing these groups. gnus-subscribe-options-newsgroup-method is used instead.  This variable defaults to gnus-subscribe-alphabetically.

If you don't want to mess with your .newsrc file, you can just set the two variables gnus-options-subscribe and gnus-options-not-subscribe.  These two variables do exactly the same as the .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.

Yet another variable that meddles here is gnus-auto-subscribed-groups.  It works exactly like gnus-options-subscribe, and is therefore really superfluos, but I thought it would be nice to have two of these.  This variable is more meant for setting some ground rules, while the other variable is used more for user fiddling.  By default this variable makes all new groups that come from mail backends (nnml, nnbabyl, nnfolder, nnmbox, and nnmh) subscribed.  If you don't like that, just set this variable to nil.

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

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 gnus-check-new-newsgroups is 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 gnus-save-killed-list to 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 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.

Startup Files
=============

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

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

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

You can also turn off writing the .newsrc file by setting gnus-save-newsrc-file to 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?

If gnus-save-killed-list is 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 gnus-check-new-newsgroups to nil or ask-server if you set this variable to nil (see New Groups).

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

gnus-save-newsrc-hook is called before saving any of the newsrc files, while gnus-save-quick-newsrc-hook is called just before saving the .newsrc.eld file, and gnus-save-standard-newsrc-hook is called just before saving the .newsrc file.  The latter two are commonly used to tern version control on or off.

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 dribble buffer.  This buffer is auto-saved the normal Emacs way.  If your Emacs should crash before you have saved the .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.

If gnus-use-dribble-file is nil, Gnus won't create and maintain a dribble buffer.  The default is t.

Gnus will put the dribble file(s) in gnus-dribble-directory.  If this variable is nil, which it is by default, Gnus will dribble into the same directory as the .newsrc file is located.  (This is normally the user's home directory.)

The Active File
===============

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 NNTP server.

Before examining the active file, Gnus deletes all lines that match the regexp 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 nil by default, and will slow down active file handling somewhat if you set it to anything else.

The active file can be rather Huge, so if you have a slow network, you can set gnus-read-active-file to nil to prevent Gnus from reading the active file.  This variable is t by default.

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 nil will probably make Gnus slower, not faster.  At present, having this variable nil will slow Gnus down considerably, unless you read news over a 2400 baud modem.

This variable can also have the value 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 LIST ACTIVE group command), on others this is not fast at all.  In any case, some should be faster than nil, and is certainly faster than t over slow lines.

If this variable is nil, Gnus will as for group info in total lock-step, which isn't very fast.  If it is 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 LIST ACTIVE group command, this isn't very nice to the server.

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

Startup Variables
=================

gnus-load-hook
     A hook that is run while Gnus is being loaded.  Note that this hook will normally be run just once in each Emacs session, no matter how many times you start Gnus.

gnus-startup-hook
     A hook that is run after starting up Gnus successfully.

gnus-check-bogus-newsgroups
     If non-nil, Gnus will check for and delete all bogus groups at startup.  A bogus group is a group that you have in your .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 (see Group Maintenance).

gnus-inhibit-startup-message
     If non-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.

gnus-no-groups-message
     Message displayed by Gnus when no groups are available.

The Group Buffer
****************

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

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:

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

Quite simple, huh?

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

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

(All these format variables can also be random elisp forms.  In that case, they will be evaled to insert the required lines.)

(All these format variables can also be random elisp forms.  In that case, they will be evaled to insert the required lines.)

In addition to the normal "padding" specs that format supports (eg. %7d), specifications like %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 "%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:

M
     Only marked articles.

S
     Whether the group is subscribed.

L
     Level of subscribedness.

N
     Number of unread articles.

I
     Number of dormant articles.

T
     Number of ticked articles.

R
     Number of read articles.

t
     Total number of articles.

y
     Number of unread, unticked, non-dormant articles.

i
     Number of ticked and dormant articles.

g
     Full group name.

G
     Group name.

D
     Newsgroup description.

o
     Moderated.

O
     Moderated.

s
     Select method.

n
     Select from where.

z
     A string that looks like <%s:%n> if a foreign select method is used.

u
     User defined specifier.  The next character in the format string should be a letter.  GNUS will call the function gnus-user-format-function-X, where X is the letter following %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.

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

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

S
     Default news server.

M
     Default select method.

Group Maneuvering
=================

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

n
     Go to the next group that has unread articles (gnus-group-next-unread-group).

p
DEL
     Go to the previous group group that has unread articles (gnus-group-prev-unread-group).

N
     Go to the next group (gnus-group-next-group).

P
     Go to the previous group (gnus-group-prev-group).

M-p
     Go to the next unread group on the same level (or lower) (gnus-group-next-unread-group-same-level).

M-n
     Go to the previous unread group on the same level (or lower) (gnus-group-prev-unread-group-same-level).

Three commands for jumping to groups:

j
     Jump to a group (and make it visible if it isn't already) (gnus-group-jump-to-group).  Killed groups can be jumped to, just like living groups.

,
     Jump to the unread group with the lowest level (gnus-group-best-unread-group).

.
     Jump to the first group with unread articles (gnus-group-first-unread-group).

If gnus-group-goto-unread is 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.  The default is t.

Selecting a Group
=================

SPACE
     Select the current group, switch to the summary buffer and display the first unread article (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 N, Gnus will fetch N number of articles.  If N is positive, fetch the N newest articles, if N is negative, fetch the ABS(N) oldest articles.

RET
     Select the current group and switch to the summary buffer (gnus-group-select-group).  Takes the same arguments as gnus-group-read-group---the only difference is that this command does not display the first unread article automatically upon group entry.

M-RET
     This does the same as the command above, but tries to do it with the minimum amount off fuzz (gnus-group-quick-select-group).  No scoring/killing will be performed, there will be no highlights and no expunging.  This might be useful if you're in a real hurry and have to enter some humongous groups.

c
     Mark all unticked articles in this group as read (gnus-group-catchup-current).

C
     Mark all articles in this group, even the ticked ones, as read (gnus-group-catchup-current-all).

The gnus-large-newsgroup variable says what Gnus should consider to be a big group.  This is 200 by default.  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 (-n), the n oldest articles will be fetched.  If it is positive, the n articles that have arrived most recently will be fetched.

If gnus-auto-select-first is non-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 nil in gnus-select-group-hook, which is called when a group is selected.

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

Each function takes two threads and return non-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:

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

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

Subscription Commands
=====================

S t
u
     Toggle subscription to the current group (gnus-group-unsubscribe-current-group).

S s
U
     Prompt for a group to subscribe, and then subscribe it.  If it was subscribed already, unsubscribe it instead (gnus-group-unsubscribe-group).

S k
C-k
     Kill the current group (gnus-group-kill-group).

S y
C-y
     Yank the last killed group (gnus-group-yank-group).

S w
C-w
     Kill all groups in the region (gnus-group-kill-region).

S z
     Kill all zombie groups (gnus-group-kill-all-zombies).

Also see Group Levels.

Group Levels
============

All groups have a level of 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 (see Listing Groups), or to just check for new articles in groups on a given level or lower (see Misc Group Stuff).

S l
     Set the level of the current group.  If a numeric prefix is given, the next N groups will have their levels set.  The user will be prompted for a level.

Gnus considers groups on between levels 1 and gnus-level-subscribed (inclusive) (default 5) to be subscribed, gnus-level-subscribed (exclusive) and gnus-level-unsubscribed (inclusive) (default 7) to be unsubscribed, gnus-level-zombie to be zombies (walking dead) (default 8) and gnus-level-killed to be killed (default 9), 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.  Better yet, don't touch them at all unless you know exactly what you're doing.

Two closely related variables are gnus-level-default-subscribed (default 3) and gnus-level-default-unsubscribed (default 6), 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.

If gnus-keep-same-level is non-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.

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

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

Marking Groups
==============

If you want to perform some command 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 a command on several groups.  You simply mark the groups first with the process mark and then execute the command.

#
M m
     Set the mark on the current group (gnus-group-mark-group).

M-#
< u
     Remove the mark from the current group (gnus-group-unmark-group).

M w
     Mark all groups between point and mark (gnus-group-mark-region).

Also see Process/Prefix.

Foreign Groups
==============

A 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 NNTP server, it could be a virtual group, or it could be your own personal mail group.

A foreign group (or any group, really) is specified by a name and a select method.  To take the latter first, a select method is a list where the first element says what backend to use (eg. nntp, nnspool, nnml) and the second element is the server name.  There may be additional elements in the select method, where the value may have special meaning for the backend in question.

One could say that a select method defines a virtual server---so we do just that (see The Server Buffer).

The name of the group is the name the backend will recognize the group as.

For instance, the group soc.motss on the NNTP server some.where.edu will have the name soc.motss and select method (nntp "some.where.edu").  Gnus will call this group, in all circumstances, nntp+some.where.edu:soc.motss, even though the nntp backend just knows this group as 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:

G m
     Make a new group (gnus-group-make-group).  Gnus will prompt you for a name, a method and possibly an address.  For an easier way to subscribe to NNTP groups, see Browse Foreign Server.

G r
     Rename the current group to something else (gnus-group-rename-group).  This is legal only on some groups -- mail groups mostly.  This command might very well be quite slow on some backends.

G e
     Enter a buffer where you can edit the select method of the current group (gnus-group-edit-group-method).

G p
     Enter a buffer where you can edit the group parameters (gnus-group-edit-group-parameters).

G E
     Enter a buffer where you can edit the group info (gnus-group-edit-group).

G d
     Make a directory group.  You will be prompted for a directory name (gnus-group-make-directory-group).

G h
     Make the Gnus help group (gnus-group-make-help-group).

G a
     Make a Gnus archive group (gnus-group-make-archive-group).  By default a group pointing to the most recent articles will be created (gnus-group-recent-archibe-directory), but given a prefix, a full group will be created from from gnus-group-archive-directory.

G k
     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 (gnus-group-make-kiboze-group).

G D
     Read a random directory as if with were a newsgroup with the nneething backend (gnus-group-enter-directory).

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

G DEL
     This function will delete the current group (gnus-group-delete-group).  If given a prefix, this function will actually delete all the articles in the group, and forcibly remove the group itself from the face of the Earth.  Use a prefix only if you are sure of what you are doing.

G V
     Make a new, fresh, empty nnvirtual group (gnus-group-make-empty-virtual).

G v
     Add the current group to an nnvirtual group (gnus-group-add-to-virtual).  Uses the process/prefix convention.

The different methods all have their peculiarities, of course.

If the 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 NNTP servers.

nntp
----

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

If the NNTP server is located at a non-standard port, setting the third element of the select method to this port number should allow you to connect to the right port.  You'll have to edit the group info for that (see Foreign Groups).

The name of the foreign group can be the same as a native group.  In fact, you can subscribe to the same group from as many different servers you feel like.  There will be no name collisions.

The following variables can be used to create a virtual nntp server:

nntp-server-opened-hook
     nntp-server-opened-hook is run after a connection has been made. It can be used to send commands to the NNTP server after it has been contacted.  By default is sends the command MODE READER to the server with the nntp-send-mode-reader function.  Another popular function is nntp-send-authinfo, which will prompt you for an NNTP password and stuff.

nntp-maximum-request
     If the NNTP server doesn't support NOV headers, this backend will collect headers by sending a series of head commands.  To speed things up, the backend sends lots of these commands without waiting for reply, and then reads all the replies.  This is controlled by the nntp-maximum-request variable, and is 400 by default.  If your network is buggy, you should set this to 1.

nntp-connection-timeout
     If you have lots of foreign nntp groups that you connect to regularly, you're sure to have problems with NNTP servers not responding properly, or being too loaded to reply within reasonable time.  This is can lead to awkward problems, which can be helped somewhat by setting nntp-connection-timeout.  This is an integer that says how many seconds the nntp backend should wait for a connection before giving up.  If it is nil, which is the default, no timeouts are done.

nntp-server-hook
     This hook is run as the last step when connecting to an NNTP server.

nntp-address
     The address of the remote system running the NNTP server.

nntp-port-number
     Port number to connect to when using the nntp-open-network-stream connect function.

nntp-buggy-select
     Set this to non-nil if your select routine is buggy.

nntp-nov-is-evil
     If the NNTP server does not support NOV, you could set this variable to t, but nntp usually checks whether NOV can be used automatically.

nntp-xover-commands
     List of strings that are used as commands to fetch NOV lines from a server.  The default value of this variable is ("XOVER" "XOVERVIEW").

nntp-nov-gap
     nntp normally sends just one big request for NOV lines to the server.  The server responds with one huge list of lines.  However, if you have read articles 2-5000 in the group, and only want to read article 1 and 5001, that means that nntp will fetch 4999 NOV lines that you do not want, and will not use.  This variable says how big a gap between two consecutive articles is allowed to be before the XOVER request is split into several request.  Note that if your network is fast, setting this variable to a really small number means that fetching will probably be slower.  If this variable is nil, nntp will never split requests.

nntp-prepare-server-hook
     A hook run before attempting to connect to an NNTP server.

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

nntp-warn-about-losing-connection
     If this variable is non-nil, some noise will be made when a server closes connection.

nnspool
-------

Subscribing to a foreign group from the local spool is extremely easy, and might be useful, for instance, to speed up reading groups like alt.binaries.pictures.furniture.

Anyways, you just specify nnspool as the method and "" (or anything else) as the address.

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

nnspool-inews-program
     Program used to post an article.

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

nnspool-spool-directory
     Where nnspool looks for the articles.  This is normally /usr/spool/news/.

nnspool-nov-directory
     Where nnspool will look for NOV files.  This is normally /usr/spool/news/over.view/.

nnspool-lib-dir
     Where the news lib dir is (/usr/lib/news/ by default).

nnspool-active-file
     The path of the active file.

nnspool-newsgroups-file
     The path of the group description file.

nnspool-history-file
     The path of the news history file.

nnspool-active-times-file
     The path of the active date file.

nnspool-nov-is-evil
     If non-nil, nnspool won't try to use any NOV files that it finds.

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

nnvirtual
---------

An 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 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:

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

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 soc.motss both from a server in Japan and a server in Norway, you could use the following as the group regexp:

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

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

nnkiboze
--------

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 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 (see Scoring).

You must run 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 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.

The generation of an nnkiboze group means writing two files in nnkiboze-directory, which is ~/News/ by default.  One contains the NOV header lines for all the articles in the group, and the other is an additional .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 NOV lines removed from the NOV file.

nndir
-----

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 ange-ftp, that most wonderful of all wonderful Emacs packages.  When I wrote nndir, I didn't think much about it---a backend to read directories.  Big deal.

ange-ftp changes that picture dramatically.  For instance, if you enter "/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 sina as a newsgroup.  Distributed news ahoy!

nndir will use NOV files if they are present.

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

nneething
---------

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

When nneething is presented with a directory, it will scan this directory and assign article numbers to each file. When you enter such a group, nneething must create "headers" that Gnus can use. After all, Gnus is a newsreader, in case you're forgetting. 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), 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 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., 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 nneething group the normal way with 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 nneething group, you will be told how many unread articles it contains, etc., etc.

Some variables:

nneething-map-file-directory
     All the mapping files for solid nneething groups will be stored in this directory, which defaults to ~/.nneething/.

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.

nneething-map-file
     Name of the map files.

nndoc
-----

nndoc is a cute little thing that will let you read a single file as a newsgroup.  Currently supported file types are babyl, mbox and 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:

nndoc-article-type
     This should be one of mbox, babyl or digest.

Reading Mail
------------

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

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.

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

nnmail-spool-file says where to look for new mail.  If this variable is 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 po:, and everything should go smoothly, even though I have never tested this.

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

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

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., ~/Mail/), but if this variable is non-nil, it will be used instead.

nnmail-movemail-program is executed to move mail from the user's inbox to her home directory. The default is "movemail".

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

If you are a member of a couple of mailing list, you will sometime receive two copies of the same mail. This can be quite annoying, so nnmail checks for and discards any duplicates it might find. To do this, it keeps a cache of old Message-IDs - nnmail-message-id-cache-file, which is ~/.nnmail-cache by default. The approximate maximum number of Message-IDs stored there is controlled by the nnmail-message-id-cache-length variable, which is 1000 by default. (So 1000 Message-IDs will be stored.) If all this sounds scary to you, you can set nnmail-delete-duplicates to nil (which is what it is by default), and nnmail won't do any duplicate checking.

Here's a neat feature: If you know that the recipient reads her mail with Gnus, and that she has nnmail-delete-duplicates set to t, you can send her as many insults as you like, just by using a Message-ID of a mail that you know that she's already received. Think of all the fun! She'll never see any of it! Whee!

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.

Creating Mail Groups
....................

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

You should first set gnus-secondary-select-methods to, for instance, ((nnmbox "")).  When you start up Gnus, Gnus will ask this backend for what groups it carries (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 gnus-subscribe-newsgroup-method variable.)

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

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

This variable is a list of lists, where the first element of each of these lists is the name of the mail group (they do not have to be called something beginning with mail, by the way), and the second element is a regular expression used on the header of each mail to determine if it belongs in this mail group.

The second element can also be a function.  In that case, it will be called narrowed to the headers with the first element of the rule as the argument.  It should return a non-nil value if it thinks that the mail belongs in that group.

The last of these groups should always be a general one, and the regular expression should always be "" so that it matches any mails that haven't been matched by any of the other regexps.

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.

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

Fancy Mail Splitting
....................

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

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

     ;; Messages from the mailer daemon are not crossposted to any of
     ;; the ordinary groups.  Warnings are put in a separate group
     ;; from real errors.
     (| ("from" mail (| ("subject" "warn.*" "mail.warning")
     		   "mail.misc"))
        ;; Non-error messages are crossposted to all relevant
        ;; groups, but we don't crosspost between the group for the
        ;; (ding) list and the group for other (ding) related mail.
        (& (| (any "ding@ifi\\.uio\\.no" "ding.list")
     	 ("subject" "ding" "ding.misc"))
           ;; Other mailing lists...
           (any "procmail@informatik\\.rwth-aachen\\.de" "procmail.list")
           (any "SmartList@informatik\\.rwth-aachen\\.de" "SmartList.list")
           ;; People...
           (any "larsi@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
        ;; Unmatched mail goes to the catch all group.
        "misc.misc"))")

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

GROUP
     If the split is a string, that will be taken as a group name.

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

(| SPLIT...)
     If the split is a list, and the first element is | (vertical bar), then process each SPLIT until one of them matches.  A SPLIT is said to match if it will cause the mail message to be stored in one or more groups.

(& SPLIT...)
     If the split is a list, and the first element is &, then process all SPLITs in the list.

In these splits, FIELD must match a complete field name.  VALUE must match a complete word according to the fundamental mode syntax table. You can use .* in the regexps to match partial field names or words.

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

Mail & Procmail
...............

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

This also means that you probably don't want to set nnmail-split-methods either, which has some, perhaps, unexpected side effects.

When a mail backend is queried for what groups it carries, it replies with the contents of that variable, along with any groups it has figured out that it carries by other means.  None of the backends (except nnmh) actually go out to the disk and check what groups actually exist.  (It's not trivial to distinguish between what the user thinks is a basis for a newsgroup and what is just a plain old file or directory.)

This means that you have to tell Gnus (and the backends) what groups exist by hand.

Let's take the nnmh backend as an example.

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

Go to the group buffer and type G m.  When prompted, answer foo for the name and nnmh for the method.  Repeat twice for the two other groups, bar and mail.baz.  Be sure to include all your mail groups.

That's it.  You are now set to read your mail.  An active file for this method will be created automatically.

If you use nnfolder or any other backend that store more than a single article in each file, you should never have procmail add mails to the file that Gnus sees.  Instead, procmail should put all incoming mail in nnmail-procmail-directory.  To arrive at the file name to put the incoming mail in, append nnmail-procmail-suffix to the group name.  The mail backends will read the mail from these files.

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

If you use procmail to split things directory into an nnmh directory (which you shouldn't do), you should set nnmail-keep-last-article to non-nil to prevent Gnus from ever expiring the final article in a mail newsgroup. This is quite, quite important.

Expiring Old Mail Articles
..........................

Traditional mail readers have a tendency to remove mail articles when you mark them as read, in some way.  Gnus takes a fundamentally different approach to mail reading.

Gnus basically considers mail just to be news that has been received in a rather peculiar manner.  It does not think that it has the power to actually change the mail, or delete any mail messages.  If you enter a mail group, and mark articles as "read", or kill them in some other fashion, the mail articles will still exist on the system.  I repeat: Gnus will not delete your old, read mail.  Unless you ask it to, of course.

To make Gnus get rid of your unwanted mail, you have to mark the articles as expirable.  This does not mean that the articles will disappear right away, however.  In general, a mail article will be deleted from your system if, 1) it is marked as expirable, AND 2) it is more than one week old.  If you do not mark an article as expirable, it will remain on your system until hell freezes over.  This bears repeating one more time, with some spurious capitalizations: IF you do NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.

You do not have to mark articles as expirable by hand.  Groups that match the regular expression gnus-auto-expirable-newsgroups will have all articles that you read marked as expirable automatically.  All articles that are marked as expirable have an 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:

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

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

The 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 mail.private group, a one day expiry period in the mail.junk group, and a six day expiry period everywhere else:

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

If nnmail-keep-last-article is non-nil, Gnus will never expire the final article in a mail newsgroup.  This is to make life easier for procmail users.

By the way, that line up there about Gnus never expiring non-expirable articles is a lie.  If you put total-expire in the group parameters, articles will not be marked as expirable, but all read articles will be put through the expiry process.  Use with extreme caution.  Even more dangerous is the gnus-total-expirable-newsgroups variable.  All groups that match this regexp will have all read articles put through the expiry process, which means that all old mail articles in the groups in question will be deleted after a while.  Use with extreme caution, and don't come crying to me when you discover that the regexp you used matched the wrong group and all your important mail has disappeared.  Be a man!  Or a woman!  Whatever you feel more comfortable with!  So there!

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 nnmail-spool-file to nil, none of the backends will ever attempt to read incoming mail, which should help.

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

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

nnmbox
......

The nnmbox backend will use the standard Un*x mbox file to store mail.  nnmbox will add extra headers to each mail article to say which group it belongs in.

Virtual server settings:

nnmbox-mbox-file
     The name of the mail box in the user's home directory.

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

nnmbox-get-new-mail
     If non-nil, nnmbox will read incoming mail and split it into groups.

nnbabyl
.......

The nnbabyl backend will use a babyl mail box (aka. rmail mbox) to store mail. nnbabyl will add extra headers to each mail article to say which group it belongs in.

Virtual server settings:

nnbabyl-mbox-file
     The name of the rmail mbox file.

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

nnbabyl-get-new-mail
     If non-nil, nnbabyl will read incoming mail.

nnml
....

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

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 nnml-directory variable.  The default value is ~/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.

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

Virtual server settings:

nnml-directory
     All nnml directories will be placed under this directory.

nnml-active-file
     The active file for the nnml server.

nnml-newsgroups-file
     The nnml group description file.

nnml-get-new-mail
     If non-nil, nnml will read incoming mail.

nnml-nov-is-evil
     If non-nil, this backend will ignore any NOV files.

nnml-nov-file-name
     The name o