\input texinfo @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
-@setfilename gnus
-@settitle (ding) Gnus 1.0 Manual
+@setfilename gnus.info
+@settitle September Gnus Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@ifinfo
-This file documents GNUS, the GNU Emacs newsreader.
+This file documents Gnus, the GNU Emacs newsreader.
-Copyright (C) 1989, 1990, 1993 Free Software Foundation, Inc.
+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
into another language, under the above conditions for modified versions.
@end ifinfo
+@iftex
+
@titlepage
-@title Gnus Manual
+@title September Gnus Manual
-@author by Lars Ingebrigtsen
+@author by Lars Magne Ingebrigtsen
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1989, 1990, 1993 Free Software Foundation, Inc.
+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
@end titlepage
@page
-@node Top
-@top The Gnus News Reader
+@end iftex
-You can read news (and mail) from within Emacs by using (ding) Gnus. The
-news can be gotten by any nefarious means you can think of - NNTP, local
-spool, mail spool. All at the same time, if you want to push your luck.
+@node Top
+@top The Gnus Newsreader
-This manual documents (ding) Gnus 0.11.
+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:: Treating groups.
-* The Summary Buffer:: Reading articles.
-* The Article Buffer:: Doing stuff to articles.
-* Various:: General options.
+* 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.
+* Scoring:: Assigning values to articles.
+* Various:: General purpose settings.
* Customization:: Tailoring Gnus to your needs.
* Troubleshooting:: What you might try if things do not work.
-* Reporting Bugs:: Bugs? What bugs?!
-* Index:: Index.
+* The End:: Farewell and goodbye.
+* Appendices:: Technical stuff, Emacs intro, FAQ
+* Index:: Variable, function and concept index.
* Key Index:: Key Index.
@end menu
@node History
@chapter History
-GNUS was written by Masanobu UMEDA. When autumn crept up in '94, Lars
-Ingebrigtsen grew bored and decided to write (ding) Gnus.
+@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.
+
+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.
-(ding) Gnus is based on GNUS 4.1 and includes bits and pieces by Per
-Abrahamsen, Sudish Joseph, Felix Lee and jwz.
+During the first extended alpha period of develpment, the new Gnus was
+called "(ding) Gnus". @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?)
-The recommended pronounciation 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.
+In any case, after spending all that energy with coming up with a new
+and spiffy name, we decided that the name was @emph{too} spiffy, so we
+renamamed it back again to "Gnus". But in mixed case. "Gnus" vs.
+"@sc{gnus}". New vs. old.
-"(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?)
+Incidentally, the next Gnus generation will be called "September Gnus",
+and won't be released until February. Confused? You will be.
@menu
-* Compatibility:: Just how compatible is (ding) Gnus with GNUS?
-* New Features:: A short description of all the new stuff in Gnus.
+* Why?:: What's the point of Gnus?
+* Compatibility:: Just how compatible is Gnus with @sc{gnus}?
+* Conformity:: Gnus tries to conform to all standards.
+* Emacsen:: Gnus can be run on a few modern Emacsen.
+* Contributors:: Oodles of people.
+* New Features:: Pointers to some of 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?
+
+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. @kbd{C-u 100 M-x hail-emacs}.
+
@node Compatibility
@section Compatibility
-(ding) Gnus was designed to be fully compatible with GNUS. Almost all
-key binding have been kept. More key binding have been added, of course,
-but only in one or two obscure cases have key bindings been changed.
+@cindex compatibility
+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 Gnus. More likely than not, 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 GNUS startup files.
+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 GNUS
-internals should suffer no problems. If problems occur, please let me
-know (@kbd{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}).
+
+
+@node Conformity
+@section 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.
+
+@table @strong
+
+@item RFC 822
+There are no known breaches of this standard.
+
+@item RFC 1036
+There are no known breaches of this standard, either.
+
+@item 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.
+
+@item Son-of-RFC 1036
+We do have some breaches to this one.
+
+@table @emph
+@item 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.
+@item 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 @code{tin} and @code{Netscape} I know not to use either of
+those for posting articles. I would not have known that if it wasn't
+for the @code{X-Newsreader} header.
+@item 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 @code{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.
+@end table
+
+@end table
+
+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.
+
+
+@node Emacsen
+@section Emacsen
+@cindex Emacsen
+@cindex XEmacs
+@cindex Mule
+@cindex Emacs
+
+Gnus should work on :
+
+@itemize @bullet
+
+@item
+Emacs 19.26 and up.
+
+@item
+XEmacs 19.12 and up.
+
+@item
+Mule versions based on Emacs 19.26 and up.
+
+@end itemize
+
+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:
+
+@itemize @bullet
+
+@item
+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.
+
+@item
+The same with current-article marking---XEmacs puts an underline under
+the entire summary line while Emacs and Mule are nicer and kinder.
+
+@item
+XEmacs features more graphics---a logo and a toolbar.
+
+@item
+Citation highlighting us better under Emacs and Mule than under XEmacs.
+
+@item
+Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
+confusing.
+
+@end itemize
+
+
+@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. Micro$oft---bah.
+Amateurs. I'm @emph{much} worse. (Or is that "worser"? "much worser"?
+"worsest"?)
+
+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
+@code{gnus-topic} was written by Ilja Weis.
+@item
+The refcard was written by Vladimir Alexiev.
+@item
+I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
+@item
+@code{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, were
+suggested and added by Hallvard B Furuseth.
+@item
+Brian Edmonds has written @code{gnus-bbdb}.
+@item
+Ricardo Nassif did the proof-reading.
+@item
+Kevin Davidson came up with the name @dfn{ding}, so blame him.
+@item
+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.
+@end itemize
-However, code that depends on the buffers looking a particular way will
-almost invaribaly fail. For instance, the summary buffer no longer
-displays article numbers by default.
@node New Features
@section New Features
+@cindex new features
+
+@itemize @bullet
-The look of all buffers can be changed by setting format-like variables.
+@item
+The look of all buffers can be changed by setting format-like variables
+(@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
-Local spool and several NNTP servers can be used at once. Virtual
-groups and private mail groups are featured.
+@item
+Local spool and several @sc{nntp} servers can be used at once
+(@pxref{Foreign Groups}).
+
+@item
+You can combine groups into virtual groups (@pxref{nnvirtual}).
+
+@item
+You can read a number of different mail formats (@pxref{Reading Mail}).
+All the mail backends implement a convenient mail expiry scheme
+(@pxref{Expiring Old Mail Articles}).
+@item
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.
+their roots (thereby gathering loose sub-threads into one thread) or it
+can go back and retrieve enough headers to build a complete thread
+(@pxref{Customizing Threading}).
+@item
Killed groups can be displayed in the group buffer, and you can read
them as well.
-Gnus can do partial updates of new articles - you do not have to
-retrieve the entire active file just to check for new articles in a few
-groups.
+@item
+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
+(@pxref{The Active File}).
-Gnus implements a sliding scale of subscribedness to groups.
+@item
+Gnus implements a sliding scale of subscribedness to groups
+(@pxref{Group Levels}).
-The approach to killing has been changed. Instead of simply killing or
-not, you can score articles for easier reading.
+@item
+You can score articles according to any number of criteria
+(@pxref{Scoring}). You can even get Gnus to find out how to score
+articles for you (@pxref{Adaptive Scoring}).
+
+@item
+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 (@pxref{Auto Save}).
+
+@item
+Gnus now has its own startup file to avoid cluttering up the
+@file{.emacs} file.
+
+@item
+You can set the process mark on both groups and articles and perform
+operations on all the marked items (@pxref{Process/Prefix}).
+
+@item
+You can grep through a subset of groups and create a group from the
+results (@pxref{nnkiboze}).
+
+@item
+You can list subsets of groups according to, well, anything
+(@pxref{Listing Groups}).
+
+@item
+You can browse foreign servers and subscribe to groups from those
+servers (@pxref{Browse Foreign Server}).
+
+@item
+Gnus can fetch articles asynchronously on a second connection to the
+server (@pxref{Asynchronous Fetching}).
+
+@item
+You can cache articles locally (@pxref{Article Caching}).
+
+@item
+The uudecode functions have been expanded and generalized
+(@pxref{Decoding Articles}).
+
+@item
+You can still post uuencoded articles, which was a little-known feature
+of @sc{gnus} past (@pxref{Uuencoding & Posting}).
+
+@item
+Fetching parents (and other articles) now actually works without
+glitches (@pxref{Finding the Parent}).
+
+@item
+Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
+
+@item
+Digests (and other files) can be used as the basis for groups
+(@pxref{nndoc}).
+
+@item
+Articles can be highlighted and customized (@pxref{Customizing
+Articles}).
+
+@item
+URLs and other external references can be buttonized (@pxref{Article
+Buttons}).
+
+@item
+All Gnus buffers can be customized in a difficult fashion
+(@pxref{Windows Configuration}).
+
+@item
+You can click on buttons instead of using the keyboard
+(@pxref{Buttons}).
+
+@end itemize
+
+This is, of course, just a @emph{short} overview of the @emph{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.
+
+
+@node Newest Features
+@section Newest Features
+@cindex todo
+
+Also known as the @dfn{todo list}. Sure to be implemented before the
+next millennium.
+
+Be afraid. Be very afraid.
+
+@itemize @bullet
+@item
+Native @sc{mime} support is something that should be done.
+@item
+@code{trn}-like trees.
+@item
+@code{nn}-like pick-and-read summary interface.
+@item
+NoCeM support.
+@item
+Frame configuration.
+@item
+Floating point group levels and group bubbling.
+@item
+Automatic re-scan of incoming mail.
+@item
+Buttonize more stuff in the article buffer.
+@item
+A better and simpler method for specifying mail composing methods.
+@item
+Marks for saved, forwarded, etc articles.
+@item
+Speed up caching and adaptive scoring.
+@item
+Gather thread by filling in missing Message-IDs.
+@item
+PGP support.
+@item
+Allow posting through mail-to-news gateways.
+@item
+Speed up massive group massacres.
+@item
+@code{jka-compr} isn't fully supported.
+@item
+Create better digests.
+@item
+Do better word-wrap on cited text.
+@item
+Better X-Face support with X-Face databases and stuff.
+@item
+Support SELF-DISCIPLINE pins.
+@item
+Really do unbinhexing.
+@item
+Listing of all active groups.
+@item
+XEmacs toolbar.
+@item
+Do the X-Receipt-To thing.
+@item
+Don't kill summary buffers upon exit from the groups.
+@item
+Allow adaption on secondary marks.
+@end itemize
+
+And much, much, much more. There is more to come than has already been
+implemented. (But that's always true, isn't it?)
+
+@code{<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.
+
+@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.
+@item bogus groups
+@cindex bogus groups
+A group that exists in the @file{.newsrc} file, but isn't known to the
+server (i. e., it isn't in the active file), is a @emph{bogus group}.
+This means that the group probably doesn't exist (any more).
+@end table
@node Starting Up
@chapter Starting Gnus
+@cindex starting up
@kindex M-x gnus
-If your systems administrator has set thing up properly, starting Gnus
-and reading news is extremely easy - you just type @kbd{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.
-* First Time:: What does Gnus do the first time you start it?
+* The First Time:: What does Gnus do the first time you start it?
* The Server is Down:: How can I read my mail then?
+* Slave Gnusii:: You can have more than one Gnus active at a time.
+* Fetching a Group:: Starting Gnus just to read a group.
* New Groups:: What is Gnus supposed to do with new groups?
-* Startup Files:: Those pesky startup files - @file{.newsrc}.
+* 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.
@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 "how" and
-the second element says "where". This server is is your @dfn{local
-server}. All other servers are @dfn{foreign servers}.
+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 NNTP
-server "news.friendly.server", you'd say:
+For instance, if you want to get your daily dosage of news from the
+@samp{news.somewhere.edu} @sc{nntp} server, you'd say:
-@example
-(setq gnus-select-method '(nntp "news.friendly.server"))
-@end example
+@lisp
+(setq gnus-select-method '(nntp "news.somewhere.edu"))
+@end lisp
-If you want to use a local spool, say:
+If you want to read directly from the local spool, say:
-@example
+@lisp
(setq gnus-select-method '(nnspool ""))
-@end example
+@end lisp
+
+If you can use a local spool, you probably should, as it will almost
+certainly be much faster.
+@vindex gnus-nntpserver-file
+@cindex NNTPSERVER
+@cindex @sc{nntp} server
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 NNTP server.
+@code{NNTPSERVER} environment variable. If that variable isn't set,
+Gnus will see whether @code{gnus-nntpserver-file} (default
+@file{/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 @sc{nntp} server. That's a longshot, though.
+
+@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 NNTP
-server. If you give a non-numerical prefix to `gnus' (ie. `C-u M-x
-gnus'), Gnus will let you choose between the servers in the
-@code{gnus-secondary-servers} variable (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 is 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.
+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 is to set the
-@code{gnus-secondary-select-methods}. The select methods listed in this
-variable are in many ways just as local as the @code{gnus-select-method}
-server. They will also be asked for active files during startup (if
-that's wanted), and new newsgroups that appear from these servers will
-be subscribed (or not) just as local groups are.
+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
-@example
-(setq gnus-secondary-select-methods
- '((nnmbox "")))
-@end example
+@lisp
+(setq gnus-secondary-select-methods '((nnmbox "")))
+@end lisp
-@node First Time
+@node The First Time
@section The First Time
+@cindex first time usage
-One time has to be the first, but it doesn't have to be painful.
-
-If no startup files exist, Gnus will try to determine what groups
-that should be subscribed by default.
+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 systems administrator should have set this variable to
+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 (ie. @samp{*.newusers}). (@dfn{Random} is here defined as
-"whatever Lars think you should read".)
+groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
+"whatever Lars thinks you should read".)
-If @code{gnus-default-subscribed-newsgroups} is t, Gnus will just use
-the normal functions for treating new groups, and not do anything
+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
+problems starting. However, if you have some mail groups in addition to
the news groups, you may want to start Gnus anyway.
-You can bo that by @kbd{M-x gnus-no-server}. This will start Gnus
-without attempting to contact the default server. Gnus will be started
-on level two, so you shouldn't have any groups from the local server on
-level one or two, but only have mail groups and other foreign groups on
-these two levels.
+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!
+
+@findex gnus-no-server
+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
+@code{gnus-no-server} command to start Gnus. That might come in handy
+if you're in a hurry as well.
+
+
+@node Slave Gnusii
+@section Slave Gnusii
+@cindex slave
+
+You might want to run more than one Emacs with more than one Gnus at the
+same time. If you are using different @file{.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
+@code{.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: @dfn{Masters} and
+@dfn{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 (@dfn{Master/Slave Relationships In Computer
+Applications}) will be much more expensive, of course.)
+
+Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
+however you do it). Each subsequent slave Gnusii should be started with
+@kbd{M-x gnus-slave}. These slaves won't save normal @file{.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) @code{.newsrc} file.
+
+
+@node Fetching a Group
+@section Fetching a Group
+
+@findex gnus-fetch-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 @code{gnus-fetch-group} provides this functionality in any
+case. It takes the group name as a paramenter.
+
@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 ready-made values
+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 hierarchially.
-
+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 *all* new groups.
-
+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 off properly or subscribe to them. This is the
-default.
-
+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-nil, Gnus will ask you in a
-hierarchial fashion whether to subscribe to new groups or not. Gnus
+@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:
+@file{.newsrc} file. Here's an example:
@example
options -n !alt.all !rec.all sci.all
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 doesn't 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}.
+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-auto-subscribed-groups
+Yet another variable that meddles here is
+@code{gnus-auto-subscribed-groups}. It works exactly like
+@code{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 (@code{nnml}, @code{nnbabyl},
+@code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
+don't like that, just set this variable to @code{nil}.
@vindex gnus-check-new-newsgroups
-If you are satisfied that you never really want to see any new
-groups, you could set @code{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
-by just pressing @kbd{U} in the @dfn{group buffer}.
-
-If @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask
-the server for new groups since last time it asked instead of
-determining what groups are new by comparing active groups with known
-groups. 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 nil, which will save time both at
-startup, at exit, and all over. Saves disk space, too. The only problem
-with this method is that not all servers support this functionality.
+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}). This variable
+is @code{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
+@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} files. All information about
-what groups you read is traditionally stored in this file, which has
-a rather rigid structure.
+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 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.)
-GNUS would read whichever one of these files that were the most recently
-saved, which enabled people to swap between GNUS and other newsreaders.
+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.
+That was kinda silly, so Gnus went one better: In addition to the
+@file{.newsrc} and @file{.newsrc.el} files, 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 @file{.newsrc} by setting
-@code{gnus-save-newsrc-file} to nil, which means you can delete
-the file and save some space, as well as some time when quitting
-Gnus. However, that will make it impossible to use other newsreaders
-than (ding) Gnus. But hey, who would want to, right?
+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 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 nil if you set this variable to nil.
+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.
+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.
+@vindex gnus-save-quick-newsrc-hook
+@vindex gnus-save-standard-newsrc-hook
+@code{gnus-save-newsrc-hook} is called before saving any of the newsrc
+files, while @code{gnus-save-quick-newsrc-hook} is called just before
+saving the @file{.newsrc.eld} file, and
+@code{gnus-save-standard-newsrc-hook} is called just before saving the
+@file{.newsrc} file. The latter two are commonly used to tern version
+control on or off.
@node Auto Save
@section Auto Save
+@cindex dribble file
+@cindex auto-save
Whenever you do something that changes the Gnus data (reading articles,
-cathing up, killing/subscribing to groups,) the change is added to a
-special @dfn{dribble} buffer. This buffer is auto-saved the normal
-Emacs way.
+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.
+read it. The auto save file is deleted whenever the real startup file is
+saved.
-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. The default is @code{t}.
+
+@vindex gnus-dribble-directory
+Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
+this variable is @code{nil}, which it is by default, Gnus will dribble
+into the same directory as the @file{.newsrc} file is located. (This is
+normally the user's home directory.)
@node The Active File
@section The Active File
+@cindex active file
+@cindex ignored groups
-When Gnus starts, or indeed whenever it tries to determine if new
-articles has arrived, it reads the active file. This is a file stored
-on the NNTP server or in the local spool.
+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 to see what groups are available, Gnus
-deletes all lines in this file that match
-@code{gnus-ignored-newsgroups}. You may even use this variable to make
-Gnus ignore hierarchies you aren't interested in.
+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 nil to prevent Gnus from reading
-the entire active file.
+can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
+reading the active file. This variable is @code{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 probabaly make Gnus slower, not faster.
+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
+@sc{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-load-hook
+@vindex 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.
+
+@item gnus-startup-hook
+@vindex gnus-startup-hook
+A hook that is run after starting up Gnus successfully.
+
@item gnus-check-bogus-newsgroups
@vindex gnus-check-bogus-newsgroups
-If non-nil, Gnus will check for and delete all bogus groups at
-startup. A @dfn{bogus group} is a group that you have in you
+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.
+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-nil, the startup message won't be displayed. That way, nobody will
-notice thay you are reading news instead of doing your job.
+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 and displays various information regarding these groups.
-It is the first buffer displayed when Gnus starts.
+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 Manouvering:: Commands for moving in the group buffer.
+* Group Maneuvering:: Commands for moving in the group buffer.
* Selecting a Group:: Actually reading news.
-* Group Subscribing:: Unsubscribing, killing, subscribing.
+* Subscription Commands:: 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.
-* Listing Groups:: Gnus can list various classes of 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.
+* Group Topics:: A folding group mode divided into topics.
* 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.
Quite simple, huh?
-Those lines mean that there are 25 unread articles in
-@samp{news.announce.newusers} and no unread articles, but some ticked
-articles in @samp{alt.fan.andrea-dworkin} (see that little asterisk at
-the beginning of the line?)
+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
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.
-One extension is that specifications like @samp{%7,12s} is allowed,
-which means that the field will be at least 7 characters long, and no
-more that 12 characters long.
+(All these format variables can also be random elisp forms. In that
+case, they will be @code{eval}ed to insert the required lines.)
+
+(All these format variables can also be random elisp forms. In that
+case, they will be @code{eval}ed to insert the required lines.)
+
+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"}.
+@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.
-There should always be a colon on the line; the cursor is always moved
-to the colon. Nothing else is required - not even the group name.
+(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
+Only marked articles.
@item S
-Whether the group is subscribed
+Whether the group is subscribed.
@item L
-Level of subscribedness
+Level of subscribedness.
@item N
-Number of unread articles
+Number of unread articles.
@item I
-Number of dormant articles
+Number of dormant articles.
@item T
-Number of ticked articles
+Number of ticked articles.
@item R
-Number of read articles
+Number of read articles.
@item t
-Total number of articles
+Total number of articles.
@item y
-Number of unread, unticked, non-dormant articles
+Number of unread, unticked, non-dormant articles.
@item i
-Number of ticked and dormant articles
+Number of ticked and dormant articles.
@item g
-Full group name
+Full group name.
@item G
-Group name
+Group name.
@item D
-Newsgroup description
+Newsgroup description.
@item o
-Moderated
+Moderated.
@item O
-Moderated
+Moderated.
@item s
-Select method
+Select method.
@item n
-Select from where
+Select from where.
@item z
-A string that look like @samp{<%s:%n>} if a foreign select method is
-used.
+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 also be changed (@code{gnus-group-mode-line-format}).
-It does not understand that many format specifiers:
+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
+Default news server.
@item M
-Default select method
+Default select method.
@end table
-@node Group Manouvering
-@section Group Manouvering
+@node Group Maneuvering
+@section Group Maneuvering
+@cindex group movement
All movement commands understand the numeric prefix and will behave as
expected, hopefully.
@item n
@kindex n (Group)
@findex gnus-group-next-unread-group
-Go to the next group with unread articles
-(@code{gnus-group-next-unread-group}).
-@item p, DEL
+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 with unread articles
-(@code{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
@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}).
+(@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. The default
+is @code{t}.
+
@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 in the group
-(@code{gnus-group-read-group}). If there are no unread articles in the
-group, or if you give a prefix to this command, Gnus will offer to
-fetch all the old articles in this group from the server.
-server.
+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}).
+(@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 M-RET
+@kindex M-RET (Group)
+@findex gnus-group-quick-select-group
+This does the same as the command above, but tries to do it with the
+minimum amount off fuzz (@code{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.
+
@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
@end table
@vindex gnus-large-newsgroup
-The @code{gnus-large-newsgroup} variable says what Gnus considers to be
-a "big" group. If the group is big, 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-auto-select-newsgroup
-If @code{gnus-auto-select-newsgroup} is non-nil, the first unread
+The @code{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 (@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-first
+If @code{gnus-auto-select-first} 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 nil in
-`gnus-select-group-hook', which is called when a group is selected.
-This hook is also popularly used for sorting headers before generating
-the summary buffer.
-
-@node Group Subscribing
-@section Group Subscribing
+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 Subscription Commands
+@section Subscription Commands
+@cindex subscribing
@table @kbd
-@item u
+@item S t
+@itemx u
+@kindex S t (Group)
@kindex u (Group)
@findex gnus-group-unsubscribe-current-group
-Unsubscribe the current group, or, if it was unsubscribed already,
-subscribe it (@code{gnus-group-unsubscribe-current-group}).
-@item U
+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
-Ask the user for a group to unsubscribe, and then unsubscribe it. If
-it was unsubscribed already, subscribe it instead
-(@code{gnus-group-unsubscribe-group}).
-@item C-k
+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 C-y
+@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 C-w
+@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 M-z
-@kindex M-z (Group)
+@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
+Also @xref{Group Levels}.
+
@node Group Levels
@section Group Levels
+@cindex group level
-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 and
-lower, or to just check new articles in groups on a given level and
-lower, etc.
+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
-@kindex S (Group)
+@item S l
+@kindex S l (Group)
@findex gnus-group-set-current-level
-Set the level of the current group depending on the numeric
-prefix. For instance, @kbd{3 s} will set the level of the current
-group to three (@code{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
-Gnus considers groups on levels 1-5 to be subscribed, 6-7 to be
-unsubscribed, 8 to be zombies (walking dead) and 9 to be killed,
+@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) (default 5) to be subscribed,
+@code{gnus-level-subscribed} (exclusive) and
+@code{gnus-level-unsubscribed} (inclusive) (default 7) to be
+unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
+(default 8) and @code{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.
+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 "ordinary" groups on level 3 or
-higher, and keep your mail groups (if any) on level 1 or 2.
+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.
+
+@vindex gnus-level-default-unsubscribed
+@vindex gnus-level-default-subscribed
+Two closely related variables are @code{gnus-level-default-subscribed}
+(default 3) and @code{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.
@vindex gnus-keep-same-level
-If @code{gnus-keep-same-level} is non-nil, some movement commands will
-only move to groups that are of the same level (or lower). In
+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 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.
+
+@table @kbd
+
+@item #
+@kindex # (Group)
+@itemx M m
+@kindex M m (Group)
+@findex gnus-group-mark-group
+Set the mark on the current group (@code{gnus-group-mark-group}).
+
+@item M-#
+@kindex M-# (Group)
+@itemx < u
+@kindex M u (Group)
+@findex gnus-group-unmark-group
+Remove the mark from the current group
+(@code{gnus-group-unmark-group}).
+
+@item M w
+@kindex M w (Group)
+@findex gnus-group-mark-region
+Mark all groups between point and mark (@code{gnus-group-mark-region}).
+@end table
+
+Also @xref{Process/Prefix}.
+
+
@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
-NNTP server, it could be a virtual group or it could be your own
+@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
+@code{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 M-a
-@kindex M-a (Group)
-@findex gnus-group-add-group
-Add a new group. Gnus will prompt you for a name, a method and an
-"address" (@code{gnus-group-add-group}).
-@item M-e
-@kindex M-e (Group)
+@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 r
+@kindex G m (Group)
+@findex gnus-group-rename-group
+Rename the current group to something else
+(@code{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.
+
+@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
-Edit a group entry. Gnus will pop up a new buffer where you can edit
-the entry (@code{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 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
+@vindex gnus-group-recent-archive-directory
+Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
+default a group pointing to the most recent articles will be created
+(@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
+group will be created from 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 DEL
+@kindex G DEL (Group)
+@findex gnus-group-delete-group
+This function will delete the current group
+(@code{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.
+
+@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 NNTP server.
-* nnspool:: Reading news from the local spool.
-* nnvirtual:: Combining articles from many groups.
-* nndir:: You can read a directory as if it were a newsgroup.
-* Mail:: Reading your personal mail with Gnus.
+* 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 NNTP servers. It is 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.
+groups from different @sc{nntp} servers.
@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.
-Subscribing to a foreign group from an NNTP server is rather easy. You
-just specify @code{nntp} as method and the address of the 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.
+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
+@cindex authentification
+@cindex nntp authentification
+@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.
+
+@c @findex nntp-open-rlogin
+@c @findex nntp-open-network-stream
+@c @item nntp-open-server-function
+@c @vindex nntp-open-server-function
+@c This function is used to connect to the remote system. Two pre-made
+@c functions are @code{nntp-open-network-stream}, which is the default, and
+@c simply connects to some port or other on the remote system. The other
+@c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
+@c and then does a telnet to the @sc{nntp} server available there.
+@c
+@c @item nntp-rlogin-parameters
+@c @vindex nntp-rlogin-parameters
+@c If you use @code{nntp-open-rlogin} as the
+@c @code{nntp-open-server-function}, this list will be used as the
+@c parameter list given to @code{rsh}.
+@c
+@c @item nntp-rlogin-user-name
+@c @vindex nntp-rlogin-user-name
+@c User name on the remote system when using the @code{rlogin} connect
+@c 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.
+
+@item nntp-warn-about-losing-connection
+@vindex nntp-warn-about-losing-connection
+If this variable is non-@code{nil}, some noise will be made when a
+server closes connection.
+
+
+@end table
@node nnspool
@subsection nnspool
+@cindex @code{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 binaries groups.
+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{""} as
-the address.
+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 @code{nnspool} looks for the articles. This is normally
+@file{/usr/spool/news/}.
+
+@item nnspool-nov-directory
+@vindex nnspool-nov-directory
+Where @code{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 @code{nnvirtual}
+@cindex virtual groups
-A @dfn{virtual group} is really nothing more than a collection of
-other groups.
-
-You specify @code{nnvirtual} as the method and a regular expression that
-says which groups that you wish to have in this one as the address.
+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 @code{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
-"^alt\\.fan\\.andrea-dworkin$\\|rec\\.dworkin.*"
+"^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
@end example
-These groups can be native or foreign; everything should work smoothly,
-but if your computer explodes, it was probably my fault. (Including
-other virtual groups in this one will probably confuse Gnus, so don't do
-that.)
+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 @code{nnvirtual} groups.
+
+@node nnkiboze
+@subsection nnkiboze
+@cindex @code{nnkiboze}
+@cindex kibozing
+
+@dfn{Kibozing} is defined by @sc{oed} as "grepping through (parts of)
+the news feed". @code{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 @code{nnkiboze} method is, as with @code{nnvirtual}, a regexp
+to match groups to be "included" in the @code{nnkiboze} group. There most
+similarities between @code{nnkiboze} and @code{nnvirtual} ends.
+
+In addition to this regexp detailing component groups, an @code{nnkiboze} group
+must have a score file to say what articles that are to be included in
+the group (@pxref{Scoring}).
+
+@kindex M-x nnkiboze-generate-groups
+@findex nnkiboze-generate-groups
+You must run @kbd{M-x nnkiboze-generate-groups} after creating the
+@code{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 @code{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.
+
+@code{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 @code{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.
-One limitation, however - all groups that are included in a virtual
-group has to be alive (ie. subscribed or unsubscribed). In fact, if you
-include a group in a virtual group, and it was killed, it will be
-subscribed automagically.
+Articles that are marked as read in the @code{nnkiboze} group will have their
+@sc{nov} lines removed from the @sc{nov} file.
@node nndir
@subsection nndir
+@cindex @code{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
+it, you might treat it as a newsgroup. The files have to have numerical
names, of course.
-This situation is kinda special, so there's a shortcut for creating
-these "groups": @kbd{d} (@code{gnus-group-make-directory-group}) in the
-group buffer. You will be prompted for a directory to read.
+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 @code{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:
-@node Mail
-@subsection Mail
+@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
-Reading mail with a newsreader - isn't that just plain WeIrD? But of
-course.
-@menu
-* Creating Mail Groups:: How to create mail groups (duh).
-* Expiring Old Mail Articles:: Getting rid of unwanted mail.
-@end menu
+@node nndoc
+@subsection nndoc
+@cindex @code{nndoc}
+@cindex documentation group
+@cindex help group
+
+@code{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}.
+
+@code{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.
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 you mail in.
+depends on what format you want to store your mail in.
@menu
-* nnmbox:: Using the quite standard Un*x mbox.
-* nnrmail:: 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.
+* 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.
+* nnmbox:: Using the (quite) standard Un*x mbox.
+* nnbabyl:: Emacs programs use the rmail babyl format.
+* nnml:: Store your mail in a private spool?
+* nnmh:: An mhspool-like backend.
+* nnfolder:: Having one file for each group.
@end menu
@vindex nnmail-read-incoming-hook
reading new mail. You can use this hook to notify any mail watch
programs, if you want to.
-Gnus gives you all the opportunity you want for shooting yourself in
-your 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 unemplyed while you
-really should be out collecting empty bottles to save up for next
+@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-movemail-program
+@code{nnmail-movemail-program} is executed to move mail from the user's
+inbox to her home directory. The default is @samp{"movemail"}.
+
+@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.
+
+@vindex nnmail-message-id-cache-length
+@vindex nnmail-message-id-cache-file
+@vindex nnmail-delete-duplicates
+@cindex duplicate mails
+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
+@code{nnmail} checks for and discards any duplicates it might find. To
+do this, it keeps a cache of old @code{Message-ID}s -
+@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
+default. The approximate maximum number of @code{Message-ID}s stored
+there is controlled by the @code{nnmail-message-id-cache-length}
+variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
+stored.) If all this sounds scary to you, you can set
+@code{nnmail-delete-duplicates} to @code{nil} (which is what it is by
+default), and @code{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 @code{nnmail-delete-duplicates} set to
+@code{t}, you can send her as many insults as you like, just by using a
+@code{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.
@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 has (@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
+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
-The you should set the variable @code{nnmail-split-methods} to specify
+Then you should set the variable @code{nnmail-split-methods} to specify
how the incoming mail is to be split into groups.
-@example
+@lisp
(setq nnmail-split-methods
'(("mail.junk" "^From:.*Lars Ingebrigtsen")
- ("mail.crazzy" "^Subject:.*die\\|^Organization:.*flabby")
+ ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
("mail.other" "")))
-@end example
+@end lisp
This variable is a list of lists, where the first element of each of
-these lists contain 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.
+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 *always* be @samp{""} so that it matches all mails.
+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} to split things directory into an @code{nnmh}
+directory (which you shouldn't do), 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
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 capitalization: IF you do NOT mark
-articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
+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{X} in the third
+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:
-@example
+@lisp
(setq gnus-auto-expirable-newsgroups
- "^mail.nonsense-list\\|^mail.nice-list")
-@end example
+ "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
expiry period in the @samp{mail.junk} group, and a six day expiry period
everywhere else:
-@example
+@lisp
(setq nnmail-expiry-wait-function
- '(lambda (group)
- (cond ((string= group "mail.private")
- 31)
- ((string= group "mail.junk")
- 1)
- (t
- 6))))
-@end example
+ (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.
+
+@vindex gnus-total-expirable-newsgroups
+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. Even more dangerous is the
+@code{gnus-total-expirable-newsgroups} variable. All groups that match
+this regexp will have all read articles put through the expiry process,
+which means that @emph{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
+@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
+with! So there!
+
+
+@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 @code{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. The path of the mbox file is given by the @code{nnmbox-mbox-file}
-variable. In addition, Gnus needs to store information about active
-articles. The file specified by @code{nnmbox-active-file} will be used
-for that.
-
-@node nnrmail
-@subsubsection nnrmail
-
-@vindex nnrmail-active-file
-@vindex nnrmail-mbox-file
-The @dfn{nnrmail} backend will use a babyl mail box to store mail. The
-path of the rmail mail box file is given by the @code{nnrmail-mbox-file}
-variable. In addition, Gnus needs to store information about active
-articles. The file specified by @code{nnrmail-active-file} will be used
-for that.
+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 @code{nnbabyl}
+@cindex rmail mbox
+
+@vindex nnbabyl-active-file
+@vindex nnbabyl-mbox-file
+The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
+mbox}) 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 @code{nnml}
+@cindex mail @sc{nov} spool
-The spool mail format (@code{nnml}) isn't compatible with any other
-known format. It should be used with some caution.
+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 @samp{"~/Mail/"}.
+variable. The default value is @file{~/Mail/}.
You do not have to create any directories beforehand; Gnus will take
care of all that.
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 NOV
-databases for the incoming mails. This makes is the fastest backend when
-it comes to reading mail.
+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 @code{nnmh}
+@cindex mh-e mail spool
@code{nnmh} is just like @code{nnml}, except that is doesn't generate
-NOV databases and it doesn't keep an active file. This makes @code{nnmh}
-a *much* slower backend than @code{nnml}, but it also makes it easier to
-write procmail scripts for.
+@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 @code{nnmh} articles, you do not have to set
+this variable to @code{t}.
+@end table
+
+@node nnfolder
+@subsubsection nnfolder
+@cindex @code{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.
+
+The group parameters store information local to a particular group:
+
+@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.
+Also @xref{Mail & Post}.
+
+@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 group.
+
+@item topic
+@cindex topic
+If the group parameter list contains an element like @code{(topic
+. "some-topic")}, the group will become a member of the topic in
+question (@pxref{Group Topics}).
+
+@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.
+
+@item @var{(variable form)}
+You can use the group parameters to set variables local to the group you
+are entering. Say you want to turn threading off in
+@samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
+the group parameters of that group. @code{gnus-show-threads} will be
+made into a local variable in the summary buffer you enter, and the form
+@code{nil} will be @code{eval}ed there.
+
+This can also be used as a group-specific hook function, if you'd like.
+If you want to hear a beep when you enter the group
+@samp{alt.binaries.pictures.furniture}, you could put something like
+@code{(dummy-variable (ding))} in the parameters of that group.
+@code{dummy-variable} will be set to the result of the @code{(ding)}
+form, but who cares?
+
+@end table
+
+If you want to change the group info you can use the @kbd{G E} command
+to enter a buffer where you can edit it.
+
+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 subscribed groups that have unread articles
+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 (ie. just subscribed groups).
+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 subscribed and unsubscribed 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 (ie. just
-subscribed and unsubscribed groups).
-@item C-c C-k
-@kindex C-c C-k (Group)
+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
-List all killed groups (@code{gnus-group-list-killed}).
-@item C-c C-z
-@kindex C-c C-z (Group)
+List all killed groups (@code{gnus-group-list-killed}). If given a
+prefix argument, really list all groups that are available, but aren't
+currently (un)subscribed. This could entail reading the active file
+from the server.
+
+@item A z
+@kindex A z (Group)
@findex gnus-group-list-zombies
List all zombie groups (@code{gnus-group-list-zombies}).
+
+@item A m
+@kindex A m (Group)
+@findex gnus-group-list-matching
+List all subscribed groups with unread articles that match a regexp
+(@code{gnus-group-list-matching}).
+
+@item A M
+@kindex A M (Group)
+@findex gnus-group-list-all-matching
+List groups that match a regexp (@code{gnus-group-list-all-matching}).
+
+@item A A
+@kindex A A (Group)
+@findex gnus-group-list-active
+List absolutely all groups that are in the active file(s) of the
+server(s) you are connected to (@code{gnus-group-list-active}). This
+might very well take quite a while. It might actually be a better idea
+to do a @kbd{A m} to list all matching, and just give @samp{.} as the
+thing to match on.
+
@end table
@node Group Maintenance
@section Group Maintenance
+@cindex bogus groups
@table @kbd
@item b
@kindex b (Group)
@findex gnus-group-check-bogus-groups
-Check bogus groups and delete them
+Find bogus groups and delete them
(@code{gnus-group-check-bogus-groups}).
@item F
@kindex F (Group)
@findex gnus-find-new-newsgroups
-Find new groups (@code{gnus-find-new-newsgroups}).
+Find new groups and process them (@code{gnus-find-new-newsgroups}).
@item C-c C-x
@kindex C-c C-x (Group)
@findex gnus-group-expire-articles
Run all expirable articles in the current group through the expiry
process (if any) (@code{gnus-group-expire-articles}).
+
@item C-c M-C-x
@kindex C-c M-C-x (Group)
@findex gnus-group-expire-all-groups
Run all articles in all groups through the expiry process
(@code{gnus-group-expire-all-groups}).
+
+@item C-c C-s
+@kindex C-c C-s (Group)
+@findex gnus-group-sort-groups
+@vindex gnus-group-sort-function
+Sort the groups according to the function given by the
+@code{gnus-group-sort-function} variable
+(@code{gnus-group-sort-groups}). Available sorting functions include:
+
+@table @code
+
+@item gnus-group-sort-by-alphabet
+@findex gnus-group-sort-by-alphabet
+Sort the group names alphabetically. This is the default.
+
+@item gnus-group-sort-by-level
+@findex gnus-group-sort-by-level
+Sort by group level.
+
+@item gnus-group-sort-by-unread
+@findex gnus-group-sort-by-unread
+Sort by number of unread articles.
+
+@item gnus-group-sort-by-method
+@findex gnus-group-sort-by-method
+Sort by alphabetically on the select method.
+
+@end table
+
+@code{gnus-group-sort-function} can also be a list of sorting
+functions. In that case, the most significant sort key function must be
+the last one.
@end table
@node Browse Foreign Server
@section Browse Foreign Server
+@cindex foreign servers
+@cindex browsing servers
@table @kbd
@item B
(@code{gnus-group-browse-foreign-server}).
@end table
+@findex gnus-browse-server-mode
A new buffer with a list of available groups will appear. This buffer
will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
(well, a lot) like a normal group buffer, but with one major difference
new groups will be added to the group buffer, and then you can read them
as you would any other group.
+Future versions of Gnus may possibly permit reading groups straight from
+the browse buffer.
+
Here's a list of keystrokes available in the browse mode:
@table @kbd
@kindex n (Browse)
@findex gnus-group-next-group
Go to the next group (@code{gnus-group-next-group}).
+
@item p
-@kindex C-p (Browse)
@kindex p (Browse)
@findex gnus-group-prev-group
Go to the previous group (@code{gnus-group-prev-group}).
+
+@item SPC
+@kindex SPC (Browse)
+@findex gnus-browse-read-group
+Enter the current group and display the first article
+(@code{gnus-browse-read-group}).
+
+@item RET
+@kindex RET (Browse)
+@findex gnus-browse-select-group
+Enter the current group (@code{gnus-browse-select-group}).
+
@item u
@kindex u (Browse)
@findex gnus-browse-unsubscribe-current-group
Unsubscribe to the current group, or, as will be the case here,
subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
-@item q
+
+@item l
+@itemx q
@kindex q (Browse)
+@kindex l (Browse)
@findex gnus-browse-exit
Exit browse mode (@code{gnus-browse-exit}).
+
@item ?
@kindex ? (Browse)
@findex gnus-browse-describe-briefly
@node Exiting Gnus
@section Exiting Gnus
+@cindex exiting Gnus
-Yes, Gnus is exiting.
+Yes, Gnus is ex(c)iting.
@table @kbd
@item z
@kindex z (Group)
@findex gnus-group-suspend
-Suspend Gnus (@code{gnus-group-suspend}).
+Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
+but it kills all buffers except the Group buffer. I'm not sure why this
+is a gain, but then who am I to judge?
@item q
@kindex q (Group)
@findex gnus-group-exit
@code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
@code{gnus-exit-gnus-hook} is called when you quit Gnus.
+@findex gnus-unload
+@cindex unloading
+If you wish to completely unload Gnus and all its adherents, you can use
+the @code{gnus-unload} command. This command is also very handy when
+trying to custoize meta-variables.
+
+Note:
+
+@quotation
+Miss Lisa Cannifax, while sitting in English class, feels her feet go
+numbly heavy and herself fall into a hazy trance as the boy sitting
+behind her drew repeated lines with his pencil across the back of her
+plastic chair.
+@end quotation
+
+
+@node Group Topics
+@section Group Topics
+@cindex topics
+
+If you read lots and lots of groups, it might be convenient to group
+them according to topics. You put your Emacs groups over here, your sex
+groups over there, and the rest (what, two groups or so?) you put in
+some misc section that you never bother with anyway.
+
+To get this @emph{fab} functionality, you set
+@code{gnus-group-prepare-function} to @code{gnus-group-prepare-topics}.
+Go ahead, just try it. I'll still be here when you get back. La de
+dum... Nice tune, that... la la la... What, you're back? Yes, and now
+press @kbd{l}. There. All your groups are now listed under
+@samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
+bothered?
+
+@vindex gnus-group-topics
+To get an even more exciting division, you have to fiddle with
+@code{gnus-group-topics}. That is an alist where each entry looks like
+this:
+
+@lisp
+(TOPIC REGEXP SHOW)
+@end lisp
+
+As you've already guessed (only geniï read manuals anyway), all
+groups that match @var{regexp} gets put into a section called
+@var{topic}. If @var{show} is non-@code{nil}, it overrides
+@code{gnus-group-topic-topics-only}. In specific, if @var{show} is
+@code{t}, all groups with this topic are always shown, and if it is a
+number, these groups are never shown.
+
+@vindex gnus-group-topic-topics-only
+Whoo, this is complicated. If @code{gnus-group-topic-topics-only} is
+@code{nil}, all groups and topics will be listed, as you would expect.
+If this variable is non-@code{nil}, only the topics will be listed, and
+the groups will not be listed. This makes the group buffer much shorter,
+I'm sure you'll agree. This is all modified on a topic-by-topic basis
+by the @var{show} parameter. It makes perfect sense, really.
+
+@vindex gnus-group-topic-face
+Topics are shown with @code{gnus-group-topic-face}.
+
+@vindex gnus-topic-unique
+If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
+of (tops) one topic each. If this is @code{nil}, each group might end
+up being a member of several topics.
+
+You can also put a @code{topic} in the group parameters (@pxref{Group
+Parameters}).
+
+Now, if you select a topic, if will fold/unfold that topic, which is
+really neat, I think.
+
+Here's an example @code{gnus-group-topics}:
+
+@lisp
+(("Emacs - the Spice of Life" "^gnu.emacs\\|comp.emacs" t)
+ ("Alternativeness" "^alt" 0)
+ ("Hard Stuff" "^comp" nil)
+ ("The Rest" "." nil))
+@end lisp
+
+If you want to add a group to a topic, you can use the @kbd{G t}
+(@code{gnus-group-add-to-topic}) command. It understands the
+process/prefix convention (@pxref{Process/Prefix}).
+
+If you want to add a group to a topic, you can use the @kbd{G t}
+(@code{gnus-group-add-to-topic}) command. It understands the
+process/prefix convention (@pxref{Process/Prefix}).
+
+
@node Misc Group Stuff
@section Misc Group Stuff
@table @kbd
+
@item g
@kindex g (Group)
@findex gnus-group-get-new-news
-Check server for new articles.
-If the numeric prefix is used, this command will check only groups of
-level ARG and lower (@code{gnus-group-get-new-news}).
+Check the server(s) for new articles. If the numerical prefix is used,
+this command will check only groups of level @var{arg} and lower
+(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
+command will force a total rereading of the active file(s) from the
+backend(s).
+
@item M-g
@kindex M-g (Group)
@findex gnus-group-get-new-news-this-group
Check whether new articles have arrived in the current group
(@code{gnus-group-get-new-news-this-group}).
+
+@item ^
+@kindex ^ (Group)
+@findex gnus-group-enter-server-mode
+Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
+Server Buffer}.
+
+@item M-f
+@kindex M-f (Group)
+@findex gnus-group-fetch-faq
+Try to fetch the FAQ for the current group
+(@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
+@code{gnus-group-faq-directory}, which is usually a directory on a
+remote machine. @code{ange-ftp} will be used for fetching the file.
@item R
@kindex R (Group)
@findex gnus-group-restart
@item r
@kindex r (Group)
@findex gnus-group-read-init-file
+@vindex gnus-init-file
Read the init file (@code{gnus-init-file}, which defaults to
@file{~/.gnus}) (@code{gnus-group-read-init-file}).
@item s
@item D
@kindex D (Group)
@findex gnus-group-describe-group
-Give a description of the current group
-(@code{gnus-group-describe-group}).
-@item C-c C-a
-@kindex C-c C-a (Group)
+Describe the current group (@code{gnus-group-describe-group}). If given
+a prefix, force Gnus to re-read the description from the server.
+@item G a
+@kindex G a (Group)
@findex gnus-group-apropos
-Give a listing of all groups that have names that match a regexp
+List all groups that have names that match a regexp
(@code{gnus-group-apropos}).
-@item C-c M-C-a
-@kindex C-c M-C-a (Group)
+@item G d
+@kindex G d (Group)
@findex gnus-group-description-apropos
-Give a listing of all groups that have names or descriptions that match
-a regexp (@code{gnus-group-description-apropos}).
+List all groups that have names or descriptions that match a regexp
+(@code{gnus-group-description-apropos}).
@item a
@kindex a (Group)
@findex gnus-group-post-news
@kindex V (Group)
@findex gnus-version
Display current Gnus version numbers (@code{gnus-version}).
+@item M-d
+@kindex M-d (Group)
+@findex gnus-group-describe-all-groups
+Describe all groups (@code{gnus-group-describe-all-groups}). If given a
+prefix, force Gnus to re-read the description file from the server.
@item ?
@kindex ? (Group)
@findex gnus-group-describe-briefly
@end table
@vindex gnus-group-prepare-hook
-@code{gnus-group-prepare-hook} is called after the group list is
-created in the Group buffer. It may be used to modify the group
-buffer in some strange, unnatural way.
+@code{gnus-group-prepare-hook} is called after the group buffer is
+generated. It may be used to modify the buffer in some strange,
+unnatural way.
@node The Summary Buffer
@chapter The Summary Buffer
+@cindex summary buffer
-A line for each article is displayed in the Summay buffer. You can move
-around, read articles, post articles and reply to them.
+A line for each article is displayed in the summary buffer. You can
+move around, read articles, post articles and reply to articles.
@menu
-* Summary Buffer Format:: Deciding how the summar buffer is to look.
-* Summary Manouvering:: Moving around the summary buffer.
+* Summary Buffer Format:: Deciding how the summary buffer is to look.
+* Summary Maneuvering:: Moving around the summary buffer.
* Choosing Articles:: Reading articles.
* Paging the Article:: Scrolling the current article.
* Reply Followup and Post:: Posting articles.
-* Cancelling and Superceding:: "Whoops, I shouldn't have called him that."
-* Ticking and Marking:: Marking articles as read, expirable, etc.
+* Canceling and Superseding:: "Whoops, I shouldn't have called him that."
+* Marking Articles:: Marking articles as read, expirable, etc.
+* Limiting:: You can limit the summary buffer.
* Threading:: How threads are made.
+* Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
+* Article Caching:: You may store articles in a cache.
+* Article Backlog:: Having already read articles hang around.
* Exiting the Summary Buffer:: Returning to the Group buffer.
+* Process/Prefix:: A convention used by many treatment commands.
* Saving Articles:: Ways of customizing article saving.
* Decoding Articles:: Gnus can treat series of (uu)encoded articles.
-* Various Article Stuff:: Various stuff dealing with articles.
+* Article Treatment:: The article buffer can be mangled at will.
* Summary Sorting:: You can sort the summary buffer four ways.
* Finding the Parent:: No child support? Get the parent.
-* Score Files:: Maintaining a score file.
* Mail Group Commands:: Some commands can only be used in mail groups.
* Various Summary Stuff:: What didn't fit anywhere else.
@end menu
+
@node Summary Buffer Format
@section Summary Buffer Format
+@cindex summary buffer format
+
+@menu
+* Summary Buffer Lines:: You can specify how summary lines should look.
+* Summary Buffer Mode Line:: You can say how the mode line should look.
+@end menu
+
+@findex mail-extract-address-components
+@findex gnus-extract-address-components
+@vindex gnus-extract-address-components
+Gnus will use the value of the @code{gnus-extract-address-components}
+variable as a function for getting the name and address parts of a
+@code{From} header. Two pre-defined function exist:
+@code{gnus-extract-address-components}, which is the default, quite
+fast, and too simplistic solution; and
+@code{mail-extract-address-components}, which works very nicely, but is
+slower.
+
+@vindex gnus-summary-same-subject
+@code{gnus-summary-same-subject} is a string indicating that the current
+article has the same subject as the previous. This string will be used
+with those specs that require it. The default is @samp{""}.
+
+@node Summary Buffer Lines
+@subsection Summary Buffer Lines
@vindex gnus-summary-line-format
You can change the format of the lines in the summary buffer by changing
the @code{gnus-summary-line-format} variable. It works along the same
lines a a normal @code{format} string, with some extensions.
-The default string is @samp{"%U%R%X%i %I%[%4L: %-20,20n%] %s\n"}.
+The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
The following format specification characters are understood:
@table @samp
@item N
-Article number
+Article number.
@item S
-Subject string
+Subject string.
@item s
Subject if the article is the root, @code{gnus-summary-same-subject}
otherwise.
@item F
-Full From line
+Full @code{From} line.
@item n
-The name (from the @code{From} header field)
+The name (from the @code{From} header).
+@item a
+The name (from the @code{From} header). This differs from the @code{n}
+spec in that it uses @code{gnus-extract-address-components}, which is
+slower, but may be more thorough.
@item A
-The address (from the @code{From} header field)
+The address (from the @code{From} header). This works the same way as
+the @code{a} spec.
@item L
-Number of lines in the article
+Number of lines in the article.
@item c
-Number of characters in the article
+Number of characters in the article.
@item I
-Indentation based on thread level
+Indentation based on thread level (@pxref{Customizing Threading}).
@item T
Nothing if the article is a root and lots of spaces if it isn't (it
-pushes everything after it off the screen)
+pushes everything after it off the screen).
@item \[
Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
for adopted articles.
@item \]
-Closing bracked, which is normally @samp{\]}, but can also be @samp{<}
+Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
for adopted articles.
@item <
One space for each thread level.
@item >
Twenty minus thread level spaces.
@item U
-Unread
-@item X
-Expirable
+Unread.
@item R
-Replied
+Replied.
@item i
-Score
+Score as a number.
+@item z
+@vindex gnus-summary-zcore-fuzz
+Zcore, @samp{+} if above the default level and @samp{-} if below the
+default level. If the difference between
+@code{gnus-summary-default-level} and the score is less than
+@code{gnus-summary-zcore-fuzz}, this spec will not be used.
@item x
-Xref
+@code{Xref}.
@item D
-Date
+@code{Date}.
@item M
-Message-ID
+@code{Message-ID}.
@item r
-References
-@item x
-Xref
+@code{References}.
+@item t
+Number of articles in the current sub-thread. Using this spec will slow
+down summary buffer generation somewhat.
+@item e
+A single character will be displayed if the article has any children.
+@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 header as
+argument. The function should return a string, which will be inserted
+into the summary just like information from any other summary specifier.
@end table
-No elements are required, except the @samp{%U}, @samp{%R}, @samp{%X} and
-@samp{%i} fields which have to be at the beginning of the line for
-reasons of efficiency. If you try to remove those, or change them,
-you'll probably end up with a mess, at least in this version of Gnus.
+Text between @samp{%(} and @samp{%)} will be highlighted with
+@code{gnus-mouse-face} when the mouse point is placed inside the area.
+There can only be one such area.
+
+The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
+have to be handled with care. For reasons of efficiency, Gnus will
+compute what column these characters will end up in, and "hard-code"
+that. This means that it is illegal to have these specs after a
+variable-length spec. Well, you might not be arrested, but your summary
+buffer will look strange, which is bad enough.
+
+The smart choice is to have these specs as far to the left as possible.
+(Isn't that the case with everything, though? But I digress.)
+
+This restriction may disappear in later versions of Gnus.
+
+@node Summary Buffer Mode Line
+@subsection Summary Buffer Mode Line
@vindex gnus-summary-mode-line-format
You can also change the format of the summary mode bar. Set
-@code{gnus-summary-mode-line-format} to whatever you like. Here's what
-elements you have to play with:
+@code{gnus-summary-mode-line-format} to whatever you like. Here are the
+elements you can play with:
@table @samp
@item G
-Group name
+Group name.
+@item p
+Unprefixed group name.
@item A
-Current article number
+Current article number.
@item V
-Gnus version
+Gnus version.
@item U
-Number of unread articles in this group
-@item u
-Number of unselected articles in this group
+Number of unread articles in this group.
+@item e
+Number of unselected articles in this group.
@item Z
A string with the number of unread and unselected articles represented
-either as @samp{<%U(+%u) more>} if there are both unselected articles,
-and just as @samp{<%U more>} if there are just unread articles and no
-unselected ones.
+either as @samp{<%U(+%u) more>} if there are both unread and unselected
+articles, and just as @samp{<%U more>} if there are just unread articles
+and no unselected ones.
+@item g
+Shortish group name. For instance, @samp{rec.arts.anime} will be
+shortened to @samp{r.a.anime}.
+@item S
+Subject of the current article.
+@item u
+Used-defined spec.
+@item s
+Name of the current score file.
+@item d
+Number of dormant articles.
+@item t
+Number of ticked articles.
+@item r
+Number of articles that have been marked as read in this session.
+@item E
+Number of articles expunged by the score files.
@end table
-@node Summary Manouvering
-@section Summary Manouvering
+
+@node Summary Maneuvering
+@section Summary Maneuvering
+@cindex summary movement
All the straight movement commands understand the numeric prefix and
behave pretty much as you'd expect.
None of these commands select articles.
@table @kbd
-@item down
-@kindex down (Summary)
-@findex gnus-summary-next-subject
-Go to the next subject line (@code{gnus-summary-next-subject}).
-@item up
-@kindex up (Summary)
-@findex gnus-summary-prev-subject
-Go to the previous subject line (@code{gnus-summary-prev-subject}).
-@item M-n
+@item G M-n
+@itemx M-n
@kindex M-n (Summary)
+@kindex G M-n (Summary)
@findex gnus-summary-next-unread-subject
Go to the next summary line of an unread article
(@code{gnus-summary-next-unread-subject}).
-@item M-p
+@item G M-p
+@itemx M-p
@kindex M-p (Summary)
+@kindex G M-p (Summary)
@findex gnus-summary-prev-unread-subject
Go to the previous summary line of an unread article
(@code{gnus-summary-prev-unread-subject}).
-@item j
+@item G g
+@itemx j
@kindex j (Summary)
+@kindex G g (Summary)
@findex gnus-summary-goto-subject
Ask for an article number and then go to this summary line
(@code{gnus-summary-goto-subject}).
-@item l
-@kindex l (Summary)
-@findex gnus-summary-goto-last-article
-Go to the summary line of the previous article
-(@code{gnus-summary-goto-last-article}).
@end table
@vindex gnus-auto-select-next
If you are at the end of the group and issue one of the movement
commands, Gnus will offer to go to the next group. If
-@code{gnus-auto-select-next} is t and the next group is empty, Gnus
-will exit summary mode and return to the group buffer. If this
-variable is neither t nor nil, Gnus will select the next group, no
-matter if it has any unread articles or not. As a special case, if this
-variable equals @code{quietly}, Gnus will select the next group
-without asking for confirmation. Also see @code{gnus-keep-same-level}.
+@code{gnus-auto-select-next} is @code{t} and the next group is empty,
+Gnus will exit summary mode and return to the group buffer. If this
+variable is neither @code{t} nor @code{nil}, Gnus will select the next
+group, no matter whether it has any unread articles or not. As a
+special case, if this variable is @code{quietly}, Gnus will select the
+next group without asking for confirmation. If this variable is
+@code{almost-quietly}, the same will happen only if you are located on
+the last article in the group. Also @xref{Group Levels}.
+
+If Gnus asks you to press a key to confirm going to the next group, you
+can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
+buffer, searching for the next group to read without actually returning
+to the group buffer.
+
+@vindex gnus-auto-select-same
+If @code{gnus-auto-select-same} is non-@code{nil}, all the movement
+commands will try to go to the next article with the same subject as the
+current. This variable is not particularly useful if you use a threaded
+display.
+
+@vindex gnus-summary-check-current
+If @code{gnus-summary-check-current} is non-@code{nil}, all the "unread"
+movement commands will not proceed to the next (or previous) article if
+the current article is unread. Instead, they will choose the current
+article.
@vindex gnus-auto-center-summary
-If @code{gnus-auto-center-summary} is non-nil, Gnus will keep the point
-in the summary buffer centered at all times. This makes things quite
-tidy, but if you have a slow network connection, or do simply not like
-this un-Emacsism, you can set this variable to nil to get the normal
-Emacs scrolling action.
+If @code{gnus-auto-center-summary} is non-@code{nil}, Gnus will keep the
+point in the summary buffer centered at all times. This makes things
+quite tidy, but if you have a slow network connection, or simply do not
+like this un-Emacsism, you can set this variable to @code{nil} to get
+the normal Emacs scrolling action.
@node Choosing Articles
@section Choosing Articles
+@cindex selecting articles
-All the movement commands understand the numeric prefix.
-
-All the following commands select an article.
+None of the following movement commands understand the numeric prefix,
+and they all select and display an article.
@table @kbd
@item SPACE
@findex gnus-summary-next-page
Select the current article, or, if that one's read already, the next
unread article (@code{gnus-summary-next-page}).
-@item n
+@item G n
+@itemx n
@kindex n (Summary)
+@kindex G n (Summary)
@findex gnus-summary-next-unread-article
Go to next unread article (@code{gnus-summary-next-unread-article}).
-@item p
+@item G p
+@itemx p
@kindex p (Summary)
@findex gnus-summary-prev-unread-article
Go to previous unread article (@code{gnus-summary-prev-unread-article}).
-@item N
+@item G N
+@itemx N
@kindex N (Summary)
+@kindex G N (Summary)
@findex gnus-summary-next-article
Go to the next article (@code{gnus-summary-next-article}).
-@item P
+@item G P
+@itemx P
@kindex P (Summary)
+@kindex G P (Summary)
@findex gnus-summary-prev-article
Go to the previous article (@code{gnus-summary-prev-article}).
-@item M-C-n
-@kindex M-C-n (Summary)
+@item G C-n
+@kindex G C-n (Summary)
@findex gnus-summary-next-same-subject
Go to the next article with the same subject
(@code{gnus-summary-next-same-subject}).
-@item M-C-p
-@kindex M-C-p (Summary)
+@item G C-p
+@kindex G C-p (Summary)
@findex gnus-summary-prev-same-subject
Go to the previous article with the same subject
(@code{gnus-summary-prev-same-subject}).
-@item .
-@kindex . (Summary)
+@item G f
+@itemx .
+@kindex G f (Summary)
+@kindex . (Summary)
@findex gnus-summary-first-unread-article
-Go to the first unread article (@code{gnus-summary-first-unread-article}).
+Go to the first unread article
+(@code{gnus-summary-first-unread-article}).
+@item G b
+@itemx ,
+@kindex G b (Summary)
+@kindex , (Summary)
+Go to the article with the highest score
+(@code{gnus-summary-best-unread-article}).
+@item G l
+@itemx l
+@kindex l (Summary)
+@kindex G l (Summary)
+@findex gnus-summary-goto-last-article
+Go to the previous article read (@code{gnus-summary-goto-last-article}).
+@item G p
+@kindex G p (Summary)
+@findex gnus-summary-pop-article
+Pop an article off the summary history and go to this article
+(@code{gnus-summary-pop-article}). This command differs from the
+command above in that you can pop as many previous articles off the
+history as you like.
@end table
+Some variables that are relevant for moving and selecting articles:
+
+@table @code
+@item gnus-auto-extend-newsgroup
@vindex gnus-auto-extend-newsgroup
All the movement commands will try to go to the previous (or next)
article, even if that article isn't displayed in the Summary buffer if
-@code{gnus-auto-extend-newsgroup} is non-nil. Gnus will fetch the
-article from the server and present it in the article buffer.
-
+this variable is non-@code{nil}. Gnus will then fetch the article from
+the server and display it in the article buffer.
+@item gnus-select-article-hook
@vindex gnus-select-article-hook
-@code{gnus-select-article-hook} is called whenever an article is
-selected. By default it makes any threads hidden under the current
-article visible.
-
+This hook is called whenever an article is selected. By default it
+exposes any threads hidden under the selected article.
+@item gnus-mark-article-hook
@vindex gnus-mark-article-hook
-@code{gnus-mark-article-hook} is called when an article is selected for
-the first time. It is intended to be used for marking articles as read
-automatically when articles are selected.
+This hook is called whenever an article is selected. It is intended to
+be used for marking articles as read.
+@item gnus-visual-mark-article-hook
+@vindex gnus-visual-mark-article-hook
+This hook is run after selecting an article. It is meant to be used for
+highlighting the article in some way. It is not run if
+@code{gnus-visual} is @code{nil}.
+@item gnus-summary-update-hook
+@vindex gnus-summary-update-hook
+This hook is called when a summary line is changed. It is not run if
+@code{gnus-visual} is @code{nil}.
+@item gnus-summary-selected-face
+@vindex gnus-summary-selected-face
+This is the face (or @dfn{font} as some people call it) that is used to
+highlight the current article in the summary buffer.
+@item gnus-summary-highlight
+@vindex gnus-summary-highlight
+Summary lines are highlighted according to this variable, which is a
+list where the elements are on the format @code{(FORM . FACE)}. If you
+would, for instance, like ticked articles to be italic and high-scored
+articles to be bold, you could set this variable to something like
+@lisp
+(((eq mark gnus-ticked-mark) . italic)
+ ((> score default) . bold))
+@end lisp
+As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
+@var{FACE} will be applied to the line.
+@end table
@node Paging the Article
@section Scrolling the Article
+@cindex article scrolling
@table @kbd
+
@item SPACE
@kindex SPACE (Summary)
@findex gnus-summary-next-page
Pressing @kbd{SPACE} will scroll the current article forward one page,
or, if you have come to the end of the current article, will choose the
next article (@code{gnus-summary-next-page}).
+
@item DEL
@kindex DEL (Summary)
@findex gnus-summary-prev-page
-Scoll the current article back one page (@code{gnus-summary-prev-page}).
+Scroll the current article back one page (@code{gnus-summary-prev-page}).
@item RET
@kindex RET (Summary)
@findex gnus-summary-scroll-up
Scroll the current article one line forward
(@code{gnus-summary-scroll-up}).
-@item <
+
+@item A <
+@itemx <
@kindex < (Summary)
+@kindex A < (Summary)
@findex gnus-summary-beginning-of-article
Scroll to the beginning of the article
(@code{gnus-summary-beginning-of-article}).
-@item >
+
+@item A >
+@itemx >
@kindex > (Summary)
+@kindex A > (Summary)
@findex gnus-summary-end-of-article
Scroll to the end of the article (@code{gnus-summary-end-of-article}).
+
+@item A s
+@kindex A s (Summary)
+@findex gnus-summary-isearch-article
+Perform an isearch in the article buffer
+(@code{gnus-summary-isearch-article}).
+
@end table
@node Reply Followup and Post
-@section Reply Followup and Post
+@section Reply, Followup and Post
+@cindex reply
+@cindex followup
+@cindex post
@kindex C-c C-c (Post)
All the commands for posting and mailing will put you in a post or mail
buffer where you can edit the article all you like, before you send the
-article by pressing @kbd{C-c C-c}.
+article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
+and you wish to post the article using the foreign server, you can give
+a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
+server.
+
+@menu
+* Mail:: Mailing & replying.
+* Post:: Posting and following up.
+* Mail & Post:: Mailing and posting at the same time.
+* Posting Styles:: An easier way to configure some key elements.
+* Drafts:: Postponing messages and rejected messages.
+* Rejected Articles:: What happens if the server doesn't like your article?
+@end menu
+
+@node Mail
+@subsection Mail
+
+Commands for composing a mail message:
@table @kbd
-@item a
-@kindex a (Summary)
-@findex gnus-summary-post-news
-Post an article to the current group
-(@code{gnus-summary-post-news}).
-@item f
-@kindex f (Summary)
-@findex gnus-summary-followup
-Post a followup to the current article (@code{gnus-summary-followup}).
-@item F
-@kindex F (Summary)
-@findex gnus-summary-followup-with-original
-Post a followup to the current article and include the original message
-(@code{gnus-summary-followup-with-original}).
-@item r
+@item S r
+@itemx r
+@kindex S r (Summary)
@kindex r (Summary)
@findex gnus-summary-reply
Mail a reply to the author of the current article
(@code{gnus-summary-reply}).
-@item R
+@item S R
+@itemx R
@kindex R (Summary)
+@kindex S R (Summary)
@findex gnus-summary-reply-with-original
Mail a reply to the author of the current article and include the
-original message (@code{gnus-summary-reply-with-original}).
-@item C-c C-f
-@kindex C-c C-f (Summary)
+original message (@code{gnus-summary-reply-with-original}). This
+command uses the process/prefix convention.
+@item S o m
+@kindex S o m (Summary)
@findex gnus-summary-mail-forward
Forward the current article to some other person
(@code{gnus-summary-mail-forward}).
-@item m
+@item S o p
+@kindex S o p (Summary)
+@findex gnus-summary-post-forward
+Forward the current article to a newsgroup
+(@code{gnus-summary-post-forward}).
+@item S m
+@itemx m
@kindex m (Summary)
+@kindex S m (Summary)
@findex gnus-summary-mail-other-window
Send a mail to some other person
-(@code{gnus-summary-mail-other-window}).
+(@code{gnus-summary-mail-other-window}).
+@item S D b
+@kindex S D b (Summary)
+@findex gnus-summary-resend-bounced-mail
+If you have sent a mail, but the mail was bounced back to you for some
+reason (wrong address, transient failure), you can use this command to
+resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
+will be popped into a mail buffer where you can edit the headers before
+sending the mail off again. The headers that match the regexp
+@code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
+automatically deleted first. If you give a prefix to this command, and
+the bounced mail is a reply to some other mail, Gnus will try to fetch
+that mail and display it for easy perusal of its headers. This might
+very well fail, though.
+@item S O m
+@kindex S O m (Summary)
+@findex gnus-uu-digest-mail-forward
+Digest the current series and forward the result using mail
+(@code{gnus-uu-digest-mail-forward}). This command uses the
+process/prefix convention (@pxref{Process/Prefix}).
+@item S O p
+@kindex S O p (Summary)
+@findex gnus-uu-digest-post-forward
+Digest the current series and forward the result to a newsgroup
+(@code{gnus-uu-digest-mail-forward}).
@end table
-@vindex gnus-required-headers
-Gnus determines which headers it should generate in outgoing posts by
-consulting the @code{gnus-required-headers} variable. This is a list of
-headers that Gnus makes sure is present in all outgoing posts before it
-tries to post them.
+Variables for customizing outgoing mail:
-@vindex gnus-followup-to-function
+@table @code
+@item gnus-reply-to-function
@vindex gnus-reply-to-function
-Gnus uses the normal methods to determine where replys and follow-ups
-are to go, but you can change the behaviour to suit your need by
-fiddling with the @code{gnus-reply-to-function} and
-@code{gnus-followup-to-function} variables.
+Gnus uses the normal methods to determine where replies are to go, but
+you can change the behavior to suit your needs by fiddling with this
+variable.
-To take "reply" as an example: If you want the replies to go to the
-"sender" instead of the "from" in the group "mail.stupid-list", you
-could do something like this:
+If you want the replies to go to the @samp{Sender} instead of the
+@samp{From} in the group @samp{mail.stupid-list}, you could do something
+like this:
-@example
+@lisp
(setq gnus-reply-to-function
- '(lambda (group)
- (cond ((string= group "mail.stupid-list")
- (mail-fetch-field "sender"))
- (t
- nil))))
-@end example
+ (lambda (group)
+ (cond ((string= group "mail.stupid-list")
+ (mail-fetch-field "sender"))
+ (t
+ nil))))
+@end lisp
+
+This function will be called narrowed to the head of the article that is
+being replied to.
+
+As you can see, this function should return a string if it has an
+opinion as to what the To header should be. If it does not, it should
+just return @code{nil}, and the normal methods for determining the To
+header will be used.
+
+This function can also return a list. In that case, each list element
+should be a cons, where the car should be the name of an header
+(eg. @samp{Cc}) and the cdr should be the header value
+(eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
+the head of the outgoing mail.
+
+@item gnus-mail-send-method
+@vindex gnus-mail-send-method
+This variable says how a mail should be mailed. It uses the function in
+the @code{send-mail-function} variable as the default.
+
+@item gnus-uu-digest-headers
+@vindex gnus-uu-digest-headers
+List of regexps to match headers included in digested messages. The
+headers will be included in the sequence they are matched.
+
+@item gnus-mail-hook
+@vindex gnus-mail-hook
+Hook called as the last thing after setting up a mail buffer.
+
+@item gnus-required-mail-headers
+@vindex gnus-required-mail-headers
+Gnus will generate headers in all outgoing mail instead of letting
+@code{sendmail} do it for us. This makes it possible to do more neat
+stuff, like putting mail without sending it, do hairy @code{Fcc}
+handling, and much more. This variable controls what headers Gnus will
+generate, and is of the exact same form as @code{gnus-required-headers},
+which does the same for news articles (@pxref{Post}).
+
+The @code{Newsgroups} header is illegal in this list, while @code{To} is
+required, and @code{X-Mailer} can be added if you so should want.
+
+@end table
-These functions will be called with point in the buffer of the article
-that is being replied to (or followed up).
+@kindex C-c C-c (Mail)
+@kindex C-c C-p (Mail)
+@findex gnus-put-message
+You normally send a mail message by pressing @kbd{C-c C-c}. However,
+you may wish to just put the mail message you have just written in your
+own local mail group instead of sending it. Sounds quite unlikely, but
+I found that useful, so you can now also press @kbd{C-c C-p} to
+@dfn{put} the article in the current mail group, or, if there is no such
+thing, you will be prompted for a mail group, and then the article will
+be put there. This means that the article is @dfn{not} mailed.
-@vindex mail-signature
-@vindex gnus-signature-file
-If @code{gnus-signature-file} is non-nil, it should be the name of a
-file containing a signature (@samp{~/.signature} by default). This
-signature will be appended to all outgoing post. Most people find it
-more convenient to use @code{mail-signature}, which does the same, but
-inserts the signature into the buffer before you start editing the post
-(or mail). So - if you have both of these variables set, you will get
-two signatures.
+There are three "methods" for handling all mail. The default is
+@code{sendmail}. Some people like what @code{mh} does better, and some
+people prefer @code{vm}.
+
+Three variables for customizing what to use when:
+
+@table @code
+
+@vindex gnus-mail-reply-method
+@item gnus-mail-reply-method
+This function is used to compose replies. The three functions avaibale
+are:
+
+@findex gnus-mail-reply-using-vm
+@findex gnus-mail-reply-using-mhe
+@findex gnus-mail-reply-using-mail
+@itemize @bullet
+@item
+@code{gnus-mail-reply-using-mail} (sendmail)
+@item
+@code{gnus-mail-reply-using-mhe} (mh)
+@item
+@code{gnus-mail-reply-using-vm} (vm)
+@end itemize
+
+@vindex gnus-mail-forward-method
+@item gnus-mail-forward-method
+This function is used to forward messages. The three functions avaibale
+are:
+
+@findex gnus-mail-forward-using-vm
+@findex gnus-mail-forward-using-mhe
+@findex gnus-mail-forward-using-mail
+@itemize @bullet
+@item
+@code{gnus-mail-forward-using-mail} (sendmail)
+@item
+@code{gnus-mail-forward-using-mhe} (mh)
+@item
+@code{gnus-mail-forward-using-vm} (vm)
+@end itemize
+
+@vindex gnus-mail-other-window-method
+@item gnus-mail-other-window-method
+This function is used to send mails. The three functions avaibale are:
+
+@findex gnus-mail-other-window-using-vm
+@findex gnus-mail-other-window-using-mhe
+@findex gnus-mail-other-window-using-mail
+@itemize @bullet
+@item
+@code{gnus-mail-other-window-using-mail} (sendmail)
+@item
+@code{gnus-mail-other-window-using-mhe} (mh)
+@item
+@code{gnus-mail-other-window-using-vm} (vm)
+@end itemize
+@end table
+
+
+@node Post
+@subsection Post
+
+Commands for posting an article:
+
+@table @kbd
+@item S p
+@itemx a
+@kindex a (Summary)
+@kindex S p (Summary)
+@findex gnus-summary-post-news
+Post an article to the current group
+(@code{gnus-summary-post-news}).
+@item S f
+@itemx f
+@kindex f (Summary)
+@kindex S f (Summary)
+@findex gnus-summary-followup
+Post a followup to the current article (@code{gnus-summary-followup}).
+@item S F
+@itemx F
+@kindex S F (Summary)
+@kindex F (Summary)
+@findex gnus-summary-followup-with-original
+Post a followup to the current article and include the original message
+(@code{gnus-summary-followup-with-original}). This command uses the
+process/prefix convention.
+@item S u
+@kindex S u (Summary)
+@findex gnus-uu-post-news
+Uuencode a file, split it into parts, and post it as a series
+(@code{gnus-uu-post-news}).
+@c (@pxref{Uuencoding & Posting}).
+@end table
+
+@vindex gnus-required-headers
+@code{gnus-required-headers} a list of header symbols. These headers
+will either be automatically generated, or, if that's impossible, they
+will be prompted for. The following symbols are legal:
+
+@table @code
+@item From
+This required header will be filled out with the result of the
+@code{gnus-inews-user-name} function, which depends on the
+@code{gnus-user-from-line}, @code{gnus-user-login-name},
+@code{gnus-local-domain} and @code{user-mail-address} variables.
+@item Subject
+This required header will be prompted for if not present already.
+@item Newsgroups
+This required header says which newsgroups the article is to be posted
+to. If it isn't present already, it will be prompted for.
+@item Organization
+@cindex organization
+@vindex gnus-local-organization
+@vindex gnus-organization-file
+This optional header will be filled out depending on the
+@code{gnus-local-organization} variable. @code{gnus-organization-file}
+will be used if that variable is nil.
+@item Lines
+This optional header will be computed by Gnus.
+@item Message-ID
+This required header will be generated by Gnus. A unique ID will be
+created based on date, time, user name and system name.
+@item X-Newsreader
+This optional header will be filled out with the Gnus version numbers.
+@end table
+
+In addition, you can enter conses into this list. The car of this cons
+should be a symbol. This symbol's name is the name of the header, and
+the cdr can either be a string to be entered verbatim as the value of
+this header, or it can be a function to be called. This function should
+return a string to be inserted. For instance, if you want to insert
+@samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
+into the list. If you want to insert a funny quote, you could enter
+something like @code{(X-Yow . yow)} into the list. The function
+@code{yow} will then be called without any arguments.
+
+The list contains a cons where the car of the cons is @code{optional},
+the cdr of this cons will only be inserted if it is non-@code{nil}.
+
+Other variables for customizing outgoing articles:
+
+@table @code
+@item gnus-post-method
+@vindex gnus-post-method
+If non-@code{nil}, Gnus will use this method instead of the default
+select method when posting.
+
+@item nntp-news-default-headers
+@vindex nntp-news-default-headers
+If non-@code{nil}, this variable will override
+@code{mail-default-headers} when posting. This variable should then be
+a string. This string will be inserted, as is, in the head of all
+outgoing articles.
+
+@item gnus-use-followup-to
+@vindex gnus-use-followup-to
+If @code{nil}, always ignore the Followup-To header. If it is @code{t},
+use its value, but ignore the special value @samp{poster}, which will
+send the followup as a reply mail to the person you are responding to.
+If it is the symbol @code{ask}, query the user before posting.
+If it is the symbol @code{use}, always use the value.
+
+@item gnus-followup-to-function
+@vindex gnus-followup-to-function
+This variable is most useful in mail groups, where "following up" really
+means sending a mail to a list address. Gnus uses the normal methods to
+determine where follow-ups are to go, but you can change the behavior
+to suit your needs by fiddling with this variable.
+
+If you want the followups to go to the @samp{Sender} instead of the
+@samp{From} in the group @samp{mail.stupid-list}, you could do something
+like this:
+
+@lisp
+(setq gnus-followup-to-function
+ (lambda (group)
+ (cond ((string= group "mail.stupid-list")
+ (mail-fetch-field "sender"))
+ (t
+ nil))))
+@end lisp
+
+This function will be called narrowed to header of the article that is
+being followed up.
+
+@item gnus-removable-headers
+@vindex gnus-removable-headers
+Some headers that are generated are toxic to the @sc{nntp} server.
+These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
+so these headers are deleted if they are present in this list of
+symbols.
+
+@item gnus-deletable-headers
+@vindex gnus-deletable-headers
+Headers in this list that were previously generated by Gnus will be
+deleted before posting. Let's say you post an article. Then you decide
+to post it again to some other group, you naughty boy, so you jump back
+to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
+ship it off again. By default, this variable makes sure that the old
+generated @code{Message-ID} is deleted, and a new one generated. If
+this isn't done, the entire empire would probably crumble, anarchy would
+prevail, and cats would start walking on two legs and rule the world.
+Allegedly.
+
+@item gnus-signature-function
+@vindex gnus-signature-function
+If non-@code{nil}, this variable should be a function that returns a
+signature file name. The function will be called with the name of the
+group being posted to. If the function returns a string that doesn't
+correspond to a file, the string itself is inserted. If the function
+returns @code{nil}, the @code{gnus-signature-file} variable will be used
+instead.
+
+@item gnus-post-prepare-function
@vindex gnus-post-prepare-function
-In any case, @code{gnus-post-prepare-function} is called with the name
-of the current group after the post buffer has been initialized, and can
-be used for inserting a signature. Nice if you use different signatures
-in different groups.
+This function is called with the name of the current group after the
+post buffer has been initialized, and can be used for inserting a
+signature. Nice if you use different signatures in different groups.
+
+@item gnus-post-prepare-hook
+@vindex gnus-post-prepare-hook
+This hook is called after a post buffer has been prepared. If you want
+to insert a signature at this point, you could put
+@code{gnus-inews-insert-signature} into this hook.
+
+@item news-reply-header-hook
+@vindex news-reply-header-hook
+A related variable when following up and replying is this variable,
+which inserts the @dfn{quote line}. The default value is:
+
+@lisp
+(defvar news-reply-header-hook
+ (lambda ()
+ (insert "In article " news-reply-yank-message-id
+ " " news-reply-yank-from " writes:\n\n")))
+@end lisp
+
+This will create lines like:
-@vindex gnus-auto-mail-to-author
-If @code{gnus-auto-mail-to-author} is non-nil, Gnus will send a mail
-with a copy of all follow-ups to the authors of the articles you follow
-up. It's nice in one way - you make sure that the person you are
-responding to gets your response. Other people loathe this method and
-will hate you dearly for it, because it means that they will first get a
-mail, and then have to read the same article later when they read the
-news. It is nil by default.
+@example
+In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
+@end example
-@vindex gnus-mail-send-method
-@code{gnus-mail-send-method} says how a mail should be mailed. It uses
-the function in the @code{send-mail-function} as the default.
+Having the @code{Message-ID} in this line is probably overkill, so I
+would suggest this hook instead:
+
+@lisp
+(setq news-reply-header-hook
+ (lambda () (insert news-reply-yank-from " writes:\n\n")))
+@end lisp
+@item gnus-prepare-article-hook
@vindex gnus-prepare-article-hook
-@code{gnus-prepare-article-hook} is called before the header fields have
-been prepared. By default it inserts the signature specified by
-@code{gnus-signature-file}.
+This hook is called before the headers have been prepared.
+@item gnus-inews-article-function
+@vindex gnus-inews-article-function
+This function is used to do the actual article processing and header
+checking/generation.
+
+@item gnus-inews-article-hook
@vindex gnus-inews-article-hook
-@code{gnus-inews-article-hook} is called right before the article is
-posted. By default it handles FCC processing (ie. saving the article to
-a file.)
+This hook is called right before the article is posted. By default it
+handles FCC processing (i.e., saving the article to a file.)
+
+@item gnus-inews-article-header-hook
+@vindex gnus-inews-article-header-hook
+This hook is called after inserting the required headers in an article
+to be posted. The hook is called from the @code{*post-news*} buffer,
+narrowed to the head, and is intended for people who would like to
+insert additional headers, or just change headers in some way or other.
+
+@item gnus-check-before-posting
+@vindex gnus-check-before-posting
+If non-@code{nil}, Gnus will attempt to check the legality of the
+headers, as well as some other stuff, before posting. You can control
+the granularity of the check by adding or removing elements from this
+list. Legal elemetents are:
+
+@table @code
+@item subject-cmsg
+Check the subject for commands.
+@item sender
+Insert a new @code{Sender} header if the @code{From} header looks odd.
+@item multiple-headers
+Check for the existence of multiple equal headers.
+@item sendsys
+Check for the existence of version and sendsys commands.
+@item message-id
+Check whether the @code{Message-ID} looks ok.
+@item from
+Check whether the @code{From} header seems nice.
+@item long-lines
+Check for too long lines.
+@item control-chars
+Check for illegal characters.
+@item size
+Check for excessive size.
+@item new-text
+Check whether there is any new text in the messages.
+@item signature
+Check the length of the signature.
+@item approved
+Check whether the article has an @code{Approved} header, which is
+something only moderators should include.
+@end table
+
+@end table
+
+
+@node Mail & Post
+@subsection Mail & Post
+
+Commands for sending mail and post at the same time:
+
+@table @kbd
+@item S b
+@kindex S b (Summary)
+@findex gnus-summary-followup-and-reply
+Post a followup and send a reply to the current article
+(@code{gnus-summary-followup-and-reply}).
+@item S B
+@kindex S B (Summary)
+@findex gnus-summary-followup-and-reply-with-original
+Post a followup and send a reply to the current article and include the
+original message (@code{gnus-summary-followup-and-reply-with-original}).
+This command uses the process/prefix convention.
+@end table
+
+Here's a list of variables that are relevant to both mailing and
+posting:
+
+@table @code
+@item gnus-signature-file
+@itemx mail-signature
+@vindex mail-signature
+@vindex gnus-signature-file
+@cindex double signature
+@cindex signature
+If @code{gnus-signature-file} is non-@code{nil}, it should be the name
+of a file containing a signature (@samp{~/.signature} by default). This
+signature will be appended to all outgoing post. Most people find it
+more convenient to use @code{mail-signature}, which (sort of) does the
+same, but inserts the signature into the buffer before you start editing
+the post (or mail). So---if you have both of these variables set, you
+will get two signatures. Note that @code{mail-signature} does not work
+the same way as @code{gnus-signature-file}, which is a bit confusing.
+If @code{mail-signature} is @code{t}, it will insert
+@file{~/.signature}. If it is a string, this string will be inserted.
+
+Note that RFC1036 says that a signature should be preceded by the three
+characters @samp{-- } on a line by themselves. This is to make it
+easier for the recipient to automatically recognize and process the
+signature. So don't remove those characters, even though you might feel
+that they ruin you beautiful design, like, totally.
+
+Also note that no signature should be more than four lines long.
+Including ASCII graphics is an efficient way to get everybody to believe
+that you are silly and have nothing important to say.
+
+@item mail-yank-prefix
+@vindex mail-yank-prefix
+@cindex yanking
+@cindex quoting
+When you are replying to or following up an article, you normally want
+to quote the person you are answering. Inserting quoted text is done by
+@dfn{yanking}, and each quoted line you yank will have
+@code{mail-yank-prefix} prepended to it. This is @samp{ } by default,
+which isn't very pretty. Most everybody prefers that lines are
+prepended with @samp{> }, so @code{(setq mail-yank-prefix "> ")} in your
+@file{.emacs} file.
+
+@item mail-yank-ignored-headers
+@vindex mail-yank-ignored-headers
+When you yank a message, you do not want to quote any headers, so
+@code{(setq mail-yank-ignored-headers "^")}.
+
+@item user-mail-address
+@vindex user-mail-address
+If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
+@code{gnus-local-domain} are @code{nil}, Gnus will use
+@code{user-mail-address} as the address part of the @code{From} header.
+
+@item gnus-local-domain
+@vindex gnus-local-domain
+@cindex domain
+The local doman name excluding the host name. If your host is called
+@samp{"narfi.ifi.uio.no"}, then this variable should be
+@samp{"ifi.uio.no"}.
+
+@item gnus-local-domain
+@vindex gnus-local-domain
+@cindex domain
+The local doman name excluding the host name. If your host is called
+@samp{"narfi.ifi.uio.no"}, then this variable should be
+@samp{"ifi.uio.no"}.
+
+@item gnus-user-from-line
+@vindex gnus-user-from-line
+Your full, complete e-mail address with name. This variable overrides
+the other Gnus variables if it is non-@code{nil}.
+
+Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
+(Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
+<larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
+probably illegal in mail), but the name has to be quoted if it contains
+non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
+<larsi@@ifi.uio.no>"}.
+
+@item mail-default-headers
+@vindex mail-default-headers
+This is a string that will be inserted into the header of all outgoing
+mail messages and news articles. Convenient to use to insert standard
+headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
+variable will override this one when posting articles.
+
+@item gnus-auto-mail-to-author
+@vindex gnus-auto-mail-to-author
+If @code{ask}, you will be prompted for whether you want to send a mail
+copy to the author of the article you are following up. If
+non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
+all follow-ups to the authors of the articles you follow up. It's nice
+in one way---you make sure that the person you are responding to gets
+your response. Other people loathe this method and will hate you dearly
+for it, because it means that they will first get a mail, and then have
+to read the same article later when they read the news. It is
+@code{nil} by default.
+
+@item gnus-mail-courtesy-message
+@vindex gnus-mail-courtesy-message
+This is a string that will be prepended to all mails that are the result
+of using the variable described above.
+
+@item gnus-outgoing-message-group
+@vindex gnus-outgoing-message-group
+All outgoing messages will be put in this group. If you want to store
+all your outgoing mail and articles in the group @samp{nnml:archive},
+you set this variable to that value. This variable can also be a list of
+group names.
+
+If you want to have greater control over what group to put each
+message in, you can set this variable to a function that checks the
+current newsgroup name and then returns a suitable group name (or list
+of names).
+
+@item gnus-mailing-list-groups
+@findex gnus-mailing-list-groups
+@cindex mailing lists
+
+If your newsserver offer groups that are really mailing lists that are
+gatewayed to the @sc{nntp} server, you can read those groups without
+problems, but you can't post/followup to them without some difficulty.
+One solution is to add a @code{to-address} to the group parameters
+(@pxref{Group Parameters}). An easier thing to do is set the
+@code{gnus-mailing-list-groups} to a regexp that match the groups that
+really are mailing lists. Then, at least, followups to the mailing
+lists will work most of the time. Posting to these groups (@kbd{a}) is
+still a pain, though.
+
+
+@end table
-@node Cancelling and Superceding
-@section Cancelling Articles
+You may want to do spell-checking on messages that you send out. Or, if
+you don't want to spell-check by hand, you could add automatic
+spell-checking via the @code{ispell} package:
+
+@vindex news-inews-hook
+@lisp
+(add-hook 'news-inews-hook 'ispell-message) ;For news posts
+(add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
+@end lisp
+
+@findex gnus-inews-insert-mime-headers
+If you want to insert some @sc{mime} headers into the articles you post,
+without doing any actual encoding, you could add
+@code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
+
+
+@node Posting Styles
+@subsection Posting Styles
+@cindex posting styles
+@cindex styles
+
+All them variables, they make my head swim.
+
+So what if you want a different @code{Organization} and signature based
+on what groups you post to? And you post both from your home machine
+and your work machine, and you want different @code{From} lines, and so
+on?
+
+@vindex gnus-posting-styles
+One way to do stuff like that is to write clever hooks that change the
+variables you need to have changed. That's a bit boring, so somebody
+came up with the bright idea of letting the user specify these things in
+a handy alist. Here's an example of a @code{gnus-posting-styles}
+variable:
+
+@lisp
+((".*" (signature . "Peace and happiness") (organization . "What me?"))
+ ("^comp" (signature . "Death to everybody"))
+ ("comp.emacs.i-love-it" (organization . "Emacs is it")))
+@end lisp
+
+As you might surmise from this example, this alist consists of several
+@dfn{styles}. Each style will be applicable if the first element
+"matches", in some form or other. The entire alist will be iterated
+over, from the beginning towards the end, and each match will be
+applied, which means that attributes in later styles that match override
+the same attributes in earlier matching styles. So
+@samp{comp.programming.literate} will have the @samp{Death to everybody}
+signature and the @samp{What me?} @code{Organization} header.
+
+The first element in each style is called the @code{match}. If it's a
+string, then Gnus will try to regexp match it against the group name.
+If it's a function symbol, that function will be called with no
+arguments. If it's a variable symbol, then the variable will be
+referenced. If it's a list, then that list will be @code{eval}ed. In
+any case, if this returns a non-@code{nil} value, then the style is said
+to @dfn{match}.
+
+Each style may contain a random amount of @dfn{attributes}. Each
+attribute consists of a @var{(name . value)} pair. The attribute name
+can be one of @code{signature}, @code{organization} or @code{from}.
+The attribute name can also be a string. In that case, this will be
+used as a header name, and the value will be inserted in the headers of
+the article.
+
+The attribute value can be a string (used verbatim), a function (the
+return value will be used), a variable (its value will be used) or a
+list (it will be @code{eval}ed and the return value will be used).
+
+So here's a new example:
+
+@lisp
+(setq gnus-posting-styles
+ '((".*"
+ (signature . "~/.signature")
+ (from . "user@@foo (user)")
+ ("X-Home-Page" . (getenv "WWW_HOME"))
+ (organization . "People's Front Against MWM"))
+ ("^rec.humor"
+ (signature . my-funny-signature-randomizer))
+ ((equal (system-name) "gnarly")
+ (signature . my-quote-randomizer))
+ (posting-from-work-p
+ (signature . "~/.work-signature")
+ (from . "user@@bar.foo (user)")
+ (organization . "Important Work, Inc"))
+ ("^nn.+:"
+ (signature . "~/.mail-signature"))))
+@end lisp
+
+
+
+@node Drafts
+@subsection Drafts
+@cindex drafts
+
+If you are writing a message (mail or news) and suddenly remember that
+you have a steak in the oven (or pesto in the food processor, you craazy
+vegetarians), you'll probably wish there was a method to save the
+message you are writing so that you can continue editing it some other
+day, and send it when you feel its finished.
+
+@kindex C-c C-d (Mail)
+@kindex C-c C-d (Post)
+@findex gnus-enter-into-draft-group
+@vindex gnus-draft-group-directory
+What you then do is simply push @kbd{C-c C-d}
+(@code{gnus-enter-into-draft-group}). This will put the current
+(unfinished) message in a special draft group (which is implemented as
+an @code{nndir} group, if you absolutely have to know) called
+@samp{nndir:drafts}. The variable @code{gnus-draft-group-directory}
+controls both the name of the group and the location---the leaf element
+in the path will be used as the name of the group.
+
+If the group doesn't exist, it will be created and you'll be subscribed
+to it.
+
+@findex gnus-summary-send-draft
+@kindex S D c S (Summary)
+When you want to continue editing the article, you simply enter the
+draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
+that. You will be placed in a buffer where you left off.
+
+Rejected articles will also be put in this draft group (@pxref{Rejected
+Articles}).
+
+@findex gnus-summary-send-all-drafts
+If you have lots of rejected messages you want to post (or mail) without
+doing further editing, you can use the @kbd{S D a} command
+(@code{gnus-summary-send-all-drafts}). This command understands the
+process/prefix convention (@pxref{Process/Prefix}).
+
+
+@node Rejected Articles
+@subsection Rejected Articles
+@cindex rejected articles
+
+Sometimes a news server will reject an article. Perhaps the server
+doesn't like your face. Perhaps it just feels miserable. Perhaps
+@emph{there be demons}. Perhaps you have included too much cited text.
+Perhaps the disk is full. Perhaps the server is down.
+
+These situations are, of course, totally beyond the control of Gnus.
+(Gnus, of course, loves the way you look, always feels great, has angels
+fluttering around inside of it, doesn't care about how much cited text
+you include, never runs full and never goes down.) So Gnus saves these
+articles until some later time when the server feels better.
+
+The rejected articles will automatically be put in a special draft group
+(@pxref{Drafts}). When the server comes back up again, you'd then
+typically enter that group and send all the articles off.
+
+
+@node Canceling and Superseding
+@section Canceling Articles
+@cindex canceling articles
+@cindex superseding articles
Have you ever written something, and then decided that you really,
-really, really hadn't posted that?
+really, really wish you hadn't posted that?
Well, you can't cancel mail, but you can cancel posts.
@findex gnus-summary-cancel-article
@kindex C (Summary)
Find the article you wish to cancel (you can only cancel your own
-articles, so don't try any funny stuff). Then press @kbd{C}
-(@code{gnus-summary-cancel-article}). Your article will be cancelled.
+articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
+c} (@code{gnus-summary-cancel-article}). Your article will be
+canceled---machines all over the world will be deleting your article.
Be aware, however, that not all sites honor cancels, so your article may
-live on in some parts of the world, while most sites will delete the
-cancelled article.
+live on here and there, while most sites will delete the article in
+question.
If you discover that you have made some mistakes and want to do some
corrections, you can post a @dfn{superseding} article that will replace
@findex gnus-summary-supersede-article
@kindex S (Summary)
-Go to the original article and press @kbd{S}
+Go to the original article and press @kbd{S s}
(@code{gnus-summary-supersede-article}). You will be put in a buffer
where you can edit the article all you want before sending it off the
usual way.
-The same goes for superseding as for cancelling, only more so: Some
+@vindex gnus-delete-supersedes-headers
+You probably want to delete some of the old headers before sending the
+superseding article---@code{Path} and @code{Date} are probably
+incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
+match the lines you want removed. The default is
+@samp{"^Path:\\|^Date"}.
+
+The same goes for superseding as for canceling, only more so: Some
sites do not honor superseding. On those sites, it will appear that you
have posted almost the same article twice.
-If you have just posted the article, and changed your mind right away,
+If you have just posted the article, and change your mind right away,
there is a trick you can use to cancel/supersede the article without
waiting for the article to appear on your site first. You simply return
to the post buffer (which is called @code{*post-buf*}). There you will
the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
header by substituting one of those words for @samp{Message-ID}. Then
just press @kbd{C-c C-c} to send the article as you would do normally.
-The previous article will be cancelled/superseded.
+The previous article will be canceled/superseded.
+
+Just remember, kids: There is no 'c' in 'supersede'.
-@node Ticking and Marking
-@section Ticking and Marking
+@node Marking Articles
+@section Marking Articles
+@cindex article marking
+@cindex article ticking
+@cindex marks
There are several marks you can set on an article.
-First you have the marks that decide the "readed-ness" (whoo,
-neato-keano neologism ohoy!) of the article. It can be unread, ticked,
-dormant or read, in ascending readed-ness ordering.
+You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
+neologism ohoy!) of the article. Alphabetic marks generally mean
+@dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
+
+In addition, you also have marks that do not affect readedness.
+
+@menu
+* Unread Articles:: Marks for unread articles.
+* Read Articles:: Marks for read articles.
+* Other Marks:: Marks that do not affect readedness.
+@end menu
+
+@ifinfo
+There's a plethora of commands for manipulating these marks:
+@end ifinfo
+
+@menu
+* Setting Marks:: How to set and remove marks.
+* Setting Process Marks:: How to mark articles for later processing.
+@end menu
+
+@node Unread Articles
+@subsection Unread Articles
+
+The following marks mark articles as unread, in one form or other.
+@vindex gnus-dormant-mark
+@vindex gnus-ticked-mark
+@table @samp
+@item !
@dfn{Ticked articles} are articles that will remain visible always. If
you see an article that you find interesting, or you want to put off
reading it, or replying to it, until sometime later, you'd typically
tick it. However, articles can be expired, so if you want to keep an
-article forever, you'll have to save it. Ticked articles have a @samp{-}
-in the first column.
+article forever, you'll have to save it. Ticked articles have a
+@samp{!} (@code{gnus-ticked-mark}) in the first column.
+@item ?
+A @dfn{dormant} article is marked with a @samp{?}
+(@code{gnus-dormant-mark}), and will only appear in the summary buffer
+if there are followups to it.
+@item SPC
+An @dfn{unread} article is marked with a @samp{SPC}
+(@code{gnus-unread-mark}). These are articles that haven't been read at
+all yet.
+@end table
+
+@node Read Articles
+@subsection Read Articles
+@cindex expirable mark
-A @dfn{dormant} article is marked with a @samp{+}, and will only appear
-in the summary buffer if there are followups to it.
+All the following marks mark articles as read.
+
+@table @samp
+@item r
+Articles that are marked as read. They have a @samp{r}
+(@code{gnus-del-mark}) in the first column. These are articles that the
+user has marked as read more or less manually.
+@item R
+Articles that are actually read are marked with @samp{R}
+(@code{gnus-read-mark}).
+@item O
+Articles that were marked as read in previous sessions are now
+@dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
+@item K
+Marked as killed (@code{gnus-killed-mark}).
+@item X
+Marked as killed by kill files (@code{gnus-kill-file-mark}).
+@item Y
+Marked as read by having a too low score (@code{gnus-low-score-mark}).
+@item C
+Marked as read by a catchup (@code{gnus-catchup-mark}).
+@item G
+Canceled article (@code{gnus-cancelled-mark})
+@end table
-Articles that are marked as read - are just that. They have a @samp{D}
-in the first column. Unread articles have a space in the first column.
+All these marks just mean that the article is marked as read, really.
+They are interpreted differently by the adaptive scoring scheme,
+however.
-There are also some marks that do not affect readed-ness:
+One more special mark, though:
+@table @samp
+@item E
You can also mark articles as @dfn{expirable} (or have them marked as
such automatically). That doesn't make much sense in normal groups,
because a user does not control the expiring of news articles, but in
mail groups, for instance, articles that are marked as @dfn{expirable}
-can be deleted by Gnus at any time. Expirable articles have a @samp{X}
-in the third column.
+can be deleted by Gnus at any time. Expirable articles are marked with
+@samp{E} (@code{gnus-expirable-mark}).
+@end table
+
+@node Other Marks
+@subsection Other Marks
+@cindex process mark
+@cindex bookmarks
-You can set a bookmark in the current article. Say you are reading a
+There are some marks that have nothing to do with whether the article is
+read or not.
+
+You can set a bookmark in the current article. Say you are reading a
long thesis on cat's urinary tracts, and have to go home for dinner
-before you've finished reading the thesis. You can then set a bookmark
+before you've finished reading the thesis. You can then set a bookmark
in the article, and Gnus will jump to this bookmark the next time it
encounters the article.
-Finally we have the @dfn{process mark}. A variety of commands react to
-the presence of the process mark. For instance, @kbd{C-c C-v M-C-v}
-(@code{gnus-uu-decode-and-view-marked-articles}) will uudecode and view
-all artciles that have been marked with the process mark. Articles
-marked with the process mark have a @samp{#} in the third column.
+All articles that you have replied to or made a followup to (i.e., have
+answered) will be marked with an @samp{A} in the second column
+(@code{gnus-replied-mark}).
+
+@vindex gnus-not-empty-thread-mark
+@vindex gnus-empty-thread-mark
+It the @samp{%e} spec is used, the presence of threads or not will be
+marked with @code{gnus-not-empty-thread-mark} and
+@code{gnus-empty-thread-mark}, respectively.
+
+@vindex gnus-process-mark
+Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
+variety of commands react to the presence of the process mark. For
+instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
+all articles that have been marked with the process mark. Articles
+marked with the process mark have a @samp{#} in the second column.
+
+@node Setting Marks
+@subsection Setting Marks
+@cindex setting marks
All the marking commands understand the numeric prefix.
@table @kbd
-@item -
-@kindex - (Summary)
-@findex gnus-summary-mark-as-unread-forward
-Tick the current article (@code{gnus-summary-mark-as-unread-forward}).
-@item +
-@kindex + (Summary)
+@item M t
+@itemx !
+@kindex ! (Summary)
+@kindex M t (Summary)
+@findex gnus-summary-tick-article-forward
+Tick the current article (@code{gnus-summary-tick-article-forward}).
+@item M ?
+@itemx ?
+@kindex ? (Summary)
+@kindex M ? (Summary)
@findex gnus-summary-mark-as-dormant
Mark the current article as dormant
(@code{gnus-summary-mark-as-dormant}).
-@item d
+@item M d
+@itemx d
+@kindex M d (Summary)
@kindex d (Summary)
@findex gnus-summary-mark-as-read-forward
Mark the current article as read
(@code{gnus-summary-mark-as-read-forward}).
-@item k
+@item M k
+@itemx k
@kindex k (Summary)
+@kindex M k (Summary)
@findex gnus-summary-kill-same-subject-and-select
Mark all articles that have the same subject as the current one as read,
and then select the next unread article
(@code{gnus-summary-kill-same-subject-and-select}).
-@item C-k
+@item M K
+@itemx C-k
+@kindex M K (Summary)
@kindex C-k (Summary)
@findex gnus-summary-kill-same-subject
Mark all articles that have the same subject as the current one as read
(@code{gnus-summary-kill-same-subject}).
-@item M-u
+@item M C
+@kindex M C (Summary)
+@findex gnus-summary-catchup
+Mark all unread articles in the group as read
+(@code{gnus-summary-catchup}).
+@item M C-c
+@kindex M C-c (Summary)
+@findex gnus-summary-catchup-all
+Mark all articles in the group as read---even the ticked and dormant
+articles (@code{gnus-summary-catchup-all}).
+@item M H
+@kindex M H (Summary)
+@findex gnus-summary-catchup-to-here
+Catchup the current group to point
+(@code{gnus-summary-catchup-to-here}).
+@item C-w
+@kindex C-w (Summary)
+@findex gnus-summary-mark-region-as-read
+Mark all articles between point and mark as read
+(@code{gnus-summary-mark-region-as-read}).
+@item M V k
+@kindex M V k (Summary)
+@findex gnus-summary-kill-below
+Kill all articles with scores below the default score (or below the
+numeric prefix) (@code{gnus-summary-kill-below}).
+@item M c
+@itemx M-u
+@kindex M c (Summary)
@kindex M-u (Summary)
@findex gnus-summary-clear-mark-forward
-Clear tick and read marks from the current article
+Clear all readedness-marks from the current article
(@code{gnus-summary-clear-mark-forward}).
-@item x
-@kindex x (Summary)
+@item M e
+@itemx E
+@kindex M e (Summary)
+@kindex E (Summary)
@findex gnus-summary-mark-as-expirable
Mark the current article as expirable
(@code{gnus-summary-mark-as-expirable}).
-@item X
-@kindex X (Summary)
-@findex gnus-summary-unmark-as-expirable
-Remove the expiry mark from the current article
-(@code{gnus-summary-unmark-as-expirable}).
-@item b
-@kindex b (Summary)
+@item M b
+@kindex M b (Summary)
@findex gnus-summary-set-bookmark
Set a bookmark in the current article
(@code{gnus-summary-set-bookmark}).
-@item B
-@kindex B (Summary)
+@item M B
+@kindex M B (Summary)
@findex gnus-summary-remove-bookmark
Remove the bookmark from the current article
(@code{gnus-summary-remove-bookmark}).
-@item M-d
-@kindex M-d (Summary)
-@findex gnus-summary-delete-marked-as-read
-Expunge all deleted articles from the summary buffer
-(@code{gnus-summary-delete-marked-as-read}).
-@item M-C-d
-@kindex M-C-d (Summary)
-@findex gnus-summary-delete-marked-with
-Ask for a mark and then expunge all articles that have been marked with
-that mark (@code{gnus-summary-delete-marked-with}).
-@item C-c M-C-s
-@kindex C-c M-C-s (Summary)
-@findex gnus-summary-show-all-expunged
-Display all expunged articles (@code{gnus-summary-show-all-expunged}).
-@item M-+
-@kindex M-+ (Summary)
-@findex gnus-summary-show-all-dormant
-Display all dormant articles (@code{gnus-summary-show-all-dormant}).
-@end table
-
-There are a few functions for setting the process mark:
+@item M V c
+@kindex M V c (Summary)
+@findex gnus-summary-clear-above
+Clear all marks from articles with scores over the default score (or
+over the numeric prefix) (@code{gnus-summary-clear-above}).
+@item M V u
+@kindex M V u (Summary)
+@findex gnus-summary-tick-above
+Tick all articles with scores over the default score (or over the
+numeric prefix) (@code{gnus-summary-tick-above}).
+@item M V m
+@kindex M V m (Summary)
+@findex gnus-summary-mark-above
+Prompt for a mark, and mark all articles with scores over the default
+score (or over the numeric prefix) with this mark
+(@code{gnus-summary-clear-above}).
+@end table
+
+@code{gnus-summary-goto-unread}
+The @code{gnus-summary-goto-unread} variable controls what action should
+be taken after setting a mark. If non-@code{nil}, point will move to
+the next/previous unread article. If @code{nil}, point will just move
+one line up or down. The default is @code{t}.
+
+
+@node Setting Process Marks
+@subsection Setting Process Marks
+@cindex setting process marks
@table @kbd
-@item #
+@item M P p
+@itemx #
@kindex # (Summary)
-@findex gnus-summary-mark-article-as-processable
+@kindex M P p (Summary)
+@findex gnus-summary-mark-as-processable
Mark the current article with the process mark
-(@code{gnus-summary-mark-article-as-processable}).
-@findex gnus-summary-unmark-article-as-processable
-@item M-#
+(@code{gnus-summary-mark-as-processable}).
+@findex gnus-summary-unmark-as-processable
+@item M P u
+@itemx M-#
+@kindex M P u (Summary)
@kindex M-# (Summary)
-Remove the process mark from the current article
-(@code{gnus-summary-unmark-article-as-processable}).
-@item C-c M-#
-@kindex C-c M-# (Summary)
-@findex gnus-summary-unmark-all-articles-as-processable
+Remove the process mark, if any, from the current article
+(@code{gnus-summary-unmark-as-processable}).
+@item M P U
+@kindex M P U (Summary)
+@findex gnus-summary-unmark-all-processable
Remove the process mark from all articles
-(@code{gnus-summary-unmark-all-articles-as-processable}).
-@item C-c C-v C-r
-@kindex C-c C-v C-r (Summary)
+(@code{gnus-summary-unmark-all-processable}).
+@item M P R
+@kindex M P R (Summary)
@findex gnus-uu-mark-by-regexp
Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
-@item C-c C-v r
-@kindex C-c C-v r (Summary)
+@item M P r
+@kindex M P r (Summary)
@findex gnus-uu-mark-region
-Mark articles in the region (@code{gnus-uu-mark-region}).
-@item C-c C-v t
-@kindex C-c C-v t (Summary)
+Mark articles in region (@code{gnus-uu-mark-region}).
+@item M P t
+@kindex M P t (Summary)
@findex gnus-uu-mark-thread
Mark all articles in the current (sub)thread
(@code{gnus-uu-mark-thread}).
+@item M P T
+@kindex M P T (Summary)
+@findex gnus-uu-unmark-thread
+Unmark all articles in the current (sub)thread
+(@code{gnus-uu-unmark-thread}).
+@item M P s
+@kindex M P s (Summary)
+@findex gnus-uu-mark-series
+Mark all articles in the current series (@code{gnus-uu-mark-series}).
+@item M P S
+@kindex M P S (Summary)
+@findex gnus-uu-mark-sparse
+Mark all series that have already had some articles marked
+(@code{gnus-uu-mark-sparse}).
+@item M P a
+@kindex M P a (Summary)
+@findex gnus-uu-mark-all
+Mark all articles in series order (@code{gnus-uu-mark-series}).
+@item M P b
+@kindex M P b (Summary)
+@findex gnus-uu-mark-buffer
+Mark all articles in the buffer in the order they appear
+(@code{gnus-uu-mark-buffer}).
+@end table
+
+
+@node Limiting
+@section Limiting
+@cindex limiting
+
+It can be convenient to limit the summary buffer to just show some
+subset of the articles currently in the group. The effect most limit
+commands have is to remove a few (or many) articles from the summary
+buffer.
+
+@table @kbd
+
+@item / /
+@kindex / / (Summary)
+@findex gnus-summary-limit-to-subject
+Limit the summary buffer to articles that match some subject
+(@code{gnus-summary-limit-to-subject}).
+
+@item / u
+@itemx x
+@kindex / u (Summary)
+@kindex x (Summary)
+@findex gnus-summary-limit-to-unread
+Limit the summary buffer to articles that are not marked as read
+(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
+buffer to articles that are strictly unread. This means that ticked and
+dormant articles will also be excluded.
+
+@item / m
+@kindex / m (Summary)
+@findex gnus-summary-limit-to-marks
+Ask for a mark and then limit to all articles that have not been marked
+with that mark (@code{gnus-summary-limit-to-marks}).
+
+@item / n
+@kindex / n (Summary)
+@findex
+Limit the summary buffer to the current article
+(@code{gnus-summary-limit-to-articles}). Uses the process/prefix
+convention (@pxref{Process/Prefix}).
+
+@item / w
+@kindex / w (Summary)
+@findex gnus-summary-pop-limit
+Pop the previous limit off the stack and restore it
+(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
+the stack.
+
+@item / s
+@itemx /
+@kindex / s (Summary)
+@kindex / (Summary)
+@findex gnus-summary-limit-to-subject
+Limit the summary buffer to articles that have a subject that matches a
+regexp (@code{gnus-summary-limit-to-subject}).
+
+@item / v
+@kindex / v (Summary)
+@findex gnus-summary-limit-to-score
+Limit the summary buffer to articles that have a score at or above some
+score (@code{gnus-summary-limit-to-score}).
+
+@item / E
+@itemx M S
+@kindex M S (Summary)
+@kindex / E (Summary)
+@findex gnus-summary-limit-include-expunged
+Display all expunged articles
+(@code{gnus-summary-limit-include-expunged}).
+
+@item / D
+@kindex / D (Summary)
+@findex gnus-summary-limit-include-dormant
+Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
+
+@item / d
+@kindex / d (Summary)
+@findex gnus-summary-limit-exclude-dormant
+Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
+
+@item / c
+@kindex / c (Summary)
+@findex gnus-summary-limit-exclude-childless-dormant
+Hide all dormant articles that have no children
+(@code{gnus-summary-limit-exclude-childless-dormant}).
+
@end table
-@findex gnus-uu-marked-universal-argument
-@kindex C-c C-v C-u (Summary)
-Finally, we have @kbd{C-c C-v C-u}
-(@code{gnus-uu-marked-universal-argument}) that will perform any
-operation on all articles that have been marked with the process mark.
@node Threading
@section Threading
+@cindex threading
+@cindex article threading
-Gnus @dfn{threads} articles by default. @dfn{Threading} is to put
-replies to articles directly after the articles they reply to - in a
-hierarchial fashion.
+Gnus threads articles by default. @dfn{To thread} is to put replies to
+articles directly after the articles they reply to---in a hierarchical
+fashion.
@menu
* Customizing Threading:: Variables you can change to affect the threading.
-* Threading Commands:: Thread based commands in the summary buffer.
+* Thread Commands:: Thread based commands in the summary buffer.
@end menu
@node Customizing Threading
@subsection Customizing Threading
+@cindex customizing threading
+@cindex <
+@cindex >
@table @code
@item gnus-show-threads
@vindex gnus-show-threads
-If this variable is nil, no threading will be done, and all of the rest
-of the variables here will have no effect. Turning threading off will
-speed group selection up a bit, but it is sure to make reading
+If this variable is @code{nil}, no threading will be done, and all of
+the rest of the variables here will have no effect. Turning threading
+off will speed group selection up a bit, but it is sure to make reading
slower and more awkward.
+
@item gnus-fetch-old-headers
@vindex gnus-fetch-old-headers
-If non-nil, Gnus will attempt to build old threads by fetching more old
-headers - headers to articles that are marked as read. This only works
-if the server you are using supports XOVER. Also remember that if the
-root of the thread has been expired by the server, there's not much Gnus
-can do about that.
-@item gnus-gather-loose-threads
-@vindex gnus-gather-loose-threads
-If non-nil, Gnus will gather all loose subtrees into one big tree and
-create a dummy root at the top. (Wait a minute. Root at the top? Yup.)
-Loose subtrees occur when the real root has expired, or you've read it
-in a previous session.
+If non-@code{nil}, Gnus will attempt to build old threads by fetching
+more old headers---headers to articles that are marked as read. If you
+would like to display as few summary lines as possible, but still
+connect as many loose threads as possible, you should set this variable
+to @code{some} or a number. If you set it to a number, no more than
+that number of extra old headers will be fetched. In either case,
+fetching old headers only works if the backend you are using carries
+overview files---this would normally be @code{nntp}, @code{nnspool} and
+@code{nnml}. Also remember that if the root of the thread has been
+expired by the server, there's not much Gnus can do about that.
+
+@item gnus-summary-gather-subject-limit
+Loose threads are gathered by comparing subjects of articles. If this
+variable is @code{nil}, Gnus requires an exact match between the
+subjects of the loose threads before gathering them into one big
+super-thread. This might be too strict a requirement, what with the
+presence of stupid newsreaders that chop off long subjects lines. If
+you think so, set this variable to, say, 20 to require that only the
+first 20 characters of the subjects have to match. If you set this
+variable to a real low number, you'll find that Gnus will gather
+everything in sight into one thread, which isn't very helpful.
+
+@cindex fuzzy article gathering
+If you set this variable to the special value @code{fuzzy}, Gnus will
+use a fuzzy string comparison algorithm on the subjects.
+
+@vindex gnus-summary-gather-exclude-subject
+Since loose thread gathering is done on subjects only, that might lead
+to many false hits, especially with certain common subjects like
+@samp{""} and @samp{"(none)"}. To make the situation slightly better,
+you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
+what subjects should be excluded from the gathering process. The
+default is @samp{"^ *$\\|^(none)$"}.
+
@item gnus-summary-make-false-root
@vindex gnus-summary-make-false-root
+If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
+and create a dummy root at the top. (Wait a minute. Root at the top?
+Yup.) Loose subtrees occur when the real root has expired, or you've
+read or killed the root in a previous session.
+
When there is no real root of a thread, Gnus will have to fudge
-something. This variable says what method Gnus should use while
-fudging. There are four possible value:
+something. This variable says what fudging method Gnus should use.
+There are four possible values:
+
+@cindex adopting articles
@table @code
@item adopt
-Gnus will make the first of the orphaned articles the parent. This
-parent will adopt all the other articles. The adopted articles will be
-marked as such by pointy brackeds instead of square brackets.
+Gnus will make the first of the orphaned articles the parent. This
+parent will adopt all the other articles. The adopted articles will be
+marked as such by pointy brackets (@samp{<>}) instead of the standard
+square brackets (@samp{[]}). This is the default method.
+
@item dummy
-Gnus will create a dummy that will stand in as the parent. This dummy
-will be displayed on a line of its own, but it does not correspond to
-any real article.
+Gnus will create a dummy summary line that will pretend to be the
+parent. This dummy line does not correspond to any real article, so
+selecting it will just select the first real article after the dummy
+article.
+
@item empty
Gnus won't actually make any article the parent, but simply leave the
-subject field of all orphans except the first empty. (It will use
-@code{gnus-summary-same-subject} as the subject.)
+subject field of all orphans except the first empty. (Actually, it will
+use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
+Buffer Format}).)
+
+@item none
+Don't make any article parent at all. Just gather the threads and
+display them after one another.
+
@item nil
-Don't make any article parent at all.
+Don't gather loose threads.
@end table
@item gnus-thread-hide-subtree
@vindex gnus-thread-hide-subtree
-If non-nil, all subtrees will be hidden when the summary buffer is
-generated.
+If non-@code{nil}, all threads will be hidden when the summary buffer is
+generated.
+
@item gnus-thread-hide-killed
@vindex gnus-thread-hide-killed
-if you kill a thread and this variable is non-nil, the subtree will be
-hidden.
+if you kill a thread and this variable is non-@code{nil}, the subtree
+will be hidden.
+
@item gnus-thread-ignore-subject
@vindex gnus-thread-ignore-subject
Sometimes somebody changes the subject in the middle of a thread. If
-this variable is non-nil, the change in subject is ignored. If it is
-nil, which is the default, a change in the subject will result in a new
-thread.
+this variable is non-@code{nil}, the subject change is ignored. If it
+is @code{nil}, which is the default, a change in the subject will result
+in a new thread.
+
@item gnus-thread-indent-level
@vindex gnus-thread-indent-level
-This is a number which says how many spaces to indent a thread. The
-default is @samp{4}.
+This is a number that says how much each sub-thread should be indented.
+The default is @samp{4}.
@end table
-@node Threading Commands
-@subsection Threading Commands
+@node Thread Commands
+@subsection Thread Commands
+@cindex thread commands
@table @kbd
-@item M-C-k
+
+@item T k
+@itemx M-C-k
+@kindex T k (Summary)
@kindex M-C-k (Summary)
@findex gnus-summary-kill-thread
-Mark all articles under the current one as read
+Mark all articles in the current sub-thread as read
(@code{gnus-summary-kill-thread}). If the prefix argument is positive,
-remove all marks. If the prefix argument is negative, tick articles.
-@item M-C-t
-@kindex M-C-t (Summary)
+remove all marks instead. If the prefix argument is negative, tick
+articles instead.
+
+@item T l
+@itemx M-C-l
+@kindex T l (Summary)
+@kindex M-C-l (Summary)
+@findex gnus-summary-lower-thread
+Lower the score of the current thread
+(@code{gnus-summary-lower-thread}).
+
+@item T i
+@kindex T i (Summary)
+@findex gnus-summary-raise-thread
+Increase the score of the current thread
+(@code{gnus-summary-raise-thread}).
+
+@item T #
+@kindex T # (Summary)
+@findex gnus-uu-mark-thread
+Set the process mark on the current thread
+(@code{gnus-uu-mark-thread}).
+
+@item T M-#
+@kindex T M-# (Summary)
+@findex gnus-uu-unmark-thread
+Remove the process mark from the current thread
+(@code{gnus-uu-unmark-thread}).
+
+@item T T
+@kindex T T (Summary)
@findex gnus-summary-toggle-threads
-Toggle showing threads (@code{gnus-summary-toggle-threads}).
-@item M-C-s
-@kindex M-C-s (Summary)
+Toggle threading (@code{gnus-summary-toggle-threads}).
+
+@item T s
+@kindex T s (Summary)
@findex gnus-summary-show-thread
-Show the thread hidden under the current article, if any
-(@code{gnus-summary-show-thread}).
-@item M-C-h
-@kindex M-C-h (Summary)
+Expose the thread hidden under the current article, if any
+(@code{gnus-summary-show-thread}).
+
+@item T h
+@kindex T h (Summary)
@findex gnus-summary-hide-thread
Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
+
+@item T S
+@kindex T S (Summary)
+@findex gnus-summary-show-all-threads
+Expose all hidden threads (@code{gnus-summary-show-all-threads}).
+
+@item T H
+@kindex T H (Summary)
+@findex gnus-summary-hide-all-threads
+Hide all threads (@code{gnus-summary-hide-all-threads}).
@end table
-The following commands are all thread movement commands. They all
+The following commands are thread movement commands. They all
understand the numeric prefix.
@table @kbd
-@item M-C-f
-@kindex M-C-f (Summary)
+@item T n
+@kindex T n (Summary)
@findex gnus-summary-next-thread
Go to the next thread (@code{gnus-summary-next-thread}).
-@item M-C-b
-@kindex M-C-b (Summary)
+@item T p
+@kindex T p (Summary)
@findex gnus-summary-prev-thread
Go to the previous thread (@code{gnus-summary-prev-thread}).
-@item M-C-d
-@kindex M-C-d (Summary)
+@item T d
+@kindex T d (Summary)
@findex gnus-summary-down-thread
Descend the thread (@code{gnus-summary-down-thread}).
-@item M-C-u
-@kindex M-C-u (Summary)
+@item T u
+@kindex T u (Summary)
@findex gnus-summary-up-thread
Ascend the thread (@code{gnus-summary-up-thread}).
@end table
+@vindex gnus-thread-operation-ignore-subject
+If you ignore subject while threading, you'll naturally end up with
+threads that have several different subjects in them. If you then issue
+a command like `T k' (@code{gnus-summary-kill-thread}) you might not
+wish to kill the entire thread, but just those parts of the thread that
+have the same subject as the current article. If you like this idea,
+you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
+is non-@code{nil} (which it is by default), subjects will be ignored
+when doing thread commands. If this variable is @code{nil}, articles in
+the same thread with different subjects will not be included in the
+operation in question. If this variable is @code{fuzzy}, only articles
+that have subjects that are fuzzily equal will be included.
+
+
+@node Asynchronous Fetching
+@section Asynchronous Article Fetching
+@cindex asynchronous article fetching
+
+If you read your news from an @sc{nntp} server that's far away, the
+network latencies may make reading articles a chore. You have to wait
+for a while after pressing @kbd{n} to go to the next article before the
+article appears. Why can't Gnus just go ahead and fetch the article
+while you are reading the previous one? Why not, indeed.
+
+First, some caveats. There are some pitfalls to using asynchronous
+article fetching, especially the way Gnus does it.
+
+Let's say you are reading article 1, which is short, and article 2 is
+quite long, and you are not interested in reading that. Gnus does not
+know this, so it goes ahead and fetches article 2. You decide to read
+article 3, but since Gnus is in the process of fetching article 2, the
+connection is blocked.
+
+To avoid these situations, Gnus will open two (count 'em two)
+connections to the server. Some people may think this isn't a very nice
+thing to do, but I don't see any real alternatives. Setting up that
+extra connection takes some time, so Gnus startup will be slower.
+
+Gnus will fetch more articles than you will read. This will mean that
+the link between your machine and the @sc{nntp} server will become more
+loaded than if you didn't use article pre-fetch. The server itself will
+also become more loaded---both with the extra article requests, and the
+extra connection.
+
+Ok, so now you know that you shouldn't really use this thing... unless
+you really want to.
+
+@vindex gnus-asynchronous
+Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
+happen automatically.
+
+@vindex nntp-async-number
+You can control how many articles that are to be pre-fetched by setting
+@code{nntp-async-number}. This is five by default, which means that when
+you read an article in the group, @code{nntp} will pre-fetch the next
+five articles. 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.
+
+@vindex gnus-asynchronous-article-function
+You may wish to create some sort of scheme for choosing which articles
+that @code{nntp} should consider as candidates for pre-fetching. For
+instance, you may wish to pre-fetch all articles with high scores, and
+not pre-fetch low-scored articles. You can do that by setting the
+@code{gnus-asynchronous-article-function}, which will be called with an
+alist where the keys are the article numbers. Your function should
+return an alist where the articles you are not interested in have been
+removed. You could also do sorting on article score and the like.
+
+@node Article Caching
+@section Article Caching
+@cindex article caching
+@cindex caching
+
+If you have an @emph{extremely} slow @sc{nntp} connection, you may
+consider turning article caching on. Each article will then be stored
+locally under your home directory. As you may surmise, this could
+potentially use @emph{huge} amounts of disk space, as well as eat up all
+your inodes so fast it will make your head swim. In vodka.
+
+Used carefully, though, it could be just an easier way to save articles.
+
+@vindex gnus-use-long-file-name
+@vindex gnus-cache-directory
+@vindex gnus-use-cache
+To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
+all articles that are ticked or marked as dormant will then be copied
+over to your local cache (@code{gnus-cache-directory}). Whether this
+cache is flat or hierarchal is controlled by the
+@code{gnus-use-long-file-name} variable, as usual.
+
+When re-select a ticked or dormant article, it will be fetched from the
+cache instead of from the server. As articles in your cache will never
+expire, this might serve as a method of saving articles while still
+keeping them where they belong. Just mark all articles you want to save
+as dormant, and don't worry.
+
+When an article is marked as read, is it removed from the cache.
+
+@vindex gnus-cache-remove-articles
+@vindex gnus-cache-enter-articles
+The entering/removal of articles from the cache is controlled by the
+@code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
+variables. Both are lists of symbols. The first is @code{(ticked
+dormant)} by default, meaning that ticked and dormant articles will be
+put in the cache. The latter is @code{(read)} by default, meaning that
+articles that are marked as read are removed from the cache. Possibly
+symbols in these two lists are @code{ticked}, @code{dormant},
+@code{unread} and @code{read}.
+
+@findex gnus-jog-cache
+So where does the massive article-fetching and storing come into the
+picture? The @code{gnus-jog-cache} command will go through all
+subscribed newsgroups, request all unread articles, and store them in
+the cache. You should only ever, ever ever ever, use this command if 1)
+your connection to the @sc{nntp} server is really, really, really slow
+and 2) you have a really, really, really huge disk. Seriously.
+
+@vindex gnus-uncacheable-groups
+It is likely that you do not want caching on some groups. For instance,
+if your @code{nnml} mail is located under your home directory, it makes no
+sense to cache it somewhere else under your home directory. Unless you
+feel that it's neat to use twice as much space. To limit the caching,
+you could set the @code{gnus-uncacheable-groups} regexp to
+@samp{"^nnml"}, for instance. This variable is @samp{"^nnvirtual"} by
+default, since caching doesn't really work in @code{nnvirtual} groups,
+since @code{nnvirtual} assigns random article numbers to its articles.
+
+
+@node Article Backlog
+@section Article Backlog
+@cindex backlog
+@cindex article backlog
+
+If you have a slow connection, but the idea of using caching seems
+unappealing to you (and it is, really), you can help the situation some
+by switching on the @dfn{backlog}. This is where Gnus will buffer
+already read articles so that it doesn't have to re-fetch articles
+you've already read. This only helps if you are in the habit of
+re-selecting articles you've recently read, of course. If you never do
+that, turning the backlog on will slow Gnus down a little bit, and
+increase memory usage some.
+
+@vindex gnus-keep-backlog
+If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
+at most @var{n} old articles in a buffer for later re-fetching. If this
+variable is non-@code{nil} and is not a number, Gnus will store
+@emph{all} read articles, which means that your Emacs will group without
+bound before exploding and taking your machine down with you. I put
+that in there just to keep y'all on your toes.
+
+This variable is @code{nil} by default.
+
+
@node Exiting the Summary Buffer
@section Exiting the Summary Buffer
+@cindex summary exit
+
+Exiting from the summary buffer will normally update all info on the
+group and return you to the group buffer.
@table @kbd
-@item q
+@item Z Z
+@itemx q
+@kindex Z Z (Summary)
@kindex q (Summary)
@findex gnus-summary-exit
-Exit the current group and update all the information
-(@code{gnus-summary-exit}).
-@item Q
+@vindex gnus-summary-exit-hook
+@vindex gnus-summary-prepare-exit-hook
+Exit the current group and update all information on the group
+(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
+called before doing much of the exiting, and calls
+@code{gnus-summary-expire-articles} by default.
+@code{gnus-summary-exit-hook} is called after finishing the exiting
+process.
+@item Z E
+@itemx Q
+@kindex Z E (Summary)
@kindex Q (Summary)
-@findex gnus-summary-quit
-Exit the current group without updating any information
-(@code{gnus-summary-quit}).
-@item c
+@findex gnus-summary-exit-no-update
+Exit the current group without updating any information on the group
+(@code{gnus-summary-exit-no-update}).
+@item Z c
+@itemx c
+@kindex Z c (Summary)
@kindex c (Summary)
@findex gnus-summary-catchup-and-exit
-Mark all articles in the group as read and exit
-(@code{gnus-summary-catchup-and-exit}).
+Mark all unticked articles in the group as read and then exit
+(@code{gnus-summary-catchup-and-exit}).
+@item Z C
+@kindex Z C (Summary)
+@findex gnus-summary-catchup-all-and-exit
+Mark all articles, even the ticked ones, as read and then exit
+(@code{gnus-summary-catchup-all-and-exit}).
+@item Z n
+@kindex Z n (Summary)
+@findex gnus-summary-catchup-and-goto-next-group
+Mark all articles as read and go to the next group
+(@code{gnus-summary-catchup-and-goto-next-group}).
+@item Z R
+@kindex Z R (Summary)
+@findex gnus-summary-reselect-current-group
+Exit this group, and then enter it again
+(@code{gnus-summary-reselect-current-group}). If given a prefix, select
+all articles, both read and unread.
+@item Z G
+@itemx M-g
+@kindex Z G (Summary)
+@kindex M-g (Summary)
+@findex gnus-summary-rescan-group
+Exit the group, check for new articles in the group, and select the
+group (@code{gnus-summary-rescan-group}). If given a prefix, select all
+articles, both read and unread.
+@item Z N
+@kindex Z N (Summary)
+@findex gnus-summary-next-group
+Exit the group and go to the next group
+(@code{gnus-summary-next-group}).
+@item Z P
+@kindex Z P (Summary)
+@findex gnus-summary-prev-group
+Exit the group and go to the previous group
+(@code{gnus-summary-prev-group}).
@end table
@vindex gnus-exit-group-hook
group.
@vindex gnus-use-cross-reference
-When you exit the summary buffer, the data on the current group will
-be updated (which articles you have read, which articles you have
-replied to, etc.) If the @code{gnus-use-cross-reference} variable is
-non-nil, articles that are cross-referenced to this group, and are
-marked as read, will also be marked as read in the other groups they
-were cross-posted to. This ensures that you'll never have to read the
-same article more than once.
-
-Unless, of course, somebody has posted it to several groups
-separately. If so, send them a nasty-gram.
-
-One other thing that may cause Gnus to not do the cross-posting thing
-correctly is if you use an NNTP server that supports xover (which is
-very nice, because it speeds things up considerably) which does not
-include the Xref header in its NOV lines. This is Evil, but it's
-common. Gnus tries to Do The Right Thing even with xover by registering
-the Xref lines of all articles you actually read, but if you kill the
-articles, or just mark them as read without reading them, Gnus will not
-get a chance to snoop the Xref lines out of these articles, and will be
-unable to use the cross reference mechanism.
+The data on the current group will be updated (which articles you have
+read, which articles you have replied to, etc.) when you exit the
+summary buffer. If the @code{gnus-use-cross-reference} variable is
+@code{t} (which is the default), articles that are cross-referenced to
+this group and are marked as read, will also be marked as read in the
+other subscribed groups they were cross-posted to. If this variable is
+neither @code{nil} nor @code{t}, the article will be marked as read in
+both subscribed and unsubscribed groups.
+
+Marking cross-posted articles as read ensures that you'll never have to
+read the same article more than once. Unless, of course, somebody has
+posted it to several groups separately. Posting the same article to
+several groups (not cross-posting) is called @dfn{spamming}, and you are
+by law required to send nasty-grams to anyone who perpetrates such a
+heinous crime.
+
+Remember: Cross-posting is kinda ok, but posting the same article
+separately to several groups is not.
+
+One thing that may cause Gnus to not do the cross-posting thing
+correctly is if you use an @sc{nntp} server that supports @sc{xover}
+(which is very nice, because it speeds things up considerably) which
+does not include the @code{Xref} header in its @sc{nov} lines. This is
+Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
+even with @sc{xover} by registering the @code{Xref} lines of all
+articles you actually read, but if you kill the articles, or just mark
+them as read without reading them, Gnus will not get a chance to snoop
+the @code{Xref} lines out of these articles, and will be unable to use
+the cross reference mechanism.
@vindex gnus-nov-is-evil
-If you want Gnus to get the Xrefs right all the time, you have to set
-@code{gnus-nov-is-evil} to t, which slows things down considerably.
+If you want Gnus to get the @code{Xref}s right all the time, you have to
+set @code{gnus-nov-is-evil} to @code{t}, which slows things down
+considerably.
C'est la vie.
+@node Process/Prefix
+@section Process/Prefix
+@cindex process/prefix convention
+
+Many functions, among them functions for moving, decoding and saving
+articles, use what is known as the @dfn{Process/Prefix convention}.
+
+This is a method for figuring out what articles that the user wants the
+command to be performed on.
+
+It goes like this:
+
+If the numeric prefix is N, perform the operation on the next N
+articles, starting with the current one. If the numeric prefix is
+negative, perform the operation on the previous N articles, starting
+with the current one.
+
+If there is no numeric prefix, but some articles are marked with the
+process mark, perform the operation on the articles that are marked with
+the process mark.
+
+If there is neither a numeric prefix nor any articles marked with the
+process mark, just perform the operation on the current article.
+
+Quite simple, really, but it needs to be made clear so that surprises
+are avoided.
+
@node Saving Articles
@section Saving Articles
+@cindex saving articles
Gnus can save articles in a number of ways. Below is the documentation
-for saving articles in a fairly straight-forward fashion (ie. little
+for saving articles in a fairly straight-forward fashion (i.e., little
processing of the article is done before it is saved). For a different
-approach (uudecoding, unsharing, digesting) see gnus-uu.
+approach (uudecoding, unsharing) you should use @code{gnus-uu}
+(@pxref{Decoding Articles}).
@vindex gnus-save-all-headers
-If @code{gnus-save-all-headers} is non-nil, Gnus will not delete
+If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
unwanted headers before saving the article.
+@vindex gnus-saved-headers
+If the preceeding variable is @code{nil}, all headers that match the
+@code{gnus-saved-headers} regexp will be kept, while the rest will be
+deleted before saving.
+
@table @kbd
-@item o
+
+@item O o
+@itemx o
+@kindex O o (Summary)
@kindex o (Summary)
@findex gnus-summary-save-article
-Save the current article (@code{gnus-summary-save-article}).
-@item C-o
-@kindex C-o (Summary)
-@findex gnus-summary-save-rmail
+Save the current article using the default article saver
+(@code{gnus-summary-save-article}).
+
+@item O m
+@kindex O m (Summary)
+@findex gnus-summary-save-article-mail
+Save the current article in mail format
+(@code{gnus-summary-save-article-mail}).
+
+@item O r
+@kindex O r (Summary)
+@findex gnus-summary-save-article-mail
Save the current article in rmail format
-(@code{gnus-summary-save-rmail}).
+(@code{gnus-summary-save-article-rmail}).
+
+@item O f
+@kindex O f (Summary)
+@findex gnus-summary-save-article-file
+Save the current article in plain file format
+(@code{gnus-summary-save-article-file}).
+
+@item O b
+@kindex O b (Summary)
+@findex gnus-summary-save-article-body-file
+Save the current article body in plain file format
+(@code{gnus-summary-save-article-body-file}).
+
+@item O h
+@kindex O h (Summary)
+@findex gnus-summary-save-article-folder
+Save the current article in mh folder format
+(@code{gnus-summary-save-article-folder}).
+
+@item O p
+@kindex O p (Summary)
+@findex gnus-summary-pipe-output
+Save the current article in a pipe. Uhm, like, what I mean is---Pipe
+the current article to a process (@code{gnus-summary-pipe-output}).
@end table
+@vindex gnus-prompt-before-saving
+All these commands use the process/prefix convention
+(@pxref{Process/Prefix}). If you save bunches of articles using these
+functions, you might get tired of being prompted for files to save each
+and every article in. The prompting action is controlled by
+the @code{gnus-prompt-before-saving} variable, which is @code{always} by
+default, giving you that excessive prompting action you know and
+loathe. If you set this variable to @code{t} instead, you'll be promted
+just once for each series of articles you save. If you like to really
+have Gnus do all your thinking for you, you can even set this variable
+to @code{nil}, which means that you will never be prompted for files to
+save articles in. Gnus will simply save all the articles in the default
+files.
+
+
@vindex gnus-default-article-saver
You can customize the @code{gnus-default-article-saver} variable to make
-Gnus what you want it to. You can use any of the four ready-made
-functions below, or you can create your own.
+Gnus do what you want it to. You can use any of the four ready-made
+functions below, or you can create your own.
@table @code
+
@item gnus-summary-save-in-rmail
-@vindex gnus-summary-save-in-rmail
-This is the format Gnus uses by default, @dfn{babyl}. Uses the function
-in the @code{gnus-rmail-save-name} variable to get a file name to save
-the article in. The default is @code{gnus-plain-save-name}.
+@findex gnus-summary-save-in-rmail
+This is the default format, @dfn{babyl}. Uses the function in the
+@code{gnus-rmail-save-name} variable to get a file name to save the
+article in. The default is @code{gnus-plain-save-name}.
+
@item gnus-summary-save-in-mail
-@vindex gnus-summary-save-in-mail
+@findex gnus-summary-save-in-mail
Save in a Unix mail (mbox) file. Uses the function in the
@code{gnus-mail-save-name} variable to get a file name to save the
article in. The default is @code{gnus-plain-save-name}.
+
@item gnus-summary-save-in-file
-@vindex gnus-summary-save-in-file
+@findex gnus-summary-save-in-file
Append the article straight to an ordinary file. Uses the function in
the @code{gnus-file-save-name} variable to get a file name to save the
article in. The default is @code{gnus-numeric-save-name}.
+
+@item gnus-summary-save-body-in-file
+@findex gnus-summary-save-body-in-file
+Append the article body to an ordinary file. Uses the function in the
+@code{gnus-file-save-name} variable to get a file name to save the
+article in. The default is @code{gnus-numeric-save-name}.
+
@item gnus-summary-save-in-folder
-@vindex gnus-summary-save-in-folder
+@findex gnus-summary-save-in-folder
Save the article to an MH folder using @code{rcvstore} from the MH
library.
+
+@item gnus-summary-save-in-vm
+@findex gnus-summary-save-in-vm
+Save the article in a VM folder. You have to have the VM mail
+reader to use this setting.
@end table
All of these functions, except for the last one, will save the article
in the @code{gnus-article-save-directory}, which is initialized from the
-@samp{SAVEDIR} environment variable.
+@samp{SAVEDIR} environment variable. This is @file{~/News/} by
+default.
As you can see above, the functions use different functions to find a
suitable name of a file to save the article in. Below is a list of
-available functions that generates names:
+available functions that generate names:
@table @code
@item gnus-Numeric-save-name
Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
@end table
+@vindex gnus-split-methods
+You can have Gnus suggest where to save articles by plonking regexp into
+the @code{gnus-split-methods} alist. The syntax of this variable is the
+same as @code{nnmail-split-methods}. For instance, if you would like to
+save articles related to Gnus in the file @file{gnus-stuff}, and articles
+related to VM in @code{vm-stuff}, you could set this variable to something
+like:
+
+@lisp
+(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
+ ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff"))
+@end lisp
+
+@vindex gnus-split-methods
+You can have Gnus suggest where to save articles by plonking regexp into
+the @code{gnus-split-methods} alist. The syntax of this variable is the
+same as @code{nnmail-split-methods}. For instance, if you would like to
+save articles related to Gnus in the file @file{gnus-stuff}, and articles
+related to VM in @code{vm-stuff}, you could set this variable to something
+like:
+
+@lisp
+(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
+ ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff"))
+@end lisp
+
@vindex gnus-use-long-file-name
Finally, you have the @code{gnus-use-long-file-name} variable. If it is
-nil, all the preceding functions will replace all periods (@samp{.}) in
-the group names with slashes (@samp{/}) - which means that the functions
-will generate hierarchies of directories instead of having all the files
-in the toplevel directory (@samp{~/News/alt/andrea-dworkin} instead of
-@samp{~/News/alt.andrea-dworkin}.)
+@code{nil}, all the preceding functions will replace all periods
+(@samp{.}) in the group names with slashes (@samp{/})---which means that
+the functions will generate hierarchies of directories instead of having
+all the files in the toplevel directory
+(@samp{~/News/alt/andrea-dworkin} instead of
+@samp{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
+on most systems. However, for historical reasons, this is @code{nil} on
+Xenix and usg-unix-v machines by default.
+
+This function also affects kill and score file names. If this variable
+is a list, and the list contains the element @code{not-score}, long file
+names will not be used for score files, if it contains the element
+@code{not-save}, long file names will not be used for saving, and if it
+contains the element @code{not-kill}, long file names will not be used
+for kill files.
+
+If you'd like to save articles in a hierarchy that looks something like
+a spool, you could
+
+@lisp
+(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
+(setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
+@end lisp
+
+Then just save with @kbd{o}. You'd then read this hierarchy with
+ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
+the toplevel directory as the argument (@file{~/News/}). Then just walk
+around to the groups/directories with @code{nneething}.
+
@node Decoding Articles
@section Decoding Articles
+@cindex decoding articles
+
+Sometime users post articles (or series of articles) that have been
+encoded in some way or other. Gnus can decode them for you.
+
+@menu
+* Uuencoded Articles:: Uudecode articles.
+* Shared Articles:: Unshar articles.
+* PostScript Files:: Split PostScript.
+* Decoding Variables:: Variables for a happy decoding.
+* Viewing Files:: You want to look at the result of the decoding?
+@end menu
-Gnus has a plethora of functions for handling series of (uu)encoded
-articles. Gnus can find out by itself what articles belong to one
-series, decode all the articles and unpack/view/save the resulting
-file(s). All these functions belong to the `gnus-uu' package and are
-reached from the summary buffer as three-key keystrokes: @key{C-c C-v
-KEY}. That last key varies, of course, but all these functions use the
-@key{C-c C-v} prefix keystroke.
+All these functions use the process/prefix convention
+(@pxref{Process/Prefix}) for finding out what articles to work on, with
+the extension that a "single article" means "a single series". Gnus can
+find out by itself what articles belong to a series, decode all the
+articles and unpack/view/save the resulting file(s).
Gnus guesses what articles are in the series according to the following
simplish rule: The subjects must be (nearly) identical, except for the
series}, will not be properly recognized by any of the automatic viewing
commands, and you have to mark the articles manually with @key{#}.
-@menu
-* Decoding Commands:: Decoding in various ways.
-* Setting the Process Mark:: You can mark which articles to work on.
-* Other Related Commands:: Other related commands.
-* Viewing Files:: You can view the resulting decoded files.
-* Decoding Variables:: No, you do not have to decode any variables.
-@end menu
-
-@node Decoding Commands
-@subsection Decoding Commands
+@node Uuencoded Articles
+@subsection Uuencoded Articles
+@cindex uudecode
+@cindex uuencoded articles
-All the keystrokes for decoding follow a strict pattern.
-
-@table @key
-@item C-c C-v C-KEY
-This is a function for decoding and viewing.
-@item C-c C-v KEY
-This is a function for decoding and saving.
-@item C-c C-v M-C-KEY
-This is a function for decoding and viewing marked articles.
-@item C-c C-v M-KEY
-This is a function for decoding and saving marked articles.
+@table @kbd
+@item X u
+@kindex X u (Summary)
+@findex gnus-uu-decode-uu
+Uudecodes the current series (@code{gnus-uu-decode-uu}).
+@item X U
+@kindex X U (Summary)
+@findex gnus-uu-decode-uu-and-save
+Uudecodes and saves the current series
+(@code{gnus-uu-decode-uu-and-save}).
+@item X v u
+@kindex X v u (Summary)
+@findex gnus-uu-decode-uu-view
+Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
+@item X v U
+@kindex X v U (Summary)
+@findex gnus-uu-decode-uu-and-save-view
+Uudecodes, views and saves the current series
+(@code{gnus-uu-decode-uu-and-save-view}).
@end table
-
-@menu
-* Decoding With uudecode:: The most common encoding on the net.
-* Decoding With unshar:: This is used some in source groups.
-* Decoding With Other Decoders:: Binhex and plain save.
-@end menu
-@node Decoding With uudecode
-@subsubsection Decoding With uudecode
-
-@table @key
-@item C-c C-v C-v
-@kindex C-c C-v C-v (Summary)
-@findex gnus-uu-decode-and-view
-Decode and view the series of articles that the current article is a
-part of (@code{gnus-uu-decode-and-view}).
-@item C-c C-v v
-@kindex C-c C-v v (Summary)
-@findex gnus-uu-decode-and-save
-Decode and save the series of articles that the current article is a
-part of (@code{gnus-uu-decode-and-save}).
-@item C-c C-v M-C-v
-@kindex C-c C-v M-C-v (Summary)
-@findex gnus-uu-marked-decode-and-view
-Decode and view the marked articles
-(@code{gnus-uu-marked-decode-and-view}).
-@item C-c C-v M-v
-@kindex C-c C-v M-v (Summary)
-@findex gnus-uu-marked-decode-and-view
-Decode and save the marked articles
-(@code{gnus-uu-marked-decode-and-view}).
-@item C-c C-v C-w
-@kindex C-c C-v C-w (Summary)
-@findex gnus-uu-decode-and-view-all-articles
-Decode and view all articles in the group
-(@code{gnus-uu-decode-and-view-all-articles}).
-@item C-c C-v w
-@kindex C-c C-v w (Summary)
-@findex gnus-uu-decode-and-save-all-articles
-Decode and save all articles in the group
-(@code{gnus-uu-decode-and-save-all-articles}).
-@item C-c C-v M-C-w
-@kindex C-c C-v M-C-w (Summary)
-@findex gnus-uu-decode-and-view-all-marked-files
-Decode and view all series of articles that are marked
-(@code{gnus-uu-decode-and-view-all-marked-files}).
-@item C-c C-v M-w
-@kindex C-c C-v M-w (Summary)
-@findex gnus-uu-decode-and-save-all-marked-files
-Decode and save all series of articles that are marked
-(@code{gnus-uu-decode-and-save-all-marked-files}).
-@item C-c C-v C-a
-@kindex C-c C-v C-a (Summary)
-@findex gnus-uu-decode-and-view-all-articles
-Decode and view all unread articles in the group
-(@code{gnus-uu-decode-and-view-all-articles}).
-@item C-c C-v a
-@kindex C-c C-v a (Summary)
-@findex gnus-uu-decode-and-save-all-articles
-Decode and save all unread articles in the group
-(@code{gnus-uu-decode-and-save-all-articles}).
-@item C-c C-v C-b
-@kindex C-c C-v C-b (Summary)
-@findex gnus-uu-decode-and-show-in-buffer
-Decode the current article and show the result in the article
-buffer. This might be useful if somebody has encoded (parts of) an
-article, for some strange reason
-(@code{gnus-uu-decode-and-show-in-buffer}).
-@end table
-
-The @code{gnus-uu-decode-and-save-all-marked-files} need some
-explanation. It allows you to mark all articles that are part of series
-of articles you are interested in in a group. You only have to mark
-one article for each series of articles you want, and then you call this
-function, which will find all articles that are part of the series you
-want. Is that clear? And they say it's a stupid idea getting drunk
-before writing documentation! Bah!
-
-@node Decoding With unshar
-@subsubsection Decoding With unshar
-
-Using @code{unshar} introduces rather large security holes - it actually
-runs the code it finds in the articles. So you should, at least, peek
-through the articles you want to unshar before using these functions.
+Remember that these all react to the presence of articles marked with
+the process mark. If, for instance, you'd like to uncode and save an
+entire newsgroup, you'd typically do @kbd{M P a}
+(@code{gnus-uu-mark-all}) and then @kbd{X U}
+(@code{gnus-uu-decode-uu-and-save}).
+
+All this is very much different from how @code{gnus-uu} worked with
+@sc{gnus 4.1}, where you had explicit keystrokes for everything under
+the sun. This version of @code{gnus-uu} generally assumes that you mark
+articles in some way (@pxref{Setting Process Marks}) and then press
+@kbd{X u}.
+
+Note: When trying to decode articles that have names matching
+@code{gnus-uu-notify-files}, which is hard-coded to
+@samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
+automatically post an article on @samp{comp.unix.wizards} saying that
+you have just viewed the file in question. This feature can't be turned
+off.
+
+@node Shared Articles
+@subsection Shared Articles
+@cindex unshar
+@cindex shared articles
@table @kbd
-@item C-c C-v C-s
-@kindex C-c C-v C-s (Summary)
-@findex gnus-uu-shar-and-view
-@kindex C-c C-v C-s (Summary)
-@findex gnus-uu-shar-and-view
-Unshar and view the series of articles that the current article is a
-part of (@code{gnus-uu-shar-and-view}).
-@item C-c C-v s
-@kindex C-c C-v s (Summary)
-@findex gnus-uu-shar-and-save
-@kindex C-c C-v s (Summary)
-@findex gnus-uu-shar-and-save
-Unshar and save the series of articles that the current article is a
-part of (@code{gnus-uu-shar-and-save}).
-@item C-c C-v M-C-s
-@kindex C-c C-v M-C-s (Summary)
-@findex gnus-uu-marked-shar-and-view
-@kindex C-c C-v M-C-s (Summary)
-@findex gnus-uu-marked-shar-and-view
-Unshar and view the marked articles
-(@code{gnus-uu-marked-shar-and-view}).
-@item C-c C-v M-s
-@kindex C-c C-v M-s (Summary)
-@findex gnus-uu-marked-shar-and-view
-@kindex C-c C-v M-s (Summary)
-@findex gnus-uu-marked-shar-and-view
-Unshar and save the marked articles
-(@code{gnus-uu-marked-shar-and-view}).
-@end table
-
-@node Decoding With Other Decoders
-@subsubsection Decoding With Other Decoders
-
-These commands are entry points to all the decoding methods Gnus knows -
-uudecode, unshar, unbinhex and save. You will be prompted for what
-method you want to employ.
+@item X s
+@kindex X s (Summary)
+@findex gnus-uu-decode-unshar
+Unshars the current series (@code{gnus-uu-decode-unshar}).
+@item X S
+@kindex X S (Summary)
+@findex gnus-uu-decode-unshar-and-save
+Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
+@item X v s
+@kindex X v s (Summary)
+@findex gnus-uu-decode-unshar-view
+Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
+@item X v S
+@kindex X v S (Summary)
+@findex gnus-uu-decode-unshar-and-save-view
+Unshars, views and saves the current series
+(@code{gnus-uu-decode-unshar-and-save-view}).
+@end table
-@table @kbd
-@item C-c C-v C-m
-@kindex C-c C-v C-m (Summary)
-@findex gnus-uu-multi-decode-and-view
-Decode (by some method) and view the series of articles that the current
-article is a part of (@code{gnus-uu-multi-decode-and-view}).
-@item C-c C-v m
-@kindex C-c C-v m (Summary)
-@findex gnus-uu-multi-decode-and-save
-Decode (by some method) and save the series of articles that the current
-article is a part of (@code{gnus-uu-multi-decode-and-save}).
-@item C-c C-v M-C-m
-@kindex C-c C-v M-C-m (Summary)
-@findex gnus-uu-marked-multi-decode-and-view
-Decode (by some method) and view the marked articles
-(@code{gnus-uu-marked-multi-decode-and-view}).
-@item C-c C-v M-m
-@kindex C-c C-v M-m (Summary)
-@findex gnus-uu-marked-multi-decode-and-view
-Decode (by some method) and save the marked articles
-(@code{gnus-uu-marked-multi-decode-and-view}).
-@item C-c C-v C-j
-@kindex C-c C-v C-j (Summary)
-@findex gnus-uu-threaded-multi-decode-and-view
-Decode (by some method) and view all articles in the current thread
-(@code{gnus-uu-threaded-multi-decode-and-view}).
-@item C-c C-v C-j
-@kindex C-c C-v C-j (Summary)
-@findex gnus-uu-threaded-multi-decode-and-view
-Decode (by some method) and save all articles in the current thread
-(@code{gnus-uu-threaded-multi-decode-and-view}).
-@end table
-
-@node Setting the Process Mark
-@subsection Setting the Process Mark
-
-The process mark is used by other parts of Gnus, not just the `gnus-uu'
-package. However, this is where it is most useful, so it adds some
-further methods for setting the mark.
+@node PostScript Files
+@subsection PostScript Files
+@cindex PostScript
@table @kbd
-@item C-c C-v C-r
-@kindex C-c C-v C-r (Summary)
-@findex gnus-uu-mark-by-regexp
-Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
-@item C-c C-v r
-@kindex C-c C-v r (Summary)
-@findex gnus-uu-mark-region
-Mark all articles between point and mark (@code{gnus-uu-mark-region}).
-@item C-c C-v t
-@kindex C-c C-v t (Summary)
-@findex gnus-uu-mark-thread
-Mark all articles downward in the current thread
-(@code{gnus-uu-mark-thread}).
-@end table
-
-@node Other Related Commands
-@subsection Other Related Commands
-
-@table @key
-@item C-c C-v f
-@kindex C-c C-v f (Summary)
-@findex gnus-uu-digest-and-forward
-Digest and forward all articles that are part of a series
-(@code{gnus-uu-digest-and-forward}).
-@item C-c C-v M-f
-@kindex C-c C-v M-f (Summary)
-@findex gnus-uu-marked-digest-and-forward
-Digest and forward all marked articles
-(@code{gnus-uu-marked-digest-and-forward}).
-@item C-c C-v C-i
-@kindex C-c C-v C-i (Summary)
-@findex gnus-uu-toggle-interactive-view
-Instead of having windows popping up automatically, it can be handy to
-view files interactivly, especially when viewing archives
-(@code{gnus-uu-toggle-interactive-view}).
-@item C-c C-v C-t
-@kindex C-c C-v C-t (Summary)
-@findex gnus-uu
-Toggle any of the most important @code{gnus-uu} variables
-(@code{gnus-uu-toggle-any-variable}).
-@item C-c C-v C-l
-@kindex C-c C-v C-l (Summary)
-@findex gnus-uu-edit-begin-line
-Edit the @samp{begin} line of an uuencoded article, if any
-(@code{gnus-uu-edit-begin-line}).
-@item C-c C-v p
-@kindex C-c C-v p (Summary)
-@findex gnus-uu-post-news
-Uuencode and post an file. If the file is large, it will be split into a
-series of articles that will be posted (@code{gnus-uu-post-news}).
+@item X p
+@kindex X p (Summary)
+@findex gnus-uu-decode-postscript
+Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
+@item X P
+@kindex X P (Summary)
+@findex gnus-uu-decode-postscript-and-save
+Unpack and save the current PostScript series
+(@code{gnus-uu-decode-postscript-and-save}).
+@item X v p
+@kindex X v p (Summary)
+@findex gnus-uu-decode-postscript-view
+View the current PostScript series
+(@code{gnus-uu-decode-postscript-view}).
+@item X v P
+@kindex X v P (Summary)
+@findex gnus-uu-decode-postscript-and-save-view
+View and save the current PostScript series
+(@code{gnus-uu-decode-postscript-and-save-view}).
@end table
-@node Viewing Files
-@subsection Viewing Files
-
-When using the view commands, @code{gnus-uu-decode-and-view} for
-instance, Gnus will (normally, see below) try to view the file according
-to the rules given in @code{gnus-uu-default-view-rules} and
-@code{gnus-uu-user-view-rules}. If it recognizes the file, it will
-display it immediately. If the file is some sort of archive, Gnus will
-attempt to unpack the archive and see if any of the files in the archive
-can be viewed. For instance, if you have a gzipped tar file
-@file{pics.tar.gz} containing the files @file{pic1.jpg} and
-@file{pic2.gif}, Gnus will uncompress and detar the main file, and then
-view the two pictures. This unpacking process is recursive, so if the
-archive contains archives of archives, it'll all be unpacked.
-
-If the view command doesn't recognise the file type, or can't view it
-because you don't have the viewer, or can't view *any* of the files in
-the archive, the user will be asked if she wishes to have the file saved
-somewhere. Note that if the decoded file is an archive, and Gnus
-manages to view some of the files in the archive, it won't tell the user
-that there were some files that were unviewable. Try interactive view
-for a different approach.
-
@node Decoding Variables
@subsection Decoding Variables
@menu
* Rule Variables:: Variables that say how a file is to be viewed.
* Other Decode Variables:: Other decode variables.
+* Uuencoding & Posting:: Variables for customizing uuencoding.
@end menu
@node Rule Variables
@subsubsection Rule Variables
+@cindex rule variables
-Gnus uses @dfn{rule} variables to decide how to view a file. All these
+Gnus uses @dfn{rule variables} to decide how to view a file. All these
variables are on the form
-@example
+@lisp
(list '(regexp1 command2)
'(regexp2 command2)
...)
-@end example
+@end lisp
@table @code
@item gnus-uu-user-view-rules
This variable is consulted first when viewing files. If you wish to use,
for instance, @code{sox} to convert an @samp{.au} sound file, you could
say something like:
-@example
+@lisp
(setq gnus-uu-user-view-rules
(list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
-@end example
+@end lisp
@item gnus-uu-user-view-rules-end
@vindex gnus-uu-user-view-rules-end
This variable is consulted if Gnus couldn't make any matches from the
user and default view rules.
-@item gnus-uu-user-interactive-view-rules
-@vindex gnus-uu-user-interactive-view-rules
-This is the variable used instead of @code{gnus-uu-user-view-rules}
-when in interactive mode.
-@item gnus-uu-user-interactive-view-rules-end
-@vindex gnus-uu-user-interactive-view-rules-end
-This variable is used instead of @code{gnus-uu-user-view-rules-end} when
-in interactive mode.
@item gnus-uu-user-archive-rules
@vindex gnus-uu-user-archive-rules
-This variable can be used to say what comamnds should be used to unpack
+This variable can be used to say what commands should be used to unpack
archives.
@end table
@item gnus-uu-ignore-files-by-type
@vindex gnus-uu-ignore-files-by-type
-Files with a MIME type matching this variable won't be viewed. Note
-that Gnus tries to guess what type the file is based on the
-name. gnus-uu is not a MIME package, so this is slightly kludgy.
+Files with a @sc{mime} type matching this variable won't be viewed.
+Note that Gnus tries to guess what type the file is based on the name.
+@code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
+kludgey.
@item gnus-uu-tmp-dir
@vindex gnus-uu-tmp-dir
-Where gnus-uu does its work.
+Where @code{gnus-uu} does its work.
@item gnus-uu-do-not-unpack-archives
@vindex gnus-uu-do-not-unpack-archives
-Non-nil means that gnus-uu won't peek inside archives looking for files
-to dispay.
+Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
+looking for files to display.
@item gnus-uu-view-and-save
@vindex gnus-uu-view-and-save
-Non-nil means that the user will always be asked to save a file after
-viewing it.
-
-@item gnus-uu-asynchronous
-@vindex gnus-uu-asynchronous
-Non-nil means that files will be viewed asynchronously. This can be
-useful if you're viewing long @file{.mod} files, for instance, which
-often takes several minutes. Note, however, that since gnus-uu doesn't
-ask, and if you are viewing an archive with lots of viewable files,
-you'll get them all up more or less at once, which can be confusing, to
-say the least. To get gnus-uu to ask you before viewing a file, set the
-@code{gnus-uu-ask-before-view} variable.
-
-@item gnus-uu-ask-before-view
-@vindex gnus-uu-ask-before-view
-Non-nil means that gnus-uu will ask you before viewing each file.
+Non-@code{nil} means that the user will always be asked to save a file
+after viewing it.
@item gnus-uu-ignore-default-view-rules
@vindex gnus-uu-ignore-default-view-rules
-Non-nil means that gnus-uu will ignore the default viewing rules.
+Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
+rules.
@item gnus-uu-ignore-default-archive-rules
@vindex gnus-uu-ignore-default-archive-rules
-Non-nil means that gnus-uu will ignore the default archive unpacking
-commands.
+Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
+unpacking commands.
@item gnus-uu-kill-carriage-return
@vindex gnus-uu-kill-carriage-return
-Non-nil means that gnus-uu will strip all carriage returns from
-articles.
+Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
+from articles.
@item gnus-uu-unmark-articles-not-decoded
@vindex gnus-uu-unmark-articles-not-decoded
-Non-nil means that gnus-uu will mark articles that were unsuccessfully
-decoded as unread.
-
-@item gnus-uu-output-window-height
-@vindex gnus-uu-output-window-height
-This variable says how tall the output buffer window is to be when using
-interactive view mode.
+Non-@code{nil} means that @code{gnus-uu} will mark articles that were
+unsuccessfully decoded as unread.
@item gnus-uu-correct-stripped-uucode
@vindex gnus-uu-correct-stripped-uucode
-Non-nil means that gnus-uu will *try* to fix uuencoded files that have
-had traling spaces deleted.
-
-@item gnus-uu-use-interactive-view
-@vindex gnus-uu-use-interactive-view
-Non-nil means that gnus-uu will use interactive viewing mode.
+Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
+uuencoded files that have had trailing spaces deleted.
@item gnus-uu-view-with-metamail
@vindex gnus-uu-view-with-metamail
-Non-nil means that gnus-uu will ignore the viewing commands defined by
-the rule variables and just fudge a MIME content type based on the file
-name. The result will be fed to metamail for viewing.
+Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
+commands defined by the rule variables and just fudge a @sc{mime}
+content type based on the file name. The result will be fed to
+@code{metamail} for viewing.
@item gnus-uu-save-in-digest
@vindex gnus-uu-save-in-digest
-Non-nil means that gnus-uu, when asked to save without decoding, will
-save in digests. If this variable is nil, gnus-uu will just save
-everything in a file without any embellishments. The digesting almost
-conforms to RFC1153 - no easy way to specify any meaningful volume and
-issue numbers were found, so I simply dropped them.
+Non-@code{nil} means that @code{gnus-uu}, when asked to save without
+decoding, will save in digests. If this variable is @code{nil},
+@code{gnus-uu} will just save everything in a file without any
+embellishments. The digesting almost conforms to RFC1153---no easy way
+to specify any meaningful volume and issue numbers were found, so I
+simply dropped them.
+
+@end table
+
+@node Uuencoding & Posting
+@subsubsection Uuencoding & Posting
+
+@table @code
@item gnus-uu-post-include-before-composing
@vindex gnus-uu-post-include-before-composing
-Non-nil means that gnus-uu will ask for a file to encode before you
-compose the article. If this variable is t, you can either include an
-encoded file with @key{C-c C-i} or have one included for you when you
-post the article.
+Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
+before you compose the article. If this variable is @code{t}, you can
+either include an encoded file with @key{C-c C-i} or have one included
+for you when you post the article.
@item gnus-uu-post-length
@vindex gnus-uu-post-length
@item gnus-uu-post-threaded
@vindex gnus-uu-post-threaded
-Non-nil means that gnus-uu will post the encoded file in a thread. This
-may not be smart, as no other decoder I have seen are able to follow
-threads when collecting uuencoded articles. (Well, I have seen one
-package that does that - gnus-uu, but somehow, I don't think that
-counts...) Default is nil.
+Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
+thread. This may not be smart, as no other decoder I have seen are able
+to follow threads when collecting uuencoded articles. (Well, I have
+seen one package that does that---@code{gnus-uu}, but somehow, I don't
+think that counts...) Default is @code{nil}.
@item gnus-uu-post-separate-description
@vindex gnus-uu-post-separate-description
-Non-nil means that the description will be posted in a separate article.
-The first article will typically be numbered (0/x). If this variable is
-nil, the description the user enters will be included at the beginning
-of the first article, which will be numbered (1/x). Default is t.
+Non-@code{nil} means that the description will be posted in a separate
+article. The first article will typically be numbered (0/x). If this
+variable is @code{nil}, the description the user enters will be included
+at the beginning of the first article, which will be numbered (1/x).
+Default is @code{t}.
@end table
-@node Various Article Stuff
-@section Various Article Stuff
+@node Viewing Files
+@subsection Viewing Files
+@cindex viewing files
+@cindex pseudo-articles
+
+After decoding, if the file is some sort of archive, Gnus will attempt
+to unpack the archive and see if any of the files in the archive can be
+viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
+containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
+uncompress and detar the main file, and then view the two pictures.
+This unpacking process is recursive, so if the archive contains archives
+of archives, it'll all be unpacked.
+
+Finally, Gnus will normally insert a @dfn{pseudo-article} for each
+extracted file into the summary buffer. If you go to these "articles",
+you will be prompted for a command to run (usually Gnus will make a
+suggestion), and then the command will be run.
+
+@vindex gnus-view-pseudo-asynchronously
+If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
+until the viewing is done before proceeding.
+
+@vindex gnus-view-pseudos
+If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
+the pseudo-articles into the summary buffer, but view them
+immediately. If this variable is @code{not-confirm}, the user won't even
+be asked for a confirmation before viewing is done.
+
+@vindex gnus-view-pseudos-separately
+If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
+pseudo-article will be created for each file to be viewed. If
+@code{nil}, all files that use the same viewing command will be given as
+a list of parameters to that command.
+
+So; there you are, reading your @emph{pseudo-articles} in your
+@emph{virtual newsgroup} from the @emph{virtual server}; and you think:
+Why isn't anything real anymore? How did we get here?
+
+
+@node Article Treatment
+@section Article Treatment
+
+Reading through this huge manual, you may have quite forgotten that the
+object of newsreaders are to actually, like, read what people have
+written. Reading articles. Unfortunately, people are quite bad at
+writing, so there are tons of functions and variables to make reading
+these articles easier.
+
+@menu
+* Article Highlighting:: You want to make the article look like fruit salad.
+* Article Hiding:: You also want to make certain info go away.
+* Article Washing:: Lots of way-neat functions to make life better.
+* Article Buttons:: Clcik on URLs, Message-IDs, addresses and the like.
+* Article Date:: Grumble, UT!
+@end menu
+
+
+@node Article Highlighting
+@subsection Article Highlighting
+@cindex highlight
+
+Not only do you want your article buffer to look like fruit salad, but
+you want it to look like technicolor fruit salad.
@table @kbd
-@item w
-@kindex w (Summary)
+
+@item W H a
+@kindex W H a (Summary)
+@findex gnus-article-highlight
+Highlight the current article (@code{gnus-article-highlight}).
+
+@item W H h
+@kindex W H h (Summary)
+@findex gnus-article-highlight-headers
+@vindex gnus-header-face-alist
+Highlight the headers (@code{gnus-article-highlight-headers}). The
+highlighting will be done according to the @code{gnus-header-face-alist}
+variable, which is a list where each element has the form @var{(regexp
+name content)}. @var{regexp} is a regular expression for matching the
+header, @var{name} is the face used for highling the header name and
+@var{content} is the face for highlighting the header value. The first
+match made will be used.
+
+@item W H c
+@kindex W H c (Summary)
+@findex gnus-article-highlight-citation
+Highlight cited text (@code{gnus-article-highlight-citation}).
+
+Some variables to customize the citation highlights:
+
+@table @code
+@vindex gnus-cite-parse-max-size
+@item gnus-cite-parse-max-size
+If the article size if bigger than this variable (which is 25000 by
+default), no citation highlighting will be performed.
+
+@item gnus-cite-prefix-regexp
+@vindex gnus-cite-prefix-regexp
+Regexp mathcing the longest possible citation prefix on a line.
+
+@item gnus-cite-max-prefix
+@vindex gnus-cite-max-prefix
+Maximum possible length for a citation prefix (default 20).
+
+@item gnus-supercite-regexp
+@vindex gnus-supercite-regexp
+Regexp matching normal SuperCite attribution lines.
+
+@item gnus-supercite-secondary-regexp
+@vindex gnus-supercite-secondary-regexp
+Regexp matching mangled SuperCite attribution lines.
+
+@item gnus-cite-minimum-match-count
+@vindex gnus-cite-minimum-match-count
+Minimum number of identical prefixes we have to see before we believe
+that it's a citation.
+
+@item gnus-cite-attribution-prefix
+@vindex gnus-cite-attribution-prefix
+Regexp matching the beginning of an attribution line.
+
+@item gnus-cite-addtribution-suffix
+@vindex gnus-cite-addtribution-suffix
+Regexp matching the end of an attribution line.
+
+@item gnus-cite-attribution-face
+@vindex gnus-cite-attribution-face
+Face used for attribution lines. It is merged with the face for the
+cited text belonging to the attribution.
+
+@end table
+
+
+@item W H s
+@kindex W H s (Summary)
+@vindex gnus-signature-separator
+@findex gnus-article-highlight-signature
+Highlight the signature (@code{gnus-article-highlight-signature}).
+Everything after @code{gnus-signature-separator} in an article will be
+considered a signature.
+
+@end table
+
+
+@node Article Hiding
+@subsection Article Hiding
+@cindex article hiding
+
+Or rather, hiding certain things in each article. There usually is much
+to much gruft in most articles.
+
+@table @kbd
+
+@item W W a
+@kindex W W a (Summary)
+@findex gnus-article-hide
+Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
+
+@item W W h
+@kindex W W h (Summary)
+@findex gnus-article-hide-headers
+Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
+Headers}.
+
+@item W W s
+@kindex W W s (Summary)
+@findex gnus-article-hide-signature
+Hide signature (@code{gnus-article-hide-signature}).
+
+@item W W p
+@kindex W W p (Summary)
+@findex gnus-article-hide-pgp
+Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
+
+@item W W c
+@kindex W W c (Summary)
+@findex gnus-article-hide-citation
+Hide citation (@code{gnus-article-hide-citation}). Two variables for
+customizing the hiding:
+
+@table @code
+
+@item gnus-cite-hide-percentage
+@vindex gnus-cite-hide-percentage
+If the cited text is of a bigger percentage than this variable (default
+50), hide the cited text.
+
+@item gnus-cite-hide-absolute
+@vindex gnus-cite-hide-absolute
+The cited text must be have at least this length (default 10) before it
+is hidden.
+
+@end table
+
+Also see @xref{Article Highlighting} for further variables for
+citation customization.
+
+@end table
+
+
+@node Article Washing
+@subsection Article Washing
+@cindex washing
+@cindex article washing
+
+We call this "article washing" for a really good reason. Namely, the
+@kbd{A} key was taken, so we had to use the @kbd{W} key instead.
+
+@dfn{Washing} is defined by us as "changing something from something to
+something else", but normally results in something looking better.
+Cleaner, perhaps.
+
+@table @kbd
+
+@item W l
+@kindex W l (Summary)
@findex gnus-summary-stop-page-breaking
-Remove page breaking from the current article
-(@code{gnus-summary-stop-page-breaking}).
-@item C-c C-r
-@kindex C-c C-r (Summary)
+Remove page breaks from the current article
+(@code{gnus-summary-stop-page-breaking}).
+
+@item W r
+@kindex W r (Summary)
@findex gnus-summary-caesar-message
Do a Caesar rotate (rot13) on the article buffer
(@code{gnus-summary-caesar-message}).
-@item g
-@kindex g (Summary)
+
+@item A g
+@kindex A g (Summary)
@findex gnus-summary-show-article
-Select the current article (@code{gnus-summary-show-article}).
-@item t
-@kindex t (Summary)
+(Re)fetch the current article (@code{gnus-summary-show-article}). If
+given a prefix, fetch the current article, but don't run any of the
+article treatment functions. This will give you a "raw" article, just
+the way it came from the server.
+
+@item W t
+@kindex W t (Summary)
@findex gnus-summary-toggle-header
Toggle whether to display all headers in the article buffer
(@code{gnus-summary-toggle-header}).
-@item M-t
-@kindex M-t (Summary)
+
+@item W m
+@kindex W m (Summary)
@findex gnus-summary-toggle-mime
-Toggle whether to run the article through MIME before displaying
-(@code{gnus-summary-toggle-mime}).
-@item |
-@kindex | (Summary)
-@findex gnus-summary-pipe-output
-Pipe the current article through a filter
-(@code{gnus-summary-pipe-output}).
+Toggle whether to run the article through @sc{mime} before displaying
+(@code{gnus-summary-toggle-mime}).
+
+@item W o
+@kindex W o (Summary)
+@findex gnus-article-treat-overstrike
+Treat overstrike (@code{gnus-article-treat-overstrike}).
+
+@item W w
+@kindex W w (Summary)
+@findex gnus-article-word-wrap
+Do word wrap (@code{gnus-article-word-wrap}).
+
+@item W c
+@kindex W c (Summary)
+@findex gnus-article-remove-cr
+Remove CR (@code{gnus-article-remove-cr}).
+
+@item W q
+@kindex W q (Summary)
+@findex gnus-article-de-quoted-unreadable
+Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
+
+@item W f
+@kindex W f (Summary)
+@cindex x-face
+@findex gnus-article-display-x-face
+@findex gnus-article-x-face-command
+@vindex gnus-article-x-face-command
+@vindex gnus-article-x-face-too-ugly
+Look for and display any X-Face headers
+(@code{gnus-article-display-x-face}). The command executed by this
+function is given by the @code{gnus-article-x-face-command} variable. If
+this variable is a string, this string will be executed in a sub-shell.
+If it is a function, this function will be called with the face as the
+argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
+matches the @code{From} header, the face will not be shown.
+
+@item W b
+@kindex W b (Summary)
+@findex gnus-article-add-buttons
+Add clickable buttons to the article (@code{gnus-article-add-buttons}).
+
+@item W B
+@kindex W B (Summary)
+@findex gnus-article-add-buttons-to-head
+Add clickable buttons to the article headers
+(@code{gnus-article-add-buttons-to-head}).
+
+@end table
+
+
+@node Article Buttons
+@subsection Article Buttons
+@cindex buttons
+
+People often include references to other stuff in articles, and it would
+be nice if Gnus could just fetch whatever it is that people talk about
+with the minimum of fuzz.
+
+Gnus adds @dfn{buttons} to certain standard references by default:
+Well-formed URLs, mail addresses and Message-IDs. This is controlled by
+two variables, one that handles article bodies and one that handles
+article heads:
+
+@table @code
+
+@item gnus-button-alist
+@vindex gnus-header-button-alist
+This is an alist where each entry has this form:
+
+@lisp
+(REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
+@end lisp
+
+@table @var
+
+@item regexp
+All text that match this regular expression will be considered an
+external reference. Here's a typical regexp that match embedded URLs:
+@samp{"<URL:\\([^\n\r>]*\\)>"}.
+
+@item button-par
+Gnus has to know which parts of the match is to be highlighted. This is
+a number that says what sub-expression of the regexp that is to be
+highlighted. If you want it all highlighted, you use @samp{0} here.
+
+@item use-p
+This form will be @code{eval}ed, and if the result is non-@code{nil},
+this is considered a match. This is useful if you want extra sifting to
+avoid false matches.
+
+@item function
+This function will be called when you click on this button.
+
+@item data-par
+As with @var{button-par}, this is a sub-expression number, but this one
+says which part of the match is to be sent as data to @var{function}.
+
+@end table
+
+So the full entry for buttonizing URLs is then
+
+@lisp
+("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
+@end lisp
+
+@item gnus-header-button-alist
+@vindex gnus-header-button-alist
+This is just like the other alist, except that it is applied to the
+article head only, and that each entry has an additional element that is
+used to say what headers to apply the buttonize coding to:
+
+@lisp
+(HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
+@end lisp
+
+@var{header} is a regular expression.
+
+@end table
+
+@vindex gnus-article-button-face
+@vindex gnus-article-mouse-face
+Buttons are highlighted with @code{gnus-article-button-face}, while
+@code{gnus-article-mouse-face} is used when the mouse cursor is over the
+button.
+
+
+@node Article Date
+@subsection Article Date
+
+The date is most likely generated in some obscure timezone you've never
+heard of, so it's quite nice to be able to find out what the time was
+when the article was sent.
+
+@table @kbd
+
+@item W T u
+@kindex W T u (Summary)
+@findex gnus-article-date-ut
+Display the date in UT (aka. GMT, aka ZULU)
+(@code{gnus-article-date-ut}).
+
+@item W T l
+@kindex W T l (Summary)
+@findex gnus-article-date-local
+Display the date in the local timezone (@code{gnus-article-date-local}).
+
+@item W T e
+@kindex W T e (Summary)
+@findex gnus-article-date-lapsed
+Say how much time has (e)lapsed between the article was posted and now
+(@code{gnus-article-date-lapsed}).
+
+@item W T o
+@kindex W T o (Summary)
+@findex gnus-article-date-original
+Display the original date (@code{gnus-article-date-original}). This can
+be useful if you normally use some other conversion function and is
+worried that it might be doing something totally wrong. Say, claiming
+that the article was posted in 1854. Although something like that is
+@emph{totally} impossible. Don't you trust me? *titter*
+
@end table
+
@node Summary Sorting
@section Summary Sorting
+@cindex summary sorting
You can have the summary buffer sorted in various ways, even though I
-can't really se why you'd want that.
+can't really see why you'd want that.
@table @kbd
@item C-c C-s C-n
@kindex C-c C-s C-d (Summary)
@findex gnus-summary-sort-by-date
Sort by date (@code{gnus-summary-sort-by-date}).
+@item C-c C-s C-i
+@kindex C-c C-s C-i (Summary)
+@findex gnus-summary-sort-by-score
+Sort by score (@code{gnus-summary-sort-by-score}).
@end table
+These functions will work both when you use threading and when you don't
+use threading. In the latter case, all summary lines will be sorted,
+line by line. In the former case, sorting will be done on a
+root-by-root basis, which might not be what you were looking for. To
+toggle whether to use threading, type @kbd{T T} (@pxref{Thread
+Commands}).
+
+
@node Finding the Parent
@section Finding the Parent
+@cindex parent articles
+@cindex referring articles
@findex gnus-summary-refer-parent-article
@kindex ^ (Summary)
If you'd like to read the parent of the current article, and it is not
displayed in the article buffer, you might still be able to. That is,
-if the current group is fetched by NNTP, the parent hasn't expired and
-the References in the current article are not mangled, you can just
-press @kbd{^} (@code{gnus-summary-refer-parent-article}). If everything
-goes well, you'll get the parent. If the parent is already displayed in
-the summary buffer, point will just move to this article.
+if the current group is fetched by @sc{nntp}, the parent hasn't expired
+and the @code{References} in the current article are not mangled, you
+can just press @kbd{^} or @kbd{A r}
+(@code{gnus-summary-refer-parent-article}). If everything goes well,
+you'll get the parent. If the parent is already displayed in the
+summary buffer, point will just move to this article.
+
+@findex gnus-summary-refer-references
+@kindex A R (Summary)
+You can have Gnus fetch all articles mentioned in the @code{References}
+header of the article by pushing @kbd{A R}
+(@code{gnus-summary-refer-references}).
@findex gnus-summary-refer-article
@kindex M-^ (Summary)
-You can also ask the NNTP server for an arbitrary article, no matter
-what group it belongs to. @kbd{M-^} (@code{gnus-summary-refer-article})
-will ask you for a message-id, which is one of those long thingies that
-look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to
-get it all exactly right.
-
-@node Score Files
-@section Score Files
-
-Other people call them @dfn{kill files}, but we here at (ding) Gnus
-Towers likes scoring better than killing, so we've changed the
-name. We've also changed what they do, so sit up straight and pay
-attention!
-
-All articles have a default score (@code{gnus-summary-default-score}).
-This score may be raised or lowered either interactively or by the score
-files. Articles that have a score lower than
-@code{gnus-summary-mark-below} are marked as read.
-
-If a @dfn{score file} for the current group exists, Gnus will read it
-after generating the summary buffer.
-
-The score files are files that may contain, in general, any elisp
-functions. However, it is most common just to put functions that either
-raises or lowers the score of articles based on their headers in those
-files. Hence the name.
-
-There are several commands reachable from the summary buffer that
-inserts commands for scoring articles based on the current article. You
-can, for instance, ask Gnus to lower or raise the score of all articles
-with a certain subject.
-
-@menu
-* Summary Score Commands:: Adding simple score commands to the score file.
-* Score Mode:: A mode for editing the score file.
-* Score Variables:: Customize your scoring. (My, what terminology).
-@end menu
-
-@node Summary Score Commands
-@subsection Summary Score Commands
-
-@table @kbd
-@item C-c C-k C-s
-@kindex C-c C-k C-s (Summary)
-@findex gnus-kill-file-kill-by-subject
-Kill all articles with the current subject
-(@code{gnus-kill-file-kill-by-subject}).
-@item C-c C-k C-a
-@kindex C-c C-k C-a (Summary)
-@findex gnus-kill-file-kill-by-author
-Kill all articles from the current author
-(@code{gnus-kill-file-kill-by-author}).
-@item C-c C-k C-t
-@kindex C-c C-k C-t (Summary)
-@findex gnus-kill-file-kill-by-thread
-Kill all articles in the current subthread
-(@code{gnus-kill-file-kill-by-thread}).
-@item C-c C-k C-o
-@kindex C-c C-k C-o (Summary)
-@findex gnus-kill-file-kill-by-organization
-Kill all articles from the current organization
-(@code{gnus-kill-file-kill-by-organization}).
-@item C-c C-k C-x
-@kindex C-c C-k C-x (Summary)
-@findex gnus-kill-file-kill-by-xref
-Kill all articles that have similar Xrefs to the current article
-(@code{gnus-kill-file-kill-by-xref}). This is one way to get rid of
-cross-posts.
-@end table
-
-@node Score Mode
-@subsection Score Mode
-
-To enter either the global or local score file, you can use the
-following keystrokes in the summary buffer:
-
-@table @kbd
-@item M-k
-@kindex M-k (Summary)
-@findex gnus-summary-edit-local-kill
-Edit the kill file for the current group
-(@code{gnus-summary-edit-local-kill}).
-@item M-K
-@kindex M-K (Summary)
-@findex gnus-summary-edit-global-kill
-Edit the global kill file (@code{gnus-summary-edit-global-kill}).
-@end table
-
-@node Score Variables
-@subsection Score Variables
+You can also ask the @sc{nntp} server for an arbitrary article, no
+matter what group it belongs to. @kbd{M-^}
+(@code{gnus-summary-refer-article}) will ask you for a
+@code{Message-ID}, which is one of those long thingies that look
+something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
+it all exactly right. No fuzzy searches, I'm afraid.
+
+@vindex gnus-refer-article-method
+If the group you are reading is located on a backend that does not
+support fetching by @code{Message-ID} very well (like @code{nnspool}),
+you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
+would, perhaps, be best if the @sc{nntp} server you consult is the same
+as the one that keeps the spool you are reading from updated, but that's
+not really necessary.
+
+Most of the mail backends support fetching by @code{Message-ID}, but do
+not do a particularly excellent job of it. That is, @code{nnmbox} and
+@code{nnbabyl} are able to locate articles from any groups, while
+@code{nnml} and @code{nnfolder} are only able to locate articles that
+have been posted to the current group. (Anything else would be too time
+consuming.) @code{nnmh} does not support this at all.
-@table @code
-@item gnus-kill-killed
-@vindex gnus-kill-killed
-If this variable is nil, Gnus will never apply score files to articles
-that have already been through the kill process. While this may save
-you lots of time, it also means that if you apply a kill file to a
-group, and then change the kill file and want to run it over you group
-again to kill more articles, it won't work. You have to set this
-variable to t to do that.
-@item gnus-apply-kill-hook
-@vindex gnus-apply-kill-hook
-This hook is called to do the actual article killing. This hook may do
-anything, of course, but it should call the @code{gnus-apply-kill-file}
-function, or some equivalent function, to do the killing.
-@item gnus-kill-files-directory
-@vindex gnus-kill-files-directory
-All kill files will be stored in this directory, which is initialized
-from the @samp{SAVEDIR} environment variable by default.
-@item gnus-kill-file-name
-@vindex gnus-kill-file-name
-This variable is a string that will be appended to group names to
-make a kill file name. The default is @samp{KILL}.
-@end table
@node Mail Group Commands
@section Mail Group Commands
+@cindex mail group commands
-Some commands only make sense in mail groups.
+Some commands only make sense in mail groups. If these commands are
+illegal in the current group, they will raise a hell and let you know.
+
+All these commands (except the expiry and edit commands) use the
+process/prefix convention (@pxref{Process/Prefix}).
@table @kbd
-@item M-C-x
-@kindex M-C-x (Summary)
+@item B e
+@kindex B e (Summary)
@findex gnus-summary-expire-articles
Expire all expirable articles in the group
(@code{gnus-summary-expire-articles}).
-@item M-DEL
-@kindex M-DEL (Summary)
+
+@item B M-C-e
+@kindex B M-C-e (Summary)
+@findex gnus-summary-expire-articles-now
+Expunge all the expirable articles in the group
+(@code{gnus-summary-expire-articles-now}). This means that @strong{all}
+articles that are eligeble for expiry in the current group will
+disappear forever into that big @file{/dev/null} in the sky.
+
+@item B DEL
+@kindex B DEL (Summary)
@findex gnus-summary-delete-articles
-Delete the mail article. This is "delete" as in "delete it from your
+Delete the mail article. This is "delete" as in "delete it from your
disk forever and ever, never to return again." Use with caution.
(@code{gnus-summary-delete-article}).
-@item M-m
-@kindex M-m (Summary)
+
+@item B m
+@kindex B m (Summary)
+@cindex move mail
@findex gnus-summary-move-article
Move the article from one mail group to another
(@code{gnus-summary-move-article}).
-@item M-C-m
-@kindex M-C-m (Summary)
+
+@item B c
+@kindex B c (Summary)
+@cindex copy mail
+@findex gnus-summary-copy-article
+Copy the article from one group (mail group or not) to a mail group
+(@code{gnus-summary-copy-article}).
+
+@item B i
+@kindex B i (Summary)
+@findex gnus-summary-import-article
+Import a random file into the current mail newsgroup
+(@code{gnus-summary-import-article}). You will be prompted for a file
+name, a @code{From} header and a @code{Subject} header.
+
+Something similar can be done by just starting to compose a mail
+message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
+@kbd{C-c C-p} instead. This will put the message you have just created
+into the current mail group.
+
+@item B r
+@kindex B r (Summary)
@findex gnus-summary-respool-article
Respool the mail article (@code{gnus-summary-move-article}).
+
+@item B w
+@itemx e
+@kindex B w (Summary)
+@kindex e (Summary)
+@findex gnus-summary-edit-article
+@kindex C-c C-c (Article)
+Edit the current article (@code{gnus-summary-edit-article}). To finish
+editing and make the changes permanent, type @kbd{C-c C-c}
+(@kbd{gnus-summary-edit-article-done}).
+
+@item B q
+@kindex B q (Summary)
+@findex gnus-summary-respool-query
+If you want to respool an article, you might be curious as to what group
+the article will end up in before you do the respooling. This command
+will tell you (@code{gnus-summary-fancy-query}).
@end table
@node Various Summary Stuff
@section Various Summary Stuff
+@menu
+* Group Information:: Information oriented commands.
+* Searching for Articles:: Multiple article commands.
+* Really Various Summary Commands:: Those pesky non-conformant commands.
+@end menu
+
+@vindex gnus-summary-prepare-hook
+@code{gnus-summary-prepare-hook} is called after the summary buffer has
+been generated. You might use it to, for instance, highlight lines or
+modify the look of the buffer in some other ungodly manner. I don't
+care.
+
+@node Group Information
+@subsection Group Information
+
@table @kbd
-@item &
-@kindex & (Summary)
-@findex gnus-summary-expand-window
-This command will prompt you for a header field, a regular expression to
-be matched this field, and a command to be executed if the match is
-made.
-@item =
-@kindex = (Summary)
-@findex gnus-summary-expand-window
-Delete all other windows (@code{gnus-summary-expand-window}).
-@item C-x C-s
-@kindex C-x C-s (Summary)
-@findex gnus-summary-reselect-current-group
-Exit this group, and then enter it again
-(@code{gnus-summary-reselect-current-group}).
-@item C-c C-d
-@kindex C-c C-d (Summary)
+@item H f
+@kindex H f (Summary)
+@findex gnus-summary-fetch-faq
+@vindex gnus-group-faq-directory
+Try to fetch the FAQ (list of frequently asked questions) for the
+current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
+FAQ from @code{gnus-group-faq-directory}, which is usually a directory
+on a remote machine. This variable can also be a list of directories.
+In that case, giving a prefix to this command will allow you to choose
+between the various sites. @code{ange-ftp} probably will be used for
+fetching the file.
+@item H d
+@kindex H d (Summary)
@findex gnus-summary-describe-group
Give a brief description of the current group
-(@code{gnus-summary-describe-group}).
-@item M-g
-@kindex M-g (Summary)
-@findex gnus-summary-rescan-group
-Exit group, check for new articles in the group, and select the group
-(@code{gnus-summary-rescan-group}).
-@item V
-@kindex V (Summary)
-@findex gnus-version
-Display the Gnus version numbers (@code{gnus-version}).
-@item ?
-@kindex ? (Summary)
+(@code{gnus-summary-describe-group}). If given a prefix, force
+rereading the description from the server.
+@item H h
+@kindex H h (Summary)
@findex gnus-summary-describe-briefly
Give a very brief description of the most important summary keystrokes
(@code{gnus-summary-describe-briefly}).
-@item C-c C-i
-@kindex C-c C-i (Summary)
+@item H i
+@kindex H i (Summary)
@findex gnus-info-find-node
Go to the Gnus info node (@code{gnus-info-find-node}).
@end table
-@vindex gnus-summary-prepare-hook
-@code{gnus-summary-prepare-hook} is called after the summary buffer has
-been generated. You might use it to, for instance, hilight lines, modify
-the look, or anything else you feel like. I don't care.
+@node Searching for Articles
+@subsection Searching for Articles
+
+@table @kbd
+@item M-s
+@kindex M-s (Summary)
+@findex gnus-summary-search-article-forward
+Search through all subsequent articles for a regexp
+(@code{gnus-summary-search-article-forward}).
+@item M-r
+@kindex M-r (Summary)
+@findex gnus-summary-search-article-backward
+Search through all previous articles for a regexp
+(@code{gnus-summary-search-article-backward}).
+@item &
+@kindex & (Summary)
+@findex gnus-summary-execute-command
+This command will prompt you for a header field, a regular expression to
+match on this field, and a command to be executed if the match is made
+(@code{gnus-summary-execute-command}).
+@item M-&
+@kindex M-& (Summary)
+@findex gnus-summary-universal-argument
+Perform any operation on all articles that have been marked with
+the process mark (@code{gnus-summary-universal-argument}).
+@end table
+
+@node Really Various Summary Commands
+@subsection Really Various Summary Commands
+
+@table @kbd
+@item A D
+@kindex A D (Summary)
+@findex gnus-summary-enter-digest-group
+If the current article is a digest, you might use this command to enter
+you into a group based on the current digest to ease reading
+(@code{gnus-summary-enter-digest-group}).
+@item C-t
+@kindex C-t (Summary)
+@findex gnus-summary-toggle-truncation
+Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
+@item =
+@kindex = (Summary)
+@findex gnus-summary-expand-window
+Expand the summary buffer window (@code{gnus-summary-expand-window}).
+If given a prefix, force an @code{article} window configuration.
+@end table
@node The Article Buffer
@chapter The Article Buffer
+@cindex article buffer
The articles are displayed in the article buffer, of which there is only
one. All the summary buffer share the same article buffer.
@menu
* Hiding Headers:: Deciding what headers should be displayed.
-* Using Mime:: Pushing articles through MIME before reading them.
+* Using Mime:: Pushing articles through @sc{mime} before reading them.
* Customizing Articles:: Tailoring the look of the articles.
* Article Keymap:: Keystrokes available in the article buffer
* Misc Article:: Other stuff.
@node Hiding Headers
@section Hiding Headers
+@cindex hiding headers
+@cindex deleting headers
-The top section of each article is the @dfn{header}. (The rest is the
-@dfn{body}, but you may have guessed that already.)
+The top section of each article is the @dfn{head}. (The rest is the
+@dfn{body}, but you may have guessed that already.)
@vindex gnus-show-all-headers
-There is a lot of information in the header - the name of the person who
-wrote the article, the date and the subject of the article. That might
-be very useful, buf there's also lots of information most people do not
-want to see - what systems the article has passed through before
-reaching you, the message id, the references, etc. ad nauseum - and
-you'll probably want to get rid of some of those lines. If you want to
-keep all those lines in the article buffer, you can set
-@code{gnus-show-all-headers} to t.
+There is a lot of useful information in the head: the name of the person
+who wrote the article, the date it was written and the subject of the
+article. That's well and nice, but there's also lots of information
+most people do not want to see---what systems the article has passed
+through before reaching you, the @code{Message-ID}, the
+@code{References}, etc. ad nauseum---and you'll probably want to get rid
+of some of those lines. If you want to keep all those lines in the
+article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
-Gnus provides you with two variables for sifting header lines:
+Gnus provides you with two variables for sifting headers:
@table @code
@item gnus-visible-headers
@vindex gnus-visible-headers
-If this variable is non-nil, it should be a regular expression that says
-what header lines you wish to keep in the article buffer. All header
-lines that does not match this variable will be hidden.
+If this variable is non-@code{nil}, it should be a regular expression
+that says what headers you wish to keep in the article buffer. All
+headers that do not match this variable will be hidden.
For instance, if you only want to see the name of the person who wrote
the article and the subject, you'd say:
-@example
+@lisp
(setq gnus-visible-headers "^From:\\|^Subject:")
-@end example
+@end lisp
@item gnus-ignored-headers
@vindex gnus-ignored-headers
This variable is the reverse of @code{gnus-visible-headers}. If this
-variable is set (and @code{gnus-visible-headers} is nil), it should be a
-regular expression that matches all lines that you want to hide. All
-lines that does not match this variable will remain visible.
+variable is set (and @code{gnus-visible-headers} is @code{nil}), it
+should be a regular expression that matches all lines that you want to
+hide. All lines that do not match this variable will remain visible.
-For instance, if you just want to get rid of the references line and the
-xref line, you might say:
+For instance, if you just want to get rid of the @code{References} line
+and the @code{Xref} line, you might say:
-@example
-(setq gnus-ignored-headers "^References:\\^Xref:")
-@end example
+@lisp
+(setq gnus-ignored-headers "^References:\\|^Xref:")
+@end lisp
-Note that if @code{gnus-visible-headers} is non-nil, this variable will
-have no effect.
+Note that if @code{gnus-visible-headers} is non-@code{nil}, this
+variable will have no effect.
@end table
@vindex gnus-sorted-header-list
-Gnus can also sort the headers for you. (It does this by default.) You
+Gnus can also sort the headers for you. (It does this by default.) You
can control the sorting by setting the @code{gnus-sorted-header-list}
variable. It is a list of regular expressions that says in what order
-the header lines are to be displayed.
+the headers are to be displayed.
For instance, if you want the name of the author of the article first,
and then the subject, you might say something like:
-@example
+@lisp
(setq gnus-sorted-header-list '("^From:" "^Subject:"))
-@end example
+@end lisp
Any headers that are to remain visible, but are not listed in this
-variable, will be displayed after all the headers that are listed in
-this variable.
+variable, will be displayed in random order after all the headers that
+are listed in this variable.
@node Using Mime
@section Using Mime
+@cindex @sc{mime}
Mime is a standard for waving your hands through the air, aimlessly,
while people stand around yawning.
-MIME, however, is a standard for encoding your articles, aimlessly,
+@sc{mime}, however, is a standard for encoding your articles, aimlessly,
while all newsreaders die of fear.
-MIME may specify what character set the article uses, the encoding of
-the characters, and it also makes it possible to embed pictures and
+@sc{mime} may specify what character set the article uses, the encoding
+of the characters, and it also makes it possible to embed pictures and
other naughty stuff in innocent-looking articles.
@vindex gnus-show-mime
@vindex gnus-show-mime-method
-Gnus handles MIME by shoving the articles through
+Gnus handles @sc{mime} by shoving the articles through
@code{gnus-show-mime-method}, which is @code{metamail-buffer} by
-default. Set @code{gnus-show-mime} to t if you want to use MIME all the
-time; it might be best just use the toggling functions from the summary
-buffer to avoid getting nasty surprises (for instance, you enter the
-group @samp{alt.sing-a-long} and, before you know it, MIME has
-decoded the sounds file in the article and some horrible sing-a-long
-song comes streaming out out your speakers, and you can't find the
-volume button, because there isn't one, and people are starting to look
-at you, and you try to stop the program, but you can't, and you can't
-find the program to control the volume, and everybody else in the room
-suddenly decides to look at you disdainfully, and you'll feel rather
-stupid.
+default. If @code{gnus-strict-mime} is non-@code{nil}, the @sc{mime}
+method will only be used it there are @sc{mime} headers in the article.
+Set @code{gnus-show-mime} to @code{t} if you want to use @sc{mime} all
+the time; it might be best to just use the toggling functions from the
+summary buffer to avoid getting nasty surprises. (For instance, you
+enter the group @samp{alt.sing-a-long} and, before you know it,
+@sc{mime} has decoded the sound file in the article and some horrible
+sing-a-long song comes streaming out out your speakers, and you can't
+find the volume button, because there isn't one, and people are starting
+to look at you, and you try to stop the program, but you can't, and you
+can't find the program to control the volume, and everybody else in the
+room suddenly decides to look at you disdainfully, and you'll feel
+rather stupid.)
Any similarity to real events and people is purely coincidental. Ahem.
+
@node Customizing Articles
@section Customizing Articles
+@cindex article customization
@vindex gnus-article-display-hook
The @code{gnus-article-display-hook} is called after the article has
been inserted into the article buffer. It is meant to handle all
-treatment of the article before it is displayed. By default it contains
-@code{gnus-article-hide-headers}, which hides unwanted headers.
+treatment of the article before it is displayed.
-@findex gnus-article-subcite
-@findex gnus-article-hide-signature
-@findex gnus-article-hide-citation
-Other useful functions you might add to this hook is
-@code{gnus-article-hide-citation} (which hides all cited text);
-@code{gnus-article-hide-signature} (which, umn, hides the signature);
-@code{gnus-article-subcite} (which tries to clean up the mess supercite
-makes in The Hands Of The Mad; @code{gnus-article-treat-overstrike}
-(which treats @samp{^H_} in a reasonable manner); and
-@code{gnus-article-remove-cr} (which removes trailing carriage returns).
+By default it contains @code{gnus-article-hide-headers},
+@code{gnus-article-treat-overstrike}, and
+@code{gnus-article-maybe-highlight}, but there are thousands, nay
+millions, of functions you can put in this hook. For an overview of
+functions @xref{Article Highlighting}, @xref{Article Hiding},
+@xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
You can, of course, write your own functions. The functions are called
-in the article buffer, and you can do anything you like, pretty
-much. There is no information that you have to keep in the buffer - you
-can change everything.
+from the article buffer, and you can do anything you like, pretty much.
+There is no information that you have to keep in the buffer---you can
+change everything. However, you shouldn't delete any headers. Instead
+make them invisible if you want to make them go away.
+
@node Article Keymap
@section Article Keymap
-Most of the keystrokes in the summary buffer can also be used in the
-article buffer. They should behave as if you typed them in the summary
-buffer, which means that you don't actually have to have a summary
-buffer displayed when you're reading. You can do it all from the article
-buffer.
+@c Most of the keystrokes in the summary buffer can also be used in the
+@c article buffer. They should behave as if you typed them in the summary
+@c buffer, which means that you don't actually have to have a summary
+@c buffer displayed while reading. You can do it all from the article
+@c buffer.
A few additional keystrokes are available:
@kindex DEL (Article)
@findex gnus-article-prev-page
Scroll backwards one page (@code{gnus-article-prev-page}).
-@item C-x r
-@kindex C-x r (Article)
+@item C-c ^
+@kindex C-c ^ (Article)
@findex gnus-article-refer-article
-If point is in the neighborhood of a message-id and you press @kbd{r},
-Gnus will try to get that article from the server. (Only available with
-nntp). (@code{gnus-article-refer-article}).
-@item C-x m
-@kindex C-x m (Article)
+If point is in the neighborhood of a @code{Message-ID} and you press
+@kbd{r}, Gnus will try to get that article from the server
+(@code{gnus-article-refer-article}).
+@item C-c C-m
+@kindex C-c C-m (Article)
@findex gnus-article-mail
-Send a reply to the address near point (@code{gnus-article-mail}).
-@item C-x M
-@kindex C-x M (Article)
-@findex gnus-article-mail-with-original
-Send a reply to the address near point and include the original article
-(@code{gnus-article-mail-with-original}).
+Send a reply to the address near point (@code{gnus-article-mail}). If
+given a prefix, include the mail.
@item s
@kindex s (Article)
@findex gnus-article-show-summary
@node Misc Article
@section Misc Article
-@vindex gnus-article-display-hook
+@table @code
@vindex gnus-article-prepare-hook
-The @code{gnus-article-prepare-hook} is called right after the article
-has been inserted into the article buffer. It is mainly intended for
-functions that do something depending on the contents; it should
-probably not be used for changing the contents of the article
-buffer. Use the @code{gnus-article-display-hook} for that, which is
-called after this hook is called.
-
+@item gnus-article-prepare-hook
+This hook is called right after the article has been inserted into the
+article buffer. It is mainly intended for functions that do something
+depending on the contents; it should probably not be used for changing
+the contents of the article buffer.
+@vindex gnus-article-display-hook
+@item gnus-article-display-hook
+This hook is called as the last thing when displaying an article, and is
+intended for modifying the contents of the buffer, doing highlights,
+hiding headers, and the like.
@vindex gnus-article-mode-line-format
-@code{gnus-article-mode-line-format} is a format string along the same
-lines as @code{gnus-summary-mode-line-format}. It accepts exactly the
-same format specifications as that variable.
-
+@item gnus-article-mode-line-format
+This variable is a format string along the same lines as
+@code{gnus-summary-mode-line-format}. It accepts exactly the same
+format specifications as that variable.
@vindex gnus-break-pages
-The @code{gnus-break-pages} variable controls whether @dfn{page
-breaking} is to take place. If this variable is non-nil, the articles
-will be divided into pages whenever a @code{gnus-page-delimiter} appears
-in the article. If this variable is nil, paging will not be done.
-
+@item gnus-break-pages
+Controls whether @dfn{page breaking} is to take place. If this variable
+is non-@code{nil}, the articles will be divided into pages whenever a
+page delimiter appears in the article. If this variable is @code{nil},
+paging will not be done.
+@item gnus-page-delimiter
@vindex gnus-page-delimiter
-@code{gnus-page-delimiter} is @samp{^L} (form linefeed) by default.
+This is the delimiter mentioned above. By default, it is @samp{^L}
+(form linefeed).
+@end table
-@node Various
-@chapter Various
+@node The Server Buffer
+@chapter The Server Buffer
+
+Traditionally, a @dfn{server} is a machine or a piece of software that
+one connects to, and then requests information from. Gnus does not
+connect directly to any real servers, but does all transactions through
+one backend or other. But that's just putting one layer more between
+the actual media and Gnus, so we might just as well say that each
+backend represents a virtual server.
+
+For instance, the @code{nntp} backend may be used to connect to several
+different actual @sc{nntp} servers, or, perhaps, to many different ports
+on the same actual @sc{nntp} server. You tell Gnus which backend to
+use, and what parameters to set by specifying a @dfn{select method}.
+
+These select methods specifications can sometimes become quite
+complicated---say, for instance, that you want to read from the
+@sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
+hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
+Anyways, if you had to specify that for each group that used this
+server, that would be too much work, so Gnus offers a way of putting
+names to methods, which is what you do in the server buffer.
+
+To enter the server buffer, user the @kbd{^}
+(@code{gnus-group-enter-server-mode}) command in the group buffer.
@menu
-* Interactive:: Making Gnus ask you many questions.
-* Windows Configuration:: Configuring the Gnus buffer windows.
-* Various Various:: Things that are really various.
+* Server Buffer Format:: You can customize the look of this buffer.
+* Server Commands:: Commands to manipulate servers.
+* Example Methods:: Examples server specifications.
+* Servers & Methods:: You can use server names as select methods.
+* Unavailable Servers:: Some servers you try to contact may be down.
@end menu
-@node Interactive
-@section Interactive
+@node Server Buffer Format
+@section Server Buffer Format
+@cindex server buffer format
-@table @code
-@item gnus-novice-user
-@vindex gnus-novice-user
-If this variable is non-nil, you are either a newcomer to the usenet
-world, or you are very cautious, which is a nice thing to be,
-really. You will be given questions of the type "Are you sure you want
-to do this?" before doing anything dangerous.
-@item gnus-expert-user
-@vindex gnus-expert-user
-If this variable is non-nil, you will never ever be asked any questions
-by Gnus. It will simply assume you know what your are doing, no matter
-how strange.
-@item gnus-interactive-catchup
-@vindex gnus-interactive-catchup
-Require confirmation before catching up a group if non-nil.
-@item gnus-interactive-post
-@vindex gnus-interactive-post
-If non-nil, the user will be prompted for a group name when posting
-an article.
-@item gnus-interactive-exit
-@vindex gnus-interactive-exit
-Require confirmation before exiting Gnus.
+@vindex gnus-server-line-format
+You can change the look of the server buffer lines by changing the
+@code{gnus-server-line-format} variable. This is a @code{format}-like
+variable, with some simple extensions:
+
+@table @samp
+@item h
+How the news is fetched---the backend name.
+@item n
+The name of this server.
+@item w
+Where the news is to be fetched from---the address.
@end table
-@node Windows Configuration
-@section Windows Configuration
+@node Server Commands
+@section Server Commands
+@cindex server commands
-No, there's nothing here about X, so be quiet.
+@table @kbd
+@item SPC
+Browse the current server (@code{gnus-server-read-server}).
+@item q
+Return to the group buffer (@code{gnus-server-exit}).
+@item l
+List all servers (@code{gnus-server-list-servers}).
+@item k
+Kill the current server (@code{gnus-server-kill-server}).
+@item y
+Yank the previously killed server (@code{gnus-server-yank-server}).
+@item c
+Copy the current server (@code{gnus-server-copy-server}).
+@item a
+Add a new server (@code{gnus-server-add-server}).
+@item e
+Edit a server (@code{gnus-server-edit-server}).
+@end table
-@table @code
-@item gnus-use-full-window
-@vindex gnus-use-full-window
-If non-nil, Gnus will delete all other windows and occupy the entire
-Emacs screen by itself. It is t by default.
-@item gnus-window-configuration
-@vindex gnus-window-configuration
-This variable describes how much space each Gnus buffer should be given,
-compared to the other Gnus buffers. Here's an example:
+@node Example Methods
+@section Example Methods
-@example
-(setq gnus-window-configuration
- '((summary (0 1 0))
- (groups (1 0 0))
- (article (0 3 10))))
-@end example
+Most select methods are pretty simple and self-explanatory:
-This variable is a list of lists, where each of these small lists is on
-the form @var{(action (g s a))}. As you can see, there are three
-possible @var{action}s - @code{group} (which is what happens when
-you first start Gnus, or returns from the summary buffer),
-@code{summary} (which is what happens when there are no unread articles
-in the group, and @code{article} (which is what happens when there
-is an unread article in the group).
-
-We see that in the first two actions, the respective buffers will fill
-the screen, and in the last, the article buffer will take ten lines for
-each three the summary buffer gets.
-
-@findex gnus-window-configuration-split
-This variable can also have a function as its value. In that case,
-whenever Gnus tries to configure the Gnus buffers, that function will be
-called with the @var{action} as its parameter. There is one pre-made
-function supplied, @code{gnus-window-configuration-split}, which may be
-suitable if you have a very wide Emacs window, and wants to have the
-summary buffer and the article buffer side by side. Here's the
-definition of this function, which you may use as a template for your
-own function(s):
+@lisp
+(nntp "news.funet.fi")
+@end lisp
-@example
-(defun gnus-window-configuration-split (action)
- ;; The group buffer always exists, so it's nice to use
- ;; it as a starting point.
- (switch-to-buffer gnus-group-buffer t)
- (delete-other-windows)
- (split-window-horizontally)
- (cond ((or (eq action 'group) (eq action 'summary))
- (if (and (get-buffer gnus-summary-buffer)
- (buffer-name gnus-summary-buffer))
- (switch-to-buffer-other-window gnus-summary-buffer)))
- ((eq action 'article)
- (switch-to-buffer gnus-summary-buffer t)
- (other-window 1)
- ;; Create and initialize the article buffer if it doesn't
- ;; exist.
- (gnus-article-setup-buffer)
- (switch-to-buffer gnus-article-buffer t))))
-@end example
-@end table
+Reading directly from the spool is even simpler:
-@node Various Various
-@section Various Various
+@lisp
+(nnspool "")
+@end lisp
+As you can see, the first element in a select method is the name of the
+backend, and the second is the @dfn{address}, or @dfn{name}, if you
+will.
+
+After these two elements, there may be a random number of @var{(variable
+form)} pairs.
+
+To go back to the first example---imagine that you want to read from
+port @code{15} from that machine. This is what the select method should
+look like then:
+
+@lisp
+(nntp "news.funet.fi" (nntp-port-number 15))
+@end lisp
+
+You should read the documentation to each backend to find out what
+variables are relevant, but here's an @code{nnmh} example.
+
+@code{nnmh} is a mail backend that reads a spool-like structure. Say
+you have two structures that you wish to access: One is your private
+mail spool, and the other is a public one. Here's the possible spec for
+you private mail:
+
+@lisp
+(nnmh "private" (nnmh-directory "~/private/mail/"))
+@end lisp
+
+(This server is then called @samp{private}, but you may have guessed
+that.
+
+Here's the method for the public spool:
+
+@lisp
+(nnmh "public"
+ (nnmh-directory "/usr/information/spool/")
+ (nnmh-get-new-mail nil))
+@end lisp
+
+@node Servers & Methods
+@section Servers & Methods
+
+Wherever you would normally use a select method
+(eg. @code{gnus-secondary-select-method}, in the group select method,
+when browsing a foreign server) you can use a virtual server name
+instead. This could potentially save lots of typing. And it's nice all
+over.
+
+
+@node Unavailable Servers
+@section Unavailable Servers
+
+If a server seems to be unreachable, Gnus will mark that server as
+@code{denied}. That means that any subsequent attempt to make contact
+with that server will just be ignored. "It can't be opened," Gnus will
+tell you, without making the least effort to see whether that is
+actually the case or not.
+
+That might seem quite naughty, but it does make sense most of the time.
+Let's say you have 10 groups subscribed to the server
+@samp{nepholococcygia.com}. This server is located somewhere quite far
+away from you, the machine is quite, so it takes 1 minute just to find
+out that it refuses connection from you today. If Gnus were to attempt
+to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
+that. Once it has gotten a single "connection refused", it will regard
+that server as "down".
+
+So, what happens if the machine was only feeling unwell temporarily?
+How do you test to see whether the machine has come up again?
+
+You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
+with the following commands:
+
+@table @kbd
+
+@item O
+@kindex O (Server)
+@findex gnus-server-open-server
+Try to establish connection to the server on the current line
+(@code{gnus-server-open-server}).
+
+@item C
+@kindex C (Server)
+@findex gnus-server-close-server
+Close the connection (if any) to the server
+(@code{gnus-server-close-server}).
+
+@item D
+@kindex D (Server)
+@findex gnus-server-deny-server
+Mark the current server as unreachable
+(@code{gnus-server-deny-server}).
+
+@item R
+@kindex R (Server)
+@findex gnus-server-remove-denials
+Remove all marks to whether Gnus was denied connection from all servers
+(@code{gnus-server-remove-denials}).
+
+@end table
+
+
+@node Scoring
+@chapter Scoring
+@cindex scoring
+
+Other people use @dfn{kill files}, but we here at Gnus Towers like
+scoring better than killing, so we'd rather switch than fight. They do
+something completely different as well, so sit up straight and pay
+attention!
+
+@vindex gnus-summary-mark-below
+All articles have a default score (@code{gnus-summary-default-score}),
+which is 0 by default. This score may be raised or lowered either
+interactively or by score files. Articles that have a score lower than
+@code{gnus-summary-mark-below} are marked as read.
+
+Gnus will read any @dfn{score files} that apply to the current group
+before generating the summary buffer.
+
+There are several commands in the summary buffer that insert score
+entries based on the current article. You can, for instance, ask Gnus to
+lower or increase the score of all articles with a certain subject.
+
+There are two sorts of scoring entries: Permanent and temporary.
+Temporary score entries are self-expiring entries. Any entries that are
+temporary and have not been used for, say, a week, will be removed
+silently to help keep the sizes of the score files down.
+
+@menu
+* Summary Score Commands:: Adding score entries for the current group.
+* Group Score Commands:: General score commands.
+* Score Variables:: Customize your scoring. (My, what terminology).
+* Score File Format:: What a score file may contain.
+* Score File Editing:: You can edit score files by hand as well.
+* Adaptive Scoring:: Big Sister Gnus *knows* what you read.
+* Scoring Tips:: How to score effectively.
+* Reverse Scoring:: That problem child of old is not problem.
+* Global Score Files:: Earth-spanning, ear-splitting score files.
+* Kill Files:: They are still here, but they can be ignored.
+@end menu
+
+@node Summary Score Commands
+@section Summary Score Commands
+@cindex score commands
+
+The score commands that alter score entries do not actually modify real
+score files. That would be too inefficient. Gnus maintains a cache of
+previously loaded score files, one of which is considered the
+@dfn{current score file alist}. The score commands simply insert
+entries into this list, and upon group exit, this list is saved.
+
+The current score file is by default the group's local score file, even
+if no such score file actually exists. To insert score commands into
+some other score file (eg. @file{all.SCORE}), you must first make this
+score file the current one.
+
+General score commands that don't actually change the score file:
+
+@table @kbd
+@item V s
+@kindex V s (Summary)
+@findex gnus-summary-set-score
+Set the score of the current article (@code{gnus-summary-set-score}).
+
+@item V S
+@kindex V S (Summary)
+@findex gnus-summary-current-score
+Display the score of the current article
+(@code{gnus-summary-current-score}).
+
+@item V t
+@kindex V t (Summary)
+@findex gnus-score-find-trace
+Display all score rules that have been used on the current article
+(@code{gnus-score-find-trace}).
+
+@item V a
+@kindex V a (Summary)
+@findex gnus-summary-score-entry
+Add a new score entry, and allow specifying all elements
+(@code{gnus-summary-score-entry}).
+
+@item V c
+@kindex V c (Summary)
+@findex gnus-score-change-score-file
+Make a different score file the current
+(@code{gnus-score-change-score-file}).
+
+@item V e
+@kindex V e (Summary)
+@findex gnus-score-edit-alist
+Edit the current score file (@code{gnus-score-edit-alist}). You will be
+popped into a @code{gnus-score-mode} buffer (@pxref{Score File
+Editing}).
+
+@item V f
+@kindex V f (Summary)
+@findex gnus-score-edit-file
+Edit a score file and make this score file the current one
+(@code{gnus-score-edit-file}).
+
+@item V C
+@kindex V C (Summary)
+@findex gnus-score-customize
+Customize a score file in a visually pleasing manner
+(@code{gnus-score-customize}).
+
+@item I C-i
+@kindex I C-i (Summary)
+@findex gnus-summary-raise-score
+Increase the score of the current article
+(@code{gnus-summary-raise-score}).
+
+@item L C-l
+@kindex L C-l (Summary)
+@findex gnus-summary-lower-score
+Lower the score of the current article
+(@code{gnus-summary-lower-score}).
+@end table
+
+The rest of these commands modify the local score file.
+
+@table @kbd
+@item V m
+@kindex V m (Summary)
+@findex gnus-score-set-mark-below
+Prompt for a score, and mark all articles with a score below this as
+read (@code{gnus-score-set-mark-below}).
+@item V E
+@kindex V E (Summary)
+@findex gnus-score-set-expunge-below
+Expunge all articles with a score below the default score (or the
+numeric prefix) (@code{gnus-score-set-expunge-below}).
+@end table
+
+The keystrokes for actually making score entries follow a very regular
+pattern, so there's no need to list all the commands. (Hundreds of
+them.)
+
+@enumerate
+@item
+The first key is either @kbd{I} (upper case i) for increasing the score
+or @kbd{L} for lowering the score.
+@item
+The second key says what header you want to score on. The following
+keys are available:
+@table @kbd
+@item a
+Score on the author name.
+@item s
+Score on the subject line.
+@item x
+Score on the Xref line---i.e., the cross-posting line.
+@item t
+Score on thread---the References line.
+@item d
+Score on the date.
+@item l
+Score on the number of lines.
+@item i
+Score on the Message-ID.
+@item f
+Score on followups.
+@item b
+Score on the body.
+@item h
+Score on the head.
+@end table
+
+@item
+The third key is the match type. Which match types are legal depends on
+what headers you are scoring on.
+
+@table @code
+@item strings
+
+@table @kbd
+@item e
+Exact matching.
+@item s
+Substring matching.
+@item f
+Fuzzy matching.
+@item r
+Regexp matching
+@end table
+
+@item date
+@table @kbd
+@item b
+Before date.
+@item a
+At date.
+@item n
+This date.
+@end table
+
+@item number
+@table @kbd
+@item <
+Less than number.
+@item =
+Equal to number.
+@item >
+Greater than number.
+@end table
+@end table
+
+@item
+The fourth and final key says whether this is a temporary (i.e., expiring)
+score entry, or a permanent (i.e., non-expiring) score entry, or whether
+it is to be done immediately, without adding to the score file.
+@table @kbd
+@item t
+Temporary score entry.
+@item p
+Permanent score entry.
+@item i
+Immediately scoring.
+@end table
+
+@end enumerate
+
+So, let's say you want to increase the score on the current author with
+exact matching permanently: @kbd{I a e p}. If you want to lower the
+score based on the subject line, using substring matching, and make a
+temporary score entry: @kbd{L s s t}. Pretty easy.
+
+To make things a bit more complicated, there are shortcuts. If you use
+a capital letter on either the second or third keys, Gnus will use
+defaults for the remaining one or two keystrokes. The defaults are
+"substring" and "temporary". So @kbd{I A} is the same as @kbd{I a s t},
+and @kbd{I a R} is the same as @kbd{I a r t}.
+
+@vindex gnus-score-mimic-keymap
+The @code{gnus-score-mimic-keymap} says whether these commands will
+pretend they are keymaps or not.
+
+
+@node Group Score Commands
+@section Group Score Commands
+@cindex group score commands
+
+There aren't many of these as yet, I'm afraid.
+
+@table @kbd
+
+@item W f
+@kindex W f (Group)
+@findex gnus-score-flush-cache
+Gnus maintains a cache of score alists to avoid having to reload them
+all the time. This command will flush the cache
+(@code{gnus-score-flush-cache}).
+
+@end table
+
+
+@node Score Variables
+@section Score Variables
+@cindex score variables
+
+@table @code
+@item gnus-use-scoring
+@vindex gnus-use-scoring
+If @code{nil}, Gnus will not check for score files, and will not, in
+general, do any score-related work. This is @code{t} by default.
+
+@item gnus-kill-killed
+@vindex gnus-kill-killed
+If this variable is @code{nil}, Gnus will never apply score files to
+articles that have already been through the kill process. While this
+may save you lots of time, it also means that if you apply a kill file
+to a group, and then change the kill file and want to run it over you
+group again to kill more articles, it won't work. You have to set this
+variable to @code{t} to do that. (It is @code{t} by default.)
+
+@item gnus-kill-files-directory
+@vindex gnus-kill-files-directory
+All kill and score files will be stored in this directory, which is
+initialized from the @samp{SAVEDIR} environment variable by default.
+This is @file{~/News/} by default.
+
+@item gnus-score-file-suffix
+@vindex gnus-score-file-suffix
+Suffix to add to the group name to arrive at the score file name
+(@samp{SCORE} by default.)
+
+@item gnus-score-uncacheable-files
+@vindex gnus-score-uncacheable-files
+@cindex score cache
+All score files are normally cached to avoid excessive re-loading of
+score files. However, if this might make you Emacs grow big and
+bloated, so this regexp can be used to weed out score files that are
+unlikely to be needed again. It would be a bad idea to deny caching of
+@file{all.SCORE}, while it might be a good idea to not cache
+@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
+variable is @samp{"ADAPT$"} by default, so no adaptive score files will
+be cached.
+
+@item gnus-save-score
+@vindex gnus-save-score
+If you have really complicated score files, and do lots of batch
+scoring, then you might set this variable to @code{t}. This will make
+Gnus save the scores into the @file{.newsrc.eld} file.
+
+@item gnus-save-score
+@vindex gnus-save-score
+If you have really complicated score files, and do lots of batch
+scoring, then you might set this variable to @code{t}. This will make
+Gnus save the scores into the @file{.newsrc.eld} file.
+
+@item gnus-score-interactive-default-score
+@vindex gnus-score-interactive-default-score
+Score used by all the interactive raise/lower commands to raise/lower
+score with. Default is 1000, which may seem excessive, but this is to
+ensure that the adaptive scoring scheme gets enough room to play with.
+We don't want the small changes from the adaptive scoring to overwrite
+manually entered data.
+
+@item gnus-summary-default-score
+@vindex gnus-summary-default-score
+Default score of an article, which is 0 by default.
+
+@item gnus-score-over-mark
+@vindex gnus-score-over-mark
+Mark (in the third column) used for articles with a score over the
+default. Default is @samp{+}.
+
+@item gnus-score-below-mark
+@vindex gnus-score-below-mark
+Mark (in the third column) used for articles with a score below the
+default. Default is @samp{-}.
+
+@item gnus-score-find-score-files-function
+@vindex gnus-score-find-score-files-function
+Function used to find score files for the current group. This function
+is called with the name of the group as the argument.
+
+Predefined functions available are:
+@table @code
+
+@item gnus-score-find-single
+@findex gnus-score-find-single
+Only apply the group's own score file.
+
+@item gnus-score-find-bnews
+@findex gnus-score-find-bnews
+Apply all score files that match, using bnews syntax. This is the
+default. For instance, if the current group is @samp{gnu.emacs.gnus},
+@samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
+@samp{gnu.all.SCORE} would all apply. In short, the instances of
+@samp{all} in the score file names are translated into @samp{.*}, and
+then a regexp match is done.
+
+If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
+very will. It will find stuff like @file{gnu/all/SCORE}, but will not
+find files like @file{not/gnu/all/SCORE}.
+
+@item gnus-score-find-hierarchical
+@findex gnus-score-find-hierarchical
+Apply all score files from all the parent groups.
+@end table
+This variable can also be a list of functions. In that case, all these
+functions will be called, and all the returned lists of score files will
+be applied. These functions can also return lists of score alists
+directly. In that case, the functions that return these non-file score
+alists should probably be placed before the "real" score file functions,
+to ensure that the last score file returned is the local score file.
+Phu.
+@item gnus-score-expiry-days
+@vindex gnus-score-expiry-days
+This variable says how many days should pass before an unused score file
+entry is expired. The default is 7.
+@end table
+
+@node Score File Format
+@section Score File Format
+@cindex score file format
+
+A score file is an @code{emacs-lisp} file that normally contains just a
+single form. Casual users are not expected to edit these files;
+everything can be changed from the summary buffer.
+
+Anyway, if you'd like to dig into it yourself, here's an example:
+
+@lisp
+(("from"
+ ("Lars Ingebrigtsen" -10000)
+ ("Per Abrahamsen")
+ ("larsi\\|lmi" -50000 nil R))
+ ("subject"
+ ("Ding is Badd" nil 728373))
+ ("xref"
+ ("alt.politics" -1000 728372 s))
+ ("lines"
+ (2 -100 nil <))
+ (mark 0)
+ (expunge -1000)
+ (mark-and-expunge -10)
+ (read-only nil)
+ (orphan -10)
+ (adapt t)
+ (files "/hom/larsi/News/gnu.SCORE")
+ (exclude-files "all.SCORE")
+ (local (gnus-newsgroup-auto-expire t)
+ (gnus-summary-make-false-root 'empty))
+ (eval (ding)))
+@end lisp
+
+This example demonstrates absolutely everything about a score file.
+
+Even though this looks much like lisp code, nothing here is actually
+@code{eval}ed. The lisp reader is used to read this form, though, so it
+has to be legal syntactically, if not semantically.
+
+Six keys are supported by this alist:
+
+@table @code
+@item STRING
+If the key is a string, it is the name of the header to perform the
+match on. Scoring can only be performed on these eight headers:
+@samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
+@samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
+these headers, there are three strings to tell Gnus to fetch the entire
+article and do the match on larger parts of the article: @samp{Body}
+will perform the match on the body of the article, @samp{Head} will
+perform the match on the head of the article, and @samp{All} will
+perform the match on the entire article. Note that using any of these
+last three keys will slow down group entry @emph{considerably}. The
+final "header" you can score on is @samp{Followup}. These score entries
+will result in new score entries being added for all follow-ups to
+articles that matches these score entries.
+
+Following this key is a random number of score entries, where each score
+entry has one to four elements.
+@enumerate
+@item
+The first element is the @dfn{match element}. On most headers this will
+be a string, but on the Lines and Chars headers, this must be an
+integer.
+@item
+If the second element is present, it should be a number---the @dfn{score
+element}. This number should be an integer in the neginf to posinf
+interval. This number is added to the score of the article if the match
+is successful. If this element is not present, the
+@code{gnus-score-interactive-default-score} number will be used
+instead. This is 1000 by default.
+@item
+If the third element is present, it should be a number---the @dfn{date
+element}. This date says when the last time this score entry matched,
+which provides a mechanism for expiring the score entries. It this
+element is not present, the score entry is permanent. The date is
+represented by the number of days since December 31, 1 ce.
+@item
+If the fourth element is present, it should be a symbol---the @dfn{type
+element}. This element specifies what function should be used to see
+whether this score entry matches the article. What match types that can
+be used depends on what header you wish to perform the match on.
+@table @dfn
+@item From, Subject, References, Xref, Message-ID
+For most header types, there are the @code{r} and @code{R} (regexp) as
+well as @code{s} and @code{S} (substring) types and @code{e} and
+@code{E} (exact match) types. If this element is not present, Gnus will
+assume that substring matching should be used. @code{R} and @code{S}
+differ from the other two in that the matches will be done in a
+case-sensitive manner. All these one-letter types are really just
+abbreviations for the @code{regexp}, @code{string} and @code{exact}
+types, which you can use instead, if you feel like.
+@item Lines, Chars
+These two headers use different match types: @code{<}, @code{>},
+@code{=}, @code{>=} and @code{<=}.
+@item Date
+For the Date header we have three match types: @code{before}, @code{at}
+and @code{after}. I can't really imagine this ever being useful, but,
+like, it would feel kinda silly not to provide this function. Just in
+case. You never know. Better safe than sorry. Once burnt, twice shy.
+Don't judge a book by its cover. Never not have sex on a first date.
+@item Head, Body, All
+These three match keys use the same match types as the @code{From} (etc)
+header uses.
+@item Followup
+This match key will add a score entry on all articles that followup to
+some author. Uses the same match types as the @code{From} header uses.
+@end table
+@end enumerate
+
+@item mark
+The value of this entry should be a number. Any articles with a score
+lower than this number will be marked as read.
+@item expunge
+The value of this entry should be a number. Any articles with a score
+lower than this number will be removed from the summary buffer.
+@item mark-and-expunge
+The value of this entry should be a number. Any articles with a score
+lower than this number will be marked as read and removed from the
+summary buffer.
+@item files
+The value of this entry should be any number of file names. These files
+are assumed to be score files as well, and will be loaded the same way
+this one was.
+@item exclude-files
+The clue of this entry should be any number of files. This files will
+not be loaded, even though they would normally be so, for some reason or
+other.
+@item eval
+The value of this entry will be @code{eval}el. This element will be
+ignored when handling global score files.
+@item read-only
+Read-only score files will not be updated or saved. Global score files
+should feature this atom (@pxref{Global Score Files}).
+@item orphan
+The value of this entry should be a number. Articles that do not have
+parents will get this number added to their scores.
+@item adapt
+This entry controls the adaptive scoring. If it is @code{t}, the
+default adaptive scoring rules will be used. If it is @code{ignore}, no
+adaptive scoring will be performed on this group. If it is a list, this
+list will be used as the adaptive scoring rules. If it isn't present,
+or is something other than @code{t} or @code{ignore}, the default
+adaptive scoring rules will be used. If you want to use adaptive
+scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
+@code{t}, and insert an @code{(adapt ignore)} in the groups where you do
+not want adaptive scoring. If you only want adaptive scoring in a few
+groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
+insert @code{(adapt t)} in the score files of the groups where you want
+it.
+@item local
+@cindex local variables
+The value of this entry should be a list of @code{(VAR VALUE)} pairs.
+Each @var{var} will be made buffer-local to the current summary buffer,
+and set to the value specified. This is a convenient, if somewhat
+strange, way of setting variables in some groups if you don't like hooks
+much.
+@end table
+
+@node Score File Editing
+@section Score File Editing
+
+You normally enter all scoring commands from the summary buffer, but you
+might feel the urge to edit them by hand as well, so we've supplied you
+with a mode for that.
+
+It's simply a slightly customized @code{emacs-lisp} mode, with these
+additional commands:
+
+@table @kbd
+@item C-c C-c
+@kindex C-c C-c (Score)
+@findex gnus-score-edit-done
+Save the changes you have made and return to the summary buffer
+(@code{gnus-score-edit-done}).
+@item C-c C-d
+@kindex C-c C-d (Score)
+@findex gnus-score-edit-insert-date
+Insert the current date in numerical format
+(@code{gnus-score-edit-insert-date}). This is really the day number, if
+you were wondering.
+@end table
+
+@node Adaptive Scoring
+@section Adaptive Scoring
+@cindex adaptive scoring
+
+If all this scoring is getting you down, Gnus has a way of making it all
+happen automatically---as if by magic. Or rather, as if by artificial
+stupidity, to be precise.
+
+@vindex gnus-use-adaptive-scoring
+When you read an article, or mark an article as read, or kill an
+article, you leave marks behind. On exit from the group, Gnus can sniff
+these marks and add score elements depending on what marks it finds.
+You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
+@code{t}.
+
+@vindex gnus-default-adaptive-score-alist
+To give you complete control over the scoring process, you can customize
+the @code{gnus-default-adaptive-score-alist} variable. By default, it
+looks something like this:
+
+@lisp
+(defvar gnus-default-adaptive-score-alist
+ '((gnus-unread-mark)
+ (gnus-ticked-mark (from 4))
+ (gnus-dormant-mark (from 5))
+ (gnus-del-mark (from -4) (subject -1))
+ (gnus-read-mark (from 4) (subject 2))
+ (gnus-expirable-mark (from -1) (subject -1))
+ (gnus-killed-mark (from -1) (subject -3))
+ (gnus-kill-file-mark)
+ (gnus-catchup-mark (from -1) (subject -1))))
+@end lisp
+
+As you see, each element in this alist has a mark as a key (either a
+variable name or a "real" mark---a character). Following this key is a
+random number of header/score pairs.
+
+To take @code{gnus-del-mark} as an example---this alist says that all
+articles that have that mark (i.e., are marked with @samp{D}) will have a
+score entry added to lower based on the @code{From} header by -4, and
+lowered by @code{Subject} by -1. Change this to fit your prejudices.
+
+The headers you can score on are @code{from}, @code{subject},
+@code{message-id}, @code{references}, @code{xref}, @code{lines},
+@code{chars} and @code{date}. In addition, you can score on
+@code{followup}, which will create an adaptive score entry that matches
+on the @code{References} header using the @code{Message-ID} of the
+current article, thereby matching the following thread.
+
+If you use this scheme, you should set @code{mark-below} to something
+small---like -300, perhaps, to avoid having small random changes result
+in articles getting marked as read.
+
+After using adaptive scoring for a week or so, Gnus should start to
+become properly trained and enhance the authors you like best, and kill
+the authors you like least, without you having to say so explicitly.
+
+You can control what groups the adaptive scoring is to be performed on
+by using the score files (@pxref{Score File Format}). This will also
+let you use different rules in different groups.
+
+@vindex gnus-adaptive-file-suffix
+The adaptive score entries will be put into a file where the name is the
+group name with @code{gnus-adaptive-file-suffix} appended. The default
+is @samp{ADAPT}.
+
+@vindex gnus-score-exact-adapt-limit
+When doing adaptive scoring, substring or fuzzy matching would probably
+give you the best results in most cases. However, if the header one
+matches is short, the possibility for false positives is great, so if
+the length of the match is less than
+@code{gnus-score-exact-adapt-limit}, exact matching will be used. If
+this variable is @code{nil}, exact matching will always be used to avoid
+this problem.
+
+@node Scoring Tips
+@section Scoring Tips
+@cindex scoring tips
+
+@table @dfn
+@item Crossposts
+If you want to lower the score of crossposts, the line to match on is
+the @code{Xref} header.
+@lisp
+("xref" (" talk.politics.misc:" -1000))
+@end lisp
+@item Multiple crossposts
+If you want to lower the score of articles that have been crossposted to
+more than, say, 3 groups:
+@lisp
+("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
+@end lisp
+@item Matching on the body
+This is generally not a very good idea---it takes a very long time.
+Gnus actually has to fetch each individual article from the server. But
+you might want to anyway, I guess. Even though there are three match
+keys (@code{Head}, @code{Body} and @code{All}), you should choose one
+and stick with it in each score file. If you use any two, each article
+will be fetched @emph{twice}. If you want to match a bit on the
+@code{Head} and a bit on the @code{Body}, just use @code{All} for all
+the matches.
+@item Marking as read
+You will probably want to mark articles that has a score below a certain
+number as read. This is most easily achieved by putting the following
+in your @file{all.SCORE} file:
+@lisp
+((mark -100))
+@end lisp
+You may also consider doing something similar with @code{expunge}.
+
+@item Negated charater classes
+If you say stuff like @code{[^abcd]*}, you may get unexpected results.
+That will match newlines, which might lead to, well, The Unknown. Say
+@code{[^abcd\n]*} instead.
+@end table
+
+@node Reverse Scoring
+@section Reverse Scoring
+@cindex reverse scoring
+
+If you want to keep just articles that have @samp{Sex with Emacs} in the
+subject header, and expunge all other articles, you could put something
+like this in your score file:
+
+@lisp
+(("subject"
+ ("Sex with Emacs" 2))
+ (mark 1)
+ (expunge 1))
+@end lisp
+
+So, you raise all articles that match @samp{Sex with Emacs} and mark the
+rest as read, and expunge them to boot.
+
+@node Global Score Files
+@section Global Score Files
+@cindex global score files
+
+Sure, other newsreaders have "global kill files". These are usually
+nothing more than a single kill file that applies to all groups, stored
+in the user's home directory. Bah! Puny, weak newsreaders!
+
+What I'm talking about here are Global Score Files. Score files from
+all over the world, from users everywhere, uniting all nations in one
+big, happy score file union! Ange-score! New and untested!
+
+@vindex gnus-global-score-files
+All you have to do to use other people's score files is to set the
+@code{gnus-global-score-files} variable. One entry for each score file,
+or each score file directory. Gnus will decide by itself what score
+files are applicable to which group.
+
+Say you want to use all score files in the
+@file{/ftp@@ftp.some-where:/pub/score} directory and the single score
+file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
+
+@lisp
+(setq gnus-global-score-files
+ '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
+ "/ftp@@ftp.some-where:/pub/score/"))
+@end lisp
+
+@findex gnus-score-search-global-directories
+Simple, eh? Directory names must end with a @samp{/}. These
+directories are typically scanned only once during each Gnus session.
+If you feel the need to manually re-scan the remote directories, you can
+use the @code{gnus-score-search-global-directories} command.
+
+Note that, at present, using this option will slow down group entry
+somewhat. (That is---a lot.)
+
+If you want to start maintaining score files for other people to use,
+just put your score file up for anonymous ftp and announce it to the
+world. Become a retro-moderator! Participate in the retro-moderator
+wars sure to ensue, where retro-moderators battle it out for the
+sympathy of the people, luring them to use their score files on false
+premises! Yay! The net is saved!
+
+Here are some tips for the would-be retro-moderator, off the top of my
+head:
+
+@itemize @bullet
+@item
+Articles that are heavily crossposted are probably junk.
+@item
+To lower a single inappropriate article, lower by @code{Message-ID}.
+@item
+Particularly brilliant authors can be raised on a permanent basis.
+@item
+Authors that repeatedly post off-charter for the group can safely be
+lowered out of existence.
+@item
+Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
+articles completely.
+@item
+Use expiring score entries to keep the size of the file down. You
+should probably have a long expiry period, though, as some sites keep
+old articles for a long time.
+@end itemize
+
+... I wonder whether other newsreaders will support global score files
+in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
+Wave, xrn and 1stReader are bound to implement scoring. Should we start
+holding our breath yet?
+
+
+@node Kill Files
+@section Kill Files
+@cindex kill files
+
+Gnus still supports those pesky old kill files. In fact, the kill file
+entries can now be expiring, which is something I wrote before Daniel
+Quinlan thought of doing score files, so I've left the code in there.
+
+In short, kill processing is a lot slower (and I do mean @emph{a lot})
+than score processing, so it might be a good idea to rewrite your kill
+files into score files.
+
+Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
+forms into this file, which means that you can use kill files as some
+sort of primitive hook function to be run on group entry, even though
+that isn't a very good idea.
+
+XCNormal kill files look like this:
+
+@lisp
+(gnus-kill "From" "Lars Ingebrigtsen")
+(gnus-kill "Subject" "ding")
+(gnus-expunge "X")
+@end lisp
+
+This will mark every article written by me as read, and remove them from
+the summary buffer. Very useful, you'll agree.
+
+Other programs use a totally different kill file syntax. If Gnus
+encounters what looks like a @code{rn} kill file, it will take a stab at
+interpreting it.
+
+Two functions for editing a GNUS kill file:
+
+@table @kbd
+@item M-k
+@kindex M-k (Summary)
+@findex gnus-summary-edit-local-kill
+Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
+
+@item M-K
+@kindex M-K (Summary)
+@findex gnus-summary-edit-global-kill
+Edit the general kill file (@code{gnus-summary-edit-global-kill}).
+@end table
+
+@vindex gnus-kill-file-name
+A kill file for the group @samp{soc.motss} is normally called
+@file{soc.motss.KILL}. The suffix appended to the group name to get
+this file name is detailed by the @code{gnus-kill-file-name} variable.
+The "global" kill file (not in the score file sense of "global", of
+course) is called just @file{KILL}.
+
+@vindex gnus-kill-save-kill-file
+If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
+kill file after processing, which is necessary if you use expiring
+kills.
+
+
+
+
+@node Various
+@chapter Various
+
+@menu
+* Interactive:: Making Gnus ask you many questions.
+* Windows Configuration:: Configuring the Gnus buffer windows.
+* Buttons:: Get tendonitis in ten easy steps!
+* Compilation & Init File:: How to speed Gnus up.
+* Daemons:: Gnus can do things behind your back.
+* NoCeM:: How to avoid spam and other fatty foods.
+* Various Various:: Things that are really various.
+@end menu
+
+@node Interactive
+@section Interactive
+@cindex interaction
+
+@table @code
+@item gnus-novice-user
+@vindex gnus-novice-user
+If this variable is non-@code{nil}, you are either a newcomer to the
+World of Usenet, or you are very cautious, which is a nice thing to be,
+really. You will be given questions of the type "Are you sure you want
+to do this?" before doing anything dangerous. This is @code{t} by
+default.
+
+@item gnus-expert-user
+@vindex gnus-expert-user
+If this variable is non-@code{nil}, you will never ever be asked any
+questions by Gnus. It will simply assume you know what your are doing,
+no matter how strange.
+
+@item gnus-interactive-catchup
+@vindex gnus-interactive-catchup
+Require confirmation before catching up a group if non-@code{nil}. It
+is @code{t} by default.
+
+@item gnus-interactive-post
+@vindex gnus-interactive-post
+If non-@code{nil}, the user will be prompted for a group name when
+posting an article. It is @code{t} by default.
+
+@item gnus-interactive-exit
+@vindex gnus-interactive-exit
+Require confirmation before exiting Gnus. This variable is @code{t} by
+default.
+@end table
+
+
+@node Windows Configuration
+@section Windows Configuration
+@cindex windows configuration
+
+No, there's nothing here about X, so be quiet.
+
+@table @code
+@item gnus-use-full-window
+@vindex gnus-use-full-window
+If non-@code{nil}, Gnus will delete all other windows and occupy the
+entire Emacs screen by itself. It is @code{t} by default.
+
+@item gnus-buffer-configuration
+@vindex gnus-buffer-configuration
+This variable describes how much space each Gnus buffer should be given.
+Here's an excerpt of this variable:
+
+@lisp
+((group ([group 1.0 point]
+ (if gnus-carpal [group-carpal 4])))
+ (article ([summary 0.25 point]
+ [article 1.0])))
+@end lisp
+
+This is an alist. The @dfn{key} is a symbol that names some action or
+other. For instance, when displaying the group buffer, the window
+configuration function will use @code{group} as the key. A full list of
+possible names is listed below.
+
+The @dfn{value} is a @dfn{rule} that says how much space each buffer
+should occupy. To take the @code{article} rule as an example -
+
+@lisp
+(article ([summary 0.25 point]
+ [article 1.0]))
+@end lisp
+
+This rule says that the summary buffer should occupy 25% of the screen,
+and that it is placed over the article buffer. As you may have noticed,
+100% + 25% is actually 125% (yup, I saw y'all reaching for that
+calculator there). However, the special number @code{1.0} is used to
+signal that this buffer should soak up all the rest of the space
+avaiable after the rest of the buffers have taken whatever they need.
+There should be only one buffer with the @code{1.0} size spec.
+
+Point will be put in the buffer that has the optional third element
+@code{point}.
+
+Here's a more complicated example:
+
+@lisp
+(article ([group 4]
+ [summary 0.25 point]
+ (if gnus-carpal [summary-carpal 4])
+ [article 1.0])
+@end lisp
+
+If the size spec is an integer instead of a floating point number,
+then that number will be used to say how many lines a buffer should
+occupy, not a percentage.
+
+If an element is a list instead of a vector, this list will be
+@code{eval}ed. If the result is non-@code{nil}, it will be used. This
+means that there will be three buffers if @code{gnus-carpal} is
+@code{nil}, and four buffers if @code{gnus-carpal} is non-@code{nil}.
+
+Not complicated enough for you? Well, try this on for size:
+
+@lisp
+(article ([group 1.0]
+ [gnus-carpal 4])
+ ((horizontal 0.5)
+ [summary 0.25 point]
+ [summary-carpal 4]
+ [article 1.0]))
+@end lisp
+
+Whoops. Two buffers with the mystery 100% tag. And what's that
+@code{horizontal} thingie?
+
+If the first element in one of the rule lists is a list with
+@code{horizontal} as the first element, Gnus will split the window
+horizontally, giving you two windows side-by-side. Inside each of these
+strips you may carry on all you like in the normal fashion. The number
+following @code{horizontal} says what percentage of the screen is to be
+given to this strip.
+
+For each horizontal split, there @emph{must} be one element that has the
+100% tag. The splitting is never accurate, and this buffer will eat any
+leftover lines from the splits.
+
+Here's a list of all possible keys:
+
+@code{group}, @code{summary}, @code{article}, @code{server},
+@code{browse}, @code{group-mail}, @code{summary-mail},
+@code{summary-reply}, @code{info}, @code{summary-faq},
+@code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
+@code{followup}, @code{followup-yank}, @code{edit-score}.
+
+@findex gnus-add-configuration
+Since this variable is so long and complicated, there's a function you
+can use to ease changing the config of a single setting:
+@code{gnus-add-configuration}. If, for instance, you want to change the
+@code{article} setting, you could say:
+
+@lisp
+(gnus-add-configuration
+ '(article ([group 4]
+ [summary .25 point]
+ [article 1.0])))
+@end lisp
+
+@end table
+
+@node Buttons
+@section Buttons
+@cindex buttons
+@cindex mouse
+@cindex click
+
+Those new-fangled @dfn{mouse} contraptions is very popular with the
+young, hep kids who don't want to learn the proper way to do things
+these days. Why, I remember way back in the summer of '89, when I was
+using Emacs on a Tops 20 system. Three hundred users on one single
+machine, and every user was running Simula compilers. Bah!
+
+Right.
+
+@vindex gnus-carpal
+Well, you can make Gnus display bufferfuls of buttons you can click to
+do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
+really. Tell the chiropractor I sent you.
+
+
+@table @code
+@item gnus-carpal-mode-hook
+@vindex gnus-carpal-mode-hook
+Hook run in all carpal mode buffers.
+@item gnus-carpal-button-face
+@vindex gnus-carpal-button-face
+Face used on buttons.
+@item gnus-carpal-group-buffer-buttons
+@vindex gnus-carpal-group-buffer-buttons
+Buttons in the group buffer.
+@item gnus-carpal-summary-buffer-buttons
+@vindex gnus-carpal-summary-buffer-buttons
+Buttons in the summary buffer.
+@item gnus-carpal-server-buffer-buttons
+@vindex gnus-carpal-server-buffer-buttons
+Buttons in the server buffer.
+@item gnus-carpal-browse-buffer-buttons
+@vindex gnus-carpal-browse-buffer-buttons
+Buttons in the browse buffer.
+@end table
+
+All the @code{buttons} variables are lists. The elements in these list
+is either a cons cell where the car contains a text to be displayed and
+the cdr contains a function symbol, or a simple string.
+
+
+@node Compilation & Init File
+@section Compilation & Init File
+@cindex compilation
+@cindex init file
+@cindex byte-compilation
+
+@vindex gnus-init-file
+@findex gnus-compile
+When Gnus starts up, it will read the Gnus init file
+@code{gnus-init-file}, which is @file{.gnus} by default. It is
+recommended that you keep any Gnus-related functions that you have
+written in that file. If you want to byte-compile the file, Gnus offers
+the handy @kbd{M-x gnus-compile} function that will do that for you.
+
+That's not really why that function was written, though.
+
+Remember all those line format specification variables?
+@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
+on. Now, Gnus will of course heed whatever these variables are, but,
+unfortunately, changing them will mean a quite significant slow-down.
+(The default values of these variables have byte-compiled functions
+associated with them, while the user-generated versions do not, of
+course.)
+
+To help with this, you can run @code{gnus-compile} after you've fiddled
+around with the variables and feel that you're (kind of) satisfied.
+This will result in the new specs being byte-compiled, and you'll get
+top speed again.
+
+The result of these byte-compilations will be written to
+@file{.gnus.elc} by default.
+
+Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
+@file{.gnus.elc} exists, so if you change @file{.gnus}, you should
+remove @file{.gnus.elc}.
+
+
+@node Daemons
+@section Daemons
+@cindex demons
+@cindex daemons
+
+Gnus, being larger than any program ever written (allegedly), does lots
+of strange stuff that you may wish to have done while you're not
+present. For instance, you may want it to check for new mail once in a
+while. Or you may want it to close down all connections to all servers
+when you leave Emacs idle. And stuff like that.
+
+Gnus will let you do stuff like that by defining various
+@dfn{handlers}. Each handler consists of three elements: A
+@var{function}, a @var{time}, and an @var{idle} parameter.
+
+Here's an example of a handler that closes connections when Emacs has
+been idle for thirty minutes:
+
+@lisp
+(gnus-demon-close-connections nil 30)
+@end lisp
+
+Here's a handler that scans for PGP headers every hour when Emacs is
+idle:
+
+@lisp
+(gnus-demon-scan-pgp 60 t)
+@end lisp
+
+This @var{time} parameter and than @var{idle} parameter works together
+in a strange, but wonderful fashion. Basically, if @var{idle} is
+@code{nil}, then the function will be called every @var{time} minutes.
+
+If @var{idle} is @code{t}, then the function will be called after
+@var{time} minutes only if Emacs is idle. So if Emacs is never idle,
+the function will never be called. But once Emacs goes idle, the
+function will be called every @var{time} minutes.
+
+If @var{idle} is a number and @var{time} is a number, the function will
+be called every @var{time} minutes only when Emacs has been idle for
+@var{idle} minutes.
+
+If @var{idle} is a number and @var{time} is @code{nil}, the function
+will be called once every time Emacs has been idle for @var{idle}
+minutes.
+
+And if @var{time} is a string, it should look like @samp{"07:31"}, and
+the function will then be called once every day somewhere near that
+time. Modified by the @var{idle} parameter, of course.
+
+@vindex gnus-demon-timestep
+(When I say "minute" here, I really mean @code{gnus-demon-timestep}
+seconds. This is @samp{60} by default. If you change that variable,
+all the timings in the handlers will be affected.)
+
+@vindex gnus-use-demon
+To set the whole thing in motion, though, you have to set
+@code{gnus-use-demon} to @code{t}.
+
+@vindex gnus-use-demon
+To set the whole thing in motion, though, you have to set
+@code{gnus-use-demon} to @code{t}.
+
+So, if you want to add a handler, you could put something like this in
+your @file{.gnus} file:
+
+@findex gnus-demon-add-handler
+@lisp
+(gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
+@end lisp
+
+@findex gnus-demon-add-nocem
+@findex gnus-demon-add-scanmail
+@findex gnus-demon-add-disconnection
+Some ready-made functions to do this has been created:
+@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
+@code{gnus-demon-add-scanmail}. Just put those functions in your
+@file{.gnus} if you want those abilities.
+
+@findex gnus-demon-init
+@findex gnus-demon-cancel
+@vindex gnus-demon-handlers
+If you add handlers to @code{gnus-demon-handlers} directly, you should
+run @code{gnus-demon-init} to make the changes take hold. To cancel all
+daemons, you can use the @code{gnus-demon-cancel} function.
+
+Note that adding daemons can be pretty naughty if you overdo it. Adding
+functions that scan all news and mail from all servers every two seconds
+is a sure-fire way of getting booted off any respectable system. So
+behave.
+
+
+@node NoCeM
+@section NoCeM
+@cindex nocem
+@cindex spam
+
+
+
+@node Various Various
+@section Various Various
+@cindex mode lines
+@cindex highlights
+
+@table @code
+@item gnus-verbose
+@vindex gnus-verbose
+This variable is an integer between zero and ten. The higher the value,
+the more messages will be displayed. If this variable is zero, Gnus
+will never flash any messages, if it is seven (which is the default),
+most important messages will be shown, and if it is ten, Gnus won't ever
+shut up, but will flash so many messages it will make your head swim.
+
+@item gnus-updated-mode-lines
@vindex gnus-updated-mode-lines
-The @code{gnus-updated-mode-lines} variable is a list of buffers that
-should keep their mode lines updated. The list may contain the symbols
-`group', `article' and `summary'. If the corresponding symbol is
-present, Gnus will keep that mode line updated with information that may
-be pertinent. If this variable is nil, screen refresh may be quicker.
+This is a list of buffers that should keep their mode lines updated.
+The list may contain the symbols @code{group}, @code{article} and
+@code{summary}. If the corresponding symbol is present, Gnus will keep
+that mode line updated with information that may be pertinent. If this
+variable is @code{nil}, screen refresh may be quicker.
+
+@cindex display-time
+@item gnus-mode-non-string-length
+@vindex gnus-mode-non-string-length
+By default, Gnus displays information on the current article in the mode
+lines of the summary and article buffers. The information Gnus wishes
+to display (eg. the subject of the article) is often longer than the
+mode lines, and therefore have to be cut off at some point. This
+variable says how long the other elements on the line is (i.e., the
+non-info part). If you put additional elements on the mode line (eg. a
+clock), you should modify this variable:
+@c Hook written by Keinonen Kari <kk85613@cs.tut.fi>.
+@lisp
+(add-hook 'display-time-hook
+ (lambda ()
+ (setq gnus-mode-non-string-length
+ (+ 21 (length display-time-string)))))
+@end lisp
+
+@item gnus-visual
+@vindex gnus-visual
+@cindex visual
+@cindex highlighting
+@cindex menus
+
+If @code{nil}, Gnus won't attempt to create menus or use fancy colors
+or fonts. This will also inhibit loading the @file{gnus-visual.el}
+file.
+
+This variable can also be a list of visual properties that are enabled.
+The following elements are legal, and are all set by default:
+
+@table @code
+
+@item summary-highlight
+Perform various highlighting in the summary buffer.
+
+@item article-highlight
+Perform various highlighting in the article buffer.
+
+@item highlight
+Turn on highlighting in all buffers.
+
+@item group-menu
+Create menus in the group buffer.
+
+@item summary-menu
+Create menus in the summary buffer.
+
+@item article-menu
+Create menus in the article buffer.
+
+@item browse-menu
+Create menus in the browse buffer.
+
+@item server-menu
+Create menus in the server buffer.
+
+@item menu
+Create menus in all buffers.
+
+@end table
+
+So if you only want highlighting in the article buffer and menus in all
+buffers, you couls say something like:
+
+@lisp
+(setq gnus-visual '(article-highlight menu))
+@end lisp
+
+If you want only highlighting and no menus whatsoever, you'd say:
+
+@lisp
+(setq gnus-visual '(highlight))
+@end lisp
+
+@item gnus-mouse-face
+@vindex gnus-mouse-face
+This is the face (i.e., font) used for mouse highlighting in Gnus. No
+mouse highlights will be done if @code{gnus-visual} is @code{nil}.
+
+@item gnus-display-type
+@vindex gnus-display-type
+This variable is symbol indicating the display Emacs is running under.
+The symbol should be one of @code{color}, @code{grayscale} or
+@code{mono}. If Gnus guesses this display attribute wrongly, either set
+this variable in your @file{~/.emacs} or set the resource
+@code{Emacs.displayType} in your @file{~/.Xdefaults}.
+
+@item gnus-background-mode
+@vindex gnus-background-mode
+This is a symbol indicating the Emacs background brightness. The symbol
+should be one of @code{light} or @code{dark}. If Gnus guesses this
+frame attribute wrongly, either set this variable in your @file{~/.emacs} or
+set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
+`gnus-display-type'.
+
+@item nnheader-max-head-length
+@vindex nnheader-max-head-length
+When the backends read straight heads of articles, they all try to read
+as little as possible. This variable (default @code{4096}) specifies
+the absolute max length the backends will try to read before giving up
+on finding a separator line between the head and the body. If this
+variable is @code{nil}, there is no upper read bound. If it is
+@code{t}, the backends won't try to read the articles piece by piece,
+but read the entire articles. This makes sense with some versions of
+@code{ange-ftp}.
+
+
+@end table
@node Customization
@chapter Customization
+@cindex general customization
All variables are properly documented elsewhere in this manual. This
section is designed to give general pointers on how to customize Gnus
for some quite common situations.
@menu
-* Slow NNTP Connection:: You run a local Emacs and get the news elsewhere.
+* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
* Slow Terminal Connection:: You run a remote Emacs.
* Little Disk Space:: You feel that having large setup files is icky.
* Slow Machine:: You feel like buying a faster machine.
@end menu
-@node Slow NNTP Connection
-@section Slow NNTP Connection
+@node Slow/Expensive Connection
+@section Slow/Expensive @sc{nntp} Connection
If you run Emacs on a machine locally, and get your news from a machine
over some very thin strings, you want to cut down on the amount of data
-Gnus has to get from the NNTP server.
+Gnus has to get from the @sc{nntp} server.
@table @code
@item gnus-read-active-file
-Set this to nil, which will inhibit Gnus from requesting the entire active
-file from the server. This file is often v. large. You also have to set
-@code{gnus-check-new-news} and @code{gnus-check-bogus-newsgroups} to nil
-to make sure that Gnus doesn't suddenly decide to fetch the active file
-anyway. Note that this will make it difficult for you to get hold of new
-groups.
-@item nntp-xover-is-evil
-This one has to be nil. If not, grabbing article headers from the NNTP
-server will not be very fast. Not all NNTP servers support XOVER; Gnus
-will detect this by itself.
+Set this to @code{nil}, which will inhibit Gnus from requesting the
+entire active file from the server. This file is often v. large. You
+also have to set @code{gnus-check-new-news} and
+@code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
+doesn't suddenly decide to fetch the active file anyway.
+@item gnus-nov-is-evil
+This one has to be @code{nil}. If not, grabbing article headers from
+the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
+support @sc{xover}; Gnus will detect this by itself.
@end table
@node Slow Terminal Connection
@section Slow Terminal Connection
-Let's say you use your home computer for dialling up the system that
+Let's say you use your home computer for dialing up the system that
runs Emacs and Gnus. If your modem is slow, you want to reduce the
amount of data that is sent over the wires as much as possible.
@table @code
@item gnus-auto-center-summary
-Set this to nil to inhibit Gnus from recentering the summary buffer all
-the time.
+Set this to @code{nil} to inhibit Gnus from recentering the summary
+buffer all the time.
@item gnus-visible-headers
Cut down on the headers that are included in the articles to the
-minimum. You can, in fact, make do without them altogether - most of the
+minimum. You can, in fact, make do without them altogether---most of the
useful data is in the summary buffer, anyway. Set this variable to
-@samp{""} or @samp{"^Date:"}, or whatever you feel you need.
+@samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
@item gnus-article-display-hook
Set this hook to all the available hiding commands:
-@example
+@lisp
(setq gnus-article-display-hook
'(gnus-article-hide-headers gnus-article-hide-signature
gnus-article-hide-citation))
-@end example
+@end lisp
@item gnus-use-full-window
-By setting this to nil, you can make all the windows smaller. While this
-doesn't really cut down much generally, it means that you have to see
-smaller portions of articles before deciding that you didn't want to
-read them anyway.
+By setting this to @code{nil}, you can make all the windows smaller.
+While this doesn't really cut down much generally, it means that you
+have to see smaller portions of articles before deciding that you didn't
+want to read them anyway.
@item gnus-thread-hide-subtree
-If this is non-nil, all threads in the summary buffer will be hidden
-initially.
+If this is non-@code{nil}, all threads in the summary buffer will be
+hidden initially.
@item gnus-updated-mode-lines
-If this is nil, Gnus will not put information in the buffer mode lines,
-which might save some time.
+If this is @code{nil}, Gnus will not put information in the buffer mode
+lines, which might save some time.
@end table
@node Little Disk Space
@section Little Disk Space
-The startup files can get rather large, so you may want to keep their
-sizes down a bit if you are running out of space.
+The startup files can get rather large, so you may want to cut their
+sizes a bit if you are running out of space.
@table @code
@item gnus-save-newsrc-file
-If this is nil, Gnus will never save @file{.newsrc} - it will only save
-@file{.newsrc.eld}. This means that you will not be able to use any
-other newsreaders than Gnus.
+If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
+only save @file{.newsrc.eld}. This means that you will not be able to
+use any other newsreaders than Gnus. This variable is @code{t} by
+default.
+
@item gnus-save-killed-list
-If this is nil, Gnus will not save the list of dead groups. That
-means that Gnus will not know whether groups are new or old, which
-makes automatic handling of new groups impossible. You should also
-set @code{gnus-check-new-newsgroups} and
-@code{gnus-check-bogus-newsgroups} to nil if you set this variable to
-nil.
+If this is @code{nil}, Gnus will not save the list of dead groups. You
+should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
+and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
+variable to @code{nil}. This variable is @code{t} by default.
+
@end table
+
@node Slow Machine
@section Slow Machine
If you have a slow machine, or are just really impatient, there are a
few things you can do to make Gnus run faster.
-Set @code{gnus-read-active-file}, @code{gnus-check-new-newsgroups},
-@code{gnus-check-bogus-newsgroups} to nil to make startup faster.
+Set@code{gnus-check-new-newsgroups} and
+@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
-@code{nntp-xover-is-evil} to nil to make entering and exiting the
+@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
summary buffer faster.
-Set @code{gnus-article-display-hook} to nil to make article processing a
-bit faster.
+Set @code{gnus-article-display-hook} to @code{nil} to make article
+processing a bit faster.
+
@node Troubleshooting
@chapter Troubleshooting
+@cindex troubleshooting
+
+Gnus works @emph{so} well straight out of the box---I can't imagine any
+problems, really.
+
+Ahem.
+
+@enumerate
+
+@item
+Make sure your computer is switched on.
-@node Reporting Bugs
-@chapter Reporting Bugs
+@item
+Make sure that you really load the current Gnus version. If you have
+been running @sc{gnus}, you need to exit Emacs and start it up again before
+Gnus will work.
-If you find a bug in (ding) Gnus, you can report it with the @kbd{M-x
-gnus-bug} command. @code{(setq debug-on-error t)}, and send me the
-backtrace. I will fix bugs, but I can only fix them if you send me a
-precise description as to how to reproduce the bug.
+@item
+Try doing an @kbd{M-x gnus-version}. If you get something that looks
+like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
+on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
+flee}, you have some old @file{.el} files lying around. Delete these.
+
+@item
+Read the help group (@kbd{M h} in the group buffer) for a FAQ and a
+how-to.
+@end enumerate
+
+If all else fails, report the problem as a bug.
+
+@cindex bugs
+@cindex reporting bugs
+
+@kindex M-x gnus-bug
+@findex gnus-bug
+If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
+command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
+me the backtrace. I will fix bugs, but I can only fix them if you send
+me a precise description as to how to reproduce the bug.
+
+You really can never be too detailed in a bug report. Always use the
+@kbd{M-x gnus-bug} command when you make bug reports, even if it creates
+a 10Kb mail each time you use it, and even if you have sent me your
+environment 500 times before. I don't care. I want the full info each
+time.
+
+It is also important to remember that I have no memory whatsoever. If
+you send a bug report, and I send you a reply, and then you send back
+just "No, it's not! Moron!", I will have no idea what you are insulting
+me about. Always overexplain everything. It's much easier for all of
+us---if I don't have all the information I need, I will just mail you
+and ask for more info, and everything takes more time.
If you just need help, you are better off asking on
-@samp{gnu.emacs.gnus}.
+@samp{gnu.emacs.gnus}. I'm not very helpful.
+
+
+@node The End
+@chapter The End
+
+Well, that's the manual---you can get on with your life now. Keep in
+touch. Say hello to your cats from me.
+
+My @strong{ghod}---I just can't stand goodbyes. Sniffle.
+
+Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
+
+@quotation
+@strong{Te Deum}
+@sp 1
+Not because of victories @*
+I sing,@*
+having none,@*
+but for the common sunshine,@*
+the breeze,@*
+the largess of the spring.
+@sp 1
+Not for victory@*
+but for the day's work done@*
+as well as I was able;@*
+not for a seat upon the dais@*
+but at the common table.@*
+@end quotation
+
+@node Appendices
+@chapter Appendices
+
+@menu
+* A Programmer's Guide to Gnus:: Rilly, rilly technical stuff.
+* Emacs for Heathens:: A short intruduction to Emacsian terms.
+* Frequently Asked Questions:: A question-and-answer session.
+@end menu
+
+
+@node A Programmer's Guide to Gnus
+@section A Programmer's Guide to Gnus
+
+It is my hope that other people will figure out smart stuff that Gnus
+can do, and that other people will write those smart things as well. To
+facilitate that I thought it would be a good idea to describe the inner
+workings of Gnus. And some of the not-so-inner workings, while I'm at
+it.
+
+You can never expect the internals of a program not to change, but I
+will be defining (in some details) the interface between Gnus and its
+backends (this is written in stone), the format of the score files
+(ditto), data structures (some are less likely to change than others)
+and general method of operations.
+
+@menu
+* Backend Interface:: How Gnus communicates with the servers.
+* Score File Syntax:: A BNF definition of the score file standard.
+* Headers:: How Gnus stores headers internally.
+* Ranges:: A handy format for storing mucho numbers.
+* Group Info:: The group info format.
+@end menu
+
+
+@node Backend Interface
+@subsection Backend Interface
+
+Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
+groups. It only knows how to talk to @dfn{virtual servers}. A virtual
+server is a @dfn{backend} and some @dfn{backend variables}. As examples
+of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
+examples of the latter we have @code{nntp-port-number} and
+@code{nnmbox-directory}.
+
+When Gnus asks for information from a backend---say @code{nntp}---on
+something, it will normally include a virtual server name in the
+function parameters. (If not, the backend should use the "current"
+virtual server.) For instance, @code{nntp-request-list} takes a virtual
+server as its only (optional) parameter. If this virtual server hasn't
+been opened, the function should fail.
+
+Note that a virtual server name has no relation to some physical server
+name. Take this example:
+
+@lisp
+(nntp "odd-one"
+ (nntp-address "ifi.uio.no")
+ (nntp-port-number 4324))
+@end lisp
+
+Here the virtual server name is @samp{"odd-one"} while the name of
+the physical server is @samp{"ifi.uio.no"}.
+
+The backends should be able to switch between several virtual servers.
+The standard backends implement this by keeping an alist of virtual
+server environments that it pulls down/pushes up when needed.
+
+There are two groups of interface functions: @dfn{required functions},
+which must be present, and @dfn{optional functions}, which Gnus will
+always check whether are present before attempting to call.
+
+All these functions are expected to return data in the buffer
+@code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
+unfortunately named, but we'll have to live with it. When I talk about
+"resulting data", I always refer to the data in that buffer. When I
+talk about "return value", I talk about the function value returned by
+the function call.
+
+Some backends could be said to be @dfn{server-forming} backends, and
+some might be said to not be. The latter are backends that generally
+only operate on one group at a time, and have no concept of "server" --
+they have a group, and they deliver info on that group and nothing more.
+
+In the examples and definitions I will refer to the imaginary backend
+@code{nnchoke}.
+
+@cindex @code{nnchoke}
+
+@menu
+* Required Backend Functions:: Functions that must be implemented.
+* Optional Backend Functions:: Functions that need not be implemented.
+@end menu
+
+
+@node Required Backend Functions
+@subsubsection Required Backend Functions
+
+@table @code
+
+@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
+
+@var{articles} is either a range of article numbers or a list of
+@code{Message-ID}s. Current backends do not fully support either---only
+sequences (lists) of article numbers, and most backends do not support
+retrieval of @code{Message-ID}s. But they should try for both.
+
+The result data should either be HEADs or NOV lines, and the result
+value should either be @code{headers} or @code{nov} to reflect this.
+This might later be expanded to @code{various}, which will be a mixture
+of HEADs and NOV lines, but this is currently not supported by Gnus.
+
+If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
+headers, in some meaning of the word. This is generally done by
+fetching (at most) @var{fetch-old} extra headers less than the smallest
+article number in @code{articles}, and fill in the gaps as well. The
+presence of this parameter can be ignored if the backend finds it
+cumbersome to follow the request. If this is non-@code{nil} and not a
+number, do maximum fetches.
+
+Here's an example HEAD:
+
+@example
+221 1056 Article retrieved.
+Path: ifi.uio.no!sturles
+From: sturles@@ifi.uio.no (Sturle Sunde)
+Newsgroups: ifi.discussion
+Subject: Re: Something very droll
+Date: 27 Oct 1994 14:02:57 +0100
+Organization: Dept. of Informatics, University of Oslo, Norway
+Lines: 26
+Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
+References: <38jdmq$4qu@@visbur.ifi.uio.no>
+NNTP-Posting-Host: holmenkollen.ifi.uio.no
+.
+@end example
+
+So a @code{headers} return value would imply that there's a number of
+these in the data buffer.
+
+Here's a BNF definition of such a buffer:
+
+@example
+headers = *head
+head = error / valid-head
+error-message = [ "4" / "5" ] 2number " " <error message> eol
+valid-head = valid-message *header "." eol
+valid-message = "221 " <number> " Article retrieved." eol
+header = <text> eol
+@end example
+
+If the return value is @code{nov}, the data buffer should contain
+@dfn{network overview database} lines. These are basically fields
+separated by tabs.
+
+@example
+nov-buffer = *nov-line
+nov-line = 8*9 [ field <TAB> ] eol
+field = <text except TAB>
+@end example
+
+For a closer explanation what should be in those fields,
+@xref{Headers}.
+
+
+@item (nnchoke-open-server SERVER &optional DEFINITIONS)
+
+@var{server} is here the virtual server name. @var{definitions} is a
+list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
+
+If the server can't be opened, no error should be signaled. The backend
+may then choose to refuse further attempts at connecting to this
+server. In fact, it should do so.
+
+If the server is opened already, this function should return a
+non-@code{nil} value. There should be no data returned.
+
+
+@item (nnchoke-close-server &optional SERVER)
+
+Close connection to @var{server} and free all resources connected
+to it.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-close)
+
+Close connection to all servers and free all resources that the backend
+have reserved. All buffers that have been created by that backend
+should be killed. (Not the @code{nntp-server-buffer}, though.)
+
+There should be no data returned.
+
+
+@item (nnchoke-server-opened &optional SERVER)
+
+This function should return whether @var{server} is opened, and that the
+connection to it is still alive. This function should under no
+circumstances attempt to reconnect to a server that is has lost
+connection to.
+
+There should be no data returned.
+
+
+@item (nnchoke-status-message &optional SERVER)
+
+This function should return the last error message from @var{server}.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
+
+The result data from this function should be the article specified by
+@var{article}. This might either be a @code{Message-ID} or a number.
+It is optional whether to implement retrieval by @code{Message-ID}, but
+it would be nice if that were possible.
+
+If @var{to-buffer} is non-@code{nil}, the result data should be returned
+in this buffer instead of the normal data buffer. This is to make it
+possible to avoid copying large amounts of data from one buffer to
+another, and Gnus mainly request articles to be inserted directly into
+its article buffer.
+
+
+@item (nnchoke-open-group GROUP &optional SERVER)
+
+Make @var{group} the current group.
+
+There should be no data returned by this function.
+
+
+@item (nnchoke-request-group GROUP &optional SERVER)
+
+Get data on @var{group}. This function also has the side effect of
+making @var{group} the current group.
+
+Here's an example of some result data and a definition of the same:
+
+@example
+211 56 1000 1059 ifi.discussion
+@end example
+
+The first number is the status, which should be @samp{211}. Next is the
+total number of articles in the group, the lowest article number, the
+highest article number, and finally the group name. Note that the total
+number of articles may be less than one might think while just
+considering the highest and lowest article numbers, but some articles
+may have been cancelled. Gnus just discards the total-number, so
+whether one should take the bother to generate it properly (if that is a
+problem) is left as an excercise to the reader.
+
+@example
+group-status = [ error / info ] eol
+error = [ "4" / "5" ] 2<number> " " <Error message>
+info = "211 " 3* [ <number> " " ] <string>
+@end example
+
+
+@item (nnchoke-close-group GROUP &optional SERVER)
+
+Close @var{group} and free any resources connected to it. This will be
+a no-op on most backends.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-list &optional SERVER)
+
+Return a list of all groups available on @var{server}. And that means
+@emph{all}.
+
+Here's an example from a server that only carries two groups:
+
+@example
+ifi.test 0000002200 0000002000 y
+ifi.discussion 3324 3300 n
+@end example
+
+On each line we have a group name, then the highest article number in
+that group, the lowest article number, and finally a flag.
+
+@example
+active-file = *active-line
+active-line = name " " <number> " " <number> " " flags eol
+name = <string>
+flags = "n" / "y" / "m" / "x" / "j" / "=" name
+@end example
+
+The flag says whether the group is read-only (@samp{n}), is moderated
+(@samp{m}), is dead (@samp{x}), is aliased to some other group
+(@samp{=other-group} or none of the above (@samp{y}).
+
+
+@item (nnchoke-request-post &optional SERVER)
+
+This function should post the current buffer. It might return whether
+the posting was successful or not, but that's not required. If, for
+instance, the posting is done asynchronously, it has generally not been
+completed by the time this function concludes. In that case, this
+function should set up some kind of sentinel to beep the user loud and
+clear if the posting could not be completed.
+
+There should be no result data from this function.
+
+
+@item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
+
+This function should return a buffer suitable for composing an article
+to be posted by @code{nnchoke-request-post}. If @var{post} is
+non-@code{nil}, this is not a followup, but a totally new article.
+@var{group} is the name of the group to be posted to. @var{subject} is
+the subject of the message. @var{article-buffer} is the buffer being
+followed up, if that is the case. @var{info} is the group info.
+@var{follow-to} is the group that one is supposed to re-direct the
+article ot. If @var{respect-poster} is non-@code{nil}, the special
+@samp{"poster"} value of a @code{Followup-To} header is to be respected.
+
+There should be no result data returned.
+
+@end table
+
+@node Optional Backend Functions
+@subsubsection Optional Backend Functions
+
+@table @code
+
+@item (nnchoke-retrieve-groups GROUPS &optional SERVER)
+
+@var{groups} is a list of groups, and this function should request data
+on all those groups. How it does it is of no concern to Gnus, but it
+should attempt to do this in a speedy fashion.
+
+The return value of this function can be either @code{active} or
+@code{group}, which says what the format of the result data is. The
+former is in the same format as the data from
+@code{nnchoke-request-list}, while the latter is a buffer full of lines
+in the same format as @code{nnchoke-request-group} gives.
+
+@example
+group-buffer = *active-line / *group-status
+@end example
+
+
+@item (nnchoke-request-update-info GROUP INFO &optional SERVER)
+
+A Gnus group info (@pxref{Group Info}) is handed to the backend for
+alterations. This comes in handy if the backend really carries all the
+information (as is the case with virtual an imap groups). This function
+may alter the info in any manner it sees fit, and should return the
+(altered) group info. This function may alter the group info
+destructively, so no copying is needed before boogying.
+
+There should be no result data from this function.
+
+
+@item (nnchoke-request-scan &optional GROUP SERVER)
+
+This function may be called at any time (by Gnus or anything else) to
+request that the backend check for incoming articles, in one way or
+another. A mail backend will typically read the spool file or query the
+POP server when this function is invoked. The @var{group} doesn't have
+to be heeded---if the backend decides that it is too much work just
+scanning for a single group, it may do a total scan of all groups. It
+would be nice, however, to keep things local if that's practical.
+
+There should be no result data from this function.
+
+
+@item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
+
+This is a request to fetch articles asynchronously later.
+@var{articles} is an alist of @var{(article-number line-number)}. One
+would generally expect that if one later fetches article number 4, for
+instance, some sort of asynchronous fetching of the articles after 4
+(which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
+alist) would be fetched asynchronouly, but that is left up to the
+backend. Gnus doesn't care.
+
+There should be no result data from this function.
+
+
+@item (nnchoke-request-group-description GROUP &optional SERVER)
+
+The result data from this function should be a description of
+@var{group}.
+
+@example
+description-line = name <TAB> description eol
+name = <string>
+description = <text>
+@end example
+
+@item (nnchoke-request-list-newsgroups &optional SERVER)
+
+The result data from this function should be the description of all
+groups available on the server.
+
+@example
+description-buffer = *description-line
+@end example
+
+
+@item (nnchoke-request-newgroups DATE &optional SERVER)
+
+The result data from this function should be all groups that were
+created after @samp{date}, which is in normal human-readable date
+format. The data should be in the active buffer format.
+
+
+@item (nnchoke-request-create-groups GROUP &optional SERVER)
+
+This function should create an empty group with name @var{group}.
+
+There should be no return data.
+
+
+@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
+
+This function should run the expiry process on all articles in the
+@var{articles} range (which is currently a simple list of article
+numbers.) It is left up to the backend to decide how old articles
+should be before they are removed by this function. If @var{force} is
+non-@code{nil}, all @var{articles} should be deleted, no matter how new
+they are.
+
+This function should return a list of articles that it did not/was not
+able to delete.
+
+There should be no result data returned.
+
+
+@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
+&optional LAST)
+
+This function should move @var{article} (which is a number) from
+@var{group} by calling @var{accept-form}.
+
+This function should ready the article in question for moving by
+removing any header lines it has added to the article, and generally
+should "tidy up" the article. Then it should @code{eval}
+@var{accept-form} in the buffer where the "tidy" article is. This will
+do the actual copying. If this @code{eval} returns a non-@code{nil}
+value, the article should be removed.
+
+If @var{last} is @code{nil}, that means that there is a high likelihood
+that there will be more requests issued shortly, so that allows some
+optimizations.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-accept-article GROUP &optional LAST)
+
+This function takes the current buffer and inserts it into @var{group}.
+If @var{last} in @code{nil}, that means that there will be more calls to
+this function in short order.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
+
+This function should remove @var{article} (which is a number) from
+@var{group} and insert @var{buffer} there instead.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
+
+This function should delete @var{group}. If @var{force}, it should
+really delete all the articles in the group, and then delete the group
+itself. (If there is such a thing as "the group itself".)
+
+There should be no data returned.
+
+
+@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
+
+This function should rename @var{group} into @var{new-name}. All
+articles that are in @var{group} should move to @var{new-name}.
+
+There should be no data returned.
+
+
+@end table
+
+
+@node Score File Syntax
+@subsection Score File Syntax
+
+Score files are meant to be easily parsable, but yet extremely
+mallable. It was decided that something that had the same read syntax
+as an Emacs Lisp list would fit that spec.
+
+Here's a typical score file:
+
+@lisp
+(("summary"
+ ("win95" -10000 nil s)
+ ("Gnus"))
+ ("from"
+ ("Lars" -1000))
+ (mark -100))
+@end lisp
+
+BNF definition of a score file:
+
+@example
+score-file = "" / "(" *element ")"
+element = rule / atom
+rule = string-rule / number-rule / date-rule
+string-rule = "(" quote string-header quote space *string-match ")"
+number-rule = "(" quote number-header quote space *number-match ")"
+date-rule = "(" quote date-header quote space *date-match ")"
+quote = <ascii 34>
+string-header = "subject" / "from" / "references" / "message-id" /
+ "xref" / "body" / "head" / "all" / "followup"
+number-header = "lines" / "chars"
+date-header = "date"
+string-match = "(" quote <string> quote [ "" / [ space score [ "" /
+ space date [ "" / [ space string-match-t ] ] ] ] ] ")"
+score = "nil" / <integer>
+date = "nil" / <natural number>
+string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
+ "r" / "regex" / "R" / "Regex" /
+ "e" / "exact" / "E" / "Exact" /
+ "f" / "fuzzy" / "F" / "Fuzzy"
+number-match = "(" <integer> [ "" / [ space score [ "" /
+ space date [ "" / [ space number-match-t ] ] ] ] ] ")"
+number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
+date-match = "(" quote <string> quote [ "" / [ space score [ "" /
+ space date [ "" / [ space date-match-t ] ] ] ] ")"
+date-match-t = "nil" / "at" / "before" / "after"
+atom = "(" [ required-atom / optional-atom ] ")"
+required-atom = mark / expunge / mark-and-expunge / files /
+ exclude-files / read-only / touched
+optional-atom = adapt / local / eval
+mark = "mark" space nil-or-number
+nil-or-number = "nil" / <integer>
+expunge = "expunge" space nil-or-number
+mark-and-expunge = "mark-and-expunge" space nil-or-number
+files = "files" *[ space <string> ]
+exclude-files = "exclude-files" *[ space <string> ]
+read-only = "read-only" [ space "nil" / space "t" ]
+adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
+adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
+local = "local" *[ space "(" <string> space <form> ")" ]
+eval = "eval" space <form>
+space = *[ " " / <TAB> / <NEWLINE> ]
+@end example
+
+Any unrecognized elements in a score file should be ignored, but not
+discarded.
+
+As you can see, white space is needed, but the type and amount of white
+space is irrelevant. This means that formatting of the score file is
+left up to the programmer---if it's simpler to just spew it all out on
+one looong line, then that's ok.
+
+The meaning of the various atoms are explained elsewhere in this
+manual.
+
+@node Headers
+@subsection Headers
+
+Gnus uses internally a format for storing article headers that
+corresponds to the @sc{nov} format in a mysterious fashion. One could
+almost suspect that the author looked at the @sc{nov} specification and
+just shamelessly @emph{stole} the entire thing, and one would be right.
+
+@dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
+to talk about lines in the head of an article (eg., @code{From}). It is
+used by many people as a synonym for "head"---"the header and the
+body". (That should be avoided, in my opinion.) And Gnus uses a format
+interanally that it calls "header", which is what I'm talking about
+here. This is a 9-element vector, basically, with each header (ouch)
+having one slot.
+
+These slots are, in order: @code{number}, @code{subject}, @code{from},
+@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
+@code{xref}. There are macros for accessing and setting these slots --
+they all have predicatable names beginning with @code{mail-header-} and
+@code{mail-header-set-}, respectively.
+
+The @code{xref} slot is really a @code{misc} slot. Any extra info will
+be put in there.
+
+@node Ranges
+@subsection Ranges
+
+@sc{gnus} introduced a concept that I found so useful that I've started
+using it a lot and have elaborated on it greatly.
+
+The question is simple: If you have a large amount of objects that are
+identified by numbers (say, articles, to take a @emph{wild} example)
+that you want to callify as being "included", a normal sequence isn't
+very useful. (A 200,000 length sequence is a bit long-winded.)
+
+The solution is as simple as the question: You just collapse the
+sequence.
+
+@example
+(1 2 3 4 5 6 10 11 12)
+@end example
+
+is transformed into
+
+@example
+((1 . 6) (10 . 12))
+@end example
+
+To avoid having those nasty @samp{(13 . 13)} elements to denote a
+lonesome object, a @samp{13} is a valid element:
+
+@example
+((1 . 6) 7 (10 . 12))
+@end example
+
+This means that comparing two ranges to find out whether they are equal
+is slightly tricky:
+
+@example
+((1 . 6) 7 8 (10 . 12))
+@end example
+
+and
+
+@example
+((1 . 5) (7 . 8) (10 . 12))
+@end example
+
+are equal. In fact, any non-descending list is a range:
+
+@example
+(1 2 3 4 5)
+@end example
+
+is a perfectly valid range, although a pretty longwinded one. This is
+also legal:
+
+@example
+(1 . 5)
+@end example
+
+and is equal to the previous range.
+
+Here's a BNF definition of ranges. Of course, one must remember the
+semantic requirement that the numbers are non-descending. (Any number
+of repetition of the same number is allowed, but apt to disappear in
+range handling.)
+
+@example
+range = simple-range / normal-range
+simple-range = "(" number " . " number ")"
+normal-range = "(" start-contents ")"
+contents = "" / simple-range *[ " " contents ] /
+ number *[ " " contents ]
+@end example
+
+Gnus currently uses ranges to keep track of read articles and article
+marks. I plan on implementing a number of range operators in C if The
+Powers That Be are willing to let me. (I haven't asked yet, because I
+need to do some more thinking on what operators I need to make life
+totally range-based without ever having to convert back to normal
+sequences.)
+
+
+@node Group Info
+@subsection Group Info
+
+Gnus stores all permanent info on groups in a @dfn{group info} list.
+This list is from three to six elements (or more) long and exhaustively
+describes the group.
+
+Here are two example group infos; one is a very simple group while the
+second is a more complex one:
+
+@example
+("no.group" 5 (1 . 54324))
+
+("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
+ ((tick (15 . 19)) (replied 3 6 (19 . 23)))
+ (nnml "")
+ (auto-expire (to-address "ding@@ifi.uio.no")))
+@end example
+
+The first element is the group name as Gnus knows the group; the second
+is the group level; the third is the read articles in range format; the
+fourth is a list of article marks lists; the fifth is the select method;
+and the sixth contains the group parameters.
+
+Here's a BNF definition of the group info format:
+
+@example
+info = "(" group space level space read
+ [ "" / [ space marks-list [ "" / [ space method [ "" /
+ space parameters ] ] ] ] ] ")"
+group = quote <string> quote
+level = <integer in the range of 1 to inf>
+read = range
+marks-lists = nil / "(" *marks ")"
+marks = "(" <string> range ")"
+method = "(" <string> *elisp-forms ")"
+parameters = "(" *elisp-forms ")"
+@end example
+
+Actually that @samp{marks} rule is a fib. A @samp{marks} is a
+@samp{<string>} consed on to a @samp{range}, but that's a bitch to say
+in pseudo-BNF.
+
+
+@node Emacs for Heathens
+@section Emacs for Heathens
+
+Believe it or not, but some people who use Gnus haven't really used
+Emacs much before they embarked on their journey on the Gnus Love Boat.
+If you are one of those unfortunates whom "@kbd{M-C-a}", "kill the
+region", and "set @code{gnus-flargblossen} to an alist where the key is
+a regexp that is used for matching on the group name" are magical
+phrases with little or no meaning, then this appendix is for you. If
+you are already familiar with Emacs, just ignore this and go fondle your
+cat instead.
+
+@menu
+* Keystrokes:: Entering text and executing commands.
+* Emacs Lisp:: The built-in Emacs programming language.
+@end menu
+
+
+@node Keystrokes
+@subsection Keystrokes
+
+@itemize @bullet
+@item
+Q: What is an experienced Emacs user?
+@item
+A: A person who wishes that the terminal had pedals.
+@end itemize
+
+Yes, when you use Emacs, you are apt to use the control key, the shift
+key and the meta key a lot. This is very annoying to some people
+(notably @code{vi}le users), and the rest of us just love the hell out
+of it. Just give up and submit. Emacs really does stand for
+"Escape-Meta-Alt-Control-Shift", and not "Editin Macros", as you may
+have heard from other disreputable sources (like the Emacs author).
+
+The shift key is normally located near your pinky fingers, and are
+normally used to get capital letters and stuff. You probably use it all
+the time. The control key is normally marked "CTRL" or something like
+that. The meta key is, funnily enough, never marked as such on any
+keyboards. The one I'm curretly at has a key that's marked "Alt", which
+is the meta key on this keyboard. It's usually located somewhere to the
+left hand side of the keyboard, usually on the bottom row.
+
+Now, us Emacs people doesn't say "press the meta-control-m key", because
+that's just too inconvenient. We say "press the @kbd{M-C-m} key".
+@kbd{M-} is the prefix that means "meta" and "C-" is the prefix that
+means "control". So "press @kbd{C-k}" means "press down the control
+key, and hold it down while you press @kbd{k}". "Press @kbd{M-C-k}"
+means "press down and hold down the meta key and the control key and
+then press @kbd{k}". Simple, ay?
+
+This is somewhat complicated by the fact that not all keyboards have a
+meta key. In that case you can use the "escape" key. Then @kbd{M-k}
+means "press escape, release escape, press @kbd{k}". That's much more
+work than if you have a meta key, so if that's the case, I respectfully
+suggest you get a real keyboard with a meta key. You can't live without
+it.
+
+
+
+@node Emacs Lisp
+@subsection Emacs Lisp
+
+Emacs is the King of Editors because it's really a Lisp interpreter.
+Each and every key you tap runs some Emacs Lisp code snippet, and since
+Emacs Lisp is an interpreted language, that means that you can configure
+any key to run any random code. You just, like, do it.
+
+Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
+functions. (These are byte-compiled for speed, but it's still
+interpreted.) If you decide that you don't like the way Gnus does
+certain things, it's trivial to have it do something a different way.
+(Well, at least if you know how to write Lisp code.) However, that's
+beyond the scope of this manual, so we are simply going to talk about
+some common constructs that you normally use in your @file{.emacs} file
+to customize Gnus.
+
+If you want to set the variable @code{gnus-florgbnize} to four (4), you
+write the following:
+
+@lisp
+(setq gnus-florgbnize 4)
+@end lisp
+
+This function (really "special form") @code{setq} is the one that can
+set a variable to some value. This is really all you need to know. Now
+you can go and fill your @code{.emacs} file with lots of these to change
+how Gnus works.
+
+If you have put that thing in your @code{.emacs} file, it will be read
+and @code{eval}ed (which is lispese for "run") the next time you start
+Emacs. If you want to change the variable right away, simply say
+@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
+previous "form", which here is a simple @code{setq} statement.
+
+Go ahead---just try it, if you're located at your Emacs. After you
+@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
+is the return value of the form you @code{eval}ed.
+
+Some pitfalls:
+
+If the manual says "set @code{gnus-read-active-file} to @code{some}",
+that means:
+
+@lisp
+(setq gnus-read-active-file 'some)
+@end lisp
+
+On the other hand, if the manual says "set @code{gnus-nntp-server} to
+@samp{"nntp.ifi.uio.no"}", that means:
+
+@lisp
+(setq gnus-nntp-server "nntp.ifi.uio.no")
+@end lisp
+
+So be careful not to mix up strings (the latter) with symbols (the
+former). The manual is unambiguous, but it can be confusing.
+
+
+
+@node Frequently Asked Questions
+@section Frequently Asked Questions
+
+
@node Index
@chapter Index
@c Local Variables:
@c outline-regexp: "@chap\\|@\\(sub\\)*section\\|@appendix \\|@appendix\\(sub\\)*sec\\|\^L"
@c End:
+
+\1f
projects / gnus / blobdiff