\input texinfo @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
-@setfilename gnus
-@settitle (ding) Gnus 0.84 Manual
+@setfilename gnus.info
+@settitle September Gnus Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
into another language, under the above conditions for modified versions.
@end ifinfo
+@iftex
+
@titlepage
-@title (ding) Gnus Manual
+@title September Gnus Manual
@author by Lars Magne Ingebrigtsen
@page
@end titlepage
@page
+@end iftex
+
@node Top
@top The Gnus Newsreader
* 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.
-* The End:: Farewell, and goodbye.
+* The End:: Farewell and goodbye.
+* Appendix:: Technical stuff for technical people.
* Index:: Variable, function and concept index.
* Key Index:: Key Index.
@end menu
@sc{gnus} was written by Masanobu UMEDA. When autumn crept up in '94,
Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
-The recommended pronunciation of the name this program is "ding
-guh-noose", with "ding" being half-sung in a loud, high-pitched voice,
-and "guh-noose" being grumbled and a disaffected fashion. Any
-irritation and/or damage this name may cause you is not the
-responsibility of the author, even though you might like to strangle him
-for the stupid idea.
-
If you want to investigate the person responsible for this outrage, you
can point your (feh!) web browser to
@file{http://www.ifi.uio.no/~larsi/}. This is also the primary
distribution point for the new and spiffy versions of Gnus, also know as
The Site That Destroys Newsrcs And Drives People Mad.
-@dfn{(ding)}, is, of course, short for @dfn{ding is not Gnus}, which is
-a total and utter lie, but who cares? (Besides, the "Gnus" in this
-abbreviation should probably be pronounced "news" as UMEDA intended,
-which makes it a more appropriate name, don't you think?)
+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?)
+
+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.
+
+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 @sc{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.
-* Gnus & hilit:: Old hilit19 code will not work with (ding) Gnus.
-* New Features:: A short description of all the new stuff in Gnus.
+* 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
@cindex compatibility
-(ding) Gnus was designed to be fully compatible with @sc{gnus}. Almost
-all key bindings have been kept. More key bindings have been added, of
-course, but only in one or two obscure cases have old bindings been
-changed.
+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
(@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.
+These are faster and more accurate. To make life easier for everybody,
+Gnus will by default remove all hilit calls from all hilit hooks.
+Uncleanliness! Away!
Packages like @code{expire-kill} will no longer work. As a matter of
fact, you should probably remove all old @sc{gnus} packages (and other
-code) when you start using (ding) Gnus. More likely than not, (ding)
-Gnus already does what you have written code to make @sc{gnus} do.
-(Snicker.)
+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 @sc{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
@sc{gnus} internals should suffer no problems. If problems occur,
please let me know (@kbd{M-x gnus-bug}).
-Problems specific to GNU XEmacs can be reported to popineau@@ese-metz.fr
-(Fabrice Popineau). I will just forward any such questions to him,
-anyway, so you might have to wait longer if you mail XEmacs questions to
-me.
+
+@node Conformity
+@section Conformity
+
+No rebels without a clue here, ma'am. We conform to all standards known
+to man. Except, of course, where we disagree with the standards and/or
+conventions.
+
+@table @strong
+
+@item RFC 822
+There are no known breaches to this standard.
+
+@item RFC 1036
+There are no known breaches to 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 that 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 does line breaking on this header. 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 article 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
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
@item
Kevin Davidson came up with the name @dfn{ding}, so blame him.
@item
-Stainless Steel Rat, Jack Vinson, Daniel Quinlan, Ilja Weis, Frank D. Cringle
- and Andrew Eskilsson have all contributed code and suggestions.
+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
-@node Gnus & hilit
-@section Gnus & hilit
-@cindex hilit
-
-@c Written by Sudish Joseph
-
-@code{gnus-visual} can be used to highlight the summary buffer. It
-offers far more flexibility than hilit (since it has access to more
-data; eg. the article score) in deciding how to highlight a given
-article. Also, hilit gets confused by the way Gnus manipulates the
-summary buffer, leading to errors. Such errors may be detected by
-looking for any hilit-specific functions in the @code{*Backtrace*}
-buffer. If such a reference exists, you should be using the code below.
-
-You can also get @code{gnus-visual} to highlight the article buffer, so
-you should get rid of all hilit-specific Gnus calls.
-
-Add the code below to your @file{.gnus} file to remove all the hilit
-crud:
-
-@lisp
-(add-hook 'gnus-startup-hook
- '(lambda ()
- ;; gnus-visual is far better for summary highlighting
- ;; also, hilit cannot handle a (ding) summary and will
- ;; crash on you
- (remove-hook 'gnus-summary-prepare-hook
- 'hilit-rehighlight-buffer-quietly)
- (remove-hook 'gnus-summary-prepare-hook 'hilit-install-line-hooks)
- (setq gnus-mark-article-hook '(gnus-summary-mark-unread-as-read))
- ;; this is too early for the purpose of highlighting
- (remove-hook 'gnus-article-prepare-hook
- 'hilit-rehighlight-buffer-quietly)
- ;; use this instead. note that the final t is *essential*,
- ;; this must be the last thing done
- (add-hook 'gnus-article-display-hook
- 'gnus-article-highlight t)))
-@end lisp
-
-
@node New Features
@section New Features
@cindex new features
-The look of all buffers can be changed by setting format-like variables.
+@itemize @bullet
+
+@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 @sc{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
+(@code{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.
+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.
+@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.
+entire active file just to check for new articles in a few groups
+(@pxref{The Active File}).
+
+@item
+Gnus implements a sliding scale of subscribedness to groups
+(@pxref{Group Levels}).
+
+@item
+You can score articles according to any number of criteria
+(@pxref{Scoring}). You can even get Gnus 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 to and descriptions of groups (@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
+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
-Gnus implements a sliding scale of subscribedness to groups.
+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.
-The approach to killing has been changed. Instead of simply killing or
-not, you can score articles for easier reading.
@node Newest Features
@section Newest Features
@cindex todo
Also known as the @dfn{todo list}. Sure to be implemented before the
-next millennium.
+next millennium.
+
+Be afraid. Be very afraid.
@itemize @bullet
@item
Native @sc{mime} support is something that should be done. I was hoping
I could steal code from @code{Mew}, the @sc{mime} mail reader for Emacs,
-but I'm not quite sure what the status of that project is. (ding) might
+but I'm not quite sure what the status of that project is. Gnus might
support @sc{mime} quite soon, and it might not.
+
+@item
+@code{trn}-like trees.
+@item
+@code{nn}-like pick-and-read summary interface.
+@item
+NoCeM support.
+@item
+Frame configuration.
+@item
+Re-sending bounced mail and rejected articles.
+@item
+Floating point group levels and group bubbling.
+@item
+@file{/etc/nntpserver} usage.
+@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
+Slave Gnusii to enable several Gnusii to run at once.
+@item
+PGP support.
+@item
+Allow posting through mail-to-news gateways.
+@item
+Allow renaming mail groups in a simple fashion.
+@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
+Fetching by Message-ID should work in mail groups.
+@item
+Listing of all active groups.
+@item
+XEmacs toolbar.
@item
-When the user references the parent of an article, some sort of
-re-threading should be done to build a proper tree. The same goes for
-article expunging. However, as it stands, it's not a trivial issue to
-re-generate parts of the summary buffer. Generating the entire buffer
-is very easy, but slow.
+Do the X-Receipt-To thing.
+@item
+Hierarchal group buffers.
+@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?)
+
+You can probably sneak a look at the actual up-to-the-second todo list
+by snooping @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>}.
+
@node Terminology
@chapter Terminology
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
* Finding the News:: Choosing a method for getting news.
* The First Time:: What does Gnus do the first time you start it?
* The Server is Down:: How can I read my mail then?
+* 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}.
* Auto Save:: Recovering from a crash.
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 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 @sc{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
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 uses 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{Master} 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 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 only information 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 presedence.)
+
+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
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 really never want to see any new groups,
you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
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.
+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
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 the @file{.newsrc} file by setting
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
If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
maintain a dribble buffer.
+@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
If this variable is @code{nil}, Gnus will as for group info in total
lock-step, which isn't very fast. If it is @code{some} and you use an
-NNTP server, Gnus will pump out commands as fast as it can, and read all
-the replies in one swoop. This will normally result in better
+@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.
+@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.
@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 a single 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-@code{nil}, Gnus will check for and delete all bogus groups at
bogus groups isn't very quick, so to save time and resources, it's best
to leave this option off, and instead do the checking for bogus groups
once in a while from the group buffer (@pxref{Group Maintenance}).
+
@item gnus-inhibit-startup-message
@vindex gnus-inhibit-startup-message
If non-@code{nil}, the startup message won't be displayed. That way,
your boss might not notice that you are reading news instead of doing
your job.
+
@item gnus-no-groups-message
@vindex gnus-no-groups-message
Message displayed by Gnus when no groups are available.
* 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
into the buffer just like information from any other specifier.
@end table
+@cindex *
+All the "number-of" specs will be filled with an asterisk (@samp{*}) if
+no info is available - for instance, if it is a non-activated foreign
+group, or a bogus (or semi-bogus) native group.
+
@vindex gnus-group-mode-line-format
The mode line can be changed by setting
(@code{gnus-group-mode-line-format}). It doesn't understand that many
@cindex group selection
@table @kbd
+
@item SPACE
@kindex SPACE (Group)
@findex gnus-group-read-group
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
@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
have arrived most recently will be fetched.
@vindex gnus-select-group-hook
-@vindex gnus-auto-select-newsgroup
-If @code{gnus-auto-select-newsgroup} is non-@code{nil}, the first unread
+@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 @code{nil} in
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.
+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
@table @kbd
@item #
@kindex # (Group)
-@item G m
-@kindex G m (Group)
+@item 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)
-@item G u
-@kindex G u (Group)
+@item < u
+@kindex M u (Group)
@findex gnus-group-unmark-group
Remove the mark from the current group
(@code{gnus-group-unmark-group}).
-@item G w
-@kindex G w (Group)
+@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
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
@item G h
@kindex G h (Group)
@findex gnus-group-make-help-group
-Make the (ding) Gnus help group (@code{gnus-group-make-help-group}).
+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
-Make the (ding) Gnus archive group
-(@code{gnus-group-make-archive-group}). The archive group will be
-fetched from @code{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)
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
+actuallt 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
@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.
This hook is run as the last step when connecting to an @sc{nntp}
server.
-@findex nntp-open-rlogin
-@findex nntp-open-network-stream
-@item nntp-open-server-function
-@vindex nntp-open-server-function
-This function is used to connect to the remote system. Two pre-made
-functions are @code{nntp-open-network-stream}, which is the default, and
-simply connects to some port or other on the remote system. The other
-is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
-and then does a telnet to the @sc{nntp} server available there.
-
-@item nntp-rlogin-parameters
-@vindex nntp-rlogin-parameters
-If you use @code{nntp-open-rlogin} as the
-@code{nntp-open-server-function}, this list will be used as the
-parameter list given to @code{rsh}.
-
-@item nntp-rlogin-user-name
-@vindex nntp-rlogin-user-name
-User name on the remote system when using the @code{rlogin} connect
-function.
+@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
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
In addition to this regexp detailing component groups, an nnkiboze group
must have a score file to say what articles that are to be included in
-the group (@pxref{Score Files}).
+the group (@pxref{Scoring}).
@kindex M-x nnkiboze-generate-groups
@findex nnkiboze-generate-groups
Reading mail with a newsreader - isn't that just plain WeIrD? But of
course.
+Gnus will read the mail spool when you activate a mail group. The mail
+file is first copied to your home directory. What happens after that
+depends on what format you want to store your mail in.
+
@menu
* Creating Mail Groups:: How to create mail groups.
* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
* Mail & Procmail:: Reading mail groups that procmail create.
* Expiring Old Mail Articles:: Getting rid of unwanted mail.
* Not Reading Mail:: Using mail backends for reading other files.
-@end menu
-
-Gnus will read the mail spool when you activate a mail group. The mail
-file is first copied to your home directory. What happens after that
-depends on what format you want to store your mail in.
-
-@menu
-* nnmbox:: Using the (quite) standard Un*x mbox.
-* nnbabyl:: Many Emacs programs use the rmail babyl format.
-* nnml:: Store your mail in a private spool?
-* nnmh:: An mhspool-like backend useful for procmail people.
-* nnfolder:: Having one file for each group.
+* 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
Set this variable to begin with the string @samp{po:}, and everything
should go smoothly, even though I have never tested this.
-If this variable is @code{procmail}, 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-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 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
the incoming mail in, append @code{nnmail-procmail-suffix} to the group
name. The mail backends will read the mail from these files.
-@vindex nnail-resplit-incoming
+@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{nnail-resplit-incoming} to @code{t}.
+@code{nnmail-resplit-incoming} to @code{t}.
+
+@vindex nnmail-keep-last-article
+If you use @code{procmail} to split things directory into an 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
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.
+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!
-Note that at present, Gnus will not actually delete any expirable
-articles automatically. You have to enter one of the expiry functions
-(eg. `C-c M-c-x' in the group buffer) to actually run articles through
-the expiry process. Or you can add a call to the expiry function in the
-group exit hook. Gnus will probably do all this automatically in the
-future.
@node Not Reading Mail
@subsubsection Not Reading Mail
@vindex nnbabyl-active-file
@vindex nnbabyl-mbox-file
-The @dfn{nnbabyl} backend will use a babyl mail box to store mail.
-@code{nnbabyl} will add extra headers to each mail article to say which
-group it belongs in.
+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:
In fact, the vast majority of groups will normally only have the first
three elements, which saves quite a lot of cons cells.
-At present, there's not much you can put in the group parameters list:
+The group parameters stores information local to a particular group:
@table @code
@item to-address
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 parameters (or anything else of the
-group info) you can use the @kbd{G E} to edit enter a buffer where you
-can edit the group info.
+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.
These commands all list various slices of the groups that are available.
@table @kbd
+
@item l
@itemx A s
@kindex A s (Group)
(@code{gnus-group-list-groups}). If the numeric prefix is used, this
command will list only groups of level ARG and lower. By default, it
only lists groups of level five or lower (i.e., just subscribed groups).
+
@item L
@itemx A u
@kindex A u (Group)
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 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
@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
-@findex gnus-group-sort-by-level
-@findex gnus-group-sort-by-unread
-@findex gnus-group-sort-by-alphabet
@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
-@code{gnus-group-sort-by-alphabet} (the default),
-@code{gnus-group-sort-by-unread} and @code{gnus-group-sort-by-level}.
+(@code{gnus-group-sort-groups}). Available sorting functions include:
+
+@table @code
+
+@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-alphabet
+@findex gnus-group-sort-by-alphabet
+Sort the group names alphabetically. This is the default.
+
+@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
@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
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 geniouses 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}.
+
+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
+
+
@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 server 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
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. ange-ftp will be used for fetching the file.
+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
* Paging the Article:: Scrolling the current article.
* Reply Followup and Post:: Posting articles.
* Canceling and Superseding:: "Whoops, I shouldn't have called him that."
-* Ticking and Marking:: Marking articles as read, expirable, etc.
+* 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.
* 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
Full @code{From} line.
@item n
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).
+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.
@item c
@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
@table @samp
@item G
Group name.
+@item p
+Unprefixed group name.
@item A
Current article number.
@item V
Used-defined spec.
@item s
Name of the current score file.
-@end table
-
-
-@node Summary Maneuvering
-@section Summary Maneuvering
+@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 Maneuvering
+@section Summary Maneuvering
@cindex summary movement
All the straight movement commands understand the numeric prefix and
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. Also @xref{Group Levels}.
+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
@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
@findex gnus-summary-scroll-up
Scroll the current article one line forward
(@code{gnus-summary-scroll-up}).
+
@item A <
@itemx <
@kindex < (Summary)
@findex gnus-summary-beginning-of-article
Scroll to the beginning of the article
(@code{gnus-summary-beginning-of-article}).
+
@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
* Mail:: Mailing & replying.
* Post:: Posting and following up.
* Mail & Post:: Mailing and posting at the same time.
+* Drafts:: Postponing messages and rejected messages.
+* Rejected Articles:: What happens if the server doesn't like your article?
@end menu
@node Mail
@findex gnus-summary-mail-other-window
Send a mail to some other person
(@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
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
+@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.
+
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}.
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-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
@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
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 neither @code{nil} nor @code{t}, always use the Followup-To
-value.
+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 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
@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 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
@item gnus-user-from-line
@vindex gnus-user-from-line
-Your full, complete e-mail address. This variable overrides the other
-Gnus variables if it is non-@code{nil}.
+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, but the name
-has to be quoted if it contains non-alpha-numerical characters -
-@samp{"\"Lars M. Ingebrigtsen\" <larsi@@ifi.uio.no>"}.
+<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 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).
+
@end table
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 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 subscribed to.
+
+@findex gnus-summary-send-draft
+@kindex S D c
+When you want to continue editing, 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.
+
+
+@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 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 in it, doesn't care about how much cited text you
+include, never runs full and never goes down.) So what Gnus does is
+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
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.
All the following marks mark articles as read.
@table @samp
-@item D
-Articles that are marked as read. They have a @samp{D}
+@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 d
-Articles that are actually read are marked with @samp{d}
+@item R
+Articles that are actually read are marked with @samp{R}
(@code{gnus-read-mark}).
-@item A
+@item O
Articles that were marked as read in previous sessions are now
-@dfn{ancient} and marked with @samp{A} (@code{gnus-ancient-mark}).
+@dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
@item K
Marked as killed (@code{gnus-killed-mark}).
@item X
in the article, and Gnus will jump to this bookmark the next time it
encounters the article.
-All articles that you have replied to or made a followup to will be
-marked with an @samp{R} in the second column (@code{gnus-replied-mark}).
+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
@item M C
@kindex M C (Summary)
@findex gnus-summary-catchup
-Catchup the current group (@code{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
-Catchup all articles in the current group (@code{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
@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)
@findex gnus-summary-remove-bookmark
Remove the bookmark from the current article
(@code{gnus-summary-remove-bookmark}).
-@item M M-r
-@itemx x
-@kindex M M-r (Summary)
-@kindex M-d (Summary)
-@findex gnus-summary-remove-lines-marked-as-read
-Expunge all deleted articles from the summary buffer
-(@code{gnus-summary-remove-lines-marked-as-read}).
-@item M M-C-r
-@kindex M M-C-r (Summary)
-@findex gnus-summary-remove-lines-marked-with
-Ask for a mark and then expunge all articles that have been marked with
-that mark (@code{gnus-summary-remove-lines-marked-with}).
-@item M S
-@kindex M S (Summary)
-@findex gnus-summary-show-all-expunged
-Display all expunged articles (@code{gnus-summary-show-all-expunged}).
-@item M D
-@kindex M D (Summary)
-@findex gnus-summary-show-all-dormant
-Display all dormant articles (@code{gnus-summary-show-all-dormant}).
-@item M M-D
-@kindex M M-D (Summary)
-@findex gnus-summary-hide-all-dormant
-Hide all dormant articles (@code{gnus-summary-hide-all-dormant}).
-@item M s k
-@kindex M s 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 s c
-@kindex M s c (Summary)
+@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 s u
-@kindex M s u (Summary)
+@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 s m
-@kindex M s m (Summary)
+@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
the next/previous unread article. If @code{nil}, point will just move
one line up or down.
+
@node Setting Process Marks
@subsection Setting Process Marks
@cindex setting process marks
@table @kbd
-@item M p p
+@item M P p
@itemx #
@kindex # (Summary)
-@kindex M p p (Summary)
+@kindex M P p (Summary)
@findex gnus-summary-mark-as-processable
Mark the current article with the process mark
(@code{gnus-summary-mark-as-processable}).
@findex gnus-summary-unmark-as-processable
-@item M p u
+@item M P u
@itemx M-#
-@kindex M p u (Summary)
+@kindex M P u (Summary)
@kindex M-# (Summary)
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)
+@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-processable}).
-@item M p R
-@kindex M p R (Summary)
+@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 M p r
-@kindex M p r (Summary)
+@item M P r
+@kindex M P r (Summary)
@findex gnus-uu-mark-region
Mark articles in region (@code{gnus-uu-mark-region}).
-@item M p t
-@kindex M p t (Summary)
+@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 s
-@kindex M p s (Summary)
+@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)
+@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)
+@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 M N u
+@itemx x
+@kindex M N 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 N m
+@kindex M N 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 M N n
+@kindex M N 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 M N w
+@kindex M N 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 M N s
+@itemx /
+@kindex M N 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 M N v
+@kindex M N 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 M S
+@kindex M S (Summary)
+@findex gnus-summary-show-all-expunged
+Display all expunged articles (@code{gnus-summary-show-all-expunged}).
+
+@item M N D
+@kindex M N D (Summary)
+@findex gnus-summary-limit-include-dormant
+Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
+
+@item M N d
+@kindex M N d (Summary)
+@findex gnus-summary-limit-exclude-dormant
+Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
+
+@item M N c
+@kindex M N 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
+
@node Threading
@section Threading
@cindex threading
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-@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}. In either case, fetching old headers only works if the
-select method you are using supports @sc{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.
+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
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
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.
+square brackets (@samp{[]}). This is the default method.
@item dummy
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
@vindex gnus-thread-hide-subtree
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-@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-@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 that says how much each sub-thread should be indented.
@cindex thread commands
@table @kbd
+
@item T k
@itemx M-C-k
@kindex T k (Summary)
(@code{gnus-summary-kill-thread}). If the prefix argument is positive,
remove all marks instead. If the prefix argument is negative, tick
articles instead.
+
@item T l
@itemx M-C-l
@kindex T 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
-Mark the current thread with the process mark
+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 threading (@code{gnus-summary-toggle-threads}).
+
@item T s
@kindex T s (Summary)
@findex gnus-summary-show-thread
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
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 way
+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.
+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.
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 Exiting the Summary Buffer
@section Exiting the Summary Buffer
@kindex Z Z (Summary)
@kindex q (Summary)
@findex gnus-summary-exit
+@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-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)
unwanted headers before saving the article.
@table @kbd
+
@item O o
@itemx o
@kindex O o (Summary)
@findex gnus-summary-save-article
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-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
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}).
+(@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
functions below, or you can create your own.
@table @code
+
@item gnus-summary-save-in-rmail
-@vindex gnus-summary-save-in-rmail
+@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
-@vindex 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
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
* 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
All these functions use the process/prefix convention
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 Variables:: Variables for a happy decoding.
-* Viewing Files:: You want to look at the result of the decoding?
-@end menu
-
@node Uuencoded Articles
@subsection Uuencoded Articles
@cindex uudecode
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}
+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}).
@emph{virtual newsgroup} from the @emph{virtual server}; and you think:
Why isn't anything real anymore? How did we get here?
-@node Various Article Stuff
-@section Various Article Stuff
+
+@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 H a
+@kindex W H a
+@findex gnus-article-highlight
+Highlight the current article (@code{gnus-article-highlight}).
+
+@item W H h
+@kindex W H h
+@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
+@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
+@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 A w
-@kindex A w (Summary)
+
+@item W l
+@kindex W l (Summary)
@findex gnus-summary-stop-page-breaking
Remove page breaks from the current article
(@code{gnus-summary-stop-page-breaking}).
-@item A s
-@kindex A s (Summary)
-@findex gnus-summary-isearch-article
-Perform an isearch in the article buffer
-(@code{gnus-summary-isearch-article}).
-@item A c
-@kindex A c (Summary)
+
+@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 A g
@kindex A g (Summary)
@findex gnus-summary-show-article
-Select the current article (@code{gnus-summary-show-article}).
-@item A t
-@kindex A 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 A m
-@kindex A m (Summary)
+
+@item W m
+@kindex W m (Summary)
@findex gnus-summary-toggle-mime
Toggle whether to run the article through @sc{mime} before displaying
(@code{gnus-summary-toggle-mime}).
-@end table
-There's a battery of commands for washing the article buffer:
-
-@table @kbd
-@item W h
-@kindex W h (Summary)
-@findex gnus-article-hide-headers
-Hide headers (@code{gnus-article-hide-headers}).
-@item W s
-@kindex W s (Summary)
-@findex gnus-article-hide-signature
-Hide signature (@code{gnus-article-hide-signature}).
-@item W c
-@kindex W c (Summary)
-@findex gnus-article-hide-citation
-Hide citation (@code{gnus-article-hide-citation}).
@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 d
-@kindex W d (Summary)
+
+@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
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
can't really see why you'd want that.
@table @kbd
-@item V s n
-@kindex V s n (Summary)
+@item C-c C-s C-n
+@kindex C-c C-s C-n (Summary)
@findex gnus-summary-sort-by-number
Sort by article number (@code{gnus-summary-sort-by-number}).
-@item V s a
-@kindex V s a (Summary)
+@item C-c C-s C-a
+@kindex C-c C-s C-a (Summary)
@findex gnus-summary-sort-by-author
Sort by author (@code{gnus-summary-sort-by-author}).
-@item V s s
-@kindex V s s (Summary)
+@item C-c C-s C-s
+@kindex C-c C-s C-s (Summary)
@findex gnus-summary-sort-by-subject
Sort by subject (@code{gnus-summary-sort-by-subject}).
-@item V s d
-@kindex V s d (Summary)
+@item C-c C-s C-d
+@kindex C-c C-s C-d (Summary)
@findex gnus-summary-sort-by-date
Sort by date (@code{gnus-summary-sort-by-date}).
-@item V s i
-@kindex V s i (Summary)
+@item C-c C-s C-i
+@kindex C-c C-s C-i (Summary)
@findex gnus-summary-sort-by-score
-Sort by date (@code{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
toggle whether to use threading, type @kbd{T T} (@pxref{Thread
Commands}).
+
@node Finding the Parent
@section Finding the Parent
@cindex parent articles
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 @sc{nntp} server for an arbitrary article, no
-matter what group it belongs to. @kbd{V r}
+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
as the one that keeps the spool you are reading from updated, but that's
not really necessary.
-@node Score Files
-@section Score Files
-@cindex score files
+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.
-Other people use @dfn{kill files}, but we here at (ding) 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}).
-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.
+@node Mail Group Commands
+@section Mail Group Commands
+@cindex mail group commands
-Gnus will read any @dfn{score files} that apply to the current group
-before generating the summary buffer.
+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.
-There are several commands in the summary buffer that inserts 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.
+All these commands (except the expiry and edit commands) use the
+process/prefix convention (@pxref{Process/Prefix}).
-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.
+@table @kbd
+@item B e
+@kindex B e (Summary)
+@findex gnus-summary-expire-articles
+Expire all expirable articles in the group
+(@code{gnus-summary-expire-articles}).
-@menu
-* Summary Score Commands:: Adding score commands to the score file.
-* 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
+@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.
-@node Summary Score Commands
-@subsection Summary Score Commands
-@cindex score commands
+@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
+disk forever and ever, never to return again." Use with caution.
+(@code{gnus-summary-delete-article}).
-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.
+@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}).
-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.
+@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}).
-General score commands that don't actually change the score file:
+@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.
-@table @kbd
-@item V S s
-@kindex V S s (Summary)
-@findex gnus-summary-set-score
-Set the score of the current article (@code{gnus-summary-set-score}).
-@item V S S
-@kindex V S S (Summary)
-@findex gnus-summary-current-score
-Display the score of the current article
-(@code{gnus-summary-current-score}).
-@item V S t
-@kindex V S 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 S a
-@kindex V S a (Summary)
-@findex gnus-summary-score-entry
-Add a new score entry, and allow specifying all elements
-(@code{gnus-summary-score-entry}).
-@item V S c
-@kindex V S c (Summary)
-@findex gnus-score-change-score-file
-Make a different score file the current
-(@code{gnus-score-change-score-file}).
-@item V S e
-@kindex V S 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 S f
-@kindex V S 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 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
+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.
-The rest of these commands modify the local score file.
+@item B r
+@kindex B r (Summary)
+@findex gnus-summary-respool-article
+Respool the mail article (@code{gnus-summary-move-article}).
-@table @kbd
-@item V S m
-@kindex V S 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 S E
-@kindex V S 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}).
+@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
-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.)
+@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
-@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 b
-Score on the body.
-@item h
-Score on the head.
+@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}). 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 H i
+@kindex H i (Summary)
+@findex gnus-info-find-node
+Go to the Gnus info node (@code{gnus-info-find-node}).
@end table
-@item
-The third key is the match type.
+@node Searching for Articles
+@subsection Searching for Articles
+
@table @kbd
-@item e
-Exact matching.
-@item s
-Substring matching.
-@item f
-Fuzzy matching.
-@item r
-Regexp matching
+@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
-@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.
+@node Really Various Summary Commands
+@subsection Really Various Summary Commands
+
@table @kbd
-@item t
-Temporary score entry.
-@item p
-Permanent score entry.
-@item i
-Immediately scoring.
+@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
-@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.
+@node The Article Buffer
+@chapter The Article Buffer
+@cindex article buffer
-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}.
+The articles are displayed in the article buffer, of which there is only
+one. All the summary buffer share the same article buffer.
-@vindex gnus-score-mimic-keymap
-The @code{gnus-score-mimic-keymap} says whether these commands will
-pretend they are keymaps or not.
+@menu
+* Hiding Headers:: Deciding what headers should be displayed.
+* 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.
+@end menu
-@node Score Variables
-@subsection Score Variables
-@cindex score variables
+@node Hiding Headers
+@section Hiding Headers
+@cindex hiding headers
+@cindex deleting headers
-@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.
-@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.
-@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.
-@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-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.
+The top section of each article is the @dfn{head}. (The rest is the
+@dfn{body}, but you may have guessed that already.)
-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. 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.
-@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-kill-expiry-days
-@vindex gnus-kill-expiry-days
-This variable says how many days should pass before an unused score file
-entry is expired. The default is 7.
-@end table
+@vindex gnus-show-all-headers
+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}.
-@node Score File Format
-@subsection Score File Format
-@cindex score file format
+Gnus provides you with two variables for sifting headers:
-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.
+@table @code
+@item gnus-visible-headers
+@vindex gnus-visible-headers
+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.
-Anyway, if you'd like to dig into it yourself, here's an example:
+For instance, if you only want to see the name of the person who wrote
+the article and the subject, you'd say:
@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")
- (local (gnus-newsgroup-auto-expire t)
- (gnus-summary-make-false-root 'empty))
- (eval (ding)))
+(setq gnus-visible-headers "^From:\\|^Subject:")
@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.
+@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 @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.
-Six keys are supported by this alist:
+For instance, if you just want to get rid of the @code{References} line
+and the @code{Xref} line, you might say:
-@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}.
+@lisp
+(setq gnus-ignored-headers "^References:\\|^Xref:")
+@end lisp
-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.
-@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.
+Note that if @code{gnus-visible-headers} is non-@code{nil}, this
+variable will have no effect.
@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 albeit
-strange, way of setting variables in some groups, and you don't like
-hooks much.
-@end table
+@vindex gnus-sorted-header-list
+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 headers are to be displayed.
-@node Score File Editing
-@subsection Score File Editing
+For instance, if you want the name of the author of the article first,
+and then the subject, you might say something like:
-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.
+@lisp
+(setq gnus-sorted-header-list '("^From:" "^Subject:"))
+@end lisp
-It's simply a slightly customized @code{emacs-lisp} mode, with these
-additional commands:
+Any headers that are to remain visible, but are not listed in this
+variable, will be displayed in random order after all the headers that
+are listed in this variable.
-@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 Using Mime
+@section Using Mime
+@cindex @sc{mime}
-@node Adaptive Scoring
-@subsection Adaptive Scoring
-@cindex adaptive scoring
+Mime is a standard for waving your hands through the air, aimlessly,
+while people stand around yawning.
-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.
+@sc{mime}, however, is a standard for encoding your articles, aimlessly,
+while all newsreaders die of fear.
-@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}.
+@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-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:
+@vindex gnus-show-mime
+@vindex gnus-show-mime-method
+Gnus handles @sc{mime} by shoving the articles through
+@code{gnus-show-mime-method}, which is @code{metamail-buffer} by
+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.)
-@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
+Any similarity to real events and people is purely coincidental. Ahem.
-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.
+@node Customizing Articles
+@section Customizing Articles
+@cindex article customization
-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.
+@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.
-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.
+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 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.
+You can, of course, write your own functions. The functions are called
+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.
-@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.
-@vindex gnus-score-exact-adapt-limit
-When doing adaptive scoring, substring 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}, which it is by
-default, exact matching will always be used to avoid this problem.
+@node Article Keymap
+@section Article Keymap
-@node Scoring Tips
-@subsection Scoring Tips
-@cindex scoring tips
+@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.
-@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" (" +[^ ]+:[0-9]+ +[^ ]+:[0-9]+ +[^ ]+:[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}.
+A few additional keystrokes are available:
+
+@table @kbd
+@item SPACE
+@kindex SPACE (Article)
+@findex gnus-article-next-page
+Scroll forwards one page (@code{gnus-article-next-page}).
+@item DEL
+@kindex DEL (Article)
+@findex gnus-article-prev-page
+Scroll backwards one page (@code{gnus-article-prev-page}).
+@item C-c ^
+@kindex C-c ^ (Article)
+@findex gnus-article-refer-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}). If
+given a prefix, include the mail.
+@item s
+@kindex s (Article)
+@findex gnus-article-show-summary
+Reconfigure the buffers so that the summary buffer becomes visible
+(@code{gnus-article-show-summary}).
+@item ?
+@kindex ? (Article)
+@findex gnus-article-describe-briefly
+Give a very brief description of the available keystrokes
+(@code{gnus-article-describe-briefly}).
@end table
-@node Reverse Scoring
-@subsection Reverse Scoring
-@cindex reverse scoring
+@node Misc Article
+@section Misc Article
-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:
+@table @code
+@vindex gnus-article-prepare-hook
+@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
+@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
+@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
+This is the delimiter mentioned above. By default, it is @samp{^L}
+(form linefeed).
+@end table
-@lisp
-(("subject"
- ("Sex with Emacs" 2))
- (mark 1)
- (expunge 1))
-@end lisp
+@node The Server Buffer
+@chapter The Server Buffer
-So, you raise all articles that match @samp{Sex with Emacs} and mark the
-rest as read, and expunge them to boot.
+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.
-@node Global Score Files
-@subsection Global Score Files
-@cindex global score files
+For instance, the @code{nntp} backend may be used to connect to several
+different actual nntp servers, or, perhaps, to many different ports on
+the same actual nntp server. You tell Gnus which backend to use, and
+what parameters to set by specifying a @dfn{select method}.
-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!
+These select methods specifications can sometimes become quite
+complicated - say, for instance, that you want to read from the 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.
-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!
+To enter the server buffer, user the @kbd{^}
+(@code{gnus-group-enter-server-mode}) command in the group buffer.
-@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.
+@menu
+* 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.
+@end menu
-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}:
+@node Server Buffer Format
+@section Server Buffer Format
+@cindex server buffer format
-@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
+@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:
-@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.
+@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
-Note that, at present, using this option will slow down group entry
-somewhat. (That is - a lot.)
+@node Server Commands
+@section Server Commands
+@cindex server commands
-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!
+@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
-Here are some tips for the would-be retro-moderator, off the top of my
-head:
+@node Example Methods
+@section Example Methods
-@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
+Most select methods are pretty simple and self-explanatory:
-... 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?
+@lisp
+(nntp "news.funet.fi")
+@end lisp
-@node Kill Files
-@subsection Kill Files
-@cindex kill files
+Reading directly from the spool is even simpler:
-(ding) Gnus still supports those pesky old kill files. In fact, the
-kill file entries can now be expiring, which is something I wrote before
-Per thought of doing score files, so I've left the code in there.
+@lisp
+(nnspool "")
+@end lisp
-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.
+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.
-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.
+After these two elements, there may be a random number of @var{(variable
+form)} pairs.
-Normal kill files look like this:
+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
-(gnus-kill "From" "Lars Ingebrigtsen")
-(gnus-kill "Subject" "ding")
-(gnus-expunge "X")
+(nntp "news.funet.fi" (nntp-port-number 15))
@end lisp
-This will mark every article written by me as read, and remove them from
-the summary buffer. Very useful, you'll agree.
+You should read the documentation to each backend to find out what
+variables are relevant, but here's an @code{nnmh} example.
-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.
+@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:
-Two functions for editing a GNUS kill file:
+@lisp
+(nnmh "private" (nnmh-directory "~/private/mail/"))
+@end lisp
-@table @kbd
-@item V k
-@kindex V k (Summary)
-@findex gnus-summary-edit-local-kill
-Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
+(This server is then called @samp{private}, but you may have guessed
+that.
-@item V K
-@kindex V K (Summary)
-@findex gnus-summary-edit-global-kill
-Edit the general kill file (@code{gnus-summary-edit-global-kill}).
-@end table
+Here's the method for the public spool:
-@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}.
+@lisp
+(nnmh "public"
+ (nnmh-directory "/usr/information/spool/")
+ (nnmh-get-new-mail nil))
+@end lisp
+@node Servers & Methods
+@section Servers & Methods
-@node Mail Group Commands
-@section Mail Group Commands
-@cindex mail group commands
+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.
-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}).
+@node Scoring
+@chapter Scoring
+@cindex scoring
-@table @kbd
-@item B e
-@kindex B e (Summary)
-@findex gnus-summary-expire-articles
-Expire all expirable articles in the group
-(@code{gnus-summary-expire-articles}).
+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!
-@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
-disk forever and ever, never to return again." Use with caution.
-(@code{gnus-summary-delete-article}).
+@vindex gnus-summary-mark-below
+All articles have a default score (@code{gnus-summary-default-score}).
+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.
-@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}).
+Gnus will read any @dfn{score files} that apply to the current group
+before generating the summary buffer.
-@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}).
+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.
-@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.
+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.
-@item B r
-@kindex B r (Summary)
-@findex gnus-summary-respool-article
-Respool the mail article (@code{gnus-summary-move-article}).
+@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
-@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}).
+@node Summary Score Commands
+@section Summary Score Commands
+@cindex score commands
-@item B q
-@kindex B q (Summary)
-@findex gnus-summary-fancy-query
-If you are using fancy splitting, this command will tell you where an
-article would go (@code{gnus-summary-fancy-query}).
-@end table
+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.
-@node Various Summary Stuff
-@section Various Summary Stuff
+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.
-@menu
-* Group Information:: Information oriented commands.
-* Searching for Articles:: Multiple article commands.
-* Really Various Summary Commands:: Those pesky non-conformant commands.
-@end menu
+General score commands that don't actually change the score file:
-@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.
+@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}).
-@node Group Information
-@subsection Group Information
+@item V S
+@kindex V S (Summary)
+@findex gnus-summary-current-score
+Display the score of the current article
+(@code{gnus-summary-current-score}).
-@table @kbd
-@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. @code{ange-ftp} 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}). 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 H i
-@kindex H i (Summary)
-@findex gnus-info-find-node
-Go to the Gnus info node (@code{gnus-info-find-node}).
+@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
-@node Searching for Articles
-@subsection Searching for Articles
+The rest of these commands modify the local score file.
@table @kbd
-@item V C-s
-@kindex V C-s (Summary)
-@findex gnus-summary-search-article-forward
-Search through all subsequent articles for a regexp
-(@code{gnus-summary-search-article-forward}).
-@item V C-r
-@kindex V C-r (Summary)
-@findex gnus-summary-search-article-backward
-Search through all previous articles for a regexp
-(@code{gnus-summary-search-article-backward}).
-@item V &
-@kindex V & (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 V u
-@kindex V u (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}).
+@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
-@node Really Various Summary Commands
-@subsection Really Various Summary Commands
+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 V D
-@kindex V 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 V T
-@kindex V T (Summary)
-@findex gnus-summary-toggle-truncation
-Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
-@item V e
-@kindex V e (Summary)
-@findex gnus-summary-expand-window
-Expand the summary buffer window (@code{gnus-summary-expand-window}).
+@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.
+
+@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.
+
+@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.
+
+@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-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. 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")
+ (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.
+@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 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 @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.
-@end menu
-
-@node Hiding Headers
-@section Hiding Headers
-@cindex hiding headers
-@cindex deleting headers
-
-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 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 headers:
-
-@table @code
-@item gnus-visible-headers
-@vindex gnus-visible-headers
-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:
+@node Score File Editing
+@section Score File Editing
-@lisp
-(setq gnus-visible-headers "^From:\\|^Subject:")
-@end lisp
+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.
-@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 @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.
+It's simply a slightly customized @code{emacs-lisp} mode, with these
+additional commands:
-For instance, if you just want to get rid of the @code{References} line
-and the @code{Xref} line, you might say:
+@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
-@lisp
-(setq gnus-ignored-headers "^References:\\|^Xref:")
-@end lisp
+@node Adaptive Scoring
+@section Adaptive Scoring
+@cindex adaptive scoring
-Note that if @code{gnus-visible-headers} is non-@code{nil}, this
-variable will have no effect.
-@end table
+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-sorted-header-list
-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 headers are to be displayed.
+@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}.
-For instance, if you want the name of the author of the article first,
-and then the subject, you might say something like:
+@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
-(setq gnus-sorted-header-list '("^From:" "^Subject:"))
+(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
-Any headers that are to remain visible, but are not listed in this
-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.
-
-@sc{mime}, however, is a standard for encoding your articles, aimlessly,
-while all newsreaders die of fear.
-
-@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 @sc{mime} by shoving the articles through
-@code{gnus-show-mime-method}, which is @code{metamail-buffer} by
-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.
+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.
-@findex gnus-article-subcite
-@findex gnus-article-hide-signature
-@findex gnus-article-hide-citation
-Other useful functions you might add to this hook is:
+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.
-@table @code
-@item gnus-article-hide-citation
-Hide all cited text.
-@item gnus-article-hide-signature
-Umn, hides the signature.
-@item gnus-article-treat-overstrike
-Treat @samp{^H_} in a reasonable manner.
-@item gnus-article-maybe-highlight
-Do fancy article highlighting.
-@item gnus-article-remove-cr
-Removes trailing carriage returns.
-@item gnus-article-de-quoted-unreadable
-Do naive decoding of articles encoded with Quoted-Printable.
-@item gnus-article-display-x-face
-Displays any X-Face headers.
-@end table
+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.
-You can, of course, write your own functions. The functions are called
-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.
+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.
-@node Article Keymap
-@section Article Keymap
+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.
-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 while reading. You can do it all from the article
-buffer.
+@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.
-A few additional keystrokes are available:
+@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.
-@table @kbd
-@item SPACE
-@kindex SPACE (Article)
-@findex gnus-article-next-page
-Scroll forwards one page (@code{gnus-article-next-page}).
-@item DEL
-@kindex DEL (Article)
-@findex gnus-article-prev-page
-Scroll backwards one page (@code{gnus-article-prev-page}).
-@item C-c ^
-@kindex C-c ^ (Article)
-@findex gnus-article-refer-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-c C-M
-@kindex C-c C-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}).
-@item s
-@kindex s (Article)
-@findex gnus-article-show-summary
-Reconfigure the buffers so that the summary buffer becomes visible
-(@code{gnus-article-show-summary}).
-@item ?
-@kindex ? (Article)
-@findex gnus-article-describe-briefly
-Give a very brief description of the available keystrokes
-(@code{gnus-article-describe-briefly}).
-@end table
+@node Scoring Tips
+@section Scoring Tips
+@cindex scoring tips
-@node Misc Article
-@section Misc Article
+@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" (" +[^ ]+:[0-9]+ +[^ ]+:[0-9]+ +[^ ]+:[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}.
-@table @code
-@vindex gnus-article-prepare-hook
-@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
-@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
-@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
-This is the delimiter mentioned above. By default, it is @samp{^L}
-(form linefeed).
+@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 The Server Buffer
-@chapter The Server Buffer
+@node Reverse Scoring
+@section Reverse Scoring
+@cindex reverse scoring
-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.
+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:
-For instance, the @code{nntp} backend may be used to connect to several
-different actual nntp servers, or, perhaps, to many different ports on
-the same actual nntp server. You tell Gnus which backend to use, and
-what parameters to set by specifying a @dfn{select method}.
+@lisp
+(("subject"
+ ("Sex with Emacs" 2))
+ (mark 1)
+ (expunge 1))
+@end lisp
-These select methods specifications can sometimes become quite
-complicated - say, for instance, that you want to read from the 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.
+So, you raise all articles that match @samp{Sex with Emacs} and mark the
+rest as read, and expunge them to boot.
-@menu
-* 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.
-@end menu
+@node Global Score Files
+@section Global Score Files
+@cindex global score files
-@node Server Buffer Format
-@section Server Buffer Format
-@cindex server buffer format
+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!
-@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:
+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!
-@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
+@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.
-@node Server Commands
-@section Server Commands
-@cindex server commands
+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}:
-@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
+@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
-@node Example Methods
-@section Example Methods
+@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.
-Most select methods are pretty simple and self-explanatory:
+Note that, at present, using this option will slow down group entry
+somewhat. (That is - a lot.)
-@lisp
-(nntp "news.funet.fi")
-@end lisp
+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!
-Reading directly from the spool is even simpler:
+Here are some tips for the would-be retro-moderator, off the top of my
+head:
-@lisp
-(nnspool "")
-@end lisp
+@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
-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.
+... 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?
-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:
+@node Kill Files
+@section Kill Files
+@cindex kill files
-@lisp
-(nntp "news.funet.fi" (nntp-port-number 15))
-@end lisp
+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.
-You should read the documentation to each backend to find out what
-variables are relevant, but here's an @code{nnmh} example.
+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.
-@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:
+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
-(nnmh "private" (nnmh-directory "~/private/mail/"))
+(gnus-kill "From" "Lars Ingebrigtsen")
+(gnus-kill "Subject" "ding")
+(gnus-expunge "X")
@end lisp
-(This server is then called @samp{private}, but you may have guessed
-that.
+This will mark every article written by me as read, and remove them from
+the summary buffer. Very useful, you'll agree.
-Here's the method for the public spool:
+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.
-@lisp
-(nnmh "public"
- (nnmh-directory "/usr/information/spool/")
- (nnmh-get-new-mail nil))
-@end lisp
+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 Servers & Methods
-@section Servers & Methods
@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{followup}, @code{followup-yank}, @code{edit-score}.
@findex gnus-add-configuration
Since this variable is so long and complicated, there's a function you
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
@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
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 @sc{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
@chapter Troubleshooting
@cindex troubleshooting
-(ding) Gnus works @emph{so} well straight out of the box - I can't
-imagine any problems, really.
+Gnus works @emph{so} well straight out of the box - I can't imagine any
+problems, really.
Ahem.
Gnus will work.
@item
Try doing an @kbd{M-x gnus-version}. If you get something that looks
-like @samp{(ding) Gnus v0.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.
+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.
@kindex M-x gnus-bug
@findex gnus-bug
-If you find a bug in (ding) 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.
+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.
@c If you just need help, you are better off asking on
@c @samp{gnu.emacs.gnus}.
but at the common table.@*
@end quotation
+@node Appendix
+@chapter 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
+@section Backend Interface
+
+Gnus doesn't know anything about 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 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
+@subsection 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
+@subsection 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
+@section 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
+@section 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
+@section 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
+@section 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 Index
@chapter Index
@printindex cp
projects / gnus / blobdiff