*** empty log message ***

[gnus] / texi / gnus.texi

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

@ifinfo

This file documents Gnus, the GNU Emacs newsreader.

Copyright (C) 1995 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

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

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@iftex

@titlepage
@title Gnus Manual

@author by Lars Magne Ingebrigtsen
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995 Free Software Foundation, Inc. 

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.

Cover art by Etienne Suvasa.
@end titlepage
@page

@end iftex

@node Top
@top The Gnus Newsreader

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

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

@node History
@chapter History

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

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

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

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
* Why?::                What's the point of Gnus?
* Compatibility::       Just how compatible is Gnus with @sc{gnus}?
* Conformity::          Gnus tries to conform to all standards.
* Contributors::        Oodles of people.  
* New Features::        Pointers to some of the new stuff in Gnus.
* Newest Features::     Features so new that they haven't been written yet.
@end menu

@node Why?
@section Why?

What's the point of Gnus?  

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

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

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

@node Compatibility
@section Compatibility

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

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

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

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

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

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

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

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

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

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 Contributors
@section Contributors
@cindex contributors

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

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

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


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

@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}). 
 
@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
(@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
(@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{Score
Files}).  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