\input texinfo @c -*-texinfo-*-
-@setfilename gnus.info
-@settitle September Gnus Manual
+@setfilename gnus
+@settitle Red Gnus 0.51 Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@iflatex
\documentclass[twoside,a4paper,openright]{book}
\usepackage[latin1]{inputenc}
-% \usepackage{fontenc}
-% \usepackage{babel}
\usepackage{pagestyle}
\usepackage{epsfig}
-% \usepackage{ifitricks}
\fontfamily{bembo}\selectfont
\makeindex
\newcommand{\gnushash}{\#}
\newcommand{\gnushat}{\symbol{"5E}}
\newcommand{\gnusunderline}{\symbol{"5F}}
+\newcommand{\gnusnot}{$\neg$}
\newcommand{\gnustilde}{\symbol{"7E}}
\newcommand{\gnusless}{{$<$}}
\newcommand{\gnusgreater}{{$>$}}
\marginpar[\hspace{2.5cm}\gnushead]{\gnushead}
}
-\newcommand{\gnuschapter}[1]{
+\newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi}
+
+\newcommand{\gnuspagechapter}[1]{
+{\mbox{}}
+}
+
+\newdimen{\gnusdimen}
+\gnusdimen 0pt
+
+\newcommand{\gnuschapter}[2]{
+\gnuscleardoublepage
+\ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi
+\chapter{#2}
\renewcommand{\gnussectionname}{}
-\chapter{#1}
-\renewcommand{\gnuschaptername}{#1}
+\renewcommand{\gnuschaptername}{#2}
\thispagestyle{empty}
-% \epsfig{figure=gnus-herd-\arabic{chapter}.eps,height=15cm}
+\hspace*{-2cm}
+\begin{picture}(500,500)(0,0)
+\put(0,0){\makebox(480,350)[tr]{#1}}
+\put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}}
+\end{picture}
\clearpage
}
-\newcommand{\gnusitemx}[1]{\vspace{-\itemsep}\item#1}
+\newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1}
\newcommand{\gnussection}[1]{
\renewcommand{\gnussectionname}{#1}
}
}{\end{list}}
+\newlength\gnusheadtextwidth
+\setlength{\gnusheadtextwidth}{\headtextwidth}
+\addtolength{\gnusheadtextwidth}{1cm}
+
+\newpagestyle{gnuspreamble}%
+{
+{
+\ifodd\count0
+{
+\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}}
+}
+\else
+{
+\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}}
+}
+}
+\fi
+}
+}
+{
+\ifodd\count0
+\mbox{} \hfill
+\raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
+\else
+\raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
+\hfill \mbox{}
+\fi
+}
+
+\newpagestyle{gnusindex}%
+{
+{
+\ifodd\count0
+{
+\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}}
+}
+\else
+{
+\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}
+}
+\fi
+}
+}
+{
+\ifodd\count0
+\mbox{} \hfill
+\raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
+\else
+\raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
+\hfill \mbox{}
+\fi
+}
+
\newpagestyle{gnus}%
{
{
\ifodd\count0
{
-\hspace*{-2ex}
-\underline{
-\makebox[\headtextwidth]{
-\hspace*{-2.3ex}
-\textbf{\arabic{chapter}.\arabic{section}}
-\textbf{\gnussectionname\hfill\arabic{page}}
-}}
+\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}
}
\else
{
-\hspace*{-2.25cm}
-\underline{
-\hspace*{-2.3ex}
-\makebox[\headtextwidth]{
-\textbf{\arabic{page}\hfill\gnuschaptername}
-}}
+\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}
}
\fi
}
\hfill \mbox{}
\fi
}
-\pagestyle{gnus}
+
+\pagenumbering{roman}
+\pagestyle{gnuspreamble}
@end iflatex
@end iftex
\thispagestyle{empty}
-Copyright \copyright{} 1995 Free Software Foundation, Inc.
+Copyright \copyright{} 1995,96 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
This file documents Gnus, the GNU Emacs newsreader.
-Copyright (C) 1995 Free Software Foundation, Inc.
+Copyright (C) 1995,96 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@tex
@titlepage
-@title September Gnus Manual
+@title Red Gnus 0.51 Manual
@author by Lars Magne Ingebrigtsen
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1995 Free Software Foundation, Inc.
+Copyright @copyright{} 1995,96 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@node Top
-@top The Gnus Newsreader
+@top The Red Gnus Newsreader
@ifinfo
@iftex
@iflatex
-\thispagestyle{empty}
+\tableofcontents
+\gnuscleardoublepage
@end iflatex
Gnus is the advanced, self-documenting, customizable, extensible
* The Group Buffer:: Selecting, subscribing and killing groups.
* The Summary Buffer:: Reading, saving and posting articles.
* The Article Buffer:: Displaying and handling articles.
-* Message:: Message sending interface.
* Composing Messages:: Information on sending mail and news.
* Select Methods:: Gnus reads all messages from various select methods.
* Scoring:: Assigning values to articles.
* Key Index:: Key Index.
@end menu
-
@node Starting Up
@chapter Starting Gnus
@cindex 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.
+* Slave Gnusae:: 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.
* The Active File:: Reading the active file over a slow line Takes Time.
+* Changing Servers:: You may want to move from one server to another.
* Startup Variables:: Other variables you might change.
@end menu
@node Finding the News
@section Finding the News
+@cindex finding news
@vindex gnus-select-method
@c @head
Gnus will see whether @code{gnus-nntpserver-file}
(@file{/etc/nntpserver} by default) has any opinions on the matter. If
that fails as well, Gnus will will try to use the machine that is
-running Emacs as an @sc{nntp} server. That's a long-shot, though.
+running Emacs as an @sc{nntp} server. That's a long shot, though.
@vindex gnus-nntp-server
If @code{gnus-nntp-server} is set, this variable will override
buffer. But, hey, that's your problem. Blllrph!
@findex gnus-no-server
+@kindex M-x gnus-no-server
@c @head
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.
+if you're in a hurry as well. This command will not attempt to contact
+your primary server---instead, it will just activate all groups on level
+1 and 2. (You should preferably keep no native groups on those two
+levels.)
-@node Slave Gnusii
-@section Slave Gnusiï
+@node Slave Gnusae
+@section Slave Gnusae
@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 Gnusiï to read from two different servers),
+same time. If you are using different @file{.newsrc} files (e.g., if you
+are using the two different Gnusae to read from two different servers),
that is no problem whatsoever. You just do it.
-The problem appears when you want to run two Gnusiï that use the same
+The problem appears when you want to run two Gnusae that use the same
@code{.newsrc} file.
To work around that problem some, we here at the Think-Tank at the Gnus
Towers have come up with a new concept: @dfn{Masters} and
-@dfn{servants}. (We have applied for a patent on this concept, and have
+@dfn{slaves}. (We have applied for a patent on this concept, and have
taken out a copyright on those words. If you wish to use those words in
conjunction with each other, you have to send $1 per usage instance to
me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
Applications}) will be much more expensive, of course.)
Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
-however you do it). Each subsequent slave Gnusiï should be started with
+however you do it). Each subsequent slave Gnusae should be started with
@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
-files, but instead save @dfn{slave files} that contains information only
+files, but instead save @dfn{slave files} that contain information only
on what groups have been read in the slave session. When a master Gnus
starts, it will read (and delete) these slave files, incorporating all
information from them. (The slave files will be read in the sequence
they were created, so the latest changes will have precedence.)
Information from the slave files has, of course, precedence over the
-information in the normal (i. e., master) @code{.newsrc} file.
+information in the normal (i.e., master) @code{.newsrc} file.
@node Fetching a Group
@section Fetching a Group
+@cindex fetching a group
@findex gnus-fetch-group
-It it sometime convenient to be able to just say ``I want to read this
+It it sometimes 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.
@node New Groups
@section New Groups
@cindex new groups
+@cindex subscription
+
+@vindex gnus-check-new-newsgroups
+If you are satisfied that you really never want to see any new groups,
+you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will
+also save you some time at startup. Even if this variable is
+@code{nil}, you can always subscribe to the new groups just by pressing
+@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
+is @code{t} by default.
+
+@menu
+* Checking New Groups:: Determining what groups are new.
+* Subscription Methods:: What Gnus should do with new groups.
+* Filtering New Groups:: Making Gnus ignore certain new groups.
+@end menu
+
+
+@node Checking New Groups
+@subsection Checking New Groups
+
+Gnus normally determines whether a group is new or not by comparing the
+list of groups from the active file(s) with the lists of subscribed and
+dead groups. This isn't a particularly fast method. If
+@code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
+server for new groups since the last time. This is both faster and
+cheaper. This also means that you can get rid of the list of killed
+groups altogether, so you may set @code{gnus-save-killed-list} to
+@code{nil}, which will save time both at startup, at exit, and all over.
+Saves disk space, too. Why isn't this the default, then?
+Unfortunately, not all servers support this command.
+
+I bet I know what you're thinking now: How do I find out whether my
+server supports @code{ask-server}? No? Good, because I don't have a
+fail-safe answer. I would suggest just setting this variable to
+@code{ask-server} and see whether any new groups appear within the next
+few days. If any do, then it works. If none do, then it doesn't
+work. I could write a function to make Gnus guess whether the server
+supports @code{ask-server}, but it would just be a guess. So I won't.
+You could @code{telnet} to the server and say @code{HELP} and see
+whether it lists @samp{NEWGROUPS} among the commands it understands. If
+it does, then it might work. (But there are servers that lists
+@samp{NEWGROUPS} without supporting the function properly.)
+
+This variable can also be a list of select methods. If so, Gnus will
+issue an @code{ask-server} command to each of the select methods, and
+subscribe them (or not) using the normal methods. This might be handy
+if you are monitoring a few servers for new groups. A side effect is
+that startup will take much longer, so you can meditate while waiting.
+Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
+
+
+@node Subscription Methods
+@subsection Subscription Methods
@vindex gnus-subscribe-newsgroup-method
What Gnus does when it encounters a new group is determined by the
@item gnus-subscribe-zombies
@vindex gnus-subscribe-zombies
-Make all new groups zombies. You can browse the zombies later (with
-@kbd{A z}) and either kill them all off properly, or subscribe to them.
-This is the default.
+Make all new groups zombies. This is the default. You can browse the
+zombies later (with @kbd{A z}) and either kill them all off properly
+(with @kbd{S z}), or subscribe to them (with @kbd{u}).
@item gnus-subscribe-randomly
@vindex gnus-subscribe-randomly
@item gnus-subscribe-hierarchically
@vindex gnus-subscribe-hierarchically
-Subscribe all new groups hierarchically.
+Subscribe all new groups hierarchically. The difference between this
+function and @code{gnus-subscribe-alphabetically} is slight.
+@code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly
+alphabetical fashion, while this function will enter groups into it's
+hierarchy. So if you want to have the @samp{rec} hierarchy before the
+@samp{comp} hierarchy, this function will not mess that configuration
+up. Or something like that.
@item gnus-subscribe-interactively
@vindex gnus-subscribe-interactively
@code{gnus-subscribe-hierarchical-interactive}. This is an error. This
will not work. This is ga-ga. So don't do it.
+
+@node Filtering New Groups
+@subsection Filtering New Groups
+
A nice and portable way to control which new newsgroups should be
subscribed (or ignored) is to put an @dfn{options} line at the start of
the @file{.newsrc} file. Here's an example:
@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
-also save you some time at startup. Even if this variable is
-@code{nil}, you can always subscribe to the new groups just by pressing
-@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
-is @code{t} by default.
-Gnus normally determines whether a group is new or not by comparing the
-list of groups from the active file(s) with the lists of subscribed and
-dead groups. This isn't a particularly fast method. If
-@code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
-server for new groups since the last time. This is both faster &
-cheaper. This also means that you can get rid of the list of killed
-groups altogether, so you may set @code{gnus-save-killed-list} to
-@code{nil}, which will save time both at startup, at exit, and all over.
-Saves disk space, too. Why isn't this the default, then?
-Unfortunately, not all servers support this command.
+@node Changing Servers
+@section Changing Servers
+@cindex changing servers
-I bet I know what you're thinking now: How do I find out whether my
-server supports @code{ask-server}? No? Good, because I don't have a
-fail-safe answer. I would suggest just setting this variable to
-@code{ask-server} and see whether any new groups appear within the next
-few days. If any do, then it works. If any don't, then it doesn't
-work. I could write a function to make Gnus guess whether the server
-supports @code{ask-server}, but it would just be a guess. So I won't.
-You could @code{telnet} to the server and say @code{HELP} and see
-whether it lists @samp{NEWGROUPS} among the commands it understands. If
-it does, then it might work. (But there are servers that lists
-@samp{NEWGROUPS} without supporting the function properly.)
+Sometimes it is necessary to move from one @sc{nntp} server to another.
+This happens very rarely, but perhaps you change jobs, or one server is
+very flaky and you want to use another.
-This variable can also be a list of select methods. If so, Gnus will
-issue an @code{ask-server} command to each of the select methods, and
-subscribe them (or not) using the normal methods. This might be handy
-if you are monitoring a few servers for new groups. A side effect is
-that startup will take much longer, so you can meditate while waiting.
-Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
+Changing the server is pretty easy, right? You just change
+@code{gnus-select-method} to point to the new server?
+
+@emph{Wrong!}
+
+Article numbers are not (in any way) kept synchronized between different
+@sc{nntp} servers, and the only way Gnus keeps track of what articles
+you have read is by keeping track of article numbers. So when you
+change @code{gnus-select-method}, your @file{.newsrc} file becomes
+worthless.
+
+Gnus provides a few functions to attempt to translate a @file{.newsrc}
+file from one server to another. They all have one thing in
+common---they take a looong time to run. You don't want to use these
+functions more than absolutely necessary.
+
+@kindex M-x gnus-change-server
+@findex gnus-change-server
+If you have access to both servers, Gnus can request the headers for all
+the articles you have read and compare @code{Message-ID}s and map the
+article numbers of the read articles and article marks. The @kbd{M-x
+gnus-change-server} command will do this for all your native groups. It
+will prompt for the method you want to move to.
+
+@kindex M-x gnus-group-move-group-to-server
+@findex gnus-group-move-group-to-server
+You can also move individual groups with the @kbd{M-x
+gnus-group-move-group-to-server} command. This is useful if you want to
+move a (foreign) group from one server to another.
+
+@kindex M-x gnus-group-clear-data-on-native-groups
+@findex gnus-group-clear-data-on-native-groups
+If you don't have access to both the old and new server, all your marks
+and read ranges have become worthless. You can use the @kbd{M-x
+gnus-group-clear-data-on-native-groups} command to clear out all data
+that you have on your native groups. Use with caution.
@node Startup Files
@section Startup Files
@cindex startup files
@cindex .newsrc
+@cindex .newsrc.el
+@cindex .newsrc.eld
Now, you all know about the @file{.newsrc} file. All subscription
information is traditionally stored in this file.
If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
will not save the list of killed groups to the startup file. This will
save both time (when starting and quitting) and space (on disk). It
-will also means that Gnus has no record of what groups are new or old,
+will also mean that Gnus has no record of what groups are new or old,
so the automatic new groups subscription methods become meaningless.
You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
@code{ask-server} if you set this variable to @code{nil} (@pxref{New
-Groups}).
+Groups}). This variable can also be a regular expression. If that's
+the case, remove all groups that do not match this regexp before
+saving. This can be useful in certain obscure situations that involve
+several servers where not all servers support @code{ask-server}.
@vindex gnus-startup-file
The @code{gnus-startup-file} variable says where the startup files are.
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 turn version
-control on or off. Version control is off by default when saving the
-startup files.
+control on or off. Version control is on by default when saving the
+startup files. If you want to turn backup creation off, say something like:
+
+@lisp
+(defun turn-off-backup ()
+ (set (make-local-variable 'backup-inhibited) t))
+
+(add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup)
+(add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup)
+@end lisp
+
+@vindex gnus-init-file
+When Gnus starts, it will read the @code{gnus-site-init-file}
+(@file{.../site-lisp/gnus.el} by default) and @code{gnus-init-file}
+(@file{~/.gnus.el} by default) files. These are normal Emacs Lisp files
+and can be used to avoid cluttering your @file{.emacs} and
+@file{site-init} files with Gnus stuff.
@node Auto Save
@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 as easily.
+your boss might not notice as easily that you are reading news instead of doing
+your job.
@item gnus-no-groups-message
@vindex gnus-no-groups-message
* Group Buffer Format:: Information listed and how you can change it.
* Group Maneuvering:: Commands for moving in the group buffer.
* Selecting a Group:: Actually reading news.
+* Group Data:: Changing the info for a group.
* Subscription Commands:: Unsubscribing, killing, subscribing.
* Group Levels:: Levels? What are those, then?
* Group Score:: A mechanism for finding out what groups you like.
@node Group Buffer Format
@section Group Buffer Format
-@cindex group buffer format
@menu
* Group Line Specification:: Deciding how the group buffer is to look.
@node Group Line Specification
@subsection Group Line Specification
+@cindex group buffer format
The default format of the group buffer is nice and dull, but you can
make it as exciting and ugly as you feel like.
a @code{printf} specifications, for those of you who use (feh!) C.
@xref{Formatting Variables}.
-The default value that produced those lines above is
-@samp{%M%S%5y: %(%g%)\n}.
+@samp{%M%S%5y: %(%g%)\n} is the value that produced those lines above.
There should always be a colon on the line; the cursor always moves to
the colon after performing an operation. Nothing else is required---not
@table @samp
@item M
-Only marked articles.
+An asterisk if the group only has marked articles.
@item S
Whether the group is subscribed.
Number of read articles.
@item t
-Total number of articles.
+Estimated total number of articles. (This is really @var{max-number}
+minus @var{min-number} plus 1.)
@item y
Number of unread, unticked, non-dormant articles.
@vindex gnus-group-uncollapsed-levels
Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
variable says how many levels to leave at the end of the group name.
-The default is @code{1}.
+The default is 1---this will mean that group names like
+@samp{gnu.emacs.gnus} will be shortened to @samp{g.emacs.gnus}.
+
+@item m
+@vindex gnus-new-mail-mark
+@cindex %
+@samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to
+the group lately.
+
+@item d
+A string that says when you last read the group (@pxref{Group
+Timestamp}).
@item u
User defined specifier. The next character in the format string should
be a letter. @sc{gnus} will call the function
@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
-following @samp{%u}. The function will be passed the current headers as
-argument. The function should return a string, which will be inserted
-into the buffer just like information from any other specifier.
+following @samp{%u}. The function will be passed a single dummy
+paratere as argument. The function should return a string, which will
+be inserted into the buffer just like information from any other
+specifier.
@end table
@cindex *
All the ``number-of'' specs will be filled with an asterisk (@samp{*})
if no info is available---for instance, if it is a non-activated foreign
-group, or a bogus (or semi-bogus) native group.
+group, or a bogus native group.
@node Group Modeline Specification
@subsection Group Modeline Specification
+@cindex group modeline
@vindex gnus-group-mode-line-format
The mode line can be changed by setting
-(@code{gnus-group-mode-line-format}). It doesn't understand that many
-format specifiers:
+@code{gnus-group-mode-line-format} (@pxref{Formatting Variables}). It
+doesn't understand that many format specifiers:
@table @samp
@item S
@node Group Highlighting
@subsection Group Highlighting
+@cindex highlighting
+@cindex group highlighting
@vindex gnus-group-highlight
Highlighting in the group buffer is controlled by the
The score of the group.
@item ticked
The number of ticked articles in the group.
+@item total
+The total number of articles in the group. Or rather, MAX-NUMBER minus
+MIN-NUMBER.
+@item topic
+When using the topic minor mode, this variable is bound to the current
+topic being inserted.
@end table
When the forms are @code{eval}ed, point is at the beginning of the line
(@code{gnus-group-next-unread-group}).
@item p
-
@itemx DEL
@kindex DEL (Group)
@kindex p (Group)
@findex gnus-group-prev-unread-group
-Go to the previous group group that has unread articles
+Go to the previous group that has unread articles
(@code{gnus-group-prev-unread-group}).
@item N
@item M-p
@kindex M-p (Group)
@findex gnus-group-next-unread-group-same-level
-Go to the next unread group on the same level (or lower)
+Go to the next unread group on the same (or lower) level
(@code{gnus-group-next-unread-group-same-level}).
@item M-n
@kindex M-n (Group)
@findex gnus-group-prev-unread-group-same-level
-Go to the previous unread group on the same level (or lower)
+Go to the previous unread group on the same (or lower) level
(@code{gnus-group-prev-unread-group-same-level}).
@end table
first unread article (@code{gnus-group-read-group}). If there are no
unread articles in the group, or if you give a non-numerical prefix to
this command, Gnus will offer to fetch all the old articles in this
-group from the server. If you give a numerical prefix @var{N}, Gnus
-will fetch @var{N} number of articles. If @var{N} is positive, fetch
-the @var{N} newest articles, if @var{N} is negative, fetch the
-@var{abs(N)} oldest articles.
+group from the server. If you give a numerical prefix @var{N}, @var{N}
+determines the number of articles Gnus will fetch. If @var{N} is
+positive, Gnus fetches the @var{N} newest articles, if @var{N} is
+negative, Gnus fetches the @var{abs(N)} oldest articles.
@item RET
@kindex RET (Group)
@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
+minimum amount of 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 group.
+enter some humongous group. If you give a 0 prefix to this command
+(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer.
+This might be useful if you want to toggle threading before entering the
+group.
@item M-SPACE
-@kindex M-RET (Group)
+@kindex M-SPACE (Group)
@findex gnus-group-visible-select-group
-This is yet one more command that does the same as the one above, but
-this one does it without expunging and hiding dormants
-(@code{gnus-group-visible-select-group}).
-
-@item c
-@kindex c (Group)
-@findex gnus-group-catchup-current
-@vindex gnus-group-catchup-group-hook
-Mark all unticked articles in this group as read
-(@code{gnus-group-catchup-current}).
-@code{gnus-group-catchup-group-hook} is when catching up a group from
-the group buffer.
+This is yet one more command that does the same as the @kbd{RET}
+command, but this one does it without expunging and hiding dormants
+(@code{gnus-group-visible-select-group}).
-@item C
-@kindex C (Group)
-@findex gnus-group-catchup-current-all
-Mark all articles in this group, even the ticked ones, as read
-(@code{gnus-group-catchup-current-all}).
@end table
@vindex gnus-large-newsgroup
The @code{gnus-large-newsgroup} variable says what Gnus should consider
to be a big group. This is 200 by default. If the group has more
-unread articles than this, Gnus will query the user before entering the
-group. The user can then specify how many articles should be fetched
-from the server. If the user specifies a negative number (@code{-n}),
-the @code{n} oldest articles will be fetched. If it is positive, the
-@code{n} articles that have arrived most recently will be fetched.
+(unread and/or ticked) articles than this, Gnus will query the user
+before entering the group. The user can then specify how many articles
+should be fetched from the server. If the user specifies a negative
+number (@code{-n}), the @code{n} oldest articles will be fetched. If it
+is positive, the @code{n} articles that have arrived most recently will
+be fetched.
@vindex gnus-select-group-hook
@vindex gnus-auto-select-first
@code{gnus-auto-select-first} control whether any articles are selected
-automatically when entering a group.
+automatically when entering a group with the @kbd{SPACE} command.
@table @code
in @code{gnus-select-group-hook}, which is called when a group is
selected.
-@findex gnus-thread-sort-by-total-score
-@findex gnus-thread-sort-by-date
-@findex gnus-thread-sort-by-score
-@findex gnus-thread-sort-by-subject
-@findex gnus-thread-sort-by-author
-@findex gnus-thread-sort-by-number
-@vindex gnus-thread-sort-functions
-If you are using a threaded summary display, you can sort the threads by
-setting @code{gnus-thread-sort-functions}, which is a list of functions.
-By default, sorting is done on article numbers. Ready-made sorting
-predicate functions include @code{gnus-thread-sort-by-number},
-@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
-@code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
-@code{gnus-thread-sort-by-total-score}.
-
-Each function takes two threads and return non-@code{nil} if the first
-thread should be sorted before the other. Note that sorting really is
-normally done by looking only at the roots of each thread. If you use
-more than one function, the primary sort key should be the last function
-in the list. You should probably always include
-@code{gnus-thread-sort-by-number} in the list of sorting
-functions---preferably first. This will ensure that threads that are
-equal with respect to the other sort criteria will be displayed in
-ascending article order.
-
-If you would like to sort by score, then by subject, and finally by
-number, you could do something like:
-
-@lisp
-(setq gnus-thread-sort-functions
- '(gnus-thread-sort-by-number
- gnus-thread-sort-by-subject
- gnus-thread-sort-by-score))
-@end lisp
-
-The threads that have highest score will be displayed first in the
-summary buffer. When threads have the same score, they will be sorted
-alphabetically. The threads that have the same score and the same
-subject will be sorted by number, which is (normally) the sequence in
-which the articles arrived.
-
-If you want to sort by score and then reverse arrival order, you could
-say something like:
-
-@lisp
-(setq gnus-thread-sort-functions
- '((lambda (t1 t2)
- (not (gnus-thread-sort-by-number t1 t2)))
- gnus-thread-sort-by-score))
-@end lisp
-
-@vindex gnus-thread-score-function
-The function in the @code{gnus-thread-score-function} variable (default
-@code{+}) is used for calculating the total score of a thread. Useful
-functions might be @code{max}, @code{min}, or squared means, or whatever
-tickles your fancy.
-
-@findex gnus-article-sort-functions
-@findex gnus-article-sort-by-date
-@findex gnus-article-sort-by-score
-@findex gnus-article-sort-by-subject
-@findex gnus-article-sort-by-author
-@findex gnus-article-sort-by-number
-If you are using an unthreaded display for some strange reason or other,
-you have to fiddle with the @code{gnus-article-sort-functions} variable.
-It is very similar to the @code{gnus-thread-sort-functions}, except that
-is uses slightly different functions for article comparison. Available
-sorting predicate functions are @code{gnus-article-sort-by-number},
-@code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
-@code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
-
-If you want to sort an unthreaded summary display by subject, you could
-say something like:
-
-@lisp
-(setq gnus-article-sort-functions
- '(gnus-article-sort-by-number
- gnus-article-sort-by-subject))
-@end lisp
-
@node Subscription Commands
@section Subscription Commands
-@cindex subscribing
+@cindex subscription
@table @kbd
@findex gnus-group-kill-level
Kill all groups on a certain level (@code{gnus-group-kill-level}).
These groups can't be yanked back after killing, so this command should
-be used with some caution. The only thing where this command comes in
+be used with some caution. The only time where this command comes in
really handy is when you have a @file{.newsrc} with lots of unsubscribed
-groups that you want to get rid off. @kbd{S C-k} on level @code{7} will
+groups that you want to get rid off. @kbd{S C-k} on level 7 will
kill off all unsubscribed groups that do not have message numbers in the
@file{.newsrc} file.
Also @pxref{Group Levels}.
-@node Group Levels
-@section Group Levels
-@cindex group level
-
-All groups have a level of @dfn{subscribedness}. For instance, if a
-group is on level 2, it is more subscribed than a group on level 5. You
-can ask Gnus to just list groups on a given level or lower
-(@pxref{Listing Groups}), or to just check for new articles in groups on
-a given level or lower (@pxref{Scanning New Messages}).
+@node Group Data
+@section Group Data
@table @kbd
-@item S l
-@kindex S l (Group)
-@findex gnus-group-set-current-level
-Set the level of the current group. If a numeric prefix is given, the
-next @var{n} groups will have their levels set. The user will be
+@item c
+@kindex c (Group)
+@findex gnus-group-catchup-current
+@vindex gnus-group-catchup-group-hook
+Mark all unticked articles in this group as read
+(@code{gnus-group-catchup-current}).
+@code{gnus-group-catchup-group-hook} is called when catching up a group from
+the group buffer.
+
+@item C
+@kindex C (Group)
+@findex gnus-group-catchup-current-all
+Mark all articles in this group, even the ticked ones, as read
+(@code{gnus-group-catchup-current-all}).
+
+@item M-c
+@kindex M-c (Group)
+@findex gnus-group-clear-data
+Clear the data from the current group---nix out marks and the list of
+read articles (@code{gnus-group-clear-data}).
+
+@item M-x gnus-group-clear-data-on-native-groups
+@kindex M-x gnus-group-clear-data-on-native-groups
+@findex gnus-group-clear-data-on-native-groups
+If you have switched from one @sc{nntp} server to another, all your marks
+and read ranges have become worthless. You can use this command to
+clear out all data that you have on your native groups. Use with
+caution.
+
+@end table
+
+
+@node Group Levels
+@section Group Levels
+@cindex group level
+@cindex level
+
+All groups have a level of @dfn{subscribedness}. For instance, if a
+group is on level 2, it is more subscribed than a group on level 5. You
+can ask Gnus to just list groups on a given level or lower
+(@pxref{Listing Groups}), or to just check for new articles in groups on
+a given level or lower (@pxref{Scanning New Messages}).
+
+Remember: The higher the level of the group, the less important it is.
+
+@table @kbd
+
+@item S l
+@kindex S l (Group)
+@findex gnus-group-set-current-level
+Set the level of the current group. If a numeric prefix is given, the
+next @var{n} groups will have their levels set. The user will be
prompted for a level.
@end table
for reasons of efficiency.
It is recommended that you keep all your mail groups (if any) on quite
-low levels (eg. 1 or 2).
+low levels (e.g. 1 or 2).
If you want to play with the level variables, you should show some care.
Set them once, and don't touch them ever again. Better yet, don't touch
Gnus will normally just activate groups that are on level
@code{gnus-activate-level} or less. If you don't want to activate
unsubscribed groups, for instance, you might set this variable to
-@code{5}.
+5. The default is 6.
@node Group Score
the level and the score is called the @dfn{rank} of the group. A group
that is on level 4 and has a score of 1 has a higher rank than a group
on level 5 that has a score of 300. (The level is the most significant
-part and the score is the least significant part.)
+part and the score is the least significant part.))
@findex gnus-summary-bubble-group
If you want groups you read often to get higher scores than groups you
@node Foreign Groups
@section Foreign Groups
+@cindex foreign groups
-Here are some group mode commands for making and editing general foreign
+Below are some group mode commands for making and editing general foreign
groups, as well as commands to ease the creation of a few
-special-purpose groups:
+special-purpose groups. All these commands insert the newly created
+groups under point---@code{gnus-subscribe-newsgroup-method} is not
+consulted.
@table @kbd
@item G m
@kindex G m (Group)
@findex gnus-group-make-group
+@cindex making groups
Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
for a name, a method and possibly an @dfn{address}. For an easier way
to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
@item G r
@kindex G r (Group)
@findex gnus-group-rename-group
+@cindex renaming groups
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.
+(@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 c
+@kindex G c (Group)
+@cindex customizing
+@findex gnus-group-customize
+Customize the group parameters (@code{gnus-group-customize}).
@item G e
@kindex G e (Group)
@findex gnus-group-edit-group-method
+@cindex renaming groups
Enter a buffer where you can edit the select method of the current
group (@code{gnus-group-edit-group-method}).
@item G d
@kindex G d (Group)
@findex gnus-group-make-directory-group
-Make a directory group. You will be prompted for a directory name
-(@code{gnus-group-make-directory-group}).
+@cindex nndir
+Make a directory group (@pxref{Directory Groups}). You will be prompted
+for a directory name (@code{gnus-group-make-directory-group}).
@item G h
@kindex G h (Group)
+@cindex help group
@findex gnus-group-make-help-group
Make the Gnus help group (@code{gnus-group-make-help-group}).
@item G a
@kindex G a (Group)
+@cindex (ding) archive
+@cindex archive group
@findex gnus-group-make-archive-group
@vindex gnus-group-archive-directory
@vindex gnus-group-recent-archive-directory
Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
default a group pointing to the most recent articles will be created
(@code{gnus-group-recent-archive-directory}), but given a prefix, a full
-group will be created from from @code{gnus-group-archive-directory}.
+group will be created from @code{gnus-group-archive-directory}.
@item G k
@kindex G k (Group)
@findex gnus-group-make-kiboze-group
+@cindex nnkiboze
Make a kiboze group. You will be prompted for a name, for a regexp to
match groups to be ``included'' in the kiboze group, and a series of
strings to match on headers (@code{gnus-group-make-kiboze-group}).
+@xref{Kibozed Groups}.
@item G D
@kindex G D (Group)
@findex gnus-group-enter-directory
+@cindex nneething
Read an arbitrary directory as if with were a newsgroup with the
@code{nneething} backend (@code{gnus-group-enter-directory}).
+@xref{Anything Groups}.
@item G f
@kindex G f (Group)
@findex gnus-group-make-doc-group
@cindex ClariNet Briefs
+@cindex nndoc
Make a group based on some file or other
(@code{gnus-group-make-doc-group}). If you give a prefix to this
command, you will be prompted for a file name and a file type.
Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
@code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, and
@code{forward}. If you run this command without a prefix, Gnus will
-guess at the file type.
+guess at the file type. @xref{Document Groups}.
+
+@item G w
+@kindex G w (Group)
+@findex gnus-group-make-web-group
+@cindex DejaNews
+@cindex Alta Vista
+@cindex InReference
+@cindex nnweb
+Make an ephemeral group based on a web search
+(@code{gnus-group-make-web-group}). If you give a prefix to this
+command, make a solid group instead. You will be prompted for the
+search engine type and the search string. Legal search engine types
+include @code{dejanews}, @code{altavista} and @code{reference}.
+@xref{Web Searches}.
@item G DEL
@kindex G DEL (Group)
@kindex G V (Group)
@findex gnus-group-make-empty-virtual
Make a new, fresh, empty @code{nnvirtual} group
-(@code{gnus-group-make-empty-virtual}).
+(@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}.
@item G v
@kindex G v (Group)
methods.
@vindex gnus-activate-foreign-newsgroups
-If the @code{gnus-activate-foreign-newsgroups} is a positive number,
+If @code{gnus-activate-foreign-newsgroups} is a positive number,
Gnus will check all foreign groups with this level or lower at startup.
This might take quite a while, especially if you subscribe to lots of
groups from different @sc{nntp} servers.
@section Group Parameters
@cindex group parameters
-Gnus stores all information on a group in a list that is usually known
-as the @dfn{group info}. This list has from three to six elements.
-Here's an example info.
-
-@lisp
-("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
- (nnml "private") ((to-address . "ding@@ifi.uio.no")))
-@end lisp
-
-The first element is the @dfn{group name}, as Gnus knows the group,
-anyway. The second element is the @dfn{subscription level}, which
-normally is a small integer. The third element is a list of ranges of
-read articles. The fourth element is a list of lists of article marks
-of various kinds. The fifth element is the select method (or virtual
-server, if you like). The sixth element is a list of @dfn{group
-parameters}, which is what this section is about.
-
-Any of the last three elements may be missing if they are not required.
-In fact, the vast majority of groups will normally only have the first
-three elements, which saves quite a lot of cons cells.
-
The group parameters store information local to a particular group:
@table @code
@item to-group
@cindex to-group
-If the group parameter list contains an element like @code{(to-group
-. "some.group.name")}, all posts will be sent to that group.
+Elements like @code{(to-group . "some.group.name")} means that all
+posts in that group will be sent to @code{some.group.name}.
+
+@item gcc-self
+@cindex gcc-self
+If this symbol is present in the group parameter list and set to
+@code{t}, new composed messages will be @code{Gcc}'d to the current
+group. If it is present and set to @code{none}, no @code{Gcc:} header
+will be generated, if it is present and a string, this string will be
+inserted literally as a @code{gcc} header (this symbol takes precedence over
+any default @code{Gcc} rules as described later).
@item auto-expire
@cindex auto-expire
the symbols @code{never} or @code{immediate}.
@item score-file
+@cindex score file group parameter
Elements that look like @code{(score-file . "file")} will make
-@samp{file} into the current score file for the group in question. This
+@file{file} into the current score file for the group in question. This
means that all score commands you issue will end up in that file.
+@item adapt-file
+@cindex adapt file group parameter
+Elements that look like @code{(adapt-file . "file")} will make
+@file{file} into the current adaptive file for the group in question.
+All adaptive score entries will be put into this file.
+
@item admin-address
When unsubscribing to a mailing list you should never send the
unsubscription notice to the mailing list itself. Instead, you'd send
messages to the administrative address. This parameter allows you to
put the admin address somewhere convenient.
+@item display
+Elements that look like @code{(display . MODE)} says which articles to
+display on entering the group. Legal values are:
+
+@table @code
+@item all
+Display all articles, both read and unread.
+
+@item default
+Display the default visible articles, which normally includes unread and
+ticked articles.
+@end table
+
@item comment
-This parameter allows you to enter a arbitrary comment on the group.
+This parameter allows you to enter an arbitrary comment on the group.
@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.
+are entering. If you want to turn threading off in @samp{news.answers},
+you could 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?
+If you want to hear a beep when you enter a group, you could put
+something like @code{(dummy-variable (ding))} in the parameters of that
+group. @code{dummy-variable} will be set to the result of the
+@code{(ding)} form, but who cares?
@end table
-If you want to change the group info you can use the @kbd{G E} command
-to enter a buffer where you can edit it.
+Use the @kbd{G p} command to edit group parameters of a group.
-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.
+Also @pxref{Topic Parameters}.
@node Listing Groups
List all groups that have unread articles
(@code{gnus-group-list-groups}). If the numeric prefix is used, this
command will list only groups of level ARG and lower. By default, it
-only lists groups of level five or lower (i.e., just subscribed groups).
+only lists groups of level five (i. e.,
+@code{gnus-group-default-list-level}) or lower (i.e., just subscribed
+groups).
@item L
@itemx A u
@item A m
@kindex A m (Group)
@findex gnus-group-list-matching
-List all subscribed groups with unread articles that match a regexp
+List all unread, subscribed groups with names that match a regexp
(@code{gnus-group-list-matching}).
@item A M
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.
+to do a @kbd{A M} to list all matching, and just give @samp{.} as the
+thing to match on. Also note that this command may list group that
+don't exist (yet)---these will be listed as if they are killed groups.
+Take the output with some grains of salt.
@item A a
@kindex A a (Group)
@findex gnus-group-sort-by-alphabet
Sort the group names alphabetically. This is the default.
+@item gnus-group-sort-by-real-name
+@findex gnus-group-sort-by-real-name
+Sort the group alphabetically on the real (unprefixed) group names.
+
@item gnus-group-sort-by-level
@findex gnus-group-sort-by-level
Sort by group level.
@item gnus-group-sort-by-method
@findex gnus-group-sort-by-method
-Sort by alphabetically on the select method.
+Sort alphabetically on the select method.
@end table
@item G S r
@kindex G S r (Group)
@findex gnus-group-sort-groups-by-rank
-Sort the group buffer by group level
+Sort the group buffer by group rank
(@code{gnus-group-sort-groups-by-rank}).
@item G S m
When given a prefix, all these commands will sort in reverse order.
+You can also sort a subset of the groups:
+
+@table @kbd
+@item G P a
+@kindex G P a (Group)
+@findex gnus-group-sort-selected-groups-by-alphabet
+Sort the process/prefixed groups in the group buffer alphabetically by
+group name (@code{gnus-group-sort-selected-groups-by-alphabet}).
+
+@item G P u
+@kindex G P u (Group)
+@findex gnus-group-sort-selected-groups-by-unread
+Sort the process/prefixed groups in the group buffer by the number of
+unread articles (@code{gnus-group-sort-selected-groups-by-unread}).
+
+@item G P l
+@kindex G P l (Group)
+@findex gnus-group-sort-selected-groups-by-level
+Sort the process/prefixed groups in the group buffer by group level
+(@code{gnus-group-sort-selected-groups-by-level}).
+
+@item G P v
+@kindex G P v (Group)
+@findex gnus-group-sort-selected-groups-by-score
+Sort the process/prefixed groups in the group buffer by group score
+(@code{gnus-group-sort-selected-groups-by-score}).
+
+@item G P r
+@kindex G P r (Group)
+@findex gnus-group-sort-selected-groups-by-rank
+Sort the process/prefixed groups in the group buffer by group rank
+(@code{gnus-group-sort-selected-groups-by-rank}).
+
+@item G P m
+@kindex G P m (Group)
+@findex gnus-group-sort-selected-groups-by-method
+Sort the process/prefixed groups in the group buffer alphabetically by
+backend name (@code{gnus-group-sort-selected-groups-by-method}).
+
+@end table
+
+
@node Group Maintenance
@section Group Maintenance
(@code{gnus-group-browse-foreign-server}).
@end table
-@findex gnus-browse-server-mode
+@findex gnus-browse-mode
A new buffer with a list of available groups will appear. This buffer
-will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
-(well, a lot) like a normal group buffer, but with one major difference
-- you can't enter any of the groups. If you want to read any of the
-news available on that server, you have to subscribe to the groups you
-think may be interesting, and then you have to exit this buffer. The
-new groups will be added to the group buffer, and then you can read them
-as you would any other group.
-
-Future versions of Gnus may possibly permit reading groups straight from
-the browse buffer.
+will be use the @code{gnus-browse-mode}. This buffer looks a bit (well,
+a lot) like a normal group buffer.
Here's a list of keystrokes available in the browse mode:
@item Q
@kindex Q (Group)
@findex gnus-group-quit
-Quit Gnus without saving any startup files (@code{gnus-group-quit}).
+Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}).
+The dribble file will be saved, though (@pxref{Auto Save}).
@end table
@vindex gnus-exit-gnus-hook
Note:
@quotation
-Miss Lisa Cannifax, while sitting in English class, feels her feet go
+Miss Lisa Cannifax, while sitting in English class, felt her feet go
numbly heavy and herself fall into a hazy trance as the boy sitting
behind her drew repeated lines with his pencil across the back of her
plastic chair.
even group the Emacs sex groups as a sub-topic to either the Emacs
groups or the sex groups---or both! Go wild!
+Here's an example:
+
+@example
+Gnus
+ Emacs -- I wuw it!
+ 3: comp.emacs
+ 2: alt.religion.emacs
+ Naughty Emacs
+ 452: alt.sex.emacs
+ 0: comp.talk.emacs.recovery
+ Misc
+ 8: comp.binaries.fractals
+ 13: comp.sources.unix
+@end example
+
@findex gnus-topic-mode
@kindex t (Group)
To get this @emph{fab} functionality you simply turn on (ooh!) the
@menu
* Topic Variables:: How to customize the topics the Lisp Way.
* Topic Commands:: Interactive E-Z commands.
+* Topic Sorting:: Sorting each topic individually.
* Topic Topology:: A map of the world.
+* Topic Parameters:: Parameters that apply to all groups in a topic.
@end menu
@subsection Topic Variables
@cindex topic variables
-@vindex gnus-topic-unique
-If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
-of (tops) one topic each. If this is @code{nil}, each group might end
-up being a member of several topics.
-
Now, if you select a topic, if will fold/unfold that topic, which is
really neat, I think.
@vindex gnus-topic-line-format
The topic lines themselves are created according to the
-@code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
-Elements allowed are:
+@code{gnus-topic-line-format} variable (@pxref{Formatting Variables}).
+Legal elements are:
@table @samp
@item i
@vindex gnus-topic-indent-level
Each sub-topic (and the groups in the sub-topics) will be indented with
@code{gnus-topic-indent-level} times the topic level number of spaces.
-The default is @code{2}.
+The default is 2.
@vindex gnus-topic-mode-hook
@code{gnus-topic-mode-hook} is called in topic minor mode buffers.
+@vindex gnus-topic-display-empty-topics
+The @code{gnus-topic-display-empty-topics} says whether to display even
+topics that have no unread articles in them. The default is @code{t}.
+
@node Topic Commands
@subsection Topic Commands
@table @kbd
@item T n
-@kindex T n (Group)
+@kindex T n (Topic)
@findex gnus-topic-create-topic
-Create a new topic (@code{gnus-topic-create-topic}). You will be
-prompted for a topic name and the name of the parent topic.
+Prompt for a new topic name and create it
+(@code{gnus-topic-create-topic}).
@item T m
-@kindex T m (Group)
+@kindex T m (Topic)
@findex gnus-topic-move-group
Move the current group to some other topic
-(@code{gnus-topic-move-group}). This command understands the
-process/prefix convention (@pxref{Process/Prefix}).
+(@code{gnus-topic-move-group}). This command uses the process/prefix
+convention (@pxref{Process/Prefix}).
@item T c
-@kindex T c (Group)
+@kindex T c (Topic)
@findex gnus-topic-copy-group
Copy the current group to some other topic
-(@code{gnus-topic-copy-group}). This command understands the
-process/prefix convention (@pxref{Process/Prefix}).
+(@code{gnus-topic-copy-group}). This command uses the process/prefix
+convention (@pxref{Process/Prefix}).
@item T D
-@kindex T D (Group)
+@kindex T D (Topic)
@findex gnus-topic-remove-group
Remove a group from the current topic (@code{gnus-topic-remove-group}).
-This command understands the process/prefix convention
+This command uses the process/prefix convention
(@pxref{Process/Prefix}).
@item T M
-@kindex T M (Group)
+@kindex T M (Topic)
@findex gnus-topic-move-matching
Move all groups that match some regular expression to a topic
(@code{gnus-topic-move-matching}).
@item T C
-@kindex T C (Group)
+@kindex T C (Topic)
@findex gnus-topic-copy-matching
Copy all groups that match some regular expression to a topic
(@code{gnus-topic-copy-matching}).
@item T #
-@kindex T # (Group)
+@kindex T # (Topic)
@findex gnus-topic-mark-topic
Mark all groups in the current topic with the process mark
(@code{gnus-topic-mark-topic}).
@item T M-#
-@kindex T M-# (Group)
+@kindex T M-# (Topic)
@findex gnus-topic-unmark-topic
Remove the process mark from all groups in the current topic
(@code{gnus-topic-unmark-topic}).
@item RET
-@kindex RET (Group)
+@kindex RET (Topic)
@findex gnus-topic-select-group
@itemx SPACE
Either select a group or fold a topic (@code{gnus-topic-select-group}).
prefix, group on that level (and lower) will be displayed.
@item T TAB
-@kindex T TAB (Group)
+@kindex T TAB (Topic)
@findex gnus-topic-indent
``Indent'' the current topic so that it becomes a sub-topic of the
previous topic (@code{gnus-topic-indent}). If given a prefix,
``un-indent'' the topic instead.
@item C-k
-@kindex C-k (Group)
+@kindex C-k (Topic)
@findex gnus-topic-kill-group
-Kill a group or topic (@code{gnus-topic-kill-group}).
+Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the
+topic will be removed along with the topic.
@item C-y
-@kindex C-y (Group)
+@kindex C-y (Topic)
@findex gnus-topic-yank-group
-Yank the previously killed group or topic (@code{gnus-topic-yank-group}).
-Note that all topics will be yanked before all groups.
+Yank the previously killed group or topic
+(@code{gnus-topic-yank-group}). Note that all topics will be yanked
+before all groups.
@item T r
-@kindex T r (Group)
+@kindex T r (Topic)
@findex gnus-topic-rename
Rename a topic (@code{gnus-topic-rename}).
@item T DEL
-@kindex T DEL (Group)
+@kindex T DEL (Topic)
@findex gnus-topic-delete
Delete an empty topic (@code{gnus-topic-delete}).
@item A T
-@kindex A T (Group)
+@kindex A T (Topic)
@findex gnus-topic-list-active
List all groups that Gnus knows about in a topics-ified way
(@code{gnus-topic-list-active}).
+@item G p
+@kindex G p (Topic)
+@findex gnus-topic-edit-parameters
+@cindex group parameters
+@cindex topic parameters
+@cindex parameters
+Edit the topic parameters (@code{gnus-topic-edit-parameters}).
+@xref{Topic Parameters}.
+
+@end table
+
+
+@node Topic Sorting
+@subsection Topic Sorting
+@cindex topic sorting
+
+You can sort the groups in each topic individually with the following
+commands:
+
+
+@table @kbd
+@item T S a
+@kindex T S a (Topic)
+@findex gnus-topic-sort-groups-by-alphabet
+Sort the current topic alphabetically by group name
+(@code{gnus-topic-sort-groups-by-alphabet}).
+
+@item T S u
+@kindex T S u (Topic)
+@findex gnus-topic-sort-groups-by-unread
+Sort the current topic by the number of unread articles
+(@code{gnus-topic-sort-groups-by-unread}).
+
+@item T S l
+@kindex T S l (Topic)
+@findex gnus-topic-sort-groups-by-level
+Sort the current topic by group level
+(@code{gnus-topic-sort-groups-by-level}).
+
+@item T S v
+@kindex T S v (Topic)
+@findex gnus-topic-sort-groups-by-score
+Sort the current topic by group score
+(@code{gnus-topic-sort-groups-by-score}).
+
+@item T S r
+@kindex T S r (Topic)
+@findex gnus-topic-sort-groups-by-rank
+Sort the current topic by group rank
+(@code{gnus-topic-sort-groups-by-rank}).
+
+@item T S m
+@kindex T S m (Topic)
+@findex gnus-topic-sort-groups-by-method
+Sort the current topic alphabetically by backend name
+(@code{gnus-topic-sort-groups-by-method}).
+
@end table
+@xref{Sorting Groups} for more information about group sorting.
+
@node Topic Topology
@subsection Topic Topology
@example
Gnus
Emacs -- I wuw it!
- 3: comp.emacs
- 2: alt.religion.emacs
+ 3: comp.emacs
+ 2: alt.religion.emacs
Naughty Emacs
452: alt.sex.emacs
0: comp.talk.emacs.recovery
Misc
- 8: comp.binaries.fractals
- 13: comp.sources.unix
+ 8: comp.binaries.fractals
+ 13: comp.sources.unix
@end example
-So, here we have one top-level topic, two topics under that, and one
-sub-topic under one of the sub-topics. (There is always just one (1)
-top-level topic). This topology can be expressed as follows:
+So, here we have one top-level topic (@samp{Gnus}), two topics under
+that, and one sub-topic under one of the sub-topics. (There is always
+just one (1) top-level topic). This topology can be expressed as
+follows:
@lisp
(("Gnus" visible)
allowed---@code{visible} and @code{invisible}.
+@node Topic Parameters
+@subsection Topic Parameters
+@cindex topic parameters
+
+All groups in a topic will inherit group parameters from the parent (and
+ancestor) topic parameters. All legal group parameters are legal topic
+parameters (@pxref{Group Parameters}).
+
+Group parameters (of course) override topic parameters, and topic
+parameters in sub-topics override topic parameters in super-topics. You
+know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a
+verb, although you may feel free to disagree with me here.)
+
+@example
+Gnus
+ Emacs
+ 3: comp.emacs
+ 2: alt.religion.emacs
+ 452: alt.sex.emacs
+ Relief
+ 452: alt.sex.emacs
+ 0: comp.talk.emacs.recovery
+ Misc
+ 8: comp.binaries.fractals
+ 13: comp.sources.unix
+ 452: alt.sex.emacs
+@end example
+
+The @samp{Emacs} topic has the topic parameter @code{(score-file
+. "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter
+@code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the
+topic parameter @code{(score-file . "emacs.SCORE")}. In addition,
+@samp{alt.religion.emacs} has the group parameter @code{(score-file
+. "religion.SCORE")}.
+
+Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you
+will get the @file{relief.SCORE} home score file. If you enter the same
+group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home
+score file. If you enter the group @samp{alt.religion.emacs}, you'll
+get the @file{religion.SCORE} home score file.
+
+This seems rather simple and self-evident, doesn't it? Well, yes. But
+there are some problems, especially with the @code{total-expiry}
+parameter. Say you have a mail group in two topics; one with
+@code{total-expiry} and one without. What happens when you do @kbd{M-x
+gnus-expire-all-expirable-groups}? Gnus has no way of telling which one
+of these topics you mean to expire articles from, so anything may
+happen. In fact, I hereby declare that it is @dfn{undefined} what
+happens. You just have to be careful if you do stuff like that.
+
+
@node Misc Group Stuff
@section Misc Group Stuff
@menu
* Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
* Group Information:: Information and help on groups and Gnus.
+* Group Timestamp:: Making Gnus keep track of when you last read a group.
* File Commands:: Reading and writing the Gnus files.
@end menu
@item ^
@kindex ^ (Group)
@findex gnus-group-enter-server-mode
-Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
-Server Buffer}.
+Enter the server buffer (@code{gnus-group-enter-server-mode}).
+@xref{The Server Buffer}.
@item a
@kindex a (Group)
generated. It may be used to modify the buffer in some strange,
unnatural way.
+@item gnus-permanently-visible-groups
+@vindex gnus-permanently-visible-groups
+Groups matching this regexp will always be listed in the group buffer,
+whether they are empty or not.
+
@end table
@findex gnus-group-get-new-news-this-group
@vindex gnus-goto-next-group-when-activating
Check whether new articles have arrived in the current group
-(@code{gnus-group-get-new-news-this-group}). The
-@code{gnus-goto-next-group-when-activating} variable controls whether
-this command is to move point to the next group or not. It is @code{t}
-by default.
+(@code{gnus-group-get-new-news-this-group}).
+@code{gnus-goto-next-group-when-activating} says whether this command is
+to move point to the next group or not. It is @code{t} by default.
@findex gnus-activate-all-groups
@cindex activating groups
@table @kbd
-@item M-f
-@kindex M-f (Group)
+
+@item H f
+@kindex H f (Group)
+@itemx M-f
@findex gnus-group-fetch-faq
+@vindex gnus-group-faq-directory
@cindex FAQ
@cindex ange-ftp
Try to fetch the FAQ for the current group
(@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
@code{gnus-group-faq-directory}, which is usually a directory on a
-remote machine. @code{ange-ftp} will be used for fetching the file.
+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} (or @code{efs}) will be used
+for fetching the file.
-@item D
-@kindex D (Group)
+If fetching from the first site is unsuccessful, Gnus will attempt to go
+through @code{gnus-group-faq-directory} and try to open them one by one.
+
+@item H d
+@itemx C-c C-d
+@kindex H d (Group)
+@kindex C-c C-d (Group)
@cindex describing groups
@cindex group description
@findex gnus-group-describe-group
@end table
+@node Group Timestamp
+@subsection Group Timestamp
+@cindex timestamps
+@cindex group timestamps
+
+It can be convenient to let Gnus keep track of when you last read a
+group. To set the ball rolling, you should add
+@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}:
+
+@lisp
+(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp)
+@end lisp
+
+After doing this, each time you enter a group, it'll be recorded.
+
+This information can be displayed in various ways---the easiest is to
+use the @samp{%d} spec in the group line format:
+
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n")
+@end lisp
+
+This will result in lines looking like:
+
+@example
+* 0: mail.ding 19961002T012943
+ 0: custom 19961002T012713
+@end example
+
+As you can see, the date is displayed in compact ISO 8601 format. This
+may be a bit too much, so to just display the date, you could say
+something like:
+
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n")
+@end lisp
+
+
@node File Commands
@subsection File Commands
@cindex file commands
@findex gnus-group-read-init-file
@vindex gnus-init-file
@cindex reading init file
-Read the init file (@code{gnus-init-file}, which defaults to
+Re-read the init file (@code{gnus-init-file}, which defaults to
@file{~/.gnus}) (@code{gnus-group-read-init-file}).
@item s
(@code{gnus-group-save-newsrc}). If given a prefix, force saving the
file(s) whether Gnus thinks it is necessary or not.
-@item Z
-@kindex Z (Group)
-@findex gnus-group-clear-dribble
-Clear the dribble buffer (@code{gnus-group-clear-dribble}).
+@c @item Z
+@c @kindex Z (Group)
+@c @findex gnus-group-clear-dribble
+@c Clear the dribble buffer (@code{gnus-group-clear-dribble}).
@end table
A line for each article is displayed in the summary buffer. You can
move around, read articles, post articles and reply to articles.
+The most common way to a summary buffer is to select a group from the
+group buffer (@pxref{Selecting a Group}).
+
+You can have as many summary buffers open as you wish.
+
@menu
* Summary Buffer Format:: Deciding how the summary buffer is to look.
* Summary Maneuvering:: Moving around the summary buffer.
* Marking Articles:: Marking articles as read, expirable, etc.
* Limiting:: You can limit the summary buffer.
* Threading:: How threads are made.
+* Sorting:: How articles and threads are sorted.
* Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
* Article Caching:: You may store articles in a cache.
* Persistent Articles:: Making articles expiry-resistant.
* Mail Group Commands:: Some commands can only be used in mail groups.
* Various Summary Stuff:: What didn't fit anywhere else.
* Exiting the Summary Buffer:: Returning to the Group buffer.
+* Crosspost Handling:: How crossposted articles are dealt with.
+* Duplicate Suppression:: An alternative when crosspost handling fails.
@end menu
@code{gnus-extract-address-components}, which is the default, quite
fast, and too simplistic solution; and
@code{mail-extract-address-components}, which works very nicely, but is
-slower.
+slower. The default function will return the wrong answer in 5% of the
+cases. If this is unacceptable to you, use the other function instead.
@vindex gnus-summary-same-subject
@code{gnus-summary-same-subject} is a string indicating that the current
@vindex gnus-summary-line-format
You can change the format of the lines in the summary buffer by changing
the @code{gnus-summary-line-format} variable. It works along the same
-lines a a normal @code{format} string, with some extensions.
+lines a a normal @code{format} string, with some extensions
+(@pxref{Formatting Variables}).
The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}.
@item S
Subject string.
@item s
-Subject if the article is the root, @code{gnus-summary-same-subject}
-otherwise.
+Subject if the article is the root or the previous article had a
+different subject, @code{gnus-summary-same-subject} otherwise.
+(@code{gnus-summary-same-subject} defaults to @samp{}.)
@item F
-Full @code{From} line.
+Full @code{From} header.
@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.
+spec in that it uses the function designated by the
+@code{gnus-extract-address-components} variable, which is slower, but
+may be more thorough.
@item A
The address (from the @code{From} header). This works the same way as
the @code{a} spec.
@item T
Nothing if the article is a root and lots of spaces if it isn't (it
pushes everything after it off the screen).
-@item \[
-Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
-for adopted articles.
-@item \]
-Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
+@item [
+Opening bracket, which is normally @samp{[}, but can also be @samp{<}
+for adopted articles (@pxref{Customizing Threading}).
+@item ]
+Closing bracket, which is normally @samp{]}, but can also be @samp{>}
for adopted articles.
@item >
One space for each thread level.
@code{Xref}.
@item D
@code{Date}.
+@item d
+The @code{Date} in @code{YY-MMM} format.
+@item o
+The @code{Date} in @code{YYYYMMDDTHHMMSS} format.
@item M
@code{Message-ID}.
@item r
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.
+An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the
+article has any children.
+@item P
+The line number.
@item u
User defined specifier. The next character in the format string should
be a letter. @sc{gnus} will call the function
@vindex gnus-summary-mode-line-format
You can also change the format of the summary mode bar. Set
-@code{gnus-summary-mode-line-format} to whatever you like. Here are the
-elements you can play with:
+@code{gnus-summary-mode-line-format} to whatever you like. The default
+is @samp{Gnus: %%b [%A] %Z}.
+
+Here are the elements you can play with:
@table @samp
@item G
Number of unselected articles in this group.
@item Z
A string with the number of unread and unselected articles represented
-either as @samp{<%U(+%u) more>} if there are both unread and unselected
+either as @samp{<%U(+%e) more>} if there are both unread and unselected
articles, and just as @samp{<%U more>} if there are just unread articles
and no unselected ones.
@item g
@item S
Subject of the current article.
@item u
-Used-defined spec.
+User-defined spec.
@item s
Name of the current score file.
@item d
@item gnus-summary-highlight
@vindex gnus-summary-highlight
Summary lines are highlighted according to this variable, which is a
-list where the elements are on the format @code{(FORM . FACE)}. If you
+list where the elements are on the format @var{(FORM . FACE)}. If you
would, for instance, like ticked articles to be italic and high-scored
articles to be bold, you could set this variable to something like
@lisp
@kindex j (Summary)
@kindex G j (Summary)
@findex gnus-summary-goto-article
-Ask for an article number and then go that article
+Ask for an article number and then go to that article
(@code{gnus-summary-goto-article}).
@item G g
@kindex G g (Summary)
@findex gnus-summary-goto-subject
Ask for an article number and then go the summary line of that article
-(@code{gnus-summary-goto-subject}).
+without displaying the article (@code{gnus-summary-goto-subject}).
@end table
If Gnus asks you to press a key to confirm going to the next group, you
@vindex gnus-auto-select-next
@item gnus-auto-select-next
-If you are at the end of the group and issue one of the movement
-commands, Gnus will offer to go to the next group. If this variable is
-@code{t} and the next group is empty, Gnus will exit summary mode and
-return to the group buffer. If this variable is neither @code{t} nor
-@code{nil}, Gnus will select the next group, no matter whether it has
-any unread articles or not. As a special case, if this variable is
-@code{quietly}, Gnus will select the next group without asking for
-confirmation. If this variable is @code{almost-quietly}, the same will
-happen only if you are located on the last article in the group.
-Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n}
-command will go to the next group without confirmation. Also
-@pxref{Group Levels}.
+If you issue one of the movement commands (like @kbd{n}) and there are
+no more unread articles after the current one, Gnus will offer to go to
+the next group. If this variable is @code{t} and the next group is
+empty, Gnus will exit summary mode and return to the group buffer. If
+this variable is neither @code{t} nor @code{nil}, Gnus will select the
+next group, no matter whether it has any unread articles or not. As a
+special case, if this variable is @code{quietly}, Gnus will select the
+next group without asking for confirmation. If this variable is
+@code{almost-quietly}, the same will happen only if you are located on
+the last article in the group. Finally, if this variable is
+@code{slightly-quietly}, the @kbd{Z n} command will go to the next group
+without confirmation. Also @pxref{Group Levels}.
@item gnus-auto-select-same
@vindex gnus-auto-select-same
If non-@code{nil}, all the movement commands will try to go to the next
-article with the same subject as the current. This variable is not
+article with the same subject as the current. (@dfn{Same} here might
+mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit}
+for details (@pxref{Customizing Threading}).) This variable is not
particularly useful if you use a threaded display.
@item gnus-summary-check-current
@section Choosing Articles
@cindex selecting articles
+@menu
+* Choosing Commands:: Commands for choosing articles.
+* Choosing Variables:: Variables that influence these commands.
+@end menu
+
+
+@node Choosing Commands
+@subsection Choosing Commands
+
None of the following movement commands understand the numeric prefix,
and they all select and display an article.
history as you like.
@end table
+
+@node Choosing Variables
+@subsection Choosing Variables
+
Some variables that are relevant for moving and selecting articles:
@table @code
@findex gnus-unread-mark
This hook is called whenever an article is selected. It is intended to
be used for marking articles as read. The default value is
-@code{gnus-summary-mark-unread-and-read-as-read}, and will change the
+@code{gnus-summary-mark-read-and-unread-as-read}, and will change the
mark of almost any article you read to @code{gnus-unread-mark}. The
only articles not affected by this function are ticked, dormant, and
expirable articles. If you'd instead like to just have unread articles
Scroll the current article one line forward
(@code{gnus-summary-scroll-up}).
+@item A g
+@itemx g
+@kindex A g (Summary)
+@kindex g (Summary)
+@findex gnus-summary-show-article
+(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 A <
@itemx <
@kindex < (Summary)
Scroll to the end of the article (@code{gnus-summary-end-of-article}).
@item A s
+@itemx s
@kindex A s (Summary)
+@kindex s (Summary)
@findex gnus-summary-isearch-article
Perform an isearch in the article buffer
(@code{gnus-summary-isearch-article}).
@menu
* Summary Mail Commands:: Sending mail.
* Summary Post Commands:: Sending news.
-* Summary Mail and Post Commands:: Sending both news and mail.
@end menu
Forward the current article to some other person
(@code{gnus-summary-mail-forward}).
-@item S o p
-@kindex S o p (Summary)
-@findex gnus-summary-post-forward
-Forward the current article to a newsgroup
-(@code{gnus-summary-post-forward}).
-
@item S m
@itemx m
@kindex m (Summary)
@item S D b
@kindex S D b (Summary)
@findex gnus-summary-resend-bounced-mail
-@vindex gnus-bounced-headers-junk
@cindex bouncing 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
+sending the mail off again. 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 D r
@kindex S D r (Summary)
@findex gnus-summary-resend-message
-@vindex gnus-ignored-resent-headers
Not to be confused with the previous command,
@code{gnus-summary-resend-message} will prompt you for an address to
send the current message off to, and then send it to that place. The
@code{Resent-To}, @code{Resent-From} and so on will be added. This
means that you actually send a mail to someone that has a @code{To}
header that (probably) points to yourself. This will confuse people.
-So, natcherly you'll only do that if you're really eVIl. All old
-headers that match the regular expression
-@code{gnus-ignored-resent-headers} will be deleted before resending the
-message. The default is @samp{"^Return-receipt"}.
+So, natcherly you'll only do that if you're really eVIl.
This command is mainly used if you have several accounts and want to
ship a mail to a different account of yours. (If you're both
@code{root} and @code{postmaster} and get a mail for @code{postmaster}
to the @code{root} account, you may want to resend it to
-@code{postmaster}. Ordnung muss sein!
+@code{postmaster}. Ordnung muß sein!
@item S O m
@kindex S O m (Summary)
(@code{gnus-uu-digest-mail-forward}). This command uses the
process/prefix convention (@pxref{Process/Prefix}).
-@item S O p
-@kindex S O p (Summary)
-@findex gnus-uu-digest-post-forward
-Digest the current series and forward the result to a newsgroup
-(@code{gnus-uu-digest-mail-forward}).
+@item S M-c
+@kindex S M-c (Summary)
+@findex gnus-summary-mail-crosspost-complaint
+@cindex crossposting
+@cindex excessive crossposting
+Send a complaint about excessive crossposting to the author of the
+current article (@code{gnus-summary-mail-crosspost-complaint}).
+
+@findex gnus-crosspost-complaint
+This command is provided as a way to fight back agains the current
+crossposting pandemic that's sweeping Usenet. It will compose a reply
+using the @code{gnus-crosspost-complaint} variable as a preamble. This
+command understands the process/prefix convention
+(@pxref{Process/Prefix}) and will prompt you before sending each mail.
+
@end table
@cindex post
@cindex composing news
-Commands for posting an article:
+Commands for posting a news article:
@table @kbd
@item S p
(@code{gnus-summary-followup-with-original}). This command uses the
process/prefix convention.
+@item S o p
+@kindex S o p (Summary)
+@findex gnus-summary-post-forward
+Forward the current article to a newsgroup
+(@code{gnus-summary-post-forward}).
+
+@item S O p
+@kindex S O p (Summary)
+@findex gnus-uu-digest-post-forward
+Digest the current series and forward the result to a newsgroup
+(@code{gnus-uu-digest-mail-forward}).
+
@item S u
@kindex S u (Summary)
@findex gnus-uu-post-news
@end table
-@node Summary Mail and Post Commands
-@subsection Summary Mail and Post Commands
-@cindex mail and post
-@cindex post and mail
-
-Commands for sending mail and post at the same time:
-
-@table @kbd
-@item S b
-@kindex S b (Summary)
-@findex gnus-summary-followup-and-reply
-Post a followup and send a reply to the current article
-(@code{gnus-summary-followup-and-reply}).
-
-@item S B
-@kindex S B (Summary)
-@findex gnus-summary-followup-and-reply-with-original
-Post a followup and send a reply to the current article and include the
-original message (@code{gnus-summary-followup-and-reply-with-original}).
-This command uses the process/prefix convention.
-@end table
-
-
@node Canceling and Superseding
@section Canceling Articles
@cindex canceling articles
where you can edit the article all you want before sending it off the
usual way.
-@vindex gnus-delete-supersedes-headers
-You probably want to delete some of the old headers before sending the
-superseding article---@code{Path} and @code{Date} are probably
-incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
-match the lines you want removed. The default is
-@samp{^Path:\\|^Date}.
-
The same goes for superseding as for canceling, only more so: Some
sites do not honor superseding. On those sites, it will appear that you
have posted almost the same article twice.
to the post buffer (which is called @code{*post-buf*}). There you will
find the article you just posted, with all the headers intact. Change
the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes}
-header by substituting one of those words for @code{Message-ID}. Then
-just press @kbd{C-c C-c} to send the article as you would do normally.
-The previous article will be canceled/superseded.
+header by substituting one of those words for the word
+@code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as
+you would do normally. The previous article will be
+canceled/superseded.
Just remember, kids: There is no 'c' in 'supersede'.
@node Unread Articles
@subsection Unread Articles
-The following marks mark articles as unread, in one form or other.
+The following marks mark articles as (kinda) unread, in one form or
+other.
-@vindex gnus-dormant-mark
-@vindex gnus-ticked-mark
@table @samp
@item !
+@vindex gnus-ticked-mark
+Marked as ticked (@code{gnus-ticked-mark}).
+
@dfn{Ticked articles} are articles that will remain visible always. If
you see an article that you find interesting, or you want to put off
reading it, or replying to it, until sometime later, you'd typically
tick it. However, articles can be expired, so if you want to keep an
-article forever, you'll have to save it. Ticked articles have a
-@samp{!} (@code{gnus-ticked-mark}) in the first column.
+article forever, you'll have to make it persistent (@pxref{Persistent
+Articles}).
@item ?
@vindex gnus-dormant-mark
-A @dfn{dormant} article is marked with a @samp{?}
-(@code{gnus-dormant-mark}), and will only appear in the summary buffer
-if there are followups to it.
+Marked as dormant (@code{gnus-dormant-mark}).
+
+@dfn{Dormant articles} will only appear in the summary buffer if there
+are followups to it.
@item SPACE
@vindex gnus-unread-mark
-An @dfn{unread} article is marked with a @samp{SPACE}
-(@code{gnus-unread-mark}). These are articles that haven't been read at
-all yet.
+Markes as unread (@code{gnus-unread-mark}).
+
+@dfn{Unread articles} are articles that haven't been read at all yet.
@end table
@item r
@vindex gnus-del-mark
-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.
+These are articles that the user has marked as read with the @kbd{d}
+command manually, more or less (@code{gnus-del-mark}).
@item R
@vindex gnus-read-mark
-Articles that are actually read are marked with @samp{R}
-(@code{gnus-read-mark}).
+Articles that have actually been read (@code{gnus-read-mark}).
@item O
@vindex gnus-ancient-mark
-Articles that were marked as read in previous sessions are now
-@dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
+Articles that were marked as read in previous sessions and are now
+@dfn{old} (@code{gnus-ancient-mark}).
@item K
@vindex gnus-killed-mark
@item F
@vindex gnus-souped-mark
-@sc{SOUP}ed article (@code{gnus-souped-mark}).
+@sc{SOUP}ed article (@code{gnus-souped-mark}). @xref{SOUP}.
@item Q
@vindex gnus-sparse-mark
-Sparsely reffed article (@code{gnus-sparse-mark}).
+Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing
+Threading}.
+
+@item M
+@vindex gnus-duplicate-mark
+Article marked as read by duplicate suppression
+(@code{gnus-duplicated-mark}). @xref{Duplicate Suppression}.
+
@end table
All these marks just mean that the article is marked as read, really.
-They are interpreted differently by the adaptive scoring scheme,
-however.
+They are interpreted differently when doing adaptive scoring, though.
One more special mark, though:
@table @samp
@item E
@vindex gnus-expirable-mark
-You can also mark articles as @dfn{expirable} (or have them marked as
-such automatically). That doesn't make much sense in normal groups,
-because a user does not control the expiring of news articles, but in
-mail groups, for instance, articles that are marked as @dfn{expirable}
-can be deleted by Gnus at any time. Expirable articles are marked with
-@samp{E} (@code{gnus-expirable-mark}).
+Marked as expirable (@code{gnus-expirable-mark}).
+
+Marking articles as @dfn{expirable} (or have them marked as such
+automatically) doesn't make much sense in normal groups---a user doesn't
+control the expiring of news articles, but in mail groups, for instance,
+articles that are marked as @dfn{expirable} can be deleted by Gnus at
+any time.
@end table
long thesis on cats' urinary tracts, and have to go home for dinner
before you've finished reading the thesis. You can then set a bookmark
in the article, and Gnus will jump to this bookmark the next time it
-encounters the article.
+encounters the article. @xref{Setting Marks}
@item
@vindex gnus-replied-mark
Mark the current article as read
(@code{gnus-summary-mark-as-read-forward}).
+@item D
+@kindex D (Summary)
+@findex gnus-summary-mark-as-read-backward
+Mark the current article as read and move point to the previous line
+(@code{gnus-summary-mark-as-read-backward}).
+
@item M k
@itemx k
@kindex k (Summary)
@item M C
@kindex M C (Summary)
@findex gnus-summary-catchup
-Mark all unread articles in the group as read
-(@code{gnus-summary-catchup}).
+Mark all unread articles as read (@code{gnus-summary-catchup}).
@item M C-c
@kindex M C-c (Summary)
Remove the process mark from all articles
(@code{gnus-summary-unmark-all-processable}).
+@item M P i
+@kindex M P i (Summary)
+@findex gnus-uu-invert-processable
+Invert the list of process marked articles
+(@code{gnus-uu-invert-processable}).
+
@item M P R
@kindex M P R (Summary)
@findex gnus-uu-mark-by-regexp
@findex gnus-uu-mark-buffer
Mark all articles in the buffer in the order they appear
(@code{gnus-uu-mark-buffer}).
+
+@item M P k
+@kindex M P k (Summary)
+@findex gnus-summary-kill-process-mark
+Push the current process mark set onto the stack and unmark all articles
+(@code{gnus-summary-kill-process-mark}).
+
+@item M P y
+@kindex M P y (Summary)
+@findex gnus-summary-yank-process-mark
+Pop the previous process mark set from the stack and restore it
+(@code{gnus-summary-yank-process-mark}).
+
+@item M P w
+@kindex M P w (Summary)
+@findex gnus-summary-save-process-mark
+Push the current process mark set onto the stack
+(@code{gnus-summary-save-process-mark}).
+
@end table
(setq gnus-simplify-ignored-prefixes
(concat
"\\`\\[?\\("
+ (mapconcat
+ 'identity
+ '("looking"
+ "wanted" "followup" "summary\\( of\\)?"
+ "help" "query" "problem" "question"
+ "answer" "reference" "announce"
+ "How can I" "How to" "Comparison of"
+ ;; ...
+ )
+ "\\|")
+ "\\)\\s *\\("
(mapconcat 'identity
- '("looking"
- "wanted" "followup" "summary\\( of\\)?"
- "help" "query" "problem" "question"
- "answer" "reference" "announce"
- "How can I" "How to" "Comparison of"
- ;; ...
- )
+ '("for" "for reference" "with" "about")
"\\|")
- "\\)\\s *\\("
- (mapconcat 'identity
- '("for" "for reference" "with" "about")
- "\\|")
- "\\)?\\]?:?[ \t]*"))
+ "\\)?\\]?:?[ \t]*"))
@end lisp
All words that match this regexp will be removed before comparing two
@item gnus-thread-indent-level
@vindex gnus-thread-indent-level
This is a number that says how much each sub-thread should be indented.
-The default is @code{4}.
+The default is 4.
@end table
@kindex T k (Summary)
@kindex M-C-k (Summary)
@findex gnus-summary-kill-thread
-Mark all articles in the current sub-thread as read
+Mark all articles in the current (sub-)thread as read
(@code{gnus-summary-kill-thread}). If the prefix argument is positive,
remove all marks instead. If the prefix argument is negative, tick
articles instead.
@kindex T l (Summary)
@kindex M-C-l (Summary)
@findex gnus-summary-lower-thread
-Lower the score of the current thread
+Lower the score of the current (sub-)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
+Increase the score of the current (sub-)thread
(@code{gnus-summary-raise-thread}).
@item T #
@kindex T # (Summary)
@findex gnus-uu-mark-thread
-Set the process mark on the current thread
+Set the process mark on the current (sub-)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
+Remove the process mark from the current (sub-)thread
(@code{gnus-uu-unmark-thread}).
@item T T
@item T s
@kindex T s (Summary)
@findex gnus-summary-show-thread
-Expose the thread hidden under the current article, if any
+Expose the (sub-)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}).
+Hide the current (sub-)thread (@code{gnus-summary-hide-thread}).
@item T S
@kindex T S (Summary)
that have subjects that are fuzzily equal will be included.
-@node Asynchronous Fetching
-@section Asynchronous Article Fetching
-@cindex asynchronous article fetching
+@node Sorting
+@section Sorting
-If you read your news from an @sc{nntp} server that's far away, the
-network latencies may make reading articles a chore. You have to wait
-for a while after pressing @kbd{n} to go to the next article before the
-article appears. Why can't Gnus just go ahead and fetch the article
-while you are reading the previous one? Why not, indeed.
+@findex gnus-thread-sort-by-total-score
+@findex gnus-thread-sort-by-date
+@findex gnus-thread-sort-by-score
+@findex gnus-thread-sort-by-subject
+@findex gnus-thread-sort-by-author
+@findex gnus-thread-sort-by-number
+@vindex gnus-thread-sort-functions
+If you are using a threaded summary display, you can sort the threads by
+setting @code{gnus-thread-sort-functions}, which is a list of functions.
+By default, sorting is done on article numbers. Ready-made sorting
+predicate functions include @code{gnus-thread-sort-by-number},
+@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
+@code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
+@code{gnus-thread-sort-by-total-score}.
-First, some caveats. There are some pitfalls to using asynchronous
+Each function takes two threads and return non-@code{nil} if the first
+thread should be sorted before the other. Note that sorting really is
+normally done by looking only at the roots of each thread. If you use
+more than one function, the primary sort key should be the last function
+in the list. You should probably always include
+@code{gnus-thread-sort-by-number} in the list of sorting
+functions---preferably first. This will ensure that threads that are
+equal with respect to the other sort criteria will be displayed in
+ascending article order.
+
+If you would like to sort by score, then by subject, and finally by
+number, you could do something like:
+
+@lisp
+(setq gnus-thread-sort-functions
+ '(gnus-thread-sort-by-number
+ gnus-thread-sort-by-subject
+ gnus-thread-sort-by-score))
+@end lisp
+
+The threads that have highest score will be displayed first in the
+summary buffer. When threads have the same score, they will be sorted
+alphabetically. The threads that have the same score and the same
+subject will be sorted by number, which is (normally) the sequence in
+which the articles arrived.
+
+If you want to sort by score and then reverse arrival order, you could
+say something like:
+
+@lisp
+(setq gnus-thread-sort-functions
+ '((lambda (t1 t2)
+ (not (gnus-thread-sort-by-number t1 t2)))
+ gnus-thread-sort-by-score))
+@end lisp
+
+@vindex gnus-thread-score-function
+The function in the @code{gnus-thread-score-function} variable (default
+@code{+}) is used for calculating the total score of a thread. Useful
+functions might be @code{max}, @code{min}, or squared means, or whatever
+tickles your fancy.
+
+@findex gnus-article-sort-functions
+@findex gnus-article-sort-by-date
+@findex gnus-article-sort-by-score
+@findex gnus-article-sort-by-subject
+@findex gnus-article-sort-by-author
+@findex gnus-article-sort-by-number
+If you are using an unthreaded display for some strange reason or other,
+you have to fiddle with the @code{gnus-article-sort-functions} variable.
+It is very similar to the @code{gnus-thread-sort-functions}, except that
+is uses slightly different functions for article comparison. Available
+sorting predicate functions are @code{gnus-article-sort-by-number},
+@code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
+@code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
+
+If you want to sort an unthreaded summary display by subject, you could
+say something like:
+
+@lisp
+(setq gnus-article-sort-functions
+ '(gnus-article-sort-by-number
+ gnus-article-sort-by-subject))
+@end lisp
+
+
+
+@node Asynchronous Fetching
+@section Asynchronous Article Fetching
+@cindex asynchronous article fetching
+@cindex article pre-fetch
+@cindex pre-fetch
+
+If you read your news from an @sc{nntp} server that's far away, the
+network latencies may make reading articles a chore. You have to wait
+for a while after pressing @kbd{n} to go to the next article before the
+article appears. Why can't Gnus just go ahead and fetch the article
+while you are reading the previous one? Why not, indeed.
+
+First, some caveats. There are some pitfalls to using asynchronous
article fetching, especially the way Gnus does it.
Let's say you are reading article 1, which is short, and article 2 is
Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
happen automatically.
-@vindex nntp-async-number
+@vindex gnus-use-article-prefetch
You can control how many articles that are to be pre-fetched by setting
-@code{nntp-async-number}. This is five by default, which means that when
-you read an article in the group, @code{nntp} will pre-fetch the next
-five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
-all the articles that it can without bound. If it is @code{nil}, no
-pre-fetching will be made.
-
-@vindex gnus-asynchronous-article-function
-You may wish to create some sort of scheme for choosing which articles
-that @code{nntp} should consider as candidates for pre-fetching. For
-instance, you may wish to pre-fetch all articles with high scores, and
-not pre-fetch low-scored articles. You can do that by setting the
-@code{gnus-asynchronous-article-function}, which will be called with an
-alist where the keys are the article numbers. Your function should
-return an alist where the articles you are not interested in have been
-removed. You could also do sorting on article score and the like.
+@code{gnus-use-article-prefetch}. This is 30 by default, which means
+that when you read an article in the group, the backend will pre-fetch
+the next 30 articles. If this variable is @code{t}, the backend will
+pre-fetch all the articles that it can without bound. If it is
+@code{nil}, no pre-fetching will be made.
+
+@vindex gnus-async-prefetch-article-p
+@findex gnus-async-read-p
+There are probably some articles that you don't want to pre-fetch---read
+articles, for instance. Which articles to pre-fetch is controlled by
+the @code{gnus-async-prefetch-article-p} variable. This function should
+return non-@code{nil} when the article in question is to be
+pre-fetched. The default is @code{gnus-async-read-p}, which returns
+@code{nil} on read articles. The function is called with an article
+data structure as the only parameter.
+
+If, for instance, you wish to pre-fetch only unread articles that are
+shorter than 100 lines, you could say something like:
+
+@lisp
+(defun my-async-short-unread-p (data)
+ "Return non-nil for short, unread articles."
+ (and (gnus-data-unread-p data)
+ (< (mail-header-lines (gnus-data-header data))
+ 100)))
+
+(setq gnus-async-prefetch-article-p 'my-async-short-unread-p)
+@end lisp
+
+These functions will be called many, many times, so they should
+preferrably be short and sweet to avoid slowing down Gnus too much.
+It's also probably a good idea to byte-compile things like this.
+
+@vindex gnus-prefetched-article-deletion-strategy
+Articles have to be removed from the asynch buffer sooner or later. The
+@code{gnus-prefetched-article-deletion-strategy} says when to remove
+articles. This is a list that may contain the following elements:
+
+@table @code
+@item read
+Remove articles when they are read.
+
+@item exit
+Remove articles when exiting the group.
+@end table
+
+The default value is @code{(read exit)}.
+
+@vindex gnus-use-header-prefetch
+If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles
+from the next group.
@node Article Caching
@item gnus-Numeric-save-name
@findex gnus-Numeric-save-name
-Generates file names that look like @file{~/News/Alt.andrea-dworkin/45}.
+File names like @file{~/News/Alt.andrea-dworkin/45}.
@item gnus-numeric-save-name
@findex gnus-numeric-save-name
-Generates file names that look like @file{~/News/alt.andrea-dworkin/45}.
+File names like @file{~/News/alt.andrea-dworkin/45}.
@item gnus-Plain-save-name
@findex gnus-Plain-save-name
-Generates file names that look like @file{~/News/Alt.andrea-dworkin}.
+File names like @file{~/News/Alt.andrea-dworkin}.
@item gnus-plain-save-name
@findex gnus-plain-save-name
-Generates file names that look like @file{~/News/alt.andrea-dworkin}.
+File names like @file{~/News/alt.andrea-dworkin}.
@end table
@vindex gnus-split-methods
We see that this is a list where each element is a list that has two
elements---the @dfn{match} and the @dfn{file}. The match can either be
a string (in which case it is used as a regexp to match on the article
-head); it can be a symbol (which will be called as a function); or it
-can be a list (which will be @code{eval}ed). If any of these actions
-have a non-@code{nil} result, the @dfn{file} will be used as a default
-prompt. In addition, the result of the operation itself will be used if
-the function or form called returns a string or a list of strings.
+head); it can be a symbol (which will be called as a function with the
+group name as a parameter); or it can be a list (which will be
+@code{eval}ed). If any of these actions have a non-@code{nil} result,
+the @dfn{file} will be used as a default prompt. In addition, the
+result of the operation itself will be used if the function or form
+called returns a string or a list of strings.
You basically end up with a list of file names that might be used when
saving the current article. (All ``matches'' will be used.) You will
for instance, @code{sox} to convert an @samp{.au} sound file, you could
say something like:
@lisp
- (setq gnus-uu-user-view-rules
- (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
+(setq gnus-uu-user-view-rules
+ (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
@end lisp
@item gnus-uu-user-view-rules-end
* Article Washing:: Lots of way-neat functions to make life better.
* Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
* Article Date:: Grumble, UT!
+* Article Signature:: What is a signature?
@end menu
@item gnus-supercite-regexp
@vindex gnus-supercite-regexp
-Regexp matching normal SuperCite attribution lines.
+Regexp matching normal Supercite attribution lines.
@item gnus-supercite-secondary-regexp
@vindex gnus-supercite-secondary-regexp
-Regexp matching mangled SuperCite attribution lines.
+Regexp matching mangled Supercite attribution lines.
@item gnus-cite-minimum-match-count
@vindex gnus-cite-minimum-match-count
@vindex gnus-signature-face
@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 and will be highlighted with
-@code{gnus-signature-face}, which is @code{italic} by default.
+Everything after @code{gnus-signature-separator} (@pxref{Article
+Signature}) in an article will be considered a signature and will be
+highlighted with @code{gnus-signature-face}, which is @code{italic} by
+default.
@end table
@item W W s
@kindex W W s (Summary)
@findex gnus-article-hide-signature
-Hide signature (@code{gnus-article-hide-signature}).
+Hide signature (@code{gnus-article-hide-signature}). @xref{Article
+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 P
+@kindex W W P (Summary)
+@findex gnus-article-hide-pem
+Hide @sc{pem} (privacy enhanced messages) gruft
+(@code{gnus-article-hide-pem}).
+
@item W W c
@kindex W W c (Summary)
@findex gnus-article-hide-citation
@vindex gnus-cited-text-button-line-format
Gnus adds buttons show where the cited text has been hidden, and to
allow toggle hiding the text. The format of the variable is specified
-by this format-like variable. These specs are legal:
+by this format-like variable (@pxref{Formatting Variables}). These
+specs are legal:
@table @samp
@item b
Also @pxref{Article Highlighting} for further variables for
citation customization.
-@vindex gnus-signature-limit
-@code{gnus-signature-limit} provides a limit to what is considered a
-signature. If it is a number, no signature may not be longer (in
-characters) than that number. If it is a function, the function will be
-called without any parameters, and if it returns @code{nil}, there is no
-signature in the buffer. If it is a string, it will be used as a
-regexp. If it matches, the text in question is not a signature.
-
@node Article Washing
@subsection Article Washing
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
-(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
@item W w
@kindex W w (Summary)
@findex gnus-article-fill-cited-article
-Do word wrap (@code{gnus-article-fill-cited-article}).
+Do word wrap (@code{gnus-article-fill-cited-article}). If you use this
+function in @code{gnus-article-display-hook}, it should be run fairly
+late and certainly after any highlighting.
@item W c
@kindex W c (Summary)
@findex gnus-article-remove-cr
Remove CR (@code{gnus-article-remove-cr}).
-@item W L
-@kindex W L (Summary)
-@findex gnus-article-remove-trailing-blank-lines
-Remove all blank lines at the end of the article
-(@code{gnus-article-remove-trailing-blank-lines}).
-
@item W q
@kindex W q (Summary)
@findex gnus-article-de-quoted-unreadable
@vindex gnus-article-x-face-too-ugly
Look for and display any X-Face headers
(@code{gnus-article-display-x-face}). The command executed by this
-function is given by the @code{gnus-article-x-face-command} variable. If
-this variable is a string, this string will be executed in a sub-shell.
-If it is a function, this function will be called with the face as the
-argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
-matches the @code{From} header, the face will not be shown.
+function is given by the @code{gnus-article-x-face-command} variable.
+If this variable is a string, this string will be executed in a
+sub-shell. If it is a function, this function will be called with the
+face as the argument. If the @code{gnus-article-x-face-too-ugly} (which
+is a regexp) matches the @code{From} header, the face will not be shown.
+The default action under Emacs is to fork off an @code{xv} to view the
+face; under XEmacs the default action is to display the face before the
+@code{From} header. (It's nicer if XEmacs has been compiled with X-Face
+support---that will make display somewhat faster. If there's no native
+X-Face support, Gnus will try to convert the @code{X-Face} header using
+external programs from the @code{pbmplus} package and friends.) If you
+want to have this function in the display hook, it should probably come
+last.
@item W b
@kindex W b (Summary)
Add clickable buttons to the article headers
(@code{gnus-article-add-buttons-to-head}).
+@item W E l
+@kindex W E l (Summary)
+@findex gnus-article-strip-leading-blank-lines
+Remove all blank lines from the beginning of the article
+(@code{gnus-article-strip-leading-blank-lines}).
+
+@item W E m
+@kindex W E m (Summary)
+@findex gnus-article-strip-multiple-blank-lines
+Replace all blank lines with empty lines and then all multiple empty
+lines with a single empty line.
+(@code{gnus-article-strip-multiple-blank-lines}).
+
+@item W E t
+@kindex W E t (Summary)
+@findex gnus-article-remove-trailing-blank-lines
+Remove all blank lines at the end of the article
+(@code{gnus-article-remove-trailing-blank-lines}).
+
+@item W E a
+@kindex W E a (Summary)
+@findex gnus-article-strip-blank-lines
+Do all the three commands above
+(@code{gnus-article-strip-blank-lines}).
+
@end table
@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 @code{0} here.
+highlighted. If you want it all highlighted, you use 0 here.
@item use-p
This form will be @code{eval}ed, and if the result is non-@code{nil},
@item gnus-article-button-face
@vindex gnus-article-button-face
-Face used on bottons.
+Face used on buttons.
@item gnus-article-mouse-face
@vindex gnus-article-mouse-face
@end table
+@node Article Signature
+@subsection Article Signature
+@cindex signatures
+@cindex article signature
+
+@vindex gnus-signature-separator
+Each article is divided into two parts---the head and the body. The
+body can be divided into a signature part and a text part. The variable
+that says what is to be considered a signature is
+@code{gnus-signature-separator}. This is normally the standard
+@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use
+non-standard signature separators, so this variable can also be a list
+of regular expressions to be tested, one by one. (Searches are done
+from the end of the body towards the beginning.) One likely value is:
+
+@lisp
+(setq gnus-signature-separator
+ '("^-- $" ; The standard
+ "^-- *$" ; A common mangling
+ "^-------*$" ; Many people just use a looong
+ ; line of dashes. Shame!
+ "^ *--------*$" ; Double-shame!
+ "^________*$" ; Underscores are also popular
+ "^========*$")) ; Pervert!
+@end lisp
+
+The more permissive you are, the more likely it is that you'll get false
+positives.
+
+@vindex gnus-signature-limit
+@code{gnus-signature-limit} provides a limit to what is considered a
+signature.
+
+@enumerate
+@item
+If it is an integer, no signature may be longer (in characters) than
+that integer.
+@item
+If it is a floating point number, no signature may be longer (in lines)
+than that number.
+@item
+If it is a function, the function will be called without any parameters,
+and if it returns @code{nil}, there is no signature in the buffer.
+@item
+If it is a string, it will be used as a regexp. If it matches, the text
+in question is not a signature.
+@end enumerate
+
+This variable can also be a list where the elements may be of the types
+listed above.
+
+
@node Summary Sorting
@section Summary Sorting
@cindex summary sorting
@findex gnus-summary-refer-parent-article
@kindex ^ (Summary)
If you'd like to read the parent of the current article, and it is not
-displayed in the article buffer, you might still be able to. That is,
+displayed in the summary buffer, you might still be able to. That is,
if the current group is fetched by @sc{nntp}, the parent hasn't expired
and the @code{References} in the current article are not mangled, you
can just press @kbd{^} or @kbd{A r}
you'll get the parent. If the parent is already displayed in the
summary buffer, point will just move to this article.
+If given a positive numerical prefix, fetch that many articles back into
+the ancestry. If given a negative numerical prefix, fetch just that
+ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the
+grandparent and the grandgrandparent of the current article. If you say
+@kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current
+article.
+
@findex gnus-summary-refer-references
@kindex A R (Summary)
You can have Gnus fetch all articles mentioned in the @code{References}
You can also ask the @sc{nntp} server for an arbitrary article, no
matter what group it belongs to. @kbd{M-^}
(@code{gnus-summary-refer-article}) will ask you for a
-@code{Message-ID}, which is one of those long thingies that look
-something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
-it all exactly right. No fuzzy searches, I'm afraid.
+@code{Message-ID}, which is one of those long, hard-to-read thingies
+that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You
+have to get it all exactly right. No fuzzy searches, I'm afraid.
@vindex gnus-refer-article-method
If the group you are reading is located on a backend that does not
Here are the available keystrokes when using pick mode:
@table @kbd
+@item .
+@kindex . (Pick)
+@findex gnus-summary-mark-as-processable
+Pick the article on the current line
+(@code{gnus-summary-mark-as-processable}). If given a numerical prefix,
+go to the article on that line and pick that article. (The line number
+is normally displayed on the beginning of the summary pick lines.)
+
@item SPACE
@kindex SPACE (Pick)
-@findex gnus-summary-mark-as-processable
-Pick the article (@code{gnus-summary-mark-as-processable}).
+@findex gnus-pick-next-page
+Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If
+at the end of the buffer, start reading the picked articles.
@item u
@kindex u (Pick)
@item e
@kindex e (Pick)
-@findex gnus-uu-unmark-regexp
-Pick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
+@findex gnus-uu-mark-by-regexp
+Pick articles that match a regexp (@code{gnus-uu-mark-by-regexp}).
@item E
@kindex E (Pick)
-@findex gnus-uu-unmark-regexp
-Unpick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
+@findex gnus-uu-unmark-by-regexp
+Unpick articles that match a regexp (@code{gnus-uu-unmark-by-regexp}).
@item b
@kindex b (Pick)
@vindex gnus-pick-mode-hook
@code{gnus-pick-mode-hook} is run in pick minor mode buffers.
+@vindex gnus-mark-unpicked-articles-as-read
+If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark
+all unpicked articles as read. The default is @code{nil}.
+
+@vindex gnus-summary-pick-line-format
+The summary line format in pick mode is slightly different than the
+standard format. At the beginning of each line the line number is
+displayed. The pick mode line format is controlled by the
+@code{gnus-summary-pick-line-format} variable (@pxref{Formatting
+Variables}). It accepts the same format specs that
+@code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}).
+
@node Binary Groups
@subsection Binary Groups
@example
@{***@}-(***)-[odd]-[Gun]
- | \[Jan]
- | \[odd]-[Eri]
- | \(***)-[Eri]
- | \[odd]-[Paa]
+ | \[Jan]
+ | \[odd]-[Eri]
+ | \(***)-[Eri]
+ | \[odd]-[Paa]
\[Bjo]
\[Gun]
\[Gun]-[Jor]
@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
+Delete all the expirable articles in the group
(@code{gnus-summary-expire-articles-now}). This means that @strong{all}
articles that are eligible for expiry in the current group will
disappear forever into that big @file{/dev/null} in the sky.
@item B DEL
@kindex B DEL (Summary)
-@findex gnus-summary-delete-articles
+@findex gnus-summary-delete-article
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}).
(@code{gnus-summary-import-article}). You will be prompted for a file
name, a @code{From} header and a @code{Subject} header.
-Something similar can be done by just starting to compose a mail
-message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
-@kbd{C-c M-C-p} instead. This will put the message you have just created
-into the current mail group.
-
@item B r
@kindex B r (Summary)
@findex gnus-summary-respool-article
If you want to re-spool an article, you might be curious as to what group
the article will end up in before you do the re-spooling. This command
will tell you (@code{gnus-summary-respool-query}).
+
+@item B p
+@kindex B p (Summary)
+@findex gnus-summary-article-posted-p
+Some people have a tendency to send you "courtesy" copies when they
+follow up to articles you have posted. These usually have a
+@code{Newsgroups} header in them, but not always. This command
+(@code{gnus-summary-article-posted-p}) will try to fetch the current
+article from your news server (or rather, from
+@code{gnus-refer-article-method} or @code{gnus-select-method}) and will
+report back whether it found the article or not. Even if it says that
+it didn't find the article, it may have been posted anyway---mail
+propagation is much faster than news propagation, and the news copy may
+just not have arrived yet.
+
@end table
@vindex gnus-move-split-methods
@menu
* Summary Group Information:: Information oriented commands.
* Searching for Articles:: Multiple article commands.
+* Summary Generation Commands:: (Re)generating the summary buffer.
* Really Various Summary Commands:: Those pesky non-conformant commands.
@end menu
@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}).
+Give an extremely brief description of the most important summary
+keystrokes (@code{gnus-summary-describe-briefly}).
@item H i
@kindex H i (Summary)
the process mark (@code{gnus-summary-universal-argument}).
@end table
+@node Summary Generation Commands
+@subsection Summary Generation Commands
+
+@table @kbd
+
+@item Y g
+@kindex Y g (Summary)
+@findex gnus-summary-prepare
+Regenerate the current summary buffer (@code{gnus-summary-prepare}).
+
+@item Y c
+@kindex Y c (Summary)
+@findex gnus-summary-insert-cached-articles
+Pull all cached articles (for the current group) into the summary buffer
+(@code{gnus-summary-insert-cached-articles}).
+
+@end table
+
@node Really Various Summary Commands
@subsection Really Various Summary Commands
@table @kbd
-@item A D
-@kindex A D (Summary)
+@item C-d
+@kindex C-d (Summary)
@findex gnus-summary-enter-digest-group
If the current article is a collection of other articles (for instance,
a digest), you might use this command to enter a group based on the that
guess what article type is currently displayed unless you give a prefix
to this command, which forces a ``digest'' interpretation. Basically,
whenever you see a message that is a collection of other messages on
-some format, you @kbd{A D} and read these messages in a more convenient
+some format, you @kbd{C-d} and read these messages in a more convenient
fashion.
+@item M-C-d
+@kindex M-C-d (Summary)
+@findex gnus-summary-read-document
+This command is very similar to the one above, but lets you gather
+several documents into one biiig group
+(@code{gnus-summary-read-document}). It does this by opening several
+@code{nndoc} groups for each document, and then opening an
+@code{nnvirtual} group on top of these @code{nndoc} groups. This
+command understands the process/prefix convention
+(@pxref{Process/Prefix}).
+
@item C-t
@kindex C-t (Summary)
@findex gnus-summary-toggle-truncation
-Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
+Toggle truncation of summary lines
+(@code{gnus-summary-toggle-truncation}). This will probably confuse the
+line centering function in the summary buffer, so it's not a good idea
+to have truncation switched off while reading articles.
@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
this group and are marked as read, will also be marked as read in the
other subscribed groups they were cross-posted to. If this variable is
neither @code{nil} nor @code{t}, the article will be marked as read in
-both subscribed and unsubscribed groups.
+both subscribed and unsubscribed groups (@pxref{Crosspost Handling}).
+
+
+@node Crosspost Handling
+@section Crosspost Handling
@cindex velveeta
@cindex spamming
posted it to several groups separately. Posting the same article to
several groups (not cross-posting) is called @dfn{spamming}, and you are
by law required to send nasty-grams to anyone who perpetrates such a
-heinous crime.
+heinous crime. You may want to try NoCeM handling to filter out spam
+(@pxref{NoCeM}).
Remember: Cross-posting is kinda ok, but posting the same article
-separately to several groups is not.
+separately to several groups is not. Massive cross-posting (aka.
+@dfn{velveeta}) is to be avoided at all costs, and you can even use the
+@code{gnus-summary-mail-crosspost-complaint} command to complain about
+excessive crossposting (@pxref{Summary Mail Commands}).
@cindex cross-posting
@cindex Xref
C'est la vie.
+For an alternative approach, @pxref{Duplicate Suppression}.
+
+
+@node Duplicate Suppression
+@section Duplicate Suppression
+
+By default, Gnus tries to make sure that you don't have to read the same
+article more than once by utilizing the crossposting mechanism
+(@pxref{Crosspost Handling}). However, that simple and efficient
+approach may not work satisfactorily for some users for various
+reasons.
+
+@enumerate
+@item
+The @sc{nntp} server may fail to generate the @code{Xref} header. This
+is evil and not very common.
+
+@item
+The @sc{nntp} server may fail to include the @code{Xref} header in the
+@file{.overview} data bases. This is evil and all too common, alas.
+
+@item
+You may be reading the same group (or several related groups) from
+different @sc{nntp} servers.
+
+@item
+You may be getting mail that duplicates articles posted to groups.
+@end enumerate
+
+I'm sure there are other situations that @code{Xref} handling fails as
+well, but these four are the most common situations.
+
+If, and only if, @code{Xref} handling fails for you, then you may
+consider switching on @dfn{duplicate suppression}. If you do so, Gnus
+will remember the @code{Message-ID}s of all articles you have read or
+otherwise marked as read, and then, as if by magic, mark them as read
+all subsequent times you see them---in @emph{all} groups. Using this
+mechanism is quite likely to be somewhat inefficient, but not overly
+so. It's certainly preferable to reading the same articles more than
+once.
+
+Duplicate suppression is not a very subtle instrument. It's more like a
+sledge hammer than anything else. It works in a very simple
+fashion---if you have marked an article as read, it adds this Message-ID
+to a cache. The next time it sees this Message-ID, it will mark the
+article as read the the @samp{M} mark. It doesn't care what group it
+saw the article in.
+
+@table @code
+@item gnus-suppress-duplicates
+@vindex gnus-suppress-duplicates
+If non-@code{nil}, suppress duplicates.
+
+@item gnus-save-duplicate-list
+@vindex gnus-save-duplicate-list
+If non-@code{nil}, save the list of duplicates to a file. This will
+make startup and shutdown take longer, so the default is @code{nil}.
+However, this means that only duplicate articles that is read in a
+single Gnus session are suppressed.
+
+@item gnus-duplicate-list-length
+@vindex gnus-duplicate-list-length
+This variables says how many @code{Message-ID}s to keep in the duplicate
+suppression list. The default is 10000.
+
+@item gnus-duplicate-file
+@vindex gnus-duplicate-file
+The name of the file to store the duplicate suppression list. The
+default is @file{~/News/suppression}.
+@end table
+
+If you have a tendency to stop and start Gnus often, setting
+@code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If
+you leave Gnus running for weeks on end, you may have it @code{nil}. On
+the other hand, saving the list makes startup and shutdown much slower,
+so that means that if you stop and start Gnus often, you should set
+@code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up
+to you to figure out, I think.
+
@node The Article Buffer
@chapter The Article Buffer
* 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
+* Article Keymap:: Keystrokes available in the article buffer.
* Misc Article:: Other stuff.
@end menu
@vindex gnus-show-mime-method
@vindex gnus-strict-mime
@findex metamail-buffer
-Gnus handles @sc{mime} by shoving the articles through
+Gnus handles @sc{mime} by pushing the articles through
@code{gnus-show-mime-method}, which is @code{metamail-buffer} by
default. Set @code{gnus-show-mime} to @code{t} if you want to use
@sc{mime} all the time. However, if @code{gnus-strict-mime} is
non-@code{nil}, the @sc{mime} method will only be used if there are
-@sc{mime} headers in the article.
+@sc{mime} headers in the article. If you have @code{gnus-show-mime}
+set, then you'll see some unfortunate display glitches in the article
+buffer. These can't be avoided.
It might be best to just use the toggling functions from the summary
buffer to avoid getting nasty surprises. (For instance, you enter the
treatment of the article before it is displayed.
@findex gnus-article-maybe-highlight
-By default it contains @code{gnus-article-hide-headers},
+By default this hook just 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 @pxref{Article Highlighting}, @pxref{Article Hiding},
@pxref{Article Washing}, @pxref{Article Buttons} and @pxref{Article
-Date}.
+Date}. Note that the order of functions in this hook might affect
+things, so you may have to fiddle a bit to get the desired results.
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.
@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.
+@code{gnus-summary-mode-line-format}. It accepts the same
+format specifications as that variable, with one extension:
+
+@table @samp
+@item w
+The @dfn{wash status} of the article. This is a short string with one
+character for each possible article wash operation that may have been
+performed.
+@end table
+
@vindex gnus-break-pages
@item gnus-break-pages
@end table
-@node Message
-@chapter Message
+@node Composing Messages
+@chapter Composing Messages
@cindex reply
@cindex followup
@cindex post
-All message composition (both mail and news) takes place in
-@code{message} mode buffers.
+@kindex C-c C-c (Post)
+All commands for posting and mailing will put you in a message buffer
+where you can edit the article all you like, before you send the article
+by pressing @kbd{C-c C-c}. @xref{Top, , Top, message, The Message
+Manual}. If you are in a foreign news group, and you wish to post the
+article using the foreign server, you can give a prefix to @kbd{C-c C-c}
+to make Gnus try to post using the foreign server.
-@menu
-* Message Interface:: Setting up message buffers.
-* Message Commands:: Commands you can execute in message mode buffers.
-* Message Variables:: Customizing the message buffers.
+@menu
+* Mail:: Mailing and replying.
+* Post:: Posting and following up.
+* Posting Server:: What server should you post via?
+* Mail and Post:: Mailing and posting at the same time.
+* Archived Messages:: Where Gnus stores the messages you've sent.
+@c * Posting Styles:: An easier way to configure some key elements.
+@c * Drafts:: Postponing messages and rejected messages.
+@c * Rejected Articles:: What happens if the server doesn't like your article?
@end menu
+Also see @pxref{Canceling and Superseding} for information on how to
+remove articles you shouldn't have posted.
-@node Message Interface
-@section Message Interface
-When a program (or a person) wants to respond to a message -- reply,
-follow up, forward, cancel -- the program (or person) should just put
-point in the buffer where the message is and call the required command.
-@code{Message} will then pop up a new @code{message} mode buffer with
-appropriate headers filled out, and the user can edit the message before
-sending it.
+@node Mail
+@section Mail
-@menu
-* New Mail Message::
-* New News Message::
-* Reply::
-* Wide Reply::
-* Followup::
-* Canceling News::
-* Superseding::
-* Forwarding::
-* Resending::
-* Bouncing::
-@end menu
+Variables for customizing outgoing mail:
+@table @code
+@item gnus-uu-digest-headers
+@vindex gnus-uu-digest-headers
+List of regexps to match headers included in digested messages. The
+headers will be included in the sequence they are matched.
+
+@end table
-@node New Mail Message
-@subsection New Mail Message
-@findex message-mail
-The @code{message-mail} command pops up a new message buffer.
+@node Post
+@section Post
-Two optional parameters are accepted: The first will be used as the
-@code{To} header and the second as the @code{Subject} header. If these
-aren't present, those two headers will be empty.
+Variables for composing news articles:
+@table @code
+@item gnus-sent-message-ids-file
+@vindex gnus-sent-message-ids-file
+Gnus will keep a @code{Message-ID} history file of all the mails it has
+sent. If it discovers that it has already sent a mail, it will ask the
+user whether to re-send the mail. (This is primarily useful when
+dealing with @sc{soup} packets and the like where one is apt to sent the
+same packet multiple times.) This variable says what the name of this
+history file is. It is @file{~/News/Sent-Message-IDs} by default. Set
+this variable to @code{nil} if you don't want Gnus to keep a history
+file.
-@node New News Message
-@subsection New News Message
+@item gnus-sent-message-ids-length
+@vindex gnus-sent-message-ids-length
+This variable says how many @code{Message-ID}s to keep in the history
+file. It is 1000 by default.
-@findex message-news
-The @code{message-news} command pops up a new message buffer.
+@end table
-This function accepts two optional parameters. The first will be used
-as the @code{Newsgroups} header and the second as the @code{Subject}
-header. If these aren't present, those two headers will be empty.
+@node Posting Server
+@section Posting Server
-@node Reply
-@subsection Reply
+When you press those magical @kbd{C-c C-c} keys to ship off your latest
+(extremely intelligent, of course) article, where does it go?
-@findex message-reply
-The @code{message-reply} function pops up a message buffer that's a
-reply to the message in the current buffer.
+Thank you for asking. I hate you.
-@vindex message-reply-to-function
-Message uses the normal methods to determine where replies are to go,
-but you can change the behavior to suit your needs by fiddling with the
-@code{message-reply-to-function} variable.
+@vindex gnus-post-method
-If you want the replies to go to the @code{Sender} instead of the
-@code{From}, you could do something like this:
+It can be quite complicated. Normally, Gnus will use the same native
+server. However. If your native server doesn't allow posting, just
+reading, you probably want to use some other server to post your
+(extremely intelligent and fabulously interesting) articles. You can
+then set the @code{gnus-post-method} to some other method:
@lisp
-(setq message-reply-to-function
- (lambda ()
- (cond ((equal (mail-fetch-field "from") "somebody")
- (mail-fetch-field "sender"))
- (t
- nil))))
+(setq gnus-post-method '(nnspool ""))
@end lisp
-This function will be called narrowed to the head of the article that is
-being replied to.
-
-As you can see, this function should return a string if it has an
-opinion as to what the To header should be. If it does not, it should
-just return @code{nil}, and the normal methods for determining the To
-header will be used.
-
-This function can also return a list. In that case, each list element
-should be a cons, where the car should be the name of an header
-(eg. @code{Cc}) and the cdr should be the header value
-(eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
-the head of the outgoing mail.
+Now, if you've done this, and then this server rejects your article, or
+this server is down, what do you do then? To override this variable you
+can use a non-zero prefix to the @kbd{C-c C-c} command to force using
+the ``current'' server for posting.
+If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command,
+Gnus will prompt you for what method to use for posting.
-@node Wide Reply
-@subsection Wide Reply
+You can also set @code{gnus-post-method} to a list of select methods.
+If that's the case, Gnus will always prompt you for what method to use
+for posting.
-@findex message-wide-reply
-The @code{message-wide-reply} pops up a message buffer that's a wide
-reply to the message in the current buffer.
-@vindex message-wide-reply-to-function
-Message uses the normal methods to determine where wide replies are to go,
-but you can change the behavior to suit your needs by fiddling with the
-@code{message-wide-reply-to-function}. It is used in the same way as
-@code{message-reply-to-function} (@pxref{Reply}).
+@node Mail and Post
+@section Mail and Post
+Here's a list of variables that are relevant to both mailing and
+posting:
-@node Followup
-@subsection Followup
+@table @code
+@item gnus-mailing-list-groups
+@findex gnus-mailing-list-groups
+@cindex mailing lists
-@findex message-followup
-The @code{message-followup} command pops up a message buffer that's a
-followup to the message in the current buffer.
+If your news server offers groups that are really mailing lists that are
+gatewayed to the @sc{nntp} server, you can read those groups without
+problems, but you can't post/followup to them without some difficulty.
+One solution is to add a @code{to-address} to the group parameters
+(@pxref{Group Parameters}). An easier thing to do is set the
+@code{gnus-mailing-list-groups} to a regexp that match the groups that
+really are mailing lists. Then, at least, followups to the mailing
+lists will work most of the time. Posting to these groups (@kbd{a}) is
+still a pain, though.
-@vindex message-followup-to-function
-Message uses the normal methods to determine where followups are to go,
-but you can change the behavior to suit your needs by fiddling with the
-@code{message-followup-to-function}. It is used in the same way as
-@code{message-reply-to-function} (@pxref{Reply}).
+@end table
-@vindex message-use-followup-to
-The @code{message-use-followup-to} variable says what to do about
-@code{Followup-To} headers. If it is @code{use}, always use the value.
-If it is @code{ask} (which is the default), ask whether to use the
-value. If it is @code{t}, use the value unless it is @samp{poster}. If
-it is @code{nil}, don't use the value.
+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:
+@cindex ispell
+@findex ispell-message
+@lisp
+(add-hook 'message-send-hook 'ispell-message)
+@end lisp
-@node Canceling News
-@subsection Canceling News
-@findex message-cancel-news
-The @code{message-cancel-news} command cancels the article in the
-current buffer.
+@node Archived Messages
+@section Archived Messages
+@cindex archived messages
+@cindex sent messages
+Gnus provides a few different methods for storing the mail you send.
+The default method is to use the @dfn{archive virtual server} to store
+the mail. If you want to disable this completely, you should set
+@code{gnus-message-archive-group} to @code{nil}.
-@node Superseding
-@subsection Superseding
+@vindex gnus-message-archive-method
+@code{gnus-message-archive-method} says what virtual server Gnus is to
+use to store sent messages. The default is:
-@findex message-supersede
-The @code{message-supersede} command pops up a message buffer that will
-supersede the message in the current buffer.
+@lisp
+(nnfolder "archive"
+ (nnfolder-directory "~/Mail/archive/"))
+@end lisp
-@vindex message-ignored-supersedes-headers
-Headers matching the @code{message-ignored-supersedes-headers} are
-removed before popping up the new message buffer. The default is
-@samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|^Received:\\|^X-From-Line:\\|Return-Path:}.
+You can, however, use any mail select method (@code{nnml},
+@code{nnmbox}, etc.). @code{nnfolder} is a quite likeable select method
+for doing this sort of thing, though. If you don't like the default
+directory chosen, you could say something like:
+@lisp
+(setq gnus-message-archive-method
+ '(nnfolder "archive"
+ (nnfolder-inhibit-expiry t)
+ (nnfolder-active-file "~/News/sent-mail/active")
+ (nnfolder-directory "~/News/sent-mail/")))
+@end lisp
+@vindex gnus-message-archive-group
+@cindex Gcc
+Gnus will insert @code{Gcc} headers in all outgoing messages that point
+to one or more group(s) on that server. Which group to use is
+determined by the @code{gnus-message-archive-group} variable.
-@node Forwarding
-@subsection Forwarding
+This variable can be:
-@findex message-forward
-The @code{message-forward} command pops up a message buffer to forward
-the message in the current buffer. If given a prefix, forward using
-news.
+@itemize @bullet
+@item a string
+Messages will be saved in that group.
+@item a list of strings
+Messages will be saved in all those groups.
+@item an alist of regexps, functions and forms
+When a key ``matches'', the result is used.
+@item @code{nil}
+No message archiving will take place. This is the default.
+@end itemize
-@table @code
-@item message-forward-start-separator
-@vindex message-forward-start-separator
-Delimiter inserted before forwarded messages. The default is
-@samp{------- Start of forwarded message -------\n}.
+Let's illustrate:
-@vindex message-forward-end-separator
-@item message-forward-end-separator
-@vindex message-forward-end-separator
-Delimiter inserted after forwarded messages. The default is
-@samp{------- End of forwarded message -------\n}.
+Just saving to a single group called @samp{MisK}:
+@lisp
+(setq gnus-message-archive-group "MisK")
+@end lisp
-@item message-signature-before-forwarded-message
-@vindex message-signature-before-forwarded-message
-If this variable is @code{t}, which it is by default, your personal
-signature will be inserted before the forwarded message. If not, the
-forwarded message will be inserted first in the new mail.
+Saving to two groups, @samp{MisK} and @samp{safe}:
+@lisp
+(setq gnus-message-archive-group '("MisK" "safe"))
+@end lisp
-@item message-forward-included-headers
-@vindex message-forward-included-headers
-Regexp matching header lines to be included in forwarded messages.
+Save to different groups based on what group you are in:
+@lisp
+(setq gnus-message-archive-group
+ '(("^alt" "sent-to-alt")
+ ("mail" "sent-to-mail")
+ (".*" "sent-to-misc")))
+@end lisp
-@end table
+More complex stuff:
+@lisp
+(setq gnus-message-archive-group
+ '((if (message-news-p)
+ "misc-news"
+ "misc-mail")))
+@end lisp
+How about storing all news messages in one file, but storing all mail
+messages in one file per month:
-@node Resending
-@subsection Resending
+@lisp
+(setq gnus-message-archive-group
+ '((if (message-news-p)
+ "misc-news"
+ (concat "mail." (format-time-string
+ "%Y-%m" (current-time))))))
+@end lisp
-@findex message-resend
-The @code{message-resend} command will prompt the user for an address
-and resend the message in the current buffer to that address.
+Now, when you send a message off, it will be stored in the appropriate
+group. (If you want to disable storing for just one particular message,
+you can just remove the @code{Gcc} header that has been inserted.) The
+archive group will appear in the group buffer the next time you start
+Gnus, or the next time you press @kbd{F} in the group buffer. You can
+enter it and read the articles in it just like you'd read any other
+group. If the group gets really big and annoying, you can simply rename
+if (using @kbd{G r} in the group buffer) to something
+nice---@samp{misc-mail-september-1995}, or whatever. New messages will
+continue to be stored in the old (now empty) group.
-@vindex message-ignored-resent-headers
-Headers the match the @code{message-ignored-resent-headers} regexp will
-be removed before sending the message. The default is
-@samp{^Return-receipt}.
+That's the default method of archiving sent mail. Gnus also a different
+way for the people who don't like the default method. In that case you
+should set @code{gnus-message-archive-group} to @code{nil}; this will
+disable archiving.
+XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to
+use a different value for @code{gnus-message-archive-group} there.
-@node Bouncing
-@subsection Bouncing
+@table @code
+@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.
-@findex message-bounce
-The @code{message-bounce} command will, if the current buffer contains a
-bounced mail message, pop up a message buffer stripped of the bounce
-information.
+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
-@vindex message-ignored-bounced-headers
-Headers that match the @code{message-ignored-bounced-headers} regexp
-will be removed before popping up the buffer. The default is
-@samp{^Received:}.
+@c @node Posting Styles
+@c @section Posting Styles
+@c @cindex posting styles
+@c @cindex styles
+@c
+@c All them variables, they make my head swim.
+@c
+@c So what if you want a different @code{Organization} and signature based
+@c on what groups you post to? And you post both from your home machine
+@c and your work machine, and you want different @code{From} lines, and so
+@c on?
+@c
+@c @vindex gnus-posting-styles
+@c One way to do stuff like that is to write clever hooks that change the
+@c variables you need to have changed. That's a bit boring, so somebody
+@c came up with the bright idea of letting the user specify these things in
+@c a handy alist. Here's an example of a @code{gnus-posting-styles}
+@c variable:
+@c
+@c @lisp
+@c ((".*"
+@c (signature . "Peace and happiness")
+@c (organization . "What me?"))
+@c ("^comp"
+@c (signature . "Death to everybody"))
+@c ("comp.emacs.i-love-it"
+@c (organization . "Emacs is it")))
+@c @end lisp
+@c
+@c As you might surmise from this example, this alist consists of several
+@c @dfn{styles}. Each style will be applicable if the first element
+@c ``matches'', in some form or other. The entire alist will be iterated
+@c over, from the beginning towards the end, and each match will be
+@c applied, which means that attributes in later styles that match override
+@c the same attributes in earlier matching styles. So
+@c @samp{comp.programming.literate} will have the @samp{Death to everybody}
+@c signature and the @samp{What me?} @code{Organization} header.
+@c
+@c The first element in each style is called the @code{match}. If it's a
+@c string, then Gnus will try to regexp match it against the group name.
+@c If it's a function symbol, that function will be called with no
+@c arguments. If it's a variable symbol, then the variable will be
+@c referenced. If it's a list, then that list will be @code{eval}ed. In
+@c any case, if this returns a non-@code{nil} value, then the style is said
+@c to @dfn{match}.
+@c
+@c Each style may contain a arbitrary amount of @dfn{attributes}. Each
+@c attribute consists of a @var{(name . value)} pair. The attribute name
+@c can be one of @code{signature}, @code{organization} or @code{from}. The
+@c attribute name can also be a string. In that case, this will be used as
+@c a header name, and the value will be inserted in the headers of the
+@c article.
+@c
+@c The attribute value can be a string (used verbatim), a function (the
+@c return value will be used), a variable (its value will be used) or a
+@c list (it will be @code{eval}ed and the return value will be used).
+@c
+@c So here's a new example:
+@c
+@c @lisp
+@c (setq gnus-posting-styles
+@c '((".*"
+@c (signature . "~/.signature")
+@c (from . "user@@foo (user)")
+@c ("X-Home-Page" . (getenv "WWW_HOME"))
+@c (organization . "People's Front Against MWM"))
+@c ("^rec.humor"
+@c (signature . my-funny-signature-randomizer))
+@c ((equal (system-name) "gnarly")
+@c (signature . my-quote-randomizer))
+@c (posting-from-work-p
+@c (signature . "~/.work-signature")
+@c (from . "user@@bar.foo (user)")
+@c (organization . "Important Work, Inc"))
+@c ("^nn.+:"
+@c (signature . "~/.mail-signature"))))
+@c @end lisp
+
+@c @node Drafts
+@c @section Drafts
+@c @cindex drafts
+@c
+@c If you are writing a message (mail or news) and suddenly remember that
+@c you have a steak in the oven (or some pesto in the food processor, you
+@c craazy vegetarians), you'll probably wish there was a method to save the
+@c message you are writing so that you can continue editing it some other
+@c day, and send it when you feel its finished.
+@c
+@c Well, don't worry about it. Whenever you start composing a message of
+@c some sort using the Gnus mail and post commands, the buffer you get will
+@c automatically associate to an article in a special @dfn{draft} group.
+@c If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
+@c article will be saved there. (Auto-save files also go to the draft
+@c group.)
+@c
+@c @cindex nndraft
+@c @vindex gnus-draft-group-directory
+@c The draft group is a special group (which is implemented as an
+@c @code{nndraft} group, if you absolutely have to know) called
+@c @samp{nndraft:drafts}. The variable @code{gnus-draft-group-directory}
+@c controls both the name of the group and the location---the leaf element
+@c in the path will be used as the name of the group. What makes this
+@c group special is that you can't tick any articles in it or mark any
+@c articles as read---all articles in the group are permanently unread.
+@c
+@c If the group doesn't exist, it will be created and you'll be subscribed
+@c to it.
+@c
+@c @findex gnus-dissociate-buffer-from-draft
+@c @kindex C-c M-d (Mail)
+@c @kindex C-c M-d (Post)
+@c @findex gnus-associate-buffer-with-draft
+@c @kindex C-c C-d (Mail)
+@c @kindex C-c C-d (Post)
+@c If you're writing some super-secret message that you later want to
+@c encode with PGP before sending, you may wish to turn the auto-saving
+@c (and association with the draft group) off. You never know who might be
+@c interested in reading all your extremely valuable and terribly horrible
+@c and interesting secrets. The @kbd{C-c M-d}
+@c (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
+@c If you change your mind and want to turn the auto-saving back on again,
+@c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
+@c
+@c @vindex gnus-use-draft
+@c To leave association with the draft group off by default, set
+@c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
+@c
+@c @findex gnus-summary-send-draft
+@c @kindex S D c (Summary)
+@c When you want to continue editing the article, you simply enter the
+@c draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
+@c that. You will be placed in a buffer where you left off.
+@c
+@c Rejected articles will also be put in this draft group (@pxref{Rejected
+@c Articles}).
+@c
+@c @findex gnus-summary-send-all-drafts
+@c If you have lots of rejected messages you want to post (or mail) without
+@c doing further editing, you can use the @kbd{S D a} command
+@c (@code{gnus-summary-send-all-drafts}). This command understands the
+@c process/prefix convention (@pxref{Process/Prefix}).
+@c
+@c
+@c @node Rejected Articles
+@c @section Rejected Articles
+@c @cindex rejected articles
+@c
+@c Sometimes a news server will reject an article. Perhaps the server
+@c doesn't like your face. Perhaps it just feels miserable. Perhaps
+@c @emph{there be demons}. Perhaps you have included too much cited text.
+@c Perhaps the disk is full. Perhaps the server is down.
+@c
+@c These situations are, of course, totally beyond the control of Gnus.
+@c (Gnus, of course, loves the way you look, always feels great, has angels
+@c fluttering around inside of it, doesn't care about how much cited text
+@c you include, never runs full and never goes down.) So Gnus saves these
+@c articles until some later time when the server feels better.
+@c
+@c The rejected articles will automatically be put in a special draft group
+@c (@pxref{Drafts}). When the server comes back up again, you'd then
+@c typically enter that group and send all the articles off.
+@c
-@node Message Commands
-@section Message Commands
+@node Select Methods
+@chapter Select Methods
+@cindex foreign groups
+@cindex select methods
-@menu
-* Message Header Commands:: Commands for moving to headers.
-* Message Movement:: Moving around in message buffers.
-* Message Insertion:: Inserting things into message buffers.
-* Various Message:: Various things.
-* Sending Messages:: Actually sending the message.
-@end menu
+A @dfn{foreign group} is a group that is not read by the usual (or
+default) means. It could be, for instance, a group from a different
+@sc{nntp} server, it could be a virtual group, or it could be your own
+personal mail group.
+A foreign group (or any group, really) is specified by a @dfn{name} and
+a @dfn{select method}. To take the latter first, a select method is a
+list where the first element says what backend to use (e.g. @code{nntp},
+@code{nnspool}, @code{nnml}) and the second element is the @dfn{server
+name}. There may be additional elements in the select method, where the
+value may have special meaning for the backend in question.
-@node Message Header Commands
-@subsection Message Header Commands
+One could say that a select method defines a @dfn{virtual server}---so
+we do just that (@pxref{The Server Buffer}).
-All these commands move to the header in question. If it doesn't exist,
-it will be inserted.
+The @dfn{name} of the group is the name the backend will recognize the
+group as.
-@table @kbd
+For instance, the group @samp{soc.motss} on the @sc{nntp} server
+@samp{some.where.edu} will have the name @samp{soc.motss} and select
+method @code{(nntp "some.where.edu")}. Gnus will call this group
+@samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp}
+backend just knows this group as @samp{soc.motss}.
-@item C-c ?
-@kindex C-c ? (Message)
-@findex message-goto-to
-Describe the message mode.
+The different methods all have their peculiarities, of course.
-@item C-c C-f C-t
-@kindex C-c C-f C-t (Message)
-@findex message-goto-to
-Go to the @code{To} header (@code{message-goto-to}).
+@menu
+* The Server Buffer:: Making and editing virtual servers.
+* Getting News:: Reading USENET news with Gnus.
+* Getting Mail:: Reading your personal mail with Gnus.
+* Other Sources:: Reading directories, files, SOUP packets.
+* Combined Groups:: Combining groups into one group.
+@end menu
-@item C-c C-f C-b
-@kindex C-c C-f C-b (Message)
-@findex message-goto-bcc
-Go to the @code{Bcc} header (@code{message-goto-bcc}).
-@item C-c C-f C-f
-@kindex C-c C-f C-f (Message)
-@findex message-goto-fcc
-Go to the @code{Fcc} header (@code{message-goto-fcc}).
+@node The Server Buffer
+@section The Server Buffer
-@item C-c C-f C-c
-@kindex C-c C-f C-c (Message)
-@findex message-goto-cc
-Go to the @code{Cc} header (@code{message-goto-cc}).
+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.
-@item C-c C-f C-s
-@kindex C-c C-f C-s (Message)
-@findex message-goto-subject
-Go to the @code{Subject} header (@code{message-goto-subject}).
+For instance, the @code{nntp} backend may be used to connect to several
+different actual @sc{nntp} servers, or, perhaps, to many different ports
+on the same actual @sc{nntp} server. You tell Gnus which backend to
+use, and what parameters to set by specifying a @dfn{select method}.
-@item C-c C-f C-r
-@kindex C-c C-f C-r (Message)
-@findex message-goto-reply-to
-Go to the @code{Reply-To} header (@code{message-goto-reply-to}).
+These select methods specifications can sometimes become quite
+complicated---say, for instance, that you want to read from the
+@sc{nntp} server @samp{news.funet.fi} on port number 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 naming
+select methods, which is what you do in the server buffer.
-@item C-c C-f C-n
-@kindex C-c C-f C-n (Message)
-@findex message-goto-newsgroups
-Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}).
+To enter the server buffer, user the @kbd{^}
+(@code{gnus-group-enter-server-mode}) command in the group buffer.
-@item C-c C-f C-d
-@kindex C-c C-f C-d (Message)
-@findex message-goto-distribution
-Go to the @code{Distribution} header (@code{message-goto-distribution}).
+@menu
+* Server Buffer Format:: You can customize the look of this buffer.
+* Server Commands:: Commands to manipulate servers.
+* Example Methods:: Examples server specifications.
+* Creating a Virtual Server:: An example session.
+* Servers and Methods:: You can use server names as select methods.
+* Unavailable Servers:: Some servers you try to contact may be down.
+@end menu
-@item C-c C-f C-o
-@kindex C-c C-f C-o (Message)
-@findex message-goto-followup-to
-Go to the @code{Followup-To} header (@code{message-goto-followup-to}).
+@vindex gnus-server-mode-hook
+@code{gnus-server-mode-hook} is run when creating the server buffer.
-@item C-c C-f C-k
-@kindex C-c C-f C-k (Message)
-@findex message-goto-keywords
-Go to the @code{Keywords} header (@code{message-goto-keywords}).
-@item C-c C-f C-u
-@kindex C-c C-f C-u (Message)
-@findex message-goto-summary
-Go to the @code{Summary} header (@code{message-goto-summary}).
+@node Server Buffer Format
+@subsection Server Buffer Format
+@cindex server buffer format
-@end table
+@vindex gnus-server-line-format
+You can change the look of the server buffer lines by changing the
+@code{gnus-server-line-format} variable. This is a @code{format}-like
+variable, with some simple extensions:
+@table @samp
-@node Message Movement
-@subsection Message Movement
+@item h
+How the news is fetched---the backend name.
-@table @kbd
-@item C-c C-b
-@kindex C-c C-b (Message)
-@findex message-goto-body
-Move to the beginning of the body of the message
-(@code{message-goto-body}).
+@item n
+The name of this server.
-@item C-c C-i
-@kindex C-c C-i (Message)
-@findex message-goto-signature
-Move to the signature of the message (@code{message-goto-signature}).
+@item w
+Where the news is to be fetched from---the address.
+@item s
+The opened/closed/denied status of the server.
@end table
+@vindex gnus-server-mode-line-format
+The mode line can also be customized by using the
+@code{gnus-server-mode-line-format} variable. The following specs are
+understood:
-@node Message Insertion
-@subsection Message Insertion
-
-@table @kbd
-
-@item C-c C-y
-@kindex C-c C-y (Message)
-@findex message-yank-original
-Yank the message that's being replied to into the message buffer
-(@code{message-yank-original}).
+@table @samp
+@item S
+Server name.
-@item C-c C-q
-@kindex C-c C-q (Message)
-@findex message-fill-yanked-message
-Fill the yanked message (@code{message-fill-yanked-message}).
+@item M
+Server method.
+@end table
-@item C-c C-w
-@kindex C-c C-w (Message)
-@findex message-insert-signature
-Insert a signature at the end of the buffer
-(@code{message-insert-signature}).
+Also @pxref{Formatting Variables}.
-@end table
-@table @code
-@item message-ignored-cited-headers
-@vindex message-ignored-cited-headers
-All headers that match this regexp will be removed from yanked
-messages. The default is @samp{.}, which means that all headers will be
-removed.
-
-@item message-citation-line-function
-@vindex message-citation-line-function
-Function called to insert the citation line. The default is
-@code{message-insert-citation-line}.
-
-@item message-yank-prefix
-@vindex message-yank-prefix
-@cindex yanking
-@cindex quoting
-When you are replying to or following up an article, you normally want
-to quote the person you are answering. Inserting quoted text is done by
-@dfn{yanking}, and each quoted line you yank will have
-@code{message-yank-prefix} prepended to it. The default is @samp{> }.
-If it is @code{nil}, just indent the message.
-
-@item message-indentation-spaces
-@vindex message-indentation-spaces
-Number of spaces to indent yanked messages.
-
-@item message-cite-function
-@vindex message-cite-function
-Function for citing an original message. The default is
-@code{message-cite-original}.
-
-@item message-indent-citation-function
-@vindex message-indent-citation-function
-Function for modifying a citation just inserted in the mail buffer.
-This can also be a list of functions. Each function can find the
-citation between @code{(point)} and @code{(mark t)}. And each function
-should leave point and mark around the citation text as modified.
-
-@item message-signature
-@vindex message-signature
-String to be inserted at the end of the message buffer. If @code{t}
-(which is the default), the @code{message-signature-file} file will be
-inserted instead. If a function, the result from the function will be
-used instead. If a form, the result from the form will be used instead.
-If this variable is @code{nil}, no signature will be inserted at all.
-
-@item message-signature-file
-@vindex message-signature-file
-File containing the signature to be inserted at the end of the buffer.
-The default is @samp{~/.signature}.
-
-@end table
-
-Note that RFC1036 says that a signature should be preceded by the three
-characters @samp{-- } on a line by themselves. This is to make it
-easier for the recipient to automatically recognize and process the
-signature. So don't remove those characters, even though you might feel
-that they ruin you beautiful design, like, totally.
-
-Also note that no signature should be more than four lines long.
-Including ASCII graphics is an efficient way to get everybody to believe
-that you are silly and have nothing important to say.
-
-
-
-@node Various Message
-@subsection Various Message
+@node Server Commands
+@subsection Server Commands
+@cindex server commands
@table @kbd
-@item C-c C-r
-@kindex C-c C-r (Message)
-@findex message-caesar-buffer-body
-Caesar rotate (aka. rot13) the current message
-(@code{message-caesar-buffer-body}). If narrowing is in effect, just
-rotate the visible portion of the buffer. A numerical prefix says how
-many places to rotate the text. The default is 13.
+@item a
+@kindex a (Server)
+@findex gnus-server-add-server
+Add a new server (@code{gnus-server-add-server}).
+
+@item e
+@kindex e (Server)
+@findex gnus-server-edit-server
+Edit a server (@code{gnus-server-edit-server}).
-@item C-c C-t
-@kindex C-c C-t (Message)
-@findex message-insert-to
-Insert a @code{To} header that contains the @code{Reply-To} or
-@code{From} header of the message you're following up
-(@code{message-insert-to}).
+@item SPACE
+@kindex SPACE (Server)
+@findex gnus-server-read-server
+Browse the current server (@code{gnus-server-read-server}).
-@item C-c C-n
-@kindex C-c C-n (Message)
-@findex message-insert-newsgroups
-Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
-or @code{Newsgroups} header of the article you're replying to
-(@code{message-insert-newsgroups}).
+@item q
+@kindex q (Server)
+@findex gnus-server-exit
+Return to the group buffer (@code{gnus-server-exit}).
-@end table
+@item k
+@kindex k (Server)
+@findex gnus-server-kill-server
+Kill the current server (@code{gnus-server-kill-server}).
+@item y
+@kindex y (Server)
+@findex gnus-server-yank-server
+Yank the previously killed server (@code{gnus-server-yank-server}).
-@node Sending Messages
-@subsection Sending Messages
+@item c
+@kindex c (Server)
+@findex gnus-server-copy-server
+Copy the current server (@code{gnus-server-copy-server}).
-@table @kbd
-@item C-c C-c
-@kindex C-c C-c (Message)
-@findex message-send-and-exit
-Send the message and bury the current buffer
-(@code{message-send-and-exit}).
+@item l
+@kindex l (Server)
+@findex gnus-server-list-servers
+List all servers (@code{gnus-server-list-servers}).
-@item C-c C-s
-@kindex C-c C-s (Message)
-@findex message-send
-Send the message (@code{message-send}).
+@item s
+@kindex s (Server)
+@findex gnus-server-scan-server
+Request that the server scan its sources for new articles
+(@code{gnus-server-scan-server}). This is mainly sensible with mail
+servers.
@end table
-@node Message Variables
-@section Message Variables
+@node Example Methods
+@subsection Example Methods
-@menu
-* Message Headers::
-* Mail Headers::
-* Mail Variables::
-* News Headers::
-* News Variables::
-* Various Message Variables::
-* Sending Variables::
-@end menu
+Most select methods are pretty simple and self-explanatory:
+@lisp
+(nntp "news.funet.fi")
+@end lisp
-@node Message Headers
-@subsection Message Headers
+Reading directly from the spool is even simpler:
-Message is a quite aggressive on the message generation front. It has
-to be -- it's a combined news and mail agent. To be able to send
-combined messages, it has to generate all headers itself to ensure that
-mail and news copies of messages look sufficiently similar.
+@lisp
+(nnspool "")
+@end lisp
-@table @code
+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.
-@item message-generate-headers-first
-@vindex message-generate-headers-first
-If non-@code{nil}, generate all headers before starting to compose the
-message.
-
-@item message-from-style
-@vindex message-from-style
-Specifies how @code{From} headers should look. There are four legal
-values:
-
-@table @code
-@item nil
-Just the address -- @samp{king@@grassland.com}.
+After these two elements, there may be a arbitrary number of
+@var{(variable form)} pairs.
-@item parens
-@samp{king@@grassland.com (Elvis Parsley)}.
+To go back to the first example---imagine that you want to read from
+port 15 from that machine. This is what the select method should
+look like then:
-@item angles
-@samp{Elvis Parsley <king@@grassland.com>}.
+@lisp
+(nntp "news.funet.fi" (nntp-port-number 15))
+@end lisp
-@item default
-Look like @code{angles} if that doesn't require quoting, and
-@code{parens} if it does. If even @code{parens} requires quoting, use
-@code{angles} anyway.
+You should read the documentation to each backend to find out what
+variables are relevant, but here's an @code{nnmh} example.
-@end table
+@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:
-@item message-deletable-headers
-@vindex message-deletable-headers
-Headers in this list that were previously generated by Gnus will be
-deleted before posting. Let's say you post an article. Then you decide
-to post it again to some other group, you naughty boy, so you jump back
-to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
-ship it off again. By default, this variable makes sure that the old
-generated @code{Message-ID} is deleted, and a new one generated. If
-this isn't done, the entire empire would probably crumble, anarchy would
-prevail, and cats would start walking on two legs and rule the world.
-Allegedly.
+@lisp
+(nnmh "private" (nnmh-directory "~/private/mail/"))
+@end lisp
-@item message-default-headers
-@vindex message-default-headers
-This string is inserted at the end of the headers in all message
-buffers.
+(This server is then called @samp{private}, but you may have guessed
+that.)
-@end table
+Here's the method for a public spool:
+@lisp
+(nnmh "public"
+ (nnmh-directory "/usr/information/spool/")
+ (nnmh-get-new-mail nil))
+@end lisp
-@node Mail Headers
-@subsection Mail Headers
-@table @code
-@item message-required-mail-headers
-@vindex message-required-mail-headers
-See @pxref{News Headers} for the syntax of this variable. It is
-@code{(From Date Subject (optional . In-Reply-To) Message-ID Lines
-(optional . X-Mailer))} by default.
+@node Creating a Virtual Server
+@subsection Creating a Virtual Server
-@item message-ignored-mail-headers
-@vindex message-ignored-mail-headers
-Regexp of headers to be removed before mailing. The default is
-@samp{^Gcc:\\|^Fcc:}.
+If you're saving lots of articles in the cache by using persistent
+articles, you may want to create a virtual server to read the cache.
-@item message-default-mail-headers
-@vindex message-default-mail-headers
-This string is inserted at the end of the headers in all message
-buffers that are initialized as mail.
+First you need to add a new server. The @kbd{a} command does that. It
+would probably be best to use @code{nnspool} to read the cache. You
+could also use @code{nnml} or @code{nnmh}, though.
-@end table
+Type @kbd{a nnspool RET cache RET}.
+You should now have a brand new @code{nnspool} virtual server called
+@samp{cache}. You now need to edit it to have the right definitions.
+Type @kbd{e} to edit the server. You'll be entered into a buffer that
+will contain the following:
-@node Mail Variables
-@subsection Mail Variables
+@lisp
+(nnspool "cache")
+@end lisp
-@table @code
-@item message-send-mail-function
-@vindex message-send-mail-function
-Function used to send the current buffer as mail. The default is
-@code{message-send-mail}.
+Change that to:
-@end table
+@lisp
+(nnspool "cache"
+ (nnspool-spool-directory "~/News/cache/")
+ (nnspool-nov-directory "~/News/cache/")
+ (nnspool-active-file "~/News/cache/active"))
+@end lisp
+Type @kbd{C-c C-c} to return to the server buffer. If you now press
+@kbd{RET} over this virtual server, you should be entered into a browse
+buffer, and you should be able to enter any of the groups displayed.
-@node News Headers
-@subsection News Headers
-@vindex message-required-news-headers
-@code{message-required-news-headers} a list of header symbols. These
-headers will either be automatically generated, or, if that's
-impossible, they will be prompted for. The following symbols are legal:
+@node Servers and Methods
+@subsection Servers and Methods
-@table @code
+Wherever you would normally use a select method
+(e.g. @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.
-@item From
-@cindex From
-This required header will be filled out with the result of the
-@code{message-make-from} function, which depends on the
-@code{message-from-style}, @code{user-full-name},
-@code{user-mail-address} variables.
-
-@item Subject
-@cindex Subject
-This required header will be prompted for if not present already.
-
-@item Newsgroups
-@cindex Newsgroups
-This required header says which newsgroups the article is to be posted
-to. If it isn't present already, it will be prompted for.
-
-@item Organization
-@cindex organization
-This optional header will be filled out depending on the
-@code{message-user-organization} variable.
-@code{message-user-organization-file} will be used if that variable is
-@code{t}.
-
-@item Lines
-@cindex Lines
-This optional header will be computed by Gnus.
-
-@item Message-ID
-@cindex Message-ID
-This required header will be generated by Gnus. A unique ID will be
-created based on date, time, user name and system name.
-@item X-Newsreader
-@cindex X-Newsreader
-This optional header will be filled out according to the
-@code{message-newsreader} local variable.
-
-@item X-Mailer
-This optional header will be filled out according to the
-@code{message-mailer} local variable, unless there already is an
-@code{X-Newsreader} header present.
-
-@item In-Reply-To
-This optional header is filled out using the @code{Date} and @code{From}
-header of the article being replied.
-
-@item Expires
-@cindex Expires
-This extremely optional header will be inserted according to the
-@code{message-expires} variable. It is highly deprecated and shouldn't
-be used unless you know what you're doing.
-
-@item Distribution
-@cindex Distribution
-This optional header is filled out according to the
-@code{message-distribution-function} variable. It is a deprecated and
-much misunderstood header.
-
-@item Path
-@cindex path
-This extremely optional header should probably not ever be used.
-However, some @emph{very} old servers require that this header is
-present. @code{message-user-path} further controls how this
-@code{Path} header is to look. If is is @code{nil}, the the server name
-as the leaf node. If is is a string, use the string. If it is neither
-a string nor @code{nil}, use the user name only. However, it is highly
-unlikely that you should need to fiddle with this variable at all.
-@end table
-
-@findex yow
-@cindex Mime-Version
-In addition, you can enter conses into this list. The car of this cons
-should be a symbol. This symbol's name is the name of the header, and
-the cdr can either be a string to be entered verbatim as the value of
-this header, or it can be a function to be called. This function should
-return a string to be inserted. For instance, if you want to insert
-@code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
-into the list. If you want to insert a funny quote, you could enter
-something like @code{(X-Yow . yow)} into the list. The function
-@code{yow} will then be called without any arguments.
-
-If 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 news articles:
+@node Unavailable Servers
+@subsection Unavailable Servers
-@table @code
+If a server seems to be unreachable, Gnus will mark that server as
+@code{denied}. That means that any subsequent attempt to make contact
+with that server will just be ignored. ``It can't be opened,'' Gnus
+will tell you, without making the least effort to see whether that is
+actually the case or not.
-@item message-syntax-checks
-@vindex message-syntax-checks
-If non-@code{nil}, message will attempt to check the legality of the
-headers, as well as some other stuff, before posting. You can control
-the granularity of the check by adding or removing elements from this
-list. Legal elements are:
+That might seem quite naughty, but it does make sense most of the time.
+Let's say you have 10 groups subscribed to the server
+@samp{nepholococcygia.com}. This server is located somewhere quite far
+away from you, the machine is quite, so it takes 1 minute just to find
+out that it refuses connection from you today. If Gnus were to attempt
+to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
+that. Once it has gotten a single ``connection refused'', it will
+regard that server as ``down''.
-@table @code
-@item subject-cmsg
-Check the subject for commands.
-@item sender
-@cindex 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
-@cindex sendsys
-Check for the existence of version and sendsys commands.
-@item message-id
-Check whether the @code{Message-ID} looks ok.
-@item from
-Check whether the @code{From} header seems nice.
-@item long-lines
-@cindex long lines
-Check for too long lines.
-@item control-chars
-Check for illegal characters.
-@item size
-Check for excessive size.
-@item new-text
-Check whether there is any new text in the messages.
-@item signature
-Check the length of the signature.
-@item approved
-@cindex approved
-Check whether the article has an @code{Approved} header, which is
-something only moderators should include.
-@item empty
-Check whether the article is empty.
-@item empty-headers
-Check whether any of the headers are empty.
-@end table
+So, what happens if the machine was only feeling unwell temporarily?
+How do you test to see whether the machine has come up again?
-All these conditions are checked by default.
+You jump to the server buffer (@pxref{The Server Buffer}) and poke it
+with the following commands:
-@item message-ignored-news-headers
-@vindex message-ignored-news-headers
-Regexp of headers to be removed before posting. The default is
-@samp{^NNTP-Posting-Host:\\|^Xref:\\|^Bcc:\\|^Gcc:\\|^Fcc:}.
+@table @kbd
-@item message-default-news-headers
-@vindex message-default-news-headers
-This string is inserted at the end of the headers in all message
-buffers that are initialized as news.
+@item O
+@kindex O (Server)
+@findex gnus-server-open-server
+Try to establish connection to the server on the current line
+(@code{gnus-server-open-server}).
-@end table
+@item C
+@kindex C (Server)
+@findex gnus-server-close-server
+Close the connection (if any) to the server
+(@code{gnus-server-close-server}).
+@item D
+@kindex D (Server)
+@findex gnus-server-deny-server
+Mark the current server as unreachable
+(@code{gnus-server-deny-server}).
-@node News Variables
-@subsection News Variables
+@item M-o
+@kindex M-o (Server)
+@findex gnus-server-open-all-servers
+Open the connections to all servers in the buffer
+(@code{gnus-server-open-all-servers}).
-@table @code
-@item message-send-news-function
-@vindex message-send-news-function
-Function used to send the current buffer as news. The default is
-@code{message-send-news}.
+@item M-c
+@kindex M-c (Server)
+@findex gnus-server-close-all-servers
+Close the connections to all servers in the buffer
+(@code{gnus-server-close-all-servers}).
-@item message-post-method
-@vindex message-post-method
-Method used for posting a prepared news message.
+@item R
+@kindex R (Server)
+@findex gnus-server-remove-denials
+Remove all marks to whether Gnus was denied connection from all servers
+(@code{gnus-server-remove-denials}).
@end table
-@node Various Message Variables
-@subsection Various Message Variables
-
-@table @code
-@item message-signature-separator
-@vindex message-signature-separator
-Regexp matching the signature separator. It is @samp{^-- *$} by
-default.
+@node Getting News
+@section Getting News
+@cindex reading news
+@cindex news backends
-@item mail-header-separator
-@vindex mail-header-separator
-String used to separate the headers from the body. It is @samp{--text
-follows this line--} by default.
+A newsreader is normally used for reading news. Gnus currently provides
+only two methods of getting news---it can read from an @sc{nntp} server,
+or it can read from a local spool.
-@item message-autosave-directory
-@vindex message-autosave-directory
-Directory where message buffers will be autosaved to.
+@menu
+* NNTP:: Reading news from an @sc{nntp} server.
+* News Spool:: Reading news from the local spool.
+@end menu
-@item message-setup-hook
-@vindex message-setup-hook
-Hook run when the message buffer has been initialized.
-@item message-header-setup-hook
-@vindex message-header-setup-hook
-Hook called narrowed to the headers after initializing the headers.
+@node NNTP
+@subsection @sc{nntp}
+@cindex nntp
-@item message-send-hook
-@vindex message-send-hook
-Hook run before sending messages.
+Subscribing to a foreign group from an @sc{nntp} server is rather easy.
+You just specify @code{nntp} as method and the address of the @sc{nntp}
+server as the, uhm, address.
-@item message-sent-hook
-@vindex message-sent-hook
-Hook run after sending messages.
+If the @sc{nntp} server is located at a non-standard port, setting the
+third element of the select method to this port number should allow you
+to connect to the right port. You'll have to edit the group info for
+that (@pxref{Foreign Groups}).
-@item message-mode-syntax-table
-@vindex message-mode-syntax-table
-Syntax table used in message mode buffers.
+The name of the foreign group can be the same as a native group. In
+fact, you can subscribe to the same group from as many different servers
+you feel like. There will be no name collisions.
-@end table
+The following variables can be used to create a virtual @code{nntp}
+server:
+@table @code
+@item nntp-server-opened-hook
+@vindex nntp-server-opened-hook
+@cindex @sc{mode reader}
+@cindex authinfo
+@cindex authentification
+@cindex nntp authentification
+@findex nntp-send-authinfo
+@findex nntp-send-mode-reader
+@code{nntp-server-opened-hook} is run after a connection has been made.
+It can be used to send commands to the @sc{nntp} server after it has
+been contacted. By default is sends the command @code{MODE READER} to
+the server with the @code{nntp-send-mode-reader} function.
-@node Sending Variables
-@subsection Sending Variables
+@item nntp-authinfo-function
+@vindex nntp-authinfo-function
+This function will be used to send @samp{AUTHINFO} to the @sc{nntp}
+server. Available functions include:
@table @code
+@item nntp-send-authinfo
+@findex nntp-send-authinfo
+This function will used you current login name as the user name and will
+prompt you for the password. This is the default.
-@item message-fcc-handler-function
-@vindex message-fcc-handler-function
-A function called to save outgoing articles. This function will be
-called with the name of the file to store the article in. The default
-function is @code{rmail-output} which saves in Unix mailbox format.
-
-@item message-courtesy-message
-@vindex message-courtesy-message
-When sending combined messages, this string is inserted at the start of
-the mailed copy. If this variable is @code{nil}, no such courtesy
-message will be added.
+@item nntp-send-nosy-authinfo
+@findex nntp-send-nosy-authinfo
+This function will prompt you for both user name and password.
+@item nntp-send-authinfo-from-file
+@findex nntp-send-authinfo-from-file
+This function will use your current login name as the user name and will
+read the @sc{nntp} password from @file{~/.nntp-authinfo}.
@end table
+@item nntp-server-action-alist
+@vindex nntp-server-action-alist
+This is an list of regexps to match on server types and actions to be
+taken when matches are made. For instance, if you want Gnus to beep
+every time you connect to innd, you could say something like:
+@lisp
+(setq nntp-server-action-alist
+ '(("innd" (ding))))
+@end lisp
+You probably don't want to do that, though.
+The default value is
-@node Composing Messages
-@chapter Composing Messages
-@cindex reply
-@cindex followup
-@cindex post
+@lisp
+ '(("nntpd 1\\.5\\.11t"
+ (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
+@end lisp
-@kindex C-c C-c (Post)
-All commands for posting and mailing will put you in a message buffer
-where you can edit the article all you like, before you send the article
-by pressing @kbd{C-c C-c}. If you are in a foreign news group, and you
-wish to post the article using the foreign server, you can give a prefix
-to @kbd{C-c C-c} to make Gnus try to post using the foreign server.
+This ensures that Gnus doesn't send the @code{MODE READER} command to
+nntpd 1.5.11t, since that command chokes that server, I've been told.
-@menu
-* Mail:: Mailing and replying.
-* Post:: Posting and following up.
-* Posting Server:: What server should you post via?
-* Mail and Post:: Mailing and posting at the same time.
-* Archived Messages:: Where Gnus stores the messages you've sent.
-* Posting Styles:: An easier way to configure some key elements.
-* Drafts:: Postponing messages and rejected messages.
-* Rejected Articles:: What happens if the server doesn't like your article?
-@end menu
+@item nntp-maximum-request
+@vindex nntp-maximum-request
+If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
+will collect headers by sending a series of @code{head} commands. To
+speed things up, the backend sends lots of these commands without
+waiting for reply, and then reads all the replies. This is controlled
+by the @code{nntp-maximum-request} variable, and is 400 by default. If
+your network is buggy, you should set this to 1.
-Also see @pxref{Canceling and Superseding} for information on how to
-remove articles you shouldn't have posted.
+@item nntp-connection-timeout
+@vindex nntp-connection-timeout
+If you have lots of foreign @code{nntp} groups that you connect to
+regularly, you're sure to have problems with @sc{nntp} servers not
+responding properly, or being too loaded to reply within reasonable
+time. This is can lead to awkward problems, which can be helped
+somewhat by setting @code{nntp-connection-timeout}. This is an integer
+that says how many seconds the @code{nntp} backend should wait for a
+connection before giving up. If it is @code{nil}, which is the default,
+no timeouts are done.
+@item nntp-command-timeout
+@vindex nntp-command-timeout
+@cindex PPP connections
+@cindex dynamic IP addresses
+If you're running Gnus on a machine that has a dynamically assigned
+address, Gnus may become confused. If the address of your machine
+changes after connecting to the @sc{nntp} server, Gnus will simply sit
+waiting forever for replies from the server. To help with this
+unfortunate problem, you can set this command to a number. Gnus will
+then, if it sits waiting longer than that number of seconds for a reply
+from the server, shut down the connection, start a new one, and resend
+the command. This should hopefully be transparent to the user. A
+likely number is 30 seconds.
-@node Mail
-@section Mail
+@item nntp-retry-on-break
+@vindex nntp-retry-on-break
+If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus
+hangs. This will have much the same effect as the command timeout
+described above.
-Variables for customizing outgoing mail:
+@item nntp-server-hook
+@vindex nntp-server-hook
+This hook is run as the last step when connecting to an @sc{nntp}
+server.
-@table @code
-@item gnus-uu-digest-headers
-@vindex gnus-uu-digest-headers
-List of regexps to match headers included in digested messages. The
-headers will be included in the sequence they are matched.
+@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.
-@end table
+@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-end-of-line
+@vindex nntp-end-of-line
+String to use as end-of-line markers when talking to the @sc{nntp}
+server. This is @samp{\r\n} by default, but should be @samp{\n} when
+using @code{rlogin} to talk to the server.
-@node Post
-@section Post
+@item nntp-rlogin-user-name
+@vindex nntp-rlogin-user-name
+User name on the remote system when using the @code{rlogin} connect
+function.
-Variables for composing news articles:
+@item nntp-address
+@vindex nntp-address
+The address of the remote system running the @sc{nntp} server.
-@table @code
-@item gnus-sent-message-ids-file
-@vindex gnus-sent-message-ids-file
-Gnus will keep a @code{Message-ID} history file of all the mails it has
-sent. If it discovers that it has already sent a mail, it will ask the
-user whether to re-send the mail. (This is primarily useful when
-dealing with @sc{soup} packets and the like where one is apt to sent the
-same packet multiple times.) This variable says what the name of this
-history file is. It is @file{~/News/Sent-Message-IDs} by default. Set
-this variable to @code{nil} if you don't want Gnus to keep a history
-file.
+@item nntp-port-number
+@vindex nntp-port-number
+Port number to connect to when using the @code{nntp-open-network-stream}
+connect function.
-@item gnus-sent-message-ids-length
-@vindex gnus-sent-message-ids-length
-This variable says how many @code{Message-ID}s to keep in the history
-file. It is 1000 by default.
+@item nntp-buggy-select
+@vindex nntp-buggy-select
+Set this to non-@code{nil} if your select routine is buggy.
-@end table
+@item nntp-nov-is-evil
+@vindex nntp-nov-is-evil
+If the @sc{nntp} server does not support @sc{nov}, you could set this
+variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
+can be used automatically.
+@item nntp-xover-commands
+@vindex nntp-xover-commands
+@cindex nov
+@cindex XOVER
+List of strings that are used as commands to fetch @sc{nov} lines from a
+server. The default value of this variable is @code{("XOVER"
+"XOVERVIEW")}.
-@node Posting Server
-@section Posting Server
+@item nntp-nov-gap
+@vindex nntp-nov-gap
+@code{nntp} normally sends just one big request for @sc{nov} lines to
+the server. The server responds with one huge list of lines. However,
+if you have read articles 2-5000 in the group, and only want to read
+article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
+lines that you do not want, and will not use. This variable says how
+big a gap between two consecutive articles is allowed to be before the
+@code{XOVER} request is split into several request. Note that if your
+network is fast, setting this variable to a really small number means
+that fetching will probably be slower. If this variable is @code{nil},
+@code{nntp} will never split requests.
-When you press those magical @kbd{C-c C-c} keys to ship off your latest
-(extremely intelligent, of course) article, where does it go?
+@item nntp-prepare-server-hook
+@vindex nntp-prepare-server-hook
+A hook run before attempting to connect to an @sc{nntp} server.
-Thank you for asking. I hate you.
+@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.
-@vindex gnus-post-method
+@end table
-It can be quite complicated. Normally, Gnus will use the same native
-server. However. If your native server doesn't allow posting, just
-reading, you probably want to use some other server to post your
-(extremely intelligent and fabulously interesting) articles. You can
-then set the @code{gnus-post-method} to some other method:
-@lisp
-(setq gnus-post-method '(nnspool ""))
-@end lisp
+@node News Spool
+@subsection News Spool
+@cindex nnspool
+@cindex news spool
-Now, if you've done this, and then this server rejects your article, or
-this server is down, what do you do then? To override this variable you
-can use a non-zero prefix to the @kbd{C-c C-c} command to force using
-the ``current'' server for posting.
+Subscribing to a foreign group from the local spool is extremely easy,
+and might be useful, for instance, to speed up reading groups that
+contain very big articles---@samp{alt.binaries.pictures.furniture}, for
+instance.
-If you give a zero prefix (i. e., @kbd{C-u 0 C-c C-c}) to that command,
-Gnus will prompt you for what method to use for posting.
+Anyways, you just specify @code{nnspool} as the method and @samp{} (or
+anything else) as the address.
-You can also set @code{gnus-post-method} to a list of select methods.
-If that's the case, Gnus will always prompt you for what method to use
-for posting.
+If you have access to a local spool, you should probably use that as the
+native select method (@pxref{Finding the News}). It is normally faster
+than using an @code{nntp} select method, but might not be. It depends.
+You just have to try to find out what's best at your site.
+@table @code
-@node Mail and Post
-@section Mail and Post
+@item nnspool-inews-program
+@vindex nnspool-inews-program
+Program used to post an article.
-Here's a list of variables that are relevant to both mailing and
-posting:
+@item nnspool-inews-switches
+@vindex nnspool-inews-switches
+Parameters given to the inews program when posting an article.
-@table @code
-@item gnus-mailing-list-groups
-@findex gnus-mailing-list-groups
-@cindex mailing lists
+@item nnspool-spool-directory
+@vindex nnspool-spool-directory
+Where @code{nnspool} looks for the articles. This is normally
+@file{/usr/spool/news/}.
-If your news server offers groups that are really mailing lists that are
-gatewayed to the @sc{nntp} server, you can read those groups without
-problems, but you can't post/followup to them without some difficulty.
-One solution is to add a @code{to-address} to the group parameters
-(@pxref{Group Parameters}). An easier thing to do is set the
-@code{gnus-mailing-list-groups} to a regexp that match the groups that
-really are mailing lists. Then, at least, followups to the mailing
-lists will work most of the time. Posting to these groups (@kbd{a}) is
-still a pain, though.
+@item nnspool-nov-directory
+@vindex nnspool-nov-directory
+Where @code{nnspool} will look for @sc{nov} files. This is normally
+@file{/usr/spool/news/over.view/}.
-@end table
+@item nnspool-lib-dir
+@vindex nnspool-lib-dir
+Where the news lib dir is (@file{/usr/lib/news/} by default).
-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:
+@item nnspool-active-file
+@vindex nnspool-active-file
+The path of the active file.
-@vindex news-inews-hook
-@cindex ispell
-@findex ispell-message
-@lisp
-(add-hook 'message-send-hook 'ispell-message)
-@end lisp
+@item nnspool-newsgroups-file
+@vindex nnspool-newsgroups-file
+The path of the group descriptions file.
+@item nnspool-history-file
+@vindex nnspool-history-file
+The path of the news history file.
-@node Archived Messages
-@section Archived Messages
-@cindex archived messages
-@cindex sent messages
+@item nnspool-active-times-file
+@vindex nnspool-active-times-file
+The path of the active date file.
-Gnus provides a few different methods for storing the mail you send.
-The default method is to use the @dfn{archive virtual server} to store
-the mail. If you want to disable this completely, you should set
-@code{gnus-message-archive-group} to @code{nil}.
+@item nnspool-nov-is-evil
+@vindex nnspool-nov-is-evil
+If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
+that it finds.
-@vindex gnus-message-archive-method
-@code{gnus-message-archive-method} says what virtual server Gnus is to
-use to store sent messages. It is @code{(nnfolder "archive"
-(nnfolder-directory "~/Mail/archive/"))} by default, but you can use any
-mail select method (@code{nnml}, @code{nnmbox}, etc.). However,
-@code{nnfolder} is a quite likeable select method for doing this sort of
-thing. If you don't like the default directory chosen, you could say
-something like:
+@item nnspool-sift-nov-with-sed
+@vindex nnspool-sift-nov-with-sed
+@cindex sed
+If non-@code{nil}, which is the default, use @code{sed} to get the
+relevant portion from the overview file. If nil, @code{nnspool} will
+load the entire file into a buffer and process it there.
-@lisp
-(setq gnus-message-archive-method
- '(nnfolder "archive"
- (nnfolder-inhibit-expiry t)
- (nnfolder-active-file "~/Mail/sent-mail/active")
- (nnfolder-directory "~/News/sent-mail/")))
-@end lisp
+@end table
-@vindex gnus-message-archive-group
-@cindex Gcc
-Gnus will insert @code{Gcc} headers in all outgoing messages that point
-to one or more group(s) on that server. Which group to use is
-determined by the @code{gnus-message-archive-group} variable.
-This variable can be:
+@node Getting Mail
+@section Getting Mail
+@cindex reading mail
+@cindex mail
-@itemize @bullet
-@item a string
-Messages will be saved in that group.
-@item a list of strings
-Messages will be saved in all those groups.
-@item an alist of regexps, functions and forms
-When a key ``matches'', the result is used.
-@end itemize
+Reading mail with a newsreader---isn't that just plain WeIrD? But of
+course.
-Let's illustrate:
+@menu
+* Getting Started Reading Mail:: A simple cookbook example.
+* Splitting Mail:: How to create mail groups.
+* Mail Backend Variables:: Variables for customizing mail handling.
+* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
+* Mail and Procmail:: Reading mail groups that procmail create.
+* Incorporating Old Mail:: What about the old mail you have?
+* Expiring Mail:: Getting rid of unwanted mail.
+* Washing Mail:: Removing gruft from the mail you get.
+* Duplicates:: Dealing with duplicated mail.
+* Not Reading Mail:: Using mail backends for reading other files.
+* Choosing a Mail Backend:: Gnus can read a variety of mail formats.
+@end menu
-Just saving to a single group called @samp{MisK}:
-@lisp
-(setq gnus-message-archive-group "MisK")
-@end lisp
-Saving to two groups, @samp{MisK} and @samp{safe}:
-@lisp
-(setq gnus-message-archive-group '("MisK" "safe"))
-@end lisp
+@node Getting Started Reading Mail
+@subsection Getting Started Reading Mail
-Save to different groups based on what group you are in:
-@lisp
-(setq gnus-message-archive-group
- '(("^alt" "sent-to-alt")
- ("mail" "sent-to-mail")
- (".*" "sent-to-misc")))
-@end lisp
+It's quite easy to use Gnus to read your new mail. You just plonk the
+mail backend of your choice into @code{gnus-secondary-select-methods},
+and things will happen automatically.
+
+For instance, if you want to use @code{nnml} (which is a one file per
+mail backend), you could put the following in your @file{.gnus} file:
-More complex stuff:
@lisp
-(setq gnus-message-archive-group
- '((if (message-news-p)
- "misc-news"
- "misc-mail")))
-@end lisp
+(setq gnus-secondary-select-methods
+ '((nnml "private")))
+@end lisp
-This is the default.
+Now, the next time you start Gnus, this backend will be queried for new
+articles, and it will move all the messages in your spool file to its
+directory, which is @code{~/Mail/} by default. The new group that will
+be created (@samp{mail.misc}) will be subscribed, and you can read it
+like any other group.
-How about storing all news messages in one file, but storing all mail
-messages in one file per month:
+You will probably want to split the mail into several groups, though:
@lisp
-(setq gnus-message-archive-group
- '((if (message-news-p)
- "misc-news"
- (concat "mail." (format-time-string
- "%Y-%m" (current-time))))))
+(setq nnmail-split-methods
+ '(("junk" "^From:.*Lars Ingebrigtsen")
+ ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
+ ("other" "")))
@end lisp
-Now, when you send a message off, it will be stored in the appropriate
-group. (If you want to disable storing for just one particular message,
-you can just remove the @code{Gcc} header that has been inserted.) The
-archive group will appear in the group buffer the next time you start
-Gnus, or the next time you press @kbd{F} in the group buffer. You can
-enter it and read the articles in it just like you'd read any other
-group. If the group gets really big and annoying, you can simply rename
-if (using @kbd{G r} in the group buffer) to something nice --
-@samp{misc-mail-september-1995}, or whatever. New messages will
-continue to be stored in the old (now empty) group.
+This will result in three new @code{nnml} mail groups being created:
+@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the
+mail that doesn't fit into the first two groups will be placed in the
+latter group.
-That's the default method of archiving sent mail. Gnus also offers two
-other variables for the people who don't like the default method. In
-that case you should set @code{gnus-message-archive-group} to
-@code{nil}; this will disable archiving.
+This should be sufficient for reading mail with Gnus. You might want to
+give the other sections in this part of the manual a perusal, though,
+especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}.
-@table @code
-@item gnus-author-copy
-@vindex gnus-author-copy
-@cindex AUTHORCOPY
-This is a file name, and all outgoing articles will be saved in that
-file. Initialized from the @code{AUTHORCOPY} environment variable.
-If this variable begins with the character @samp{|}, outgoing articles
-will be piped to the named program. It is possible to save an article in
-an MH folder as follows:
+@node Splitting Mail
+@subsection Splitting Mail
+@cindex splitting mail
+@cindex mail splitting
+
+@vindex nnmail-split-methods
+The @code{nnmail-split-methods} variable says how the incoming mail is
+to be split into groups.
@lisp
-(setq gnus-author-copy
- "|/usr/local/lib/mh/rcvstore +Article")
+(setq nnmail-split-methods
+ '(("mail.junk" "^From:.*Lars Ingebrigtsen")
+ ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
+ ("mail.other" "")))
@end lisp
-If the first character is not a pipe, articles are saved using the
-function specified by the @code{gnus-author-copy-saver} variable.
-
-@item gnus-author-copy-saver
-@vindex gnus-author-copy-saver
-@findex rmail-output
-A function called to save outgoing articles. This function will be
-called with the same of the file to store the article in. The default
-function is @code{rmail-output} which saves in the Unix mailbox format.
-
-@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.
+This variable is a list of lists, where the first element of each of
+these lists is the name of the mail group (they do not have to be called
+something beginning with @samp{mail}, by the way), and the second
+element is a regular expression used on the header of each mail to
+determine if it belongs in this mail group.
-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
+If the first element is the special symbol @code{junk}, then messages
+that match the regexp will disappear into the aether. Use with
+extreme caution.
+The second element can also be a function. In that case, it will be
+called narrowed to the headers with the first element of the rule as the
+argument. It should return a non-@code{nil} value if it thinks that the
+mail belongs in that group.
-@node Posting Styles
-@section Posting Styles
-@cindex posting styles
-@cindex styles
+The last of these groups should always be a general one, and the regular
+expression should @emph{always} be @samp{} so that it matches any
+mails that haven't been matched by any of the other regexps.
-All them variables, they make my head swim.
+If you like to tinker with this yourself, you can set this variable to a
+function of your choice. This function will be called without any
+arguments in a buffer narrowed to the headers of an incoming mail
+message. The function should return a list of groups names that it
+thinks should carry this mail message.
-So what if you want a different @code{Organization} and signature based
-on what groups you post to? And you post both from your home machine
-and your work machine, and you want different @code{From} lines, and so
-on?
+Note that the mail backends are free to maul the poor, innocent
+incoming headers all they want to. They all add @code{Lines} headers;
+some add @code{X-Gnus-Group} headers; most rename the Unix mbox
+@code{From<SPACE>} line to something else.
-@vindex gnus-posting-styles
-One way to do stuff like that is to write clever hooks that change the
-variables you need to have changed. That's a bit boring, so somebody
-came up with the bright idea of letting the user specify these things in
-a handy alist. Here's an example of a @code{gnus-posting-styles}
-variable:
+@vindex nnmail-crosspost
+The mail backends all support cross-posting. If several regexps match,
+the mail will be ``cross-posted'' to all those groups.
+@code{nnmail-crosspost} says whether to use this mechanism or not. Note
+that no articles are crossposted to the general (@samp{}) group.
-@lisp
-((".*"
- (signature . "Peace and happiness")
- (organization . "What me?"))
- ("^comp"
- (signature . "Death to everybody"))
- ("comp.emacs.i-love-it"
- (organization . "Emacs is it")))
-@end lisp
+@vindex nnmail-crosspost-link-function
+@cindex crosspost
+@cindex links
+@code{nnmh} and @code{nnml} makes crossposts by creating hard links to
+the crossposted articles. However, not all files systems support hard
+links. If that's the case for you, set
+@code{nnmail-crosspost-link-function} to @code{copy-file}. (This
+variable is @code{add-name-to-file} by default.)
-As you might surmise from this example, this alist consists of several
-@dfn{styles}. Each style will be applicable if the first element
-``matches'', in some form or other. The entire alist will be iterated
-over, from the beginning towards the end, and each match will be
-applied, which means that attributes in later styles that match override
-the same attributes in earlier matching styles. So
-@samp{comp.programming.literate} will have the @samp{Death to everybody}
-signature and the @samp{What me?} @code{Organization} header.
-
-The first element in each style is called the @code{match}. If it's a
-string, then Gnus will try to regexp match it against the group name.
-If it's a function symbol, that function will be called with no
-arguments. If it's a variable symbol, then the variable will be
-referenced. If it's a list, then that list will be @code{eval}ed. In
-any case, if this returns a non-@code{nil} value, then the style is said
-to @dfn{match}.
-
-Each style may contain a arbitrary amount of @dfn{attributes}. Each
-attribute consists of a @var{(name . value)} pair. The attribute name
-can be one of @code{signature}, @code{organization} or @code{from}. The
-attribute name can also be a string. In that case, this will be used as
-a header name, and the value will be inserted in the headers of the
-article.
+@kindex M-x nnmail-split-history
+@kindex nnmail-split-history
+If you wish to see where the previous mail split put the messages, you
+can use the @kbd{M-x nnmail-split-history} command.
-The attribute value can be a string (used verbatim), a function (the
-return value will be used), a variable (its value will be used) or a
-list (it will be @code{eval}ed and the return value will be used).
-
-So here's a new example:
-
-@lisp
-(setq gnus-posting-styles
- '((".*"
- (signature . "~/.signature")
- (from . "user@@foo (user)")
- ("X-Home-Page" . (getenv "WWW_HOME"))
- (organization . "People's Front Against MWM"))
- ("^rec.humor"
- (signature . my-funny-signature-randomizer))
- ((equal (system-name) "gnarly")
- (signature . my-quote-randomizer))
- (posting-from-work-p
- (signature . "~/.work-signature")
- (from . "user@@bar.foo (user)")
- (organization . "Important Work, Inc"))
- ("^nn.+:"
- (signature . "~/.mail-signature"))))
-@end lisp
+Gnus gives you all the opportunity you could possibly want for shooting
+yourself in the foot. Let's say you create a group that will contain
+all the mail you get from your boss. And then you accidentally
+unsubscribe from the group. Gnus will still put all the mail from your
+boss in the unsubscribed group, and so, when your boss mails you ``Have
+that report ready by Monday or you're fired!'', you'll never see it and,
+come Tuesday, you'll still believe that you're gainfully employed while
+you really should be out collecting empty bottles to save up for next
+month's rent money.
-@node Drafts
-@section Drafts
-@cindex drafts
-
-If you are writing a message (mail or news) and suddenly remember that
-you have a steak in the oven (or some 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.
-
-Well, don't worry about it. Whenever you start composing a message of
-some sort using the Gnus mail and post commands, the buffer you get will
-automatically associate to an article in a special @dfn{draft} group.
-If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
-article will be saved there. (Auto-save files also go to the draft
-group.)
-
-@cindex nndraft
-@vindex gnus-draft-group-directory
-The draft group is a special group (which is implemented as an
-@code{nndraft} group, if you absolutely have to know) called
-@samp{nndraft: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. What makes this
-group special is that you can't tick any articles in it or mark any
-articles as read---all articles in the group are permanently unread.
-
-If the group doesn't exist, it will be created and you'll be subscribed
-to it.
-
-@findex gnus-dissociate-buffer-from-draft
-@kindex C-c M-d (Mail)
-@kindex C-c M-d (Post)
-@findex gnus-associate-buffer-with-draft
-@kindex C-c C-d (Mail)
-@kindex C-c C-d (Post)
-If you're writing some super-secret message that you later want to
-encode with PGP before sending, you may wish to turn the auto-saving
-(and association with the draft group) off. You never know who might be
-interested in reading all your extremely valuable and terribly horrible
-and interesting secrets. The @kbd{C-c M-d}
-(@code{gnus-dissociate-buffer-from-draft}) command does that for you.
-If you change your mind and want to turn the auto-saving back on again,
-@kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
-
-@vindex gnus-use-draft
-To leave association with the draft group off by default, set
-@code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
-
-@findex gnus-summary-send-draft
-@kindex S D c (Summary)
-When you want to continue editing the article, you simply enter the
-draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
-that. You will be placed in a buffer where you left off.
-
-Rejected articles will also be put in this draft group (@pxref{Rejected
-Articles}).
-
-@findex gnus-summary-send-all-drafts
-If you have lots of rejected messages you want to post (or mail) without
-doing further editing, you can use the @kbd{S D a} command
-(@code{gnus-summary-send-all-drafts}). This command understands the
-process/prefix convention (@pxref{Process/Prefix}).
-
-
-@node Rejected Articles
-@section Rejected Articles
-@cindex rejected articles
-
-Sometimes a news server will reject an article. Perhaps the server
-doesn't like your face. Perhaps it just feels miserable. Perhaps
-@emph{there be demons}. Perhaps you have included too much cited text.
-Perhaps the disk is full. Perhaps the server is down.
-
-These situations are, of course, totally beyond the control of Gnus.
-(Gnus, of course, loves the way you look, always feels great, has angels
-fluttering around inside of it, doesn't care about how much cited text
-you include, never runs full and never goes down.) So Gnus saves these
-articles until some later time when the server feels better.
-
-The rejected articles will automatically be put in a special draft group
-(@pxref{Drafts}). When the server comes back up again, you'd then
-typically enter that group and send all the articles off.
+@node Mail Backend Variables
+@subsection Mail Backend Variables
+These variables are (for the most part) pertinent to all the various
+mail backends.
-@node Select Methods
-@chapter Select Methods
-@cindex foreign groups
-@cindex select methods
+@table @code
+@vindex nnmail-read-incoming-hook
+@item nnmail-read-incoming-hook
+The mail backends all call this hook after reading new mail. You can
+use this hook to notify any mail watch programs, if you want to.
-A @dfn{foreign group} is a group that is not read by the usual (or
-default) means. It could be, for instance, a group from a different
-@sc{nntp} server, it could be a virtual group, or it could be your own
-personal mail group.
+@vindex nnmail-spool-file
+@item nnmail-spool-file
+@cindex POP mail
+@cindex MAILHOST
+@cindex movemail
+@vindex nnmail-pop-password
+@vindex nnmail-pop-password-required
+The backends will look for new mail in this file. If this variable is
+@code{nil}, the mail backends will never attempt to fetch mail by
+themselves. If you are using a POP mail server and your name is
+@samp{larsi}, you should set this variable to @samp{po:larsi}. If
+your name is not @samp{larsi}, you should probably modify that
+slightly, but you may have guessed that already, you smart & handsome
+devil! You can also set this variable to @code{pop}, and Gnus will try
+to figure out the POP mail string by itself. In any case, Gnus will
+call @code{movemail} which will contact the POP server named in the
+@code{MAILHOST} environment variable. If the POP server needs a
+password, you can either set @code{nnmail-pop-password-required} to
+@code{t} and be prompted for the password, or set
+@code{nnmail-pop-password} to the password itself.
-A foreign group (or any group, really) is specified by a @dfn{name} and
-a @dfn{select method}. To take the latter first, a select method is a
-list where the first element says what backend to use (eg. @code{nntp},
-@code{nnspool}, @code{nnml}) and the second element is the @dfn{server
-name}. There may be additional elements in the select method, where the
-value may have special meaning for the backend in question.
+Your Emacs has to have been configured with @samp{--with-pop} before
+compilation. This is the default, but some installations have it
+switched off.
-One could say that a select method defines a @dfn{virtual server}---so
-we do just that (@pxref{The Server Buffer}).
+When you use a mail backend, Gnus will slurp all your mail from your
+inbox and plonk it down in your home directory. Gnus doesn't move any
+mail if you're not using a mail backend---you have to do a lot of magic
+invocations first. At the time when you have finished drawing the
+pentagram, lightened the candles, and sacrificed the goat, you really
+shouldn't be too surprised when Gnus moves your mail.
-The @dfn{name} of the group is the name the backend will recognize the
-group as.
+@vindex nnmail-use-procmail
+@vindex nnmail-procmail-suffix
+@item nnmail-use-procmail
+If 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{nnmail-procmail-suffix}
+will be considered incoming mailboxes, and will be searched for new
+mail.
-For instance, the group @samp{soc.motss} on the @sc{nntp} server
-@samp{some.where.edu} will have the name @samp{soc.motss} and select
-method @code{(nntp "some.where.edu")}. Gnus will call this group, in
-all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
-@code{nntp} backend just knows this group as @samp{soc.motss}.
+@vindex nnmail-crash-box
+@item nnmail-crash-box
+When the mail backends read a spool file, it is first moved to this
+file, which is @file{~/.gnus-crash-box} by default. If this file
+already exists, it will always be read (and incorporated) before any
+other spool files.
-The different methods all have their peculiarities, of course.
+@vindex nnmail-prepare-incoming-hook
+@item nnmail-prepare-incoming-hook
+This is run in a buffer that holds all the new incoming mail, and can be
+used for, well, anything, really.
-@menu
-* The Server Buffer:: Making and editing virtual servers.
-* Getting News:: Reading USENET news with Gnus.
-* Getting Mail:: Reading your personal mail with Gnus.
-* Other Sources:: Reading directories, files, SOUP packets.
-* Combined Groups:: Combining groups into one group.
-@end menu
+@vindex nnmail-split-hook
+@item nnmail-split-hook
+@findex article-decode-rfc1522
+@findex RFC1522 decoding
+Hook run in the buffer where the mail headers of each message is kept
+just before the splitting based on these headers is done. The hook is
+free to modify the buffer contents in any way it sees fit---the buffer
+is discarded after the splitting has been done, and no changes performed
+in the buffer will show up in any files. @code{article-decode-rfc1522}
+is one likely function to add to this hook.
+@vindex nnmail-pre-get-new-mail-hook
+@vindex nnmail-post-get-new-mail-hook
+@item nnmail-pre-get-new-mail-hook
+@itemx nnmail-post-get-new-mail-hook
+These are two useful hooks executed when treating new incoming
+mail---@code{nnmail-pre-get-new-mail-hook} (is called just before
+starting to handle the new mail) and
+@code{nnmail-post-get-new-mail-hook} (is called when the mail handling
+is done). Here's and example of using these two hooks to change the
+default file modes the new mail files get:
-@node The Server Buffer
-@section The Server Buffer
+@lisp
+(add-hook 'gnus-pre-get-new-mail-hook
+ (lambda () (set-default-file-modes 511)))
-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.
+(add-hook 'gnus-post-get-new-mail-hook
+ (lambda () (set-default-file-modes 551)))
+@end lisp
-For instance, the @code{nntp} backend may be used to connect to several
-different actual @sc{nntp} servers, or, perhaps, to many different ports
-on the same actual @sc{nntp} server. You tell Gnus which backend to
-use, and what parameters to set by specifying a @dfn{select method}.
+@item nnmail-tmp-directory
+@vindex nnmail-tmp-directory
+This variable says where to move the incoming mail to while processing
+it. This is usually done in the same directory that the mail backend
+inhabits (i.e., @file{~/Mail/}), but if this variable is non-@code{nil},
+it will be used instead.
-These select methods specifications can sometimes become quite
-complicated---say, for instance, that you want to read from the
-@sc{nntp} server @samp{news.funet.fi} on port number @code{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 naming
-select methods, which is what you do in the server buffer.
+@item nnmail-movemail-program
+@vindex nnmail-movemail-program
+This program is executed to move mail from the user's inbox to her home
+directory. The default is @samp{movemail}.
-To enter the server buffer, user the @kbd{^}
-(@code{gnus-group-enter-server-mode}) command in the group buffer.
+This can also be a function. In that case, the function will be called
+with two parameters -- the name of the inbox, and the file to be moved
+to.
-@menu
-* Server Buffer Format:: You can customize the look of this buffer.
-* Server Commands:: Commands to manipulate servers.
-* Example Methods:: Examples server specifications.
-* Creating a Virtual Server:: An example session.
-* Servers and Methods:: You can use server names as select methods.
-* Unavailable Servers:: Some servers you try to contact may be down.
-@end menu
+@item nnmail-delete-incoming
+@vindex nnmail-delete-incoming
+@cindex incoming mail files
+@cindex deleting incoming files
+If 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 gnus-server-mode-hook
-@code{gnus-server-mode-hook} is run when creating the server buffer.
+Since Red Gnus is an alpha release, it is to be expected to lose mail.
+(No Gnus release since (ding) Gnus 0.10 (or something like that) have
+lost mail, I think, but that's not the point.) By not deleting the
+Incoming* files, one can be sure to not lose mail -- if Gnus totally
+whacks out, one can always recover what was lost.
+Delete the @file{Incoming*} files at will.
-@node Server Buffer Format
-@subsection Server Buffer Format
-@cindex server buffer format
+@item nnmail-use-long-file-names
+@vindex nnmail-use-long-file-names
+If non-@code{nil}, the mail backends will use long file and directory
+names. Groups like @samp{mail.misc} will end up in directories like
+@file{mail.misc/}. If it is @code{nil}, the same group will end up in
+@file{mail/misc/}.
-@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:
+@item nnmail-delete-file-function
+@vindex nnmail-delete-file-function
+@findex delete-file
+Function called to delete files. It is @code{delete-file} by default.
-@table @samp
+@end table
-@item h
-How the news is fetched---the backend name.
-@item n
-The name of this server.
+@node Fancy Mail Splitting
+@subsection Fancy Mail Splitting
+@cindex mail splitting
+@cindex fancy mail splitting
-@item w
-Where the news is to be fetched from---the address.
-
-@item s
-The opened/closed/denied status of the server.
-@end table
-
-@vindex gnus-server-mode-line-format
-The mode line can also be customized by using the
-@code{gnus-server-mode-line-format} variable. The following specs are
-understood:
+@vindex nnmail-split-fancy
+@findex nnmail-split-fancy
+If the rather simple, standard method for specifying how to split mail
+doesn't allow you to do what you want, you can set
+@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
+play with the @code{nnmail-split-fancy} variable.
-@table @samp
-@item S
-Server name.
+Let's look at an example value of this variable first:
-@item M
-Server method.
-@end table
+@lisp
+;; Messages from the mailer daemon are not crossposted to any of
+;; the ordinary groups. Warnings are put in a separate group
+;; from real errors.
+(| ("from" mail (| ("subject" "warn.*" "mail.warning")
+ "mail.misc"))
+ ;; Non-error messages are crossposted to all relevant
+ ;; groups, but we don't crosspost between the group for the
+ ;; (ding) list and the group for other (ding) related mail.
+ (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
+ ("subject" "ding" "ding.misc"))
+ ;; Other mailing lists...
+ (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
+ (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
+ ;; People...
+ (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
+ ;; Unmatched mail goes to the catch all group.
+ "misc.misc"))")
+@end lisp
-Also @pxref{Formatting Variables}.
+This variable has the format of a @dfn{split}. A split is a (possibly)
+recursive structure where each split may contain other splits. Here are
+the five possible split syntaxes:
+@enumerate
-@node Server Commands
-@subsection Server Commands
-@cindex server commands
+@item
+@samp{group}: If the split is a string, that will be taken as a group name.
-@table @kbd
+@item
+@var{(FIELD VALUE SPLIT)}: If the split is a list, and the first
+element is a string, then that means that if header FIELD (a regexp)
+contains VALUE (also a regexp), then store the message as specified by
+SPLIT.
-@item a
-@kindex a (Server)
-@findex gnus-server-add-server
-Add a new server (@code{gnus-server-add-server}).
+@item
+@var{(| SPLIT...)}: If the split is a list, and the first element is
+@code{|} (vertical bar), then process each SPLIT until one of them
+matches. A SPLIT is said to match if it will cause the mail message to
+be stored in one or more groups.
-@item e
-@kindex e (Server)
-@findex gnus-server-edit-server
-Edit a server (@code{gnus-server-edit-server}).
+@item
+@var{(& SPLIT...)}: If the split is a list, and the first element is
+@code{&}, then process all SPLITs in the list.
-@item SPACE
-@kindex SPACE (Server)
-@findex gnus-server-read-server
-Browse the current server (@code{gnus-server-read-server}).
+@item
+@code{junk}: If the split is the symbol @code{junk}, then don't save
+this message anywhere.
-@item q
-@kindex q (Server)
-@findex gnus-server-exit
-Return to the group buffer (@code{gnus-server-exit}).
+@end enumerate
-@item k
-@kindex k (Server)
-@findex gnus-server-kill-server
-Kill the current server (@code{gnus-server-kill-server}).
+In these splits, FIELD must match a complete field name. VALUE must
+match a complete word according to the fundamental mode syntax table.
+You can use @code{.*} in the regexps to match partial field names or
+words.
-@item y
-@kindex y (Server)
-@findex gnus-server-yank-server
-Yank the previously killed server (@code{gnus-server-yank-server}).
+@vindex nnmail-split-abbrev-alist
+FIELD and VALUE can also be lisp symbols, in that case they are expanded
+as specified by the variable @code{nnmail-split-abbrev-alist}. This is
+an alist of cons cells, where the car of the cells contains the key, and
+the cdr contains a string.
-@item c
-@kindex c (Server)
-@findex gnus-server-copy-server
-Copy the current server (@code{gnus-server-copy-server}).
+@vindex nnmail-split-fancy-syntax-table
+@code{nnmail-split-fancy-syntax-table} is the syntax table in effect
+when all this splitting is performed.
-@item l
-@kindex l (Server)
-@findex gnus-server-list-servers
-List all servers (@code{gnus-server-list-servers}).
-@end table
+@node Mail and Procmail
+@subsection Mail and Procmail
+@cindex procmail
+@cindex slocal
+@cindex elm
+Many people use @code{procmail} (or some other mail filter program or
+external delivery agent---@code{slocal}, @code{elm}, etc) to split
+incoming mail into groups. If you do that, you should set
+@code{nnmail-spool-file} to @code{procmail} to ensure that the mail
+backends never ever try to fetch mail by themselves.
-@node Example Methods
-@subsection Example Methods
+This also means that you probably don't want to set
+@code{nnmail-split-methods} either, which has some, perhaps, unexpected
+side effects.
-Most select methods are pretty simple and self-explanatory:
+When a mail backend is queried for what groups it carries, it replies
+with the contents of that variable, along with any groups it has figured
+out that it carries by other means. None of the backends (except
+@code{nnmh}) actually go out to the disk and check what groups actually
+exist. (It's not trivial to distinguish between what the user thinks is
+a basis for a newsgroup and what is just a plain old file or directory.)
-@lisp
-(nntp "news.funet.fi")
-@end lisp
+This means that you have to tell Gnus (and the backends) what groups
+exist by hand.
-Reading directly from the spool is even simpler:
+Let's take the @code{nnmh} backend as an example.
-@lisp
-(nnspool "")
-@end lisp
+The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
+There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
-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.
+Go to the group buffer and type @kbd{G m}. When prompted, answer
+@samp{foo} for the name and @samp{nnmh} for the method. Repeat
+twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
+to include all your mail groups.
-After these two elements, there may be a arbitrary number of
-@var{(variable form)} pairs.
+That's it. You are now set to read your mail. An active file for this
+method will be created automatically.
-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:
+@vindex nnmail-procmail-suffix
+@vindex nnmail-procmail-directory
+If you use @code{nnfolder} or any other backend that store more than a
+single article in each file, you should never have procmail add mails to
+the file that Gnus sees. Instead, procmail should put all incoming mail
+in @code{nnmail-procmail-directory}. To arrive at the file name to put
+the incoming mail in, append @code{nnmail-procmail-suffix} to the group
+name. The mail backends will read the mail from these files.
-@lisp
-(nntp "news.funet.fi" (nntp-port-number 15))
-@end lisp
+@vindex nnmail-resplit-incoming
+When Gnus reads a file called @file{mail.misc.spool}, this mail will be
+put in the @code{mail.misc}, as one would expect. However, if you want
+Gnus to split the mail the normal way, you could set
+@code{nnmail-resplit-incoming} to @code{t}.
-You should read the documentation to each backend to find out what
-variables are relevant, but here's an @code{nnmh} example.
+@vindex nnmail-keep-last-article
+If you use @code{procmail} to split things directory into an @code{nnmh}
+directory (which you shouldn't do), you should set
+@code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
+ever expiring the final article in a mail newsgroup. This is quite,
+quite important.
-@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:
+Here's an example setup: The incoming spools are located in
+@file{~/incoming/} and have @samp{""} as suffixes (i. e., the incoming
+spool files have the same names as the equivalent groups). The
+@code{nnfolder} backend is to be used as the mail interface, and the
+@code{nnfolder} directory is @file{~/fMail/}.
@lisp
-(nnmh "private" (nnmh-directory "~/private/mail/"))
+(setq nnfolder-directory "~/fMail/")
+(setq nnmail-spool-file 'procmail)
+(setq nnmail-procmail-directory "~/incoming/")
+(setq gnus-secondary-select-methods '((nnfolder "")))
+(setq nnmail-procmail-suffix "")
@end lisp
-(This server is then called @samp{private}, but you may have guessed
-that.)
-
-Here's the method for a public spool:
-@lisp
-(nnmh "public"
- (nnmh-directory "/usr/information/spool/")
- (nnmh-get-new-mail nil))
-@end lisp
+@node Incorporating Old Mail
+@subsection Incorporating Old Mail
+Most people have lots of old mail stored in various file formats. If
+you have set up Gnus to read mail using one of the spiffy Gnus mail
+backends, you'll probably wish to have that old mail incorporated into
+your mail groups.
-@node Creating a Virtual Server
-@subsection Creating a Virtual Server
+Doing so can be quite easy.
-If you're saving lots of articles in the cache by using persistent
-articles, you may want to create a virtual server to read the cache.
+To take an example: You're reading mail using @code{nnml}
+(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a
+satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox
+file filled with important, but old, mail. You want to move it into
+your @code{nnml} groups.
-First you need to add a new server. The @kbd{a} command does that. It
-would probably be best to use @code{nnspool} to read the cache. You
-could also use @code{nnml} or @code{nnmh}, though.
+Here's how:
-Type @kbd{a nnspool RET cache RET}.
+@enumerate
+@item
+Go to the group buffer.
-You should now have a brand new @code{nnspool} virtual server called
-@samp{cache}. You now need to edit it to have the right definitions.
-Type @kbd{e} to edit the server. You'll be entered into a buffer that
-will contain the following:
+@item
+Type `G f' and give the path of the mbox file when prompted to create an
+@code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
-@lisp
-(nnspool "cache")
-@end lisp
+@item
+Type `SPACE' to enter the newly created group.
-Change that to:
+@item
+Type `M P b' to process-mark all articles in this group (@pxref{Setting
+Process Marks}).
-@lisp
-(nnspool "cache"
- (nnspool-spool-directory "~/News/cache/")
- (nnspool-nov-directory "~/News/cache/")
- (nnspool-active-file "~/News/cache/active"))
-@end lisp
+@item
+Type `B r' to respool all the process-marked articles, and answer
+@samp{nnml} when prompted (@pxref{Mail Group Commands}).
+@end enumerate
-Type @kbd{C-c C-c} to return to the server buffer. If you now press
-@kbd{RET} over this virtual server, you should be entered into a browse
-buffer, and you should be able to enter any of the groups displayed.
+All the mail messages in the mbox file will now also be spread out over
+all your @code{nnml} groups. Try entering them and check whether things
+have gone without a glitch. If things look ok, you may consider
+deleting the mbox file, but I wouldn't do that unless I was absolutely
+sure that all the mail has ended up where it should be.
+Respooling is also a handy thing to do if you're switching from one mail
+backend to another. Just respool all the mail in the old mail groups
+using the new mail backend.
-@node Servers and Methods
-@subsection Servers and Methods
-Wherever you would normally use a select method
-(eg. @code{gnus-secondary-select-method}, in the group select method,
-when browsing a foreign server) you can use a virtual server name
-instead. This could potentially save lots of typing. And it's nice all
-over.
+@node Expiring Mail
+@subsection Expiring Mail
+@cindex article expiry
+Traditional mail readers have a tendency to remove mail articles when
+you mark them as read, in some way. Gnus takes a fundamentally
+different approach to mail reading.
-@node Unavailable Servers
-@subsection Unavailable Servers
+Gnus basically considers mail just to be news that has been received in
+a rather peculiar manner. It does not think that it has the power to
+actually change the mail, or delete any mail messages. If you enter a
+mail group, and mark articles as ``read'', or kill them in some other
+fashion, the mail articles will still exist on the system. I repeat:
+Gnus will not delete your old, read mail. Unless you ask it to, of
+course.
-If a server seems to be unreachable, Gnus will mark that server as
-@code{denied}. That means that any subsequent attempt to make contact
-with that server will just be ignored. ``It can't be opened,'' Gnus
-will tell you, without making the least effort to see whether that is
-actually the case or not.
+To make Gnus get rid of your unwanted mail, you have to mark the
+articles as @dfn{expirable}. This does not mean that the articles will
+disappear right away, however. In general, a mail article will be
+deleted from your system if, 1) it is marked as expirable, AND 2) it is
+more than one week old. If you do not mark an article as expirable, it
+will remain on your system until hell freezes over. This bears
+repeating one more time, with some spurious capitalizations: IF you do
+NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
-That might seem quite naughty, but it does make sense most of the time.
-Let's say you have 10 groups subscribed to the server
-@samp{nepholococcygia.com}. This server is located somewhere quite far
-away from you, the machine is quite, so it takes 1 minute just to find
-out that it refuses connection from you today. If Gnus were to attempt
-to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
-that. Once it has gotten a single ``connection refused'', it will
-regard that server as ``down''.
+@vindex gnus-auto-expirable-newsgroups
+You do not have to mark articles as expirable by hand. Groups that
+match the regular expression @code{gnus-auto-expirable-newsgroups} will
+have all articles that you read marked as expirable automatically. All
+articles that are marked as expirable have an @samp{E} in the first
+column in the summary buffer.
-So, what happens if the machine was only feeling unwell temporarily?
-How do you test to see whether the machine has come up again?
+Note that making a group auto-expirable don't mean that all read
+articles are expired---only the articles that are marked as expirable
+will be expired. Also note the using the @kbd{d} command won't make
+groups expirable---only semi-automatic marking of articles as read will
+mark the articles as expirable in auto-expirable groups.
-You jump to the server buffer (@pxref{The Server Buffer}) and poke it
-with the following commands:
+Let's say you subscribe to a couple of mailing lists, and you want the
+articles you have read to disappear after a while:
-@table @kbd
+@lisp
+(setq gnus-auto-expirable-newsgroups
+ "mail.nonsense-list\\|mail.nice-list")
+@end lisp
-@item O
-@kindex O (Server)
-@findex gnus-server-open-server
-Try to establish connection to the server on the current line
-(@code{gnus-server-open-server}).
+Another way to have auto-expiry happen is to have the element
+@code{auto-expire} in the group parameters of the group.
-@item C
-@kindex C (Server)
-@findex gnus-server-close-server
-Close the connection (if any) to the server
-(@code{gnus-server-close-server}).
+If you use adaptive scoring (@pxref{Adaptive Scoring}) and
+auto-expiring, you'll have problems. Auto-expiring and adaptive scoring
+doesn't really mix very well.
-@item D
-@kindex D (Server)
-@findex gnus-server-deny-server
-Mark the current server as unreachable
-(@code{gnus-server-deny-server}).
+@vindex nnmail-expiry-wait
+The @code{nnmail-expiry-wait} variable supplies the default time an
+expirable article has to live. The default is seven days.
-@item R
-@kindex R (Server)
-@findex gnus-server-remove-denials
-Remove all marks to whether Gnus was denied connection from all servers
-(@code{gnus-server-remove-denials}).
+Gnus also supplies a function that lets you fine-tune how long articles
+are to live, based on what group they are in. Let's say you want to
+have one month expiry period in the @samp{mail.private} group, a one day
+expiry period in the @samp{mail.junk} group, and a six day expiry period
+everywhere else:
-@end table
+@vindex nnmail-expiry-wait-function
+@lisp
+(setq nnmail-expiry-wait-function
+ (lambda (group)
+ (cond ((string= group "mail.private")
+ 31)
+ ((string= group "mail.junk")
+ 1)
+ ((string= group "important")
+ 'never)
+ (t
+ 6))))
+@end lisp
+The group names that this function is fed are ``unadorned'' group
+names---no @samp{nnml:} prefixes and the like.
-@node Getting News
-@section Getting News
-@cindex reading news
-@cindex news backends
+The @code{nnmail-expiry-wait} variable and
+@code{nnmail-expiry-wait-function} function can be either a number (not
+necessarily an integer) or the symbols @code{immediate} or
+@code{never}.
-A newsreader is normally used for reading news. Gnus currently provides
-only two methods of getting news -- it can read from an @sc{nntp}
-server, or it can read from a local spool.
+You can also use the @code{expiry-wait} group parameter to selectively
+change the expiry period (@pxref{Group Parameters}).
-@menu
-* NNTP:: Reading news from an @sc{nntp} server.
-* News Spool:: Reading news from the local spool.
-@end menu
+@vindex nnmail-keep-last-article
+If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
+expire the final article in a mail newsgroup. This is to make life
+easier for procmail users.
+@vindex gnus-total-expirable-newsgroups
+By the way, that line up there about Gnus never expiring non-expirable
+articles is a lie. If you put @code{total-expire} in the group
+parameters, articles will not be marked as expirable, but all read
+articles will be put through the expiry process. Use with extreme
+caution. Even more dangerous is the
+@code{gnus-total-expirable-newsgroups} variable. All groups that match
+this regexp will have all read articles put through the expiry process,
+which means that @emph{all} old mail articles in the groups in question
+will be deleted after a while. Use with extreme caution, and don't come
+crying to me when you discover that the regexp you used matched the
+wrong group and all your important mail has disappeared. Be a
+@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
+with! So there!
-@node NNTP
-@subsection @sc{nntp}
-@cindex nntp
+Most people make most of their mail groups total-expirable, though.
-Subscribing to a foreign group from an @sc{nntp} server is rather easy.
-You just specify @code{nntp} as method and the address of the @sc{nntp}
-server as the, uhm, address.
-If the @sc{nntp} server is located at a non-standard port, setting the
-third element of the select method to this port number should allow you
-to connect to the right port. You'll have to edit the group info for
-that (@pxref{Foreign Groups}).
+@node Washing Mail
+@subsection Washing Mail
+@cindex mail washing
+@cindex list server brain damage
+@cindex incoming mail treatment
-The name of the foreign group can be the same as a native group. In
-fact, you can subscribe to the same group from as many different servers
-you feel like. There will be no name collisions.
+Mailers and list servers are notorious for doing all sorts of really,
+really stupid things with mail. ``Hey, RFC822 doesn't explicitly
+prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the
+end of all lines passing through our server, so let's do that!!!!1!''
+Yes, but RFC822 wasn't designed to be read by morons. Things that were
+considered to be self-evident were not discussed. So. Here we are.
-The following variables can be used to create a virtual @code{nntp}
-server:
+Case in point: The German version of Microsoft Exchange adds @samp{AW:
+} to the subjects of replies instead of @samp{Re: }. I could pretend to
+be shocked and dismayed by this, but I haven't got the energy. It is to
+laugh.
-@table @code
+Gnus provides a plethora of functions for washing articles while
+displaying them, but it might be nicer to do the filtering before
+storing the mail to disc. For that purpose, we have three hooks and
+various functions that can be put in these hooks.
-@item nntp-server-opened-hook
-@vindex nntp-server-opened-hook
-@cindex @sc{mode reader}
-@cindex authinfo
-@cindex authentification
-@cindex nntp authentification
-@findex nntp-send-authinfo
-@findex nntp-send-mode-reader
-@code{nntp-server-opened-hook} is run after a connection has been made.
-It can be used to send commands to the @sc{nntp} server after it has
-been contacted. By default is sends the command @code{MODE READER} to
-the server with the @code{nntp-send-mode-reader} function. Another
-popular function is @code{nntp-send-authinfo}, which will prompt you for
-an @sc{nntp} password and stuff.
+@table @code
+@item nnmail-prepare-incoming-hook
+@vindex nnmail-prepare-incoming-hook
+This hook is called before doing anything with the mail and is meant for
+grand, sweeping gestures. Functions to be used include:
-@item nntp-server-action-alist
-@vindex nntp-server-action-alist
-This is an list of regexps to match on server types and actions to be
-taken when matches are made. For instance, if you want Gnus to beep
-every time you connect to innd, you could say something like:
+@table @code
+@item nnheader-ms-strip-cr
+@findex nnheader-ms-strip-cr
+Remove trailing carriage returns from each line. This is default on
+Emacs running on MS machines.
-@lisp
-(setq nntp-server-action-alist
- '(("innd" (ding))))
-@end lisp
+@end table
-You probably don't want to do that, though.
+@item nnmail-prepare-incoming-header-hook
+@vindex nnmail-prepare-incoming-header-hook
+This hook is called narrowed to each header. It can be used when
+cleaning up the headers. Functions that can be used include:
-The default value is
+@table @code
+@item nnmail-remove-leading-whitespace
+@findex nnmail-remove-leading-whitespace
+Clear leading white space that ``helpful'' listservs have added to the
+headers too make them look nice. Aaah.
+
+@item nnmail-remove-list-identifiers
+@findex nnmail-remove-list-identifiers
+Some list servers add an identifier---for example, @samp{(idm)}---to the
+beginning of all @code{Subject} headers. I'm sure that's nice for
+people who use stone age mail readers. This function will remove
+strings that match the @code{nnmail-list-identifiers} regexp, which can
+also be a list of regexp.
+
+For instance, if you want to remove the @samp{(idm)} and the
+@samp{nagnagnag} identifiers:
@lisp
- '(("nntpd 1\\.5\\.11t"
- (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
+(setq nnmail-list-identifiers
+ '("(idm)" "nagnagnag"))
@end lisp
-This ensures that Gnus doesn't send the @code{MODE READER} command to
-nntpd 1.5.11t, since that command chokes that server, I've been told.
+@item nnmail-remove-tabs
+@findex nnmail-remove-tabs
+Translate all @samp{TAB} characters into @samp{SPACE} characters.
-@item nntp-maximum-request
-@vindex nntp-maximum-request
-If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
-will collect headers by sending a series of @code{head} commands. To
-speed things up, the backend sends lots of these commands without
-waiting for reply, and then reads all the replies. This is controlled
-by the @code{nntp-maximum-request} variable, and is 400 by default. If
-your network is buggy, you should set this to 1.
+@end table
-@item nntp-connection-timeout
-@vindex nntp-connection-timeout
-If you have lots of foreign @code{nntp} groups that you connect to
-regularly, you're sure to have problems with @sc{nntp} servers not
-responding properly, or being too loaded to reply within reasonable
-time. This is can lead to awkward problems, which can be helped
-somewhat by setting @code{nntp-connection-timeout}. This is an integer
-that says how many seconds the @code{nntp} backend should wait for a
-connection before giving up. If it is @code{nil}, which is the default,
-no timeouts are done.
+@item nnmail-prepare-incoming-message-hook
+@vindex nnmail-prepare-incoming-message-hook
+This hook is called narrowed to each message. Functions to be used
+include:
-@item nntp-command-timeout
-@vindex nntp-command-timeout
-@cindex PPP connections
-@cindex dynamic IP addresses
-If you're running Gnus on a machine that has a dynamically assigned
-address, Gnus may become confused. If the address of your machine
-changes after connecting to the @sc{nntp} server, Gnus will simply sit
-waiting forever for replies from the server. To help with this
-unfortunate problem, you can set this command to a number. Gnus will
-then, if it sits waiting longer than that number of seconds for a reply
-from the server, shut down the connection, start a new one, and resend
-the command. This should hopefully be transparent to the user. A
-likely number is 30 seconds.
+@table @code
+@item article-de-quoted-unreadable
+@findex article-de-quoted-unreadable
+Decode Quoted Readable encoding.
-@item nntp-retry-on-break
-@vindex nntp-retry-on-break
-If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus
-hangs. This will have much the same effect as the command timeout
-described above.
+@end table
+@end table
-@item nntp-server-hook
-@vindex nntp-server-hook
-This hook is run as the last step when connecting to an @sc{nntp}
-server.
-@findex nntp-open-rlogin
-@findex nntp-open-network-stream
-@item nntp-open-server-function
-@vindex nntp-open-server-function
-This function is used to connect to the remote system. Two pre-made
-functions are @code{nntp-open-network-stream}, which is the default, and
-simply connects to some port or other on the remote system. The other
-is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
-and then does a telnet to the @sc{nntp} server available there.
+@node Duplicates
+@subsection Duplicates
-@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}.
+@vindex nnmail-treat-duplicates
+@vindex nnmail-message-id-cache-length
+@vindex nnmail-message-id-cache-file
+@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 treats 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-treat-duplicates} to @code{warn} (which is what it is by
+default), and @code{nnmail} won't delete duplicate mails. Instead it
+will generate a brand new @code{Message-ID} for the mail and insert a
+warning into the head of the mail saying that it thinks that this is a
+duplicate of a different message.
-@item nntp-end-of-line
-@vindex nntp-end-of-line
-String to use as end-of-line markers when talking to the @sc{nntp}
-server. This is @samp{\r\n} by default, but should be @samp{\n} when
-using @code{rlogin} to talk to the server.
+This variable can also be a function. If that's the case, the function
+will be called from a buffer narrowed to the message in question with
+the @code{Message-ID} as a parameter. The function must return either
+@code{nil}, @code{warn}, or @code{delete}.
-@item nntp-rlogin-user-name
-@vindex nntp-rlogin-user-name
-User name on the remote system when using the @code{rlogin} connect
-function.
+You can turn this feature off completely by setting the variable to
+@code{nil}.
-@item nntp-address
-@vindex nntp-address
-The address of the remote system running the @sc{nntp} server.
+If you want all the duplicate mails to be put into a special
+@dfn{duplicates} group, you could do that using the normal mail split
+methods:
-@item nntp-port-number
-@vindex nntp-port-number
-Port number to connect to when using the @code{nntp-open-network-stream}
-connect function.
+@lisp
+(setq nnmail-split-fancy
+ '(| ;; Messages duplicates go to a separate group.
+ ("gnus-warning" "duplication of message" "duplicate")
+ ;; Message from daemons, postmaster, and the like to another.
+ (any mail "mail.misc")
+ ;; Other rules.
+ [ ... ] ))
+@end lisp
-@item nntp-buggy-select
-@vindex nntp-buggy-select
-Set this to non-@code{nil} if your select routine is buggy.
+Or something like:
+@lisp
+(setq nnmail-split-methods
+ '(("duplicates" "^Gnus-Warning:")
+ ;; Other rules.
+ [...]))
+@end lisp
-@item nntp-nov-is-evil
-@vindex nntp-nov-is-evil
-If the @sc{nntp} server does not support @sc{nov}, you could set this
-variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
-can be used automatically.
+Here's a neat feature: If you know that the recipient reads her mail
+with Gnus, and that she has @code{nnmail-treat-duplicates} set to
+@code{delete}, 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!
-@item nntp-xover-commands
-@vindex nntp-xover-commands
-@cindex nov
-@cindex XOVER
-List of strings that are used as commands to fetch @sc{nov} lines from a
-server. The default value of this variable is @code{("XOVER"
-"XOVERVIEW")}.
-@item nntp-nov-gap
-@vindex nntp-nov-gap
-@code{nntp} normally sends just one big request for @sc{nov} lines to
-the server. The server responds with one huge list of lines. However,
-if you have read articles 2-5000 in the group, and only want to read
-article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
-lines that you do not want, and will not use. This variable says how
-big a gap between two consecutive articles is allowed to be before the
-@code{XOVER} request is split into several request. Note that if your
-network is fast, setting this variable to a really small number means
-that fetching will probably be slower. If this variable is @code{nil},
-@code{nntp} will never split requests.
+@node Not Reading Mail
+@subsection Not Reading Mail
-@item nntp-prepare-server-hook
-@vindex nntp-prepare-server-hook
-A hook run before attempting to connect to an @sc{nntp} server.
+If you start using any of the mail backends, they have the annoying
+habit of assuming that you want to read mail with them. This might not
+be unreasonable, but it might not be what you want.
-@item nntp-async-number
-@vindex nntp-async-number
-How many articles should be pre-fetched when in asynchronous mode. If
-this variable is @code{t}, @code{nntp} will pre-fetch all the articles
-that it can without bound. If it is @code{nil}, no pre-fetching will be
-made.
+If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
+will ever attempt to read incoming mail, which should help.
-@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.
+@vindex nnbabyl-get-new-mail
+@vindex nnmbox-get-new-mail
+@vindex nnml-get-new-mail
+@vindex nnmh-get-new-mail
+@vindex nnfolder-get-new-mail
+This might be too much, if, for instance, you are reading mail quite
+happily with @code{nnml} and just want to peek at some old @sc{rmail}
+file you have stashed away with @code{nnbabyl}. All backends have
+variables called backend-@code{get-new-mail}. If you want to disable
+the @code{nnbabyl} mail reading, you edit the virtual server for the
+group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
-@end table
+All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
+narrowed to the article to be saved before saving it when reading
+incoming mail.
-@node News Spool
-@subsection News Spool
-@cindex nnspool
-@cindex news spool
+@node Choosing a Mail Backend
+@subsection Choosing a Mail Backend
-Subscribing to a foreign group from the local spool is extremely easy,
-and might be useful, for instance, to speed up reading groups like
-@samp{alt.binaries.pictures.furniture}.
+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.
-Anyways, you just specify @code{nnspool} as the method and @samp{} (or
-anything else) as the address.
+@menu
+* Unix Mail Box:: Using the (quite) standard Un*x mbox.
+* Rmail Babyl:: Emacs programs use the rmail babyl format.
+* Mail Spool:: Store your mail in a private spool?
+* MH Spool:: An mhspool-like backend.
+* Mail Folders:: Having one file for each group.
+@end menu
-If you have access to a local spool, you should probably use that as the
-native select method (@pxref{Finding the News}). It is normally faster
-than using an @code{nntp} select method, but might not be. It depends.
-You just have to try to find out what's best at your site.
-@table @code
+@node Unix Mail Box
+@subsubsection Unix Mail Box
+@cindex nnmbox
+@cindex unix mail box
-@item nnspool-inews-program
-@vindex nnspool-inews-program
-Program used to post an article.
+@vindex nnmbox-active-file
+@vindex nnmbox-mbox-file
+The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
+mail. @code{nnmbox} will add extra headers to each mail article to say
+which group it belongs in.
-@item nnspool-inews-switches
-@vindex nnspool-inews-switches
-Parameters given to the inews program when posting an article.
+Virtual server settings:
-@item nnspool-spool-directory
-@vindex nnspool-spool-directory
-Where @code{nnspool} looks for the articles. This is normally
-@file{/usr/spool/news/}.
+@table @code
+@item nnmbox-mbox-file
+@vindex nnmbox-mbox-file
+The name of the mail box in the user's home directory.
-@item nnspool-nov-directory
-@vindex nnspool-nov-directory
-Where @code{nnspool} will look for @sc{nov} files. This is normally
-@file{/usr/spool/news/over.view/}.
+@item nnmbox-active-file
+@vindex nnmbox-active-file
+The name of the active file for the mail box.
-@item nnspool-lib-dir
-@vindex nnspool-lib-dir
-Where the news lib dir is (@file{/usr/lib/news/} by default).
+@item nnmbox-get-new-mail
+@vindex nnmbox-get-new-mail
+If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
+into groups.
+@end table
-@item nnspool-active-file
-@vindex nnspool-active-file
-The path of the active file.
-@item nnspool-newsgroups-file
-@vindex nnspool-newsgroups-file
-The path of the group descriptions file.
+@node Rmail Babyl
+@subsubsection Rmail Babyl
+@cindex nnbabyl
+@cindex rmail mbox
-@item nnspool-history-file
-@vindex nnspool-history-file
-The path of the news history file.
+@vindex nnbabyl-active-file
+@vindex nnbabyl-mbox-file
+The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
+mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
+article to say which group it belongs in.
-@item nnspool-active-times-file
-@vindex nnspool-active-times-file
-The path of the active date file.
+Virtual server settings:
-@item nnspool-nov-is-evil
-@vindex nnspool-nov-is-evil
-If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
-that it finds.
+@table @code
+@item nnbabyl-mbox-file
+@vindex nnbabyl-mbox-file
+The name of the rmail mbox file.
-@item nnspool-sift-nov-with-sed
-@vindex nnspool-sift-nov-with-sed
-@cindex sed
-If non-@code{nil}, which is the default, use @code{sed} to get the
-relevant portion from the overview file. If nil, @code{nnspool} will
-load the entire file into a buffer and process it there.
+@item nnbabyl-active-file
+@vindex nnbabyl-active-file
+The name of the active file for the rmail box.
+@item nnbabyl-get-new-mail
+@vindex nnbabyl-get-new-mail
+If non-@code{nil}, @code{nnbabyl} will read incoming mail.
@end table
-@node Getting Mail
-@section Getting Mail
-@cindex reading mail
-@cindex mail
+@node Mail Spool
+@subsubsection Mail Spool
+@cindex nnml
+@cindex mail @sc{nov} spool
-Reading mail with a newsreader---isn't that just plain WeIrD? But of
-course.
+The @dfn{nnml} spool mail format isn't compatible with any other known
+format. It should be used with some caution.
-@menu
-* Getting Started Reading Mail:: A simple cookbook example.
-* Splitting Mail:: How to create mail groups.
-* Mail Backend Variables:: Variables for customizing mail handling.
-* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
-* Mail and Procmail:: Reading mail groups that procmail create.
-* Incorporating Old Mail:: What about the old mail you have?
-* Expiring Mail:: Getting rid of unwanted mail.
-* Duplicates:: Dealing with duplicated mail.
-* Not Reading Mail:: Using mail backends for reading other files.
-* Choosing a Mail Backend:: Gnus can read a variety of mail formats.
-@end menu
+@vindex nnml-directory
+If you use this backend, Gnus will split all incoming mail into files;
+one file for each mail, and put the articles into the correct
+directories under the directory specified by the @code{nnml-directory}
+variable. The default value is @file{~/Mail/}.
+You do not have to create any directories beforehand; Gnus will take
+care of all that.
-@node Getting Started Reading Mail
-@subsection Getting Started Reading Mail
+If you have a strict limit as to how many files you are allowed to store
+in your account, you should not use this backend. As each mail gets its
+own file, you might very well occupy thousands of inodes within a few
+weeks. If this is no problem for you, and it isn't a problem for you
+having your friendly systems administrator walking around, madly,
+shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
+know that this is probably the fastest format to use. You do not have
+to trudge through a big mbox file just to read your new mail.
-It's quite easy to use Gnus to read your new mail. You just plonk the
-mail backend of your choice into @code{gnus-secondary-select-methods},
-and things will happen automatically.
+@code{nnml} is probably the slowest backend when it comes to article
+splitting. It has to create lots of files, and it also generates
+@sc{nov} databases for the incoming mails. This makes is the fastest
+backend when it comes to reading mail.
-For instance, if you want to use @code{nnml} (which is a one file per
-mail backend), you could put the following in your @file{.gnus} file:
+Virtual server settings:
+
+@table @code
+@item nnml-directory
+@vindex nnml-directory
+All @code{nnml} directories will be placed under this directory.
+
+@item nnml-active-file
+@vindex nnml-active-file
+The active file for the @code{nnml} server.
+
+@item nnml-newsgroups-file
+@vindex nnml-newsgroups-file
+The @code{nnml} group descriptions file. @xref{Newsgroups File
+Format}.
+
+@item nnml-get-new-mail
+@vindex nnml-get-new-mail
+If non-@code{nil}, @code{nnml} will read incoming mail.
+
+@item nnml-nov-is-evil
+@vindex nnml-nov-is-evil
+If non-@code{nil}, this backend will ignore any @sc{nov} files.
+
+@item nnml-nov-file-name
+@vindex nnml-nov-file-name
+The name of the @sc{nov} files. The default is @file{.overview}.
+
+@item nnml-prepare-save-mail-hook
+@vindex nnml-prepare-save-mail-hook
+Hook run narrowed to an article before saving.
+
+@end table
+
+@findex nnml-generate-nov-databases
+If your @code{nnml} groups and @sc{nov} files get totally out of whack,
+you can do a complete update by typing @kbd{M-x
+nnml-generate-nov-databases}. This command will trawl through the
+entire @code{nnml} hierarchy, looking at each and every article, so it
+might take a while to complete.
+
+
+@node MH Spool
+@subsubsection MH Spool
+@cindex nnmh
+@cindex mh-e mail spool
+
+@code{nnmh} is just like @code{nnml}, except that is doesn't generate
+@sc{nov} databases and it doesn't keep an active file. This makes
+@code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
+makes it easier to write procmail scripts for.
+
+Virtual server settings:
+
+@table @code
+@item nnmh-directory
+@vindex nnmh-directory
+All @code{nnmh} directories will be located under this directory.
+
+@item nnmh-get-new-mail
+@vindex nnmh-get-new-mail
+If non-@code{nil}, @code{nnmh} will read incoming mail.
+
+@item nnmh-be-safe
+@vindex nnmh-be-safe
+If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
+sure that the articles in the folder are actually what Gnus thinks they
+are. It will check date stamps and stat everything in sight, so
+setting this to @code{t} will mean a serious slow-down. If you never
+use anything but Gnus to read the @code{nnmh} articles, you do not have
+to set this variable to @code{t}.
+@end table
+
+
+@node Mail Folders
+@subsubsection Mail Folders
+@cindex nnfolder
+@cindex mbox folders
+@cindex mail folders
+
+@code{nnfolder} is a backend for storing each mail group in a separate
+file. Each file is in the standard Un*x mbox format. @code{nnfolder}
+will add extra headers to keep track of article numbers and arrival
+dates.
+
+Virtual server settings:
+
+@table @code
+@item nnfolder-directory
+@vindex nnfolder-directory
+All the @code{nnfolder} mail boxes will be stored under this directory.
+
+@item nnfolder-active-file
+@vindex nnfolder-active-file
+The name of the active file.
+
+@item nnfolder-newsgroups-file
+@vindex nnfolder-newsgroups-file
+The name of the group descriptions file. @xref{Newsgroups File Format}.
+
+@item nnfolder-get-new-mail
+@vindex nnfolder-get-new-mail
+If non-@code{nil}, @code{nnfolder} will read incoming mail.
+@end table
+
+@findex nnfolder-generate-active-file
+@kindex M-x nnfolder-generate-active-file
+If you have lots of @code{nnfolder}-like files you'd like to read with
+@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
+command to make @code{nnfolder} aware of all likely files in
+@code{nnfolder-directory}.
+
+
+@node Other Sources
+@section Other Sources
+
+Gnus can do more than just read news or mail. The methods described
+below allow Gnus to view directories and files as if they were
+newsgroups.
+
+@menu
+* Directory Groups:: You can read a directory as if it was a newsgroup.
+* Anything Groups:: Dired? Who needs dired?
+* Document Groups:: Single files can be the basis of a group.
+* SOUP:: Reading @sc{SOUP} packets ``offline''.
+* Web Searches:: Creating groups from articles that match a string.
+* Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
+@end menu
+
+
+@node Directory Groups
+@subsection Directory Groups
+@cindex nndir
+@cindex directory groups
+
+If you have a directory that has lots of articles in separate files in
+it, you might treat it as a newsgroup. The files have to have numerical
+names, of course.
+
+This might be an opportune moment to mention @code{ange-ftp}, that most
+wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
+didn't think much about it---a backend to read directories. Big deal.
+
+@code{ange-ftp} changes that picture dramatically. For instance, if you
+enter the @code{ange-ftp} file name
+@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the the directory name,
+@code{ange-ftp} will actually allow you to read this directory over at
+@samp{sina} as a newsgroup. Distributed news ahoy!
+
+@code{nndir} will use @sc{nov} files if they are present.
+
+@code{nndir} is a ``read-only'' backend---you can't delete or expire
+articles with this method. You can use @code{nnmh} or @code{nnml} for
+whatever you use @code{nndir} for, so you could switch to any of those
+methods if you feel the need to have a non-read-only @code{nndir}.
+
+
+@node Anything Groups
+@subsection Anything Groups
+@cindex nneething
+
+From the @code{nndir} backend (which reads a single spool-like
+directory), it's just a hop and a skip to @code{nneething}, which
+pretends that any arbitrary directory is a newsgroup. Strange, but
+true.
+
+When @code{nneething} is presented with a directory, it will scan this
+directory and assign article numbers to each file. When you enter such
+a group, @code{nneething} must create ``headers'' that Gnus can use.
+After all, Gnus is a newsreader, in case you're
+forgetting. @code{nneething} does this in a two-step process. First, it
+snoops each file in question. If the file looks like an article (i.e.,
+the first few lines look like headers), it will use this as the head.
+If this is just some arbitrary file without a head (e.g. a C source
+file), @code{nneething} will cobble up a header out of thin air. It
+will use file ownership, name and date and do whatever it can with these
+elements.
+
+All this should happen automatically for you, and you will be presented
+with something that looks very much like a newsgroup. Totally like a
+newsgroup, to be precise. If you select an article, it will be displayed
+in the article buffer, just as usual.
+
+If you select a line that represents a directory, Gnus will pop you into
+a new summary buffer for this @code{nneething} group. And so on. You can
+traverse the entire disk this way, if you feel like, but remember that
+Gnus is not dired, really, and does not intend to be, either.
+
+There are two overall modes to this action---ephemeral or solid. When
+doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
+will not store information on what files you have read, and what files
+are new, and so on. If you create a solid @code{nneething} group the
+normal way with @kbd{G m}, Gnus will store a mapping table between
+article numbers and file names, and you can treat this group like any
+other groups. When you activate a solid @code{nneething} group, you will
+be told how many unread articles it contains, etc., etc.
+
+Some variables:
+
+@table @code
+@item nneething-map-file-directory
+@vindex nneething-map-file-directory
+All the mapping files for solid @code{nneething} groups will be stored
+in this directory, which defaults to @file{~/.nneething/}.
+
+@item nneething-exclude-files
+@vindex nneething-exclude-files
+All files that match this regexp will be ignored. Nice to use to exclude
+auto-save files and the like, which is what it does by default.
+
+@item nneething-map-file
+@vindex nneething-map-file
+Name of the map files.
+@end table
+
+
+@node Document Groups
+@subsection Document Groups
+@cindex nndoc
+@cindex documentation group
+@cindex help group
+
+@code{nndoc} is a cute little thing that will let you read a single file
+as a newsgroup. Several files types are supported:
+
+@table @code
+@cindex babyl
+@cindex rmail mbox
+
+@item babyl
+The babyl (rmail) mail box.
+@cindex mbox
+@cindex Unix mbox
+
+@item mbox
+The standard Unix mbox file.
+
+@cindex MMDF mail box
+@item mmdf
+The MMDF mail box format.
+
+@item news
+Several news articles appended into a file.
+
+@item rnews
+@cindex rnews batch files
+The rnews batch transport format.
+@cindex forwarded messages
+
+@item forward
+Forwarded articles.
+
+@item mime-digest
+@cindex digest
+@cindex MIME digest
+@cindex 1153 digest
+@cindex RFC 1153 digest
+@cindex RFC 341 digest
+MIME (RFC 1341) digest format.
+
+@item standard-digest
+The standard (RFC 1153) digest format.
+
+@item slack-digest
+Non-standard digest format---matches most things, but does it badly.
+@end table
+
+You can also use the special ``file type'' @code{guess}, which means
+that @code{nndoc} will try to guess what file type it is looking at.
+@code{digest} means that @code{nndoc} should guess what digest type the
+file is.
+
+@code{nndoc} will not try to change the file or insert any extra headers into
+it---it will simply, like, let you use the file as the basis for a
+group. And that's it.
+
+If you have some old archived articles that you want to insert into your
+new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
+that. Say you have an old @file{RMAIL} file with mail that you now want
+to split into your new @code{nnml} groups. You look at that file using
+@code{nndoc} (using the @kbd{G f} command in the group buffer
+(@pxref{Foreign Groups})), set the process mark on all the articles in
+the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r})
+using @code{nnml}. If all goes well, all the mail in the @file{RMAIL}
+file is now also stored in lots of @code{nnml} directories, and you can
+delete that pesky @file{RMAIL} file. If you have the guts!
+
+Virtual server variables:
+
+@table @code
+@item nndoc-article-type
+@vindex nndoc-article-type
+This should be one of @code{mbox}, @code{babyl}, @code{digest},
+@code{mmdf}, @code{forward}, @code{news}, @code{rnews},
+@code{mime-digest}, @code{clari-briefs}, or @code{guess}.
+
+@item nndoc-post-type
+@vindex nndoc-post-type
+This variable says whether Gnus is to consider the group a news group or
+a mail group. There are two legal values: @code{mail} (the default)
+and @code{news}.
+@end table
+
+@menu
+* Document Server Internals:: How to add your own document types.
+@end menu
-@lisp
-(setq gnus-secondary-select-methods
- '((nnml "private")))
-@end lisp
-Now, the next time you start Gnus, this backend will be queried for new
-articles, and it will move all the messages in your spool file to its
-directory, which is @code{~/Mail/} by default. The new group that will
-be created (@samp{mail.misc}) will be subscribed, and you can read it
-like any other group.
+@node Document Server Internals
+@subsubsection Document Server Internals
-You will probably want to split the mail into several groups, though:
+Adding new document types to be recognized by @code{nndoc} isn't
+difficult. You just have to whip up a definition of what the document
+looks like, write a predicate function to recognize that document type,
+and then hook into @code{nndoc}.
-@lisp
-(setq nnmail-split-methods
- '(("junk" "^From:.*Lars Ingebrigtsen")
- ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
- ("other" "")))
-@end lisp
+First, here's an example document type definition:
-This will result in three new mail groups being created:
-@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the
-mail that doesn't fit into the first two groups will be placed in the
-latter group.
+@example
+(mmdf
+ (article-begin . "^\^A\^A\^A\^A\n")
+ (body-end . "^\^A\^A\^A\^A\n"))
+@end example
-This should be sufficient for reading mail with Gnus. You might want to
-give the other sections in this part of the manual a perusal, though,
-especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}.
+The definition is simply a unique @dfn{name} followed by a series of
+regexp pseudo-variable settings. Below are the possible
+variables---don't be daunted by the number of variables; most document
+types can be defined with very few settings:
+@table @code
+@item first-article
+If present, @code{nndoc} will skip past all text until it finds
+something that match this regexp. All text before this will be
+totally ignored.
-@node Splitting Mail
-@subsection Splitting Mail
-@cindex splitting mail
-@cindex mail splitting
+@item article-begin
+This setting has to be present in all document type definitions. It
+says what the beginning of each article looks like.
-@vindex nnmail-split-methods
-The @code{nnmail-split-methods} variable says how the incoming mail is
-to be split into groups.
+@item head-begin-function
+If present, this should be a function that moves point to the head of
+the article.
-@lisp
-(setq nnmail-split-methods
- '(("mail.junk" "^From:.*Lars Ingebrigtsen")
- ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
- ("mail.other" "")))
-@end lisp
+@item nndoc-head-begin
+If present, this should be a regexp that matches the head of the
+article.
-This variable is a list of lists, where the first element of each of
-these lists is the name of the mail group (they do not have to be called
-something beginning with @samp{mail}, by the way), and the second
-element is a regular expression used on the header of each mail to
-determine if it belongs in this mail group.
+@item nndoc-head-end
+This should match the end of the head of the article. It defaults to
+@samp{^$}---the empty line.
-The second element can also be a function. In that case, it will be
-called narrowed to the headers with the first element of the rule as the
-argument. It should return a non-@code{nil} value if it thinks that the
-mail belongs in that group.
+@item body-begin-function
+If present, this function should move point to the beginning of the body
+of the article.
-The last of these groups should always be a general one, and the regular
-expression should @emph{always} be @samp{} so that it matches any
-mails that haven't been matched by any of the other regexps.
+@item body-begin
+This should match the beginning of the body of the article. It defaults
+to @samp{^\n}.
+
+@item body-end-function
+If present, this function should move point to the end of the body of
+the article.
+
+@item body-end
+If present, this should match the end of the body of the article.
+
+@item nndoc-file-end
+If present, this should match the end of the file. All text after this
+regexp will be totally ignored.
+
+@end table
+
+So, using these variables @code{nndoc} is able to dissect a document
+file into a series of articles, each with a head and a body. However, a
+few more variables are needed since not all document types are all that
+news-like---variables needed to transform the head or the body into
+something that's palatable for Gnus:
+
+@table @code
+@item prepare-body-function
+If present, this function will be called when requesting an article. It
+will be called with point at the start of the body, and is useful if the
+document has encoded some parts of its contents.
+
+@item article-transform-function
+If present, this function is called when requesting an article. It's
+meant to be used how more wide-ranging transformation of both head and
+body of the article.
+
+@item generate-head-function
+If present, this function is called to generate a head that Gnus can
+understand. It is called with the article number as a parameter, and is
+expected to generate a nice head for the article in question. It is
+called when requesting the headers of all articles.
+
+@end table
+
+Let's look at the most complicated example I can come up with---standard
+digests:
+
+@example
+(standard-digest
+ (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+"))
+ (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+"))
+ (prepare-body-function . nndoc-unquote-dashes)
+ (body-end-function . nndoc-digest-body-end)
+ (head-end . "^ ?$")
+ (body-begin . "^ ?\n")
+ (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$")
+ (subtype digest guess))
+@end example
+
+We see that all text before a 70-width line of dashes is ignored; all
+text after a line that starts with that @samp{^End of} is also ignored;
+each article begins with a 30-width line of dashes; the line separating
+the head from the body may contain a single space; and that the body is
+run through @code{nndoc-unquote-dashes} before being delivered.
+
+To hook your own document definition into @code{nndoc}, use the
+@code{nndoc-add-type} function. It takes two parameters---the first is
+the definition itself and the second (optional) parameter says where in
+the document type definition alist to put this definition. The alist is
+traversed sequentially, and @code{nndoc-TYPE-type-p} is called for each
+type. So @code{nndoc-mmdf-type-p} is called to see whether a document
+is of @code{mmdf} type, and so on. These type predicates should return
+@code{nil} if the document is not of the correct type; @code{t} if it is
+of the correct type; and a number if the document might be of the
+correct type. A high number means high probability; a low number means
+low probability with @samp{0} being the lowest legal number.
+
+
+@node SOUP
+@subsection SOUP
+@cindex SOUP
+@cindex offline
+
+In the PC world people often talk about ``offline'' newsreaders. These
+are thingies that are combined reader/news transport monstrosities.
+With built-in modem programs. Yecchh!
+
+Of course, us Unix Weenie types of human beans use things like
+@code{uucp} and, like, @code{nntpd} and set up proper news and mail
+transport things like Ghod intended. And then we just use normal
+newsreaders.
+
+However, it can sometimes be convenient to do something a that's a bit
+easier on the brain if you have a very slow modem, and you're not really
+that interested in doing things properly.
+
+A file format called @sc{soup} has been developed for transporting news
+and mail from servers to home machines and back again. It can be a bit
+fiddly.
+
+First some terminology:
+
+@table @dfn
+
+@item server
+This is the machine that is connected to the outside world and where you
+get news and/or mail from.
+
+@item home machine
+This is the machine that you want to do the actual reading and responding
+on. It is typically not connected to the rest of the world in any way.
+
+@item packet
+Something that contains messages and/or commands. There are two kinds
+of packets:
+
+@table @dfn
+@item message packets
+These are packets made at the server, and typically contains lots of
+messages for you to read. These are called @file{SoupoutX.tgz} by
+default, where @var{X} is a number.
+
+@item response packets
+These are packets made at the home machine, and typically contains
+replies that you've written. These are called @file{SoupinX.tgz} by
+default, where @var{X} is a number.
+
+@end table
+
+@end table
+
+
+@enumerate
+
+@item
+You log in on the server and create a @sc{soup} packet. You can either
+use a dedicated @sc{soup} thingie (like the @code{awk} program), or you
+can use Gnus to create the packet with its @sc{soup} commands (@kbd{O
+s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}).
+
+@item
+You transfer the packet home. Rail, boat, car or modem will do fine.
+
+@item
+You put the packet in your home directory.
+
+@item
+You fire up Gnus on your home machine using the @code{nnsoup} backend as
+the native or secondary server.
+
+@item
+You read articles and mail and answer and followup to the things you
+want (@pxref{SOUP Replies}).
+
+@item
+You do the @kbd{G s r} command to pack these replies into a @sc{soup}
+packet.
+
+@item
+You transfer this packet to the server.
+
+@item
+You use Gnus to mail this packet out with the @kbd{G s s} command.
+
+@item
+You then repeat until you die.
+
+@end enumerate
+
+So you basically have a bipartite system---you use @code{nnsoup} for
+reading and Gnus for packing/sending these @sc{soup} packets.
+
+@menu
+* SOUP Commands:: Commands for creating and sending @sc{soup} packets
+* SOUP Groups:: A backend for reading @sc{soup} packets.
+* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
+@end menu
+
+
+@node SOUP Commands
+@subsubsection SOUP Commands
+
+These are commands for creating and manipulating @sc{soup} packets.
+
+@table @kbd
+@item G s b
+@kindex G s b (Group)
+@findex gnus-group-brew-soup
+Pack all unread articles in the current group
+(@code{gnus-group-brew-soup}). This command understands the
+process/prefix convention.
+
+@item G s w
+@kindex G s w (Group)
+@findex gnus-soup-save-areas
+Save all @sc{soup} data files (@code{gnus-soup-save-areas}).
+
+@item G s s
+@kindex G s s (Group)
+@findex gnus-soup-send-replies
+Send all replies from the replies packet
+(@code{gnus-soup-send-replies}).
+
+@item G s p
+@kindex G s p (Group)
+@findex gnus-soup-pack-packet
+Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
+
+@item G s r
+@kindex G s r (Group)
+@findex nnsoup-pack-replies
+Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
+
+@item O s
+@kindex O s (Summary)
+@findex gnus-soup-add-article
+This summary-mode command adds the current article to a @sc{soup} packet
+(@code{gnus-soup-add-article}). It understands the process/prefix
+convention (@pxref{Process/Prefix}).
+
+@end table
+
+
+There are a few variables to customize where Gnus will put all these
+thingies:
+
+@table @code
+
+@item gnus-soup-directory
+@vindex gnus-soup-directory
+Directory where Gnus will save intermediate files while composing
+@sc{soup} packets. The default is @file{~/SoupBrew/}.
+
+@item gnus-soup-replies-directory
+@vindex gnus-soup-replies-directory
+This is what Gnus will use as a temporary directory while sending our
+reply packets. @file{~/SoupBrew/SoupReplies/} is the default.
+
+@item gnus-soup-prefix-file
+@vindex gnus-soup-prefix-file
+Name of the file where Gnus stores the last used prefix. The default is
+@samp{gnus-prefix}.
+
+@item gnus-soup-packer
+@vindex gnus-soup-packer
+A format string command for packing a @sc{soup} packet. The default is
+@samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
+
+@item gnus-soup-unpacker
+@vindex gnus-soup-unpacker
+Format string command for unpacking a @sc{soup} packet. The default is
+@samp{gunzip -c %s | tar xvf -}.
+
+@item gnus-soup-packet-directory
+@vindex gnus-soup-packet-directory
+Where Gnus will look for reply packets. The default is @file{~/}.
+
+@item gnus-soup-packet-regexp
+@vindex gnus-soup-packet-regexp
+Regular expression matching @sc{soup} reply packets in
+@code{gnus-soup-packet-directory}.
+
+@end table
+
+
+@node SOUP Groups
+@subsubsection @sc{soup} Groups
+@cindex nnsoup
+
+@code{nnsoup} is the backend for reading @sc{soup} packets. It will
+read incoming packets, unpack them, and put them in a directory where
+you can read them at leisure.
+
+These are the variables you can use to customize its behavior:
+
+@table @code
+
+@item nnsoup-tmp-directory
+@vindex nnsoup-tmp-directory
+When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
+directory. (@file{/tmp/} by default.)
+
+@item nnsoup-directory
+@vindex nnsoup-directory
+@code{nnsoup} then moves each message and index file to this directory.
+The default is @file{~/SOUP/}.
+
+@item nnsoup-replies-directory
+@vindex nnsoup-replies-directory
+All replies will stored in this directory before being packed into a
+reply packet. The default is @file{~/SOUP/replies/"}.
+
+@item nnsoup-replies-format-type
+@vindex nnsoup-replies-format-type
+The @sc{soup} format of the replies packets. The default is @samp{?n}
+(rnews), and I don't think you should touch that variable. I probably
+shouldn't even have documented it. Drats! Too late!
+
+@item nnsoup-replies-index-type
+@vindex nnsoup-replies-index-type
+The index type of the replies packet. The is @samp{?n}, which means
+``none''. Don't fiddle with this one either!
-If you like to tinker with this yourself, you can set this variable to a
-function of your choice. This function will be called without any
-arguments in a buffer narrowed to the headers of an incoming mail
-message. The function should return a list of groups names that it
-thinks should carry this mail message.
+@item nnsoup-active-file
+@vindex nnsoup-active-file
+Where @code{nnsoup} stores lots of information. This is not an ``active
+file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
+this file or mess it up in any way, you're dead. The default is
+@file{~/SOUP/active}.
-Note that the mail backends are free to maul the poor, innocent
-incoming headers all they want to. They all add @code{Lines} headers;
-some add @code{X-Gnus-Group} headers; most rename the Unix mbox
-@code{From<SPACE>} line to something else.
+@item nnsoup-packer
+@vindex nnsoup-packer
+Format string command for packing a reply @sc{soup} packet. The default
+is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
-@vindex nnmail-crosspost
-The mail backends all support cross-posting. If several regexps match,
-the mail will be ``cross-posted'' to all those groups.
-@code{nnmail-crosspost} says whether to use this mechanism or not. Note
-that no articles are crossposted to the general (@samp{}) group.
+@item nnsoup-unpacker
+@vindex nnsoup-unpacker
+Format string command for unpacking incoming @sc{soup} packets. The
+default is @samp{gunzip -c %s | tar xvf -}.
-@vindex nnmail-crosspost-link-function
-@cindex crosspost
-@cindex links
-@code{nnmh} and @code{nnml} makes crossposts by creating hard links to
-the crossposted articles. However, not all files systems support hard
-links. If that's the case for you, set
-@code{nnmail-crosspost-link-function} to @code{copy-file}. (This
-variable is @code{add-name-to-file} by default.)
+@item nnsoup-packet-directory
+@vindex nnsoup-packet-directory
+Where @code{nnsoup} will look for incoming packets. The default is
+@file{~/}.
-Gnus gives you all the opportunity you could possibly want for shooting
-yourself in the foot. Let's say you create a group that will contain
-all the mail you get from your boss. And then you accidentally
-unsubscribe from the group. Gnus will still put all the mail from your
-boss in the unsubscribed group, and so, when your boss mails you ``Have
-that report ready by Monday or you're fired!'', you'll never see it and,
-come Tuesday, you'll still believe that you're gainfully employed while
-you really should be out collecting empty bottles to save up for next
-month's rent money.
+@item nnsoup-packet-regexp
+@vindex nnsoup-packet-regexp
+Regular expression matching incoming @sc{soup} packets. The default is
+@samp{Soupout}.
+@end table
-@node Mail Backend Variables
-@subsection Mail Backend Variables
-These variables are (for the most part) pertinent to all the various
-mail backends.
+@node SOUP Replies
+@subsubsection SOUP Replies
-@table @code
-@vindex nnmail-read-incoming-hook
-@item nnmail-read-incoming-hook
-The mail backends all call this hook after reading new mail. You can
-use this hook to notify any mail watch programs, if you want to.
+Just using @code{nnsoup} won't mean that your postings and mailings end
+up in @sc{soup} reply packets automagically. You have to work a bit
+more for that to happen.
-@vindex nnmail-spool-file
-@item nnmail-spool-file
-@cindex POP mail
-@cindex MAILHOST
-@cindex movemail
-The backends will look for new mail in this file. If this variable is
-@code{nil}, the mail backends will never attempt to fetch mail by
-themselves. If you are using a POP mail server and your name is
-@samp{larsi}, you should set this variable to @samp{po:larsi}. If
-your name is not @samp{larsi}, you should probably modify that
-slightly, but you may have guessed that already, you smart & handsome
-devil! You can also set this variable to @code{pop}, and Gnus will try
-to figure out the POP mail string by itself. In any case, Gnus will
-call @code{movemail} which will contact the POP server named in the
-@code{MAILHOST} environment variable.
+@findex nnsoup-set-variables
+The @code{nnsoup-set-variables} command will set the appropriate
+variables to ensure that all your followups and replies end up in the
+@sc{soup} system.
-When you use a mail backend, Gnus will slurp all your mail from your
-inbox and plonk it down in your home directory. Gnus doesn't move any
-mail if you're not using a mail backend---you have to do a lot of magic
-invocations first. At the time when you have finished drawing the
-pentagram, lightened the candles, and sacrificed the goat, you really
-shouldn't be too surprised when Gnus moves your mail.
+In specific, this is what it does:
-@vindex nnmail-use-procmail
-@vindex nnmail-procmail-suffix
-@item nnmail-use-procmail
-If 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{nnmail-procmail-suffix}
-will be considered incoming mailboxes, and will be searched for new
-mail.
+@lisp
+(setq message-send-news-function 'nnsoup-request-post)
+(setq message-send-mail-function 'nnsoup-request-mail)
+@end lisp
-@vindex nnmail-crash-box
-@item nnmail-crash-box
-When the mail backends read a spool file, it is first moved to this
-file, which is @file{~/.gnus-crash-box} by default. If this file
-already exists, it will always be read (and incorporated) before any
-other spool files.
+And that's it, really. If you only want news to go into the @sc{soup}
+system you just use the first line. If you only want mail to be
+@sc{soup}ed you use the second.
-@vindex nnmail-prepare-incoming-hook
-@item nnmail-prepare-incoming-hook
-This is run in a buffer that holds all the new incoming mail, and can be
-used for, well, anything, really.
-@vindex nnmail-pre-get-new-mail-hook
-@vindex nnmail-post-get-new-mail-hook
-@item nnmail-pre-get-new-mail-hook
-@itemx nnmail-post-get-new-mail-hook
-These are two useful hooks executed when treating new incoming
-mail---@code{nnmail-pre-get-new-mail-hook} (is called just before
-starting to handle the new mail) and
-@code{nnmail-post-get-new-mail-hook} (is called when the mail handling
-is done). Here's and example of using these two hooks to change the
-default file modes the new mail files get:
+@node Web Searches
+@subsection Web Searches
+@cindex nnweb
+@cindex DejaNews
+@cindex Alta Vista
+@cindex InReference
+@cindex Usenet searches
+@cindex searching the Usenet
+
+It's, like, too neat to search the Usenet for articles that match a
+string, but it, like, totally @emph{sucks}, like, totally, to use one of
+those, like, Web browsers, and you, like, have to, rilly, like, look at
+the commercials, so, like, with Gnus you can do @emph{rad}, rilly,
+searches without having to use a browser.
+
+The @code{nnweb} backend allows an easy interface to the mighty search
+engine. You create an @code{nnweb} group, enter a search pattern, and
+then enter the group and read the articles like you would any normal
+group. The @kbd{G w} command in the group buffer (@pxref{Foreign
+Groups}) will do this in an easy-to-use fashion.
+
+@code{nnweb} groups don't really lend themselves to being solid
+groups---they have a very fleeting idea of article numbers. In fact,
+each time you enter an @code{nnweb} group (not even changing the search
+pattern), you are likely to get the articles ordered in a different
+manner. Not even using duplicate suppression (@code{Duplicate
+Suppression}) will help, since @code{nnweb} doesn't even know the
+@code{Message-ID} of the articles before reading them using some search
+engines (DejaNews, for instance). The only possible way to keep track
+of which articles you've read is by scoring on the @code{Date}
+header---mark all articles that were posted before the last date you
+read the group as read.
+
+If the search engine changes its output substantially, @code{nnweb}
+won't be able to parse it and will fail. One could hardly fault the Web
+providers if they were to do this---their @emph{raison d'être} is to
+make money off of advertisements, not to provide services to the
+community. Since @code{nnweb} washes the ads off all the articles, one
+might think that the providers might be somewhat miffed. We'll see.
+
+You must have the @code{url} and @code{w3} package installed to be able
+to use @code{nnweb}.
-@lisp
-(add-hook 'gnus-pre-get-new-mail-hook
- (lambda () (set-default-file-modes 511)))
+Virtual server variables:
-(add-hook 'gnus-post-get-new-mail-hook
- (lambda () (set-default-file-modes 551)))
-@end lisp
+@table @code
+@item nnweb-type
+@vindex nnweb-type
+What search engine type is being used. The currently supported types
+are @code{dejanews}, @code{altavista} and @code{reference}.
+
+@item nnweb-search
+@vindex nnweb-search
+The search string to feed to the search engine.
+
+@item nnweb-max-hits
+@vindex nnweb-max-hits
+Advisory maximum number of hits per search to display. The default is
+100.
+
+@item nnweb-type-definition
+@vindex nnweb-type-definition
+Type-to-definition alist. This alist says what @code{nnweb} should do
+with the various search engine types. The following elements must be
+present:
-@item nnmail-tmp-directory
-@vindex nnmail-tmp-directory
-This variable says where to move the incoming mail to while processing
-it. This is usually done in the same directory that the mail backend
-inhabits (i.e., @file{~/Mail/}), but if this variable is non-@code{nil},
-it will be used instead.
+@table @code
+@item article
+Function to decode the article and provide something that Gnus
+understands.
-@item nnmail-movemail-program
-@vindex nnmail-movemail-program
-This program is executed to move mail from the user's inbox to her home
-directory. The default is @samp{movemail}.
+@item map
+Function to create an article number to message header and URL alist.
-@item nnmail-delete-incoming
-@vindex nnmail-delete-incoming
-@cindex incoming mail files
-@cindex deleting incoming files
-If 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.
+@item search
+Function to send the search string to the search engine.
-@item nnmail-use-long-file-names
-@vindex nnmail-use-long-file-names
-If non-@code{nil}, the mail backends will use long file and directory
-names. Groups like @samp{mail.misc} will end up in directories like
-@file{mail.misc/}. If it is @code{nil}, the same group will end up in
-@file{mail/misc/}.
+@item address
+The address the aforementioned function should send the search string
+to.
-@item nnmail-delete-file-function
-@vindex nnmail-delete-file-function
-@findex delete-file
-Function called to delete files. It is @code{delete-file} by default.
+@item id
+Format string URL to fetch an article by @code{Message-ID}.
+@end table
@end table
-@node Fancy Mail Splitting
-@subsection Fancy Mail Splitting
-@cindex mail splitting
-@cindex fancy mail splitting
-@vindex nnmail-split-fancy
-@findex nnmail-split-fancy
-If the rather simple, standard method for specifying how to split mail
-doesn't allow you to do what you want, you can set
-@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
-play with the @code{nnmail-split-fancy} variable.
+@node Mail-To-News Gateways
+@subsection Mail-To-News Gateways
+@cindex mail-to-news gateways
+@cindex gateways
-Let's look at an example value of this variable first:
+If your local @code{nntp} server doesn't allow posting, for some reason
+or other, you can post using one of the numerous mail-to-news gateways.
+The @code{nngateway} backend provides the interface.
-@lisp
-;; Messages from the mailer daemon are not crossposted to any of
-;; the ordinary groups. Warnings are put in a separate group
-;; from real errors.
-(| ("from" mail (| ("subject" "warn.*" "mail.warning")
- "mail.misc"))
- ;; Non-error messages are crossposted to all relevant
- ;; groups, but we don't crosspost between the group for the
- ;; (ding) list and the group for other (ding) related mail.
- (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
- ("subject" "ding" "ding.misc"))
- ;; Other mailing lists...
- (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
- (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
- ;; People...
- (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
- ;; Unmatched mail goes to the catch all group.
- "misc.misc"))")
-@end lisp
+Note that you can't read anything from this backend---it can only be
+used to post with.
-This variable has the format of a @dfn{split}. A split is a (possibly)
-recursive structure where each split may contain other splits. Here are
-the four possible split syntaxes:
+Server variables:
-@table @dfn
+@table @code
+@item nngateway-address
+@vindex nngateway-address
+This is the address of the mail-to-news gateway.
+
+@item nngateway-header-transformation
+@vindex nngateway-header-transformation
+News headers have often have to be transformed in some odd way or other
+for the mail-to-news gateway to accept it. This variable says what
+transformation should be called, and defaults to
+@code{nngateway-simple-header-transformation}. The function is called
+narrowed to the headers to be transformed and with one parameter---the
+gateway address.
+
+This default function just inserts a new @code{To} header based on the
+@code{Newsgroups} header and the gateway address---an article with this
+@code{Newsgroups} header:
-@item GROUP
-If the split is a string, that will be taken as a group name.
+@example
+Newsgroups: alt.religion.emacs
+@end example
-@item (FIELD VALUE SPLIT)
-If the split is a list, and the first element is a string, then that
-means that if header FIELD (a regexp) contains VALUE (also a regexp),
-then store the message as specified by SPLIT.
+will get this @code{From} header inserted:
-@item (| SPLIT...)
-If the split is a list, and the first element is @code{|} (vertical
-bar), then process each SPLIT until one of them matches. A SPLIT is
-said to match if it will cause the mail message to be stored in one or
-more groups.
+@example
+To: alt-religion-emacs@@GATEWAY
+@end example
-@item (& SPLIT...)
-If the split is a list, and the first element is @code{&}, then process
-all SPLITs in the list.
@end table
-In these splits, FIELD must match a complete field name. VALUE must
-match a complete word according to the fundamental mode syntax table.
-You can use @code{.*} in the regexps to match partial field names or
-words.
-
-@vindex nnmail-split-abbrev-alist
-FIELD and VALUE can also be lisp symbols, in that case they are expanded
-as specified by the variable @code{nnmail-split-abbrev-alist}. This is
-an alist of cons cells, where the car of the cells contains the key, and
-the cdr contains a string.
-
-@vindex nnmail-split-fancy-syntax-table
-@code{nnmail-split-fancy-syntax-table} is the syntax table in effect
-when all this splitting is performed.
+So, to use this, simply say something like:
+@lisp
+(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
+@end lisp
-@node Mail and Procmail
-@subsection Mail and Procmail
-@cindex procmail
-@cindex slocal
-@cindex elm
-Many people use @code{procmail} (or some other mail filter program or
-external delivery agent---@code{slocal}, @code{elm}, etc) to split
-incoming mail into groups. If you do that, you should set
-@code{nnmail-spool-file} to @code{procmail} to ensure that the mail
-backends never ever try to fetch mail by themselves.
+@node Combined Groups
+@section Combined Groups
-This also means that you probably don't want to set
-@code{nnmail-split-methods} either, which has some, perhaps, unexpected
-side effects.
+Gnus allows combining a mixture of all the other group types into bigger
+groups.
-When a mail backend is queried for what groups it carries, it replies
-with the contents of that variable, along with any groups it has figured
-out that it carries by other means. None of the backends (except
-@code{nnmh}) actually go out to the disk and check what groups actually
-exist. (It's not trivial to distinguish between what the user thinks is
-a basis for a newsgroup and what is just a plain old file or directory.)
+@menu
+* Virtual Groups:: Combining articles from many groups.
+* Kibozed Groups:: Looking through parts of the newsfeed for articles.
+@end menu
-This means that you have to tell Gnus (and the backends) what groups
-exist by hand.
-Let's take the @code{nnmh} backend as an example.
+@node Virtual Groups
+@subsection Virtual Groups
+@cindex nnvirtual
+@cindex virtual groups
-The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
-There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
+An @dfn{nnvirtual group} is really nothing more than a collection of
+other groups.
-Go to the group buffer and type @kbd{G m}. When prompted, answer
-@samp{foo} for the name and @samp{nnmh} for the method. Repeat
-twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
-to include all your mail groups.
+For instance, if you are tired of reading many small group, you can
+put them all in one big group, and then grow tired of reading one
+big, unwieldy group. The joys of computing!
-That's it. You are now set to read your mail. An active file for this
-method will be created automatically.
+You specify @code{nnvirtual} as the method. The address should be a
+regexp to match component groups.
-@vindex nnmail-procmail-suffix
-@vindex nnmail-procmail-directory
-If you use @code{nnfolder} or any other backend that store more than a
-single article in each file, you should never have procmail add mails to
-the file that Gnus sees. Instead, procmail should put all incoming mail
-in @code{nnmail-procmail-directory}. To arrive at the file name to put
-the incoming mail in, append @code{nnmail-procmail-suffix} to the group
-name. The mail backends will read the mail from these files.
+All marks in the virtual group will stick to the articles in the
+component groups. So if you tick an article in a virtual group, the
+article will also be ticked in the component group from whence it came.
+(And vice versa---marks from the component groups will also be shown in
+the virtual group.)
-@vindex nnmail-resplit-incoming
-When Gnus reads a file called @file{mail.misc.spool}, this mail will be
-put in the @code{mail.misc}, as one would expect. However, if you want
-Gnus to split the mail the normal way, you could set
-@code{nnmail-resplit-incoming} to @code{t}.
+Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
+newsgroups into one, big, happy newsgroup:
-@vindex nnmail-keep-last-article
-If you use @code{procmail} to split things directory into an @code{nnmh}
-directory (which you shouldn't do), you should set
-@code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
-ever expiring the final article in a mail newsgroup. This is quite,
-quite important.
+@lisp
+(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
+@end lisp
+The component groups can be native or foreign; everything should work
+smoothly, but if your computer explodes, it was probably my fault.
-@node Incorporating Old Mail
-@subsection Incorporating Old Mail
+Collecting the same group from several servers might actually be a good
+idea if users have set the Distribution header to limit distribution.
+If you would like to read @samp{soc.motss} both from a server in Japan
+and a server in Norway, you could use the following as the group regexp:
-Most people have lots of old mail stored in various file formats. If
-you have set up Gnus to read mail using one of the spiffy Gnus mail
-backends, you'll probably wish to have that old mail incorporated into
-your mail groups.
+@example
+"^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
+@end example
-Doing so can be quite easy.
+This should work kinda smoothly---all articles from both groups should
+end up in this one, and there should be no duplicates. Threading (and
+the rest) will still work as usual, but there might be problems with the
+sequence of articles. Sorting on date might be an option here
+(@pxref{Selecting a Group}.
-To take an example: You're reading mail using @code{nnml}
-(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a
-satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox
-file filled with important, but old, mail. You want to move it into
-your @code{nnml} groups.
+One limitation, however---all groups that are included in a virtual
+group has to be alive (i.e., subscribed or unsubscribed). Killed or
+zombie groups can't be component groups for @code{nnvirtual} groups.
-Here's how:
+@vindex nnvirtual-always-rescan
+If the @code{nnvirtual-always-rescan} is non-@code{nil},
+@code{nnvirtual} will always scan groups for unread articles when
+entering a virtual group. If this variable is @code{nil} (which is the
+default) and you read articles in a component group after the virtual
+group has been activated, the read articles from the component group
+will show up when you enter the virtual group. You'll also see this
+effect if you have two virtual groups that contain the same component
+group. If that's the case, you should set this variable to @code{t}.
+Or you can just tap @code{M-g} on the virtual group every time before
+you enter it---it'll have much the same effect.
-@enumerate
-@item
-Go to the group buffer.
-@item
-Type `G f' and give the path of the mbox file when prompted to create an
-@code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
+@node Kibozed Groups
+@subsection Kibozed Groups
+@cindex nnkiboze
+@cindex kibozing
-@item
-Type `SPACE' to enter the newly created group.
+@dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
+the news feed''. @code{nnkiboze} is a backend that will do this for
+you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
+with useless requests! Oh happiness!
-@item
-Type `M P b' to process-mark all articles in this group (@pxref{Setting
-Process Marks}).
+@kindex G k (Group)
+To create a kibozed group, use the @kbd{G k} command in the group
+buffer.
-@item
-Type `B r' to respool all the process-marked articles, and answer
-@samp{nnml} when prompted (@pxref{Mail Group Commands}).
-@end enumerate
+The address field of the @code{nnkiboze} method is, as with
+@code{nnvirtual}, a regexp to match groups to be ``included'' in the
+@code{nnkiboze} group. There most similarities between @code{nnkiboze}
+and @code{nnvirtual} ends.
-All the mail messages in the mbox file will now also be spread out over
-all your @code{nnml} groups. Try entering them and check whether things
-have gone without a glitch. If things look ok, you may consider
-deleting the mbox file, but I wouldn't do that unless I was absolutely
-sure that all the mail has ended up where it should be.
+In addition to this regexp detailing component groups, an @code{nnkiboze} group
+must have a score file to say what articles that are to be included in
+the group (@pxref{Scoring}).
-Respooling is also a handy thing to do if you're switching from one mail
-backend to another. Just respool all the mail in the old mail groups
-using the new mail backend.
+@kindex M-x nnkiboze-generate-groups
+@findex nnkiboze-generate-groups
+You must run @kbd{M-x nnkiboze-generate-groups} after creating the
+@code{nnkiboze} groups you want to have. This command will take time. Lots of
+time. Oodles and oodles of time. Gnus has to fetch the headers from
+all the articles in all the components groups and run them through the
+scoring process to determine if there are any articles in the groups
+that are to be part of the @code{nnkiboze} groups.
+Please limit the number of component groups by using restrictive
+regexps. Otherwise your sysadmin may become annoyed with you, and the
+@sc{nntp} site may throw you off and never let you back in again.
+Stranger things have happened.
-@node Expiring Mail
-@subsection Expiring Mail
-@cindex article expiry
+@code{nnkiboze} component groups do not have to be alive---they can be dead,
+and they can be foreign. No restrictions.
-Traditional mail readers have a tendency to remove mail articles when
-you mark them as read, in some way. Gnus takes a fundamentally
-different approach to mail reading.
+@vindex nnkiboze-directory
+The generation of an @code{nnkiboze} group means writing two files in
+@code{nnkiboze-directory}, which is @file{~/News/} by default. One
+contains the @sc{nov} header lines for all the articles in the group,
+and the other is an additional @file{.newsrc} file to store information
+on what groups that have been searched through to find component
+articles.
-Gnus basically considers mail just to be news that has been received in
-a rather peculiar manner. It does not think that it has the power to
-actually change the mail, or delete any mail messages. If you enter a
-mail group, and mark articles as ``read'', or kill them in some other
-fashion, the mail articles will still exist on the system. I repeat:
-Gnus will not delete your old, read mail. Unless you ask it to, of
-course.
+Articles that are marked as read in the @code{nnkiboze} group will have their
+@sc{nov} lines removed from the @sc{nov} file.
-To make Gnus get rid of your unwanted mail, you have to mark the
-articles as @dfn{expirable}. This does not mean that the articles will
-disappear right away, however. In general, a mail article will be
-deleted from your system if, 1) it is marked as expirable, AND 2) it is
-more than one week old. If you do not mark an article as expirable, it
-will remain on your system until hell freezes over. This bears
-repeating one more time, with some spurious capitalizations: IF you do
-NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
-@vindex gnus-auto-expirable-newsgroups
-You do not have to mark articles as expirable by hand. Groups that
-match the regular expression @code{gnus-auto-expirable-newsgroups} will
-have all articles that you read marked as expirable automatically. All
-articles that are marked as expirable have an @samp{E} in the first
-column in the summary buffer.
+@node Scoring
+@chapter Scoring
+@cindex scoring
-Let's say you subscribe to a couple of mailing lists, and you want the
-articles you have read to disappear after a while:
+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!
-@lisp
-(setq gnus-auto-expirable-newsgroups
- "mail.nonsense-list\\|mail.nice-list")
-@end lisp
+@vindex gnus-summary-mark-below
+All articles have a default score (@code{gnus-summary-default-score}),
+which is 0 by default. This score may be raised or lowered either
+interactively or by score files. Articles that have a score lower than
+@code{gnus-summary-mark-below} are marked as read.
-Another way to have auto-expiry happen is to have the element
-@code{auto-expire} in the group parameters of the group.
+Gnus will read any @dfn{score files} that apply to the current group
+before generating the summary buffer.
-@vindex nnmail-expiry-wait
-The @code{nnmail-expiry-wait} variable supplies the default time an
-expirable article has to live. The default is seven days.
+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.
-Gnus also supplies a function that lets you fine-tune how long articles
-are to live, based on what group they are in. Let's say you want to
-have one month expiry period in the @samp{mail.private} group, a one day
-expiry period in the @samp{mail.junk} group, and a six day expiry period
-everywhere else:
+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.
-@vindex nnmail-expiry-wait-function
-@lisp
-(setq nnmail-expiry-wait-function
- (lambda (group)
- (cond ((string= group "mail.private")
- 31)
- ((string= group "mail.junk")
- 1)
- ((string= group "important")
- 'never)
- (t
- 6))))
-@end lisp
+@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 @emph{knows} what you read.
+* Home Score File:: How to say where new score entries are to go.
+* Followups To Yourself:: Having Gnus notice when people answer you.
+* 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.
+* GroupLens:: Getting predictions on what you like to read.
+* Advanced Scoring:: Using logical expressions to build score rules.
+* Score Decays:: It can be useful to let scores wither away.
+@end menu
-The group names that this function is fed are ``unadorned'' group
-names---no @samp{nnml:} prefixes and the like.
-The @code{nnmail-expiry-wait} variable and
-@code{nnmail-expiry-wait-function} function can be either a number (not
-necessarily an integer) or the symbols @code{immediate} or
-@code{never}.
+@node Summary Score Commands
+@section Summary Score Commands
+@cindex score commands
-You can also use the @code{expiry-wait} group parameter to selectively
-change the expiry period (@pxref{Group Parameters}).
+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.
-@vindex nnmail-keep-last-article
-If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
-expire the final article in a mail newsgroup. This is to make life
-easier for procmail users.
+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 (e.g. @file{all.SCORE}), you must first make this
+score file the current one.
-@vindex gnus-total-expirable-newsgroups
-By the way, that line up there about Gnus never expiring non-expirable
-articles is a lie. If you put @code{total-expire} in the group
-parameters, articles will not be marked as expirable, but all read
-articles will be put through the expiry process. Use with extreme
-caution. Even more dangerous is the
-@code{gnus-total-expirable-newsgroups} variable. All groups that match
-this regexp will have all read articles put through the expiry process,
-which means that @emph{all} old mail articles in the groups in question
-will be deleted after a while. Use with extreme caution, and don't come
-crying to me when you discover that the regexp you used matched the
-wrong group and all your important mail has disappeared. Be a
-@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
-with! So there!
+General score commands that don't actually change the score file:
+@table @kbd
-@node Duplicates
-@subsection Duplicates
+@item V s
+@kindex V s (Summary)
+@findex gnus-summary-set-score
+Set the score of the current article (@code{gnus-summary-set-score}).
-@vindex nnmail-delete-duplicates
-@vindex nnmail-message-id-cache-length
-@vindex nnmail-message-id-cache-file
-@vindex nnmail-treat-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 treats 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{warn} (which is what it is by
-default), and @code{nnmail} won't delete duplicate mails. Instead it
-will generate a brand new @code{Message-ID} for the mail and insert a
-warning into the head of the mail saying that it thinks that this is a
-duplicate of a different message.
+@item V S
+@kindex V S (Summary)
+@findex gnus-summary-current-score
+Display the score of the current article
+(@code{gnus-summary-current-score}).
-This variable can also be a function. If that's the case, the function
-will be called from a buffer narrowed to the message in question with
-the @code{Message-ID} as a parameter. The function must return either
-@code{nil}, @code{warn}, or @code{delete}.
+@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}).
-You can turn this feature off completely by setting the variable to
-@code{nil}.
+@item V R
+@kindex V R (Summary)
+@findex gnus-summary-rescore
+Run the current summary through the scoring process
+(@code{gnus-summary-rescore}). This might be useful if you're playing
+around with your score files behind Gnus' back and want to see the
+effect you're having.
-If you want all the duplicate mails to be put into a special
-@dfn{duplicates} group, you could do that using the normal mail split
-methods:
+@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}).
-@lisp
-(setq nnmail-split-fancy
- '(| ;; Messages duplicates go to a separate group.
- ("gnus-warning" "duplication of message" "duplicate")
- ;; Message from daemons, postmaster, and the like to another.
- (any mail "mail.misc")
- ;; Other rules.
- [ ... ] ))
-@end lisp
+@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}).
-Or something like:
-@lisp
-(setq nnmail-split-methods
- '(("duplicates" "^Gnus-Warning:")
- ;; Other rules.
- [...]))
-@end lisp
+@item V e
+@kindex V e (Summary)
+@findex gnus-score-edit-current-scores
+Edit the current score file (@code{gnus-score-edit-current-scores}).
+You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
+File Editing}).
-Here's a neat feature: If you know that the recipient reads her mail
-with Gnus, and that she has @code{nnmail-treat-duplicates} set to
-@code{delete}, 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!
+@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 F
+@kindex V F (Summary)
+@findex gnus-score-flush-cache
+Flush the score cache (@code{gnus-score-flush-cache}). This is useful
+after editing score files.
-@node Not Reading Mail
-@subsection Not Reading Mail
+@item V C
+@kindex V C (Summary)
+@findex gnus-score-customize
+Customize a score file in a visually pleasing manner
+(@code{gnus-score-customize}).
-If you start using any of the mail backends, they have the annoying
-habit of assuming that you want to read mail with them. This might not
-be unreasonable, but it might not be what you want.
+@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}).
-If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
-will ever attempt to read incoming mail, which should help.
+@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
-@vindex nnbabyl-get-new-mail
-@vindex nnmbox-get-new-mail
-@vindex nnml-get-new-mail
-@vindex nnmh-get-new-mail
-@vindex nnfolder-get-new-mail
-This might be too much, if, for instance, you are reading mail quite
-happily with @code{nnml} and just want to peek at some old @sc{rmail}
-file you have stashed away with @code{nnbabyl}. All backends have
-variables called backend-@code{get-new-mail}. If you want to disable
-the @code{nnbabyl} mail reading, you edit the virtual server for the
-group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
+The rest of these commands modify the local score file.
-All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
-narrowed to the article to be saved before saving it when reading
-incoming mail.
+@table @kbd
+@item V m
+@kindex V m (Summary)
+@findex gnus-score-set-mark-below
+Prompt for a score, and mark all articles with a score below this as
+read (@code{gnus-score-set-mark-below}).
-@node Choosing a Mail Backend
-@subsection Choosing a Mail Backend
+@item V x
+@kindex V x (Summary)
+@findex gnus-score-set-expunge-below
+Prompt for a score, and add a score rule to the current score file to
+expunge all articles below this score
+(@code{gnus-score-set-expunge-below}).
+@end table
-Gnus will read the mail spool when you activate a mail group. The mail
-file is first copied to your home directory. What happens after that
-depends on what format you want to store your mail in.
+The keystrokes for actually making score entries follow a very regular
+pattern, so there's no need to list all the commands. (Hundreds of
+them.)
-@menu
-* Unix Mail Box:: Using the (quite) standard Un*x mbox.
-* Rmail Babyl:: Emacs programs use the rmail babyl format.
-* Mail Spool:: Store your mail in a private spool?
-* MH Spool:: An mhspool-like backend.
-* Mail Folders:: Having one file for each group.
-@end menu
+@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.
-@node Unix Mail Box
-@subsubsection Unix Mail Box
-@cindex nnmbox
-@cindex unix mail box
+@item s
+Score on the subject line.
-@vindex nnmbox-active-file
-@vindex nnmbox-mbox-file
-The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
-mail. @code{nnmbox} will add extra headers to each mail article to say
-which group it belongs in.
+@item x
+Score on the Xref line---i.e., the cross-posting line.
-Virtual server settings:
+@item t
+Score on thread---the References line.
-@table @code
-@item nnmbox-mbox-file
-@vindex nnmbox-mbox-file
-The name of the mail box in the user's home directory.
+@item d
+Score on the date.
-@item nnmbox-active-file
-@vindex nnmbox-active-file
-The name of the active file for the mail box.
+@item l
+Score on the number of lines.
-@item nnmbox-get-new-mail
-@vindex nnmbox-get-new-mail
-If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
-into groups.
-@end table
+@item i
+Score on the Message-ID.
+@item f
+Score on followups.
-@node Rmail Babyl
-@subsubsection Rmail Babyl
-@cindex nnbabyl
-@cindex rmail mbox
+@item b
+Score on the body.
-@vindex nnbabyl-active-file
-@vindex nnbabyl-mbox-file
-The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
-mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
-article to say which group it belongs in.
+@item h
+Score on the head.
+@end table
-Virtual server settings:
+@item
+The third key is the match type. Which match types are legal depends on
+what headers you are scoring on.
@table @code
-@item nnbabyl-mbox-file
-@vindex nnbabyl-mbox-file
-The name of the rmail mbox file.
-@item nnbabyl-active-file
-@vindex nnbabyl-active-file
-The name of the active file for the rmail box.
+@item strings
-@item nnbabyl-get-new-mail
-@vindex nnbabyl-get-new-mail
-If non-@code{nil}, @code{nnbabyl} will read incoming mail.
-@end table
+@table @kbd
+@item e
+Exact matching.
-@node Mail Spool
-@subsubsection Mail Spool
-@cindex nnml
-@cindex mail @sc{nov} spool
+@item s
+Substring matching.
-The @dfn{nnml} spool mail format isn't compatible with any other known
-format. It should be used with some caution.
+@item f
+Fuzzy matching.
-@vindex nnml-directory
-If you use this backend, Gnus will split all incoming mail into files;
-one file for each mail, and put the articles into the correct
-directories under the directory specified by the @code{nnml-directory}
-variable. The default value is @file{~/Mail/}.
+@item r
+Regexp matching
+@end table
-You do not have to create any directories beforehand; Gnus will take
-care of all that.
+@item date
+@table @kbd
-If you have a strict limit as to how many files you are allowed to store
-in your account, you should not use this backend. As each mail gets its
-own file, you might very well occupy thousands of inodes within a few
-weeks. If this is no problem for you, and it isn't a problem for you
-having your friendly systems administrator walking around, madly,
-shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
-know that this is probably the fastest format to use. You do not have
-to trudge through a big mbox file just to read your new mail.
+@item b
+Before date.
-@code{nnml} is probably the slowest backend when it comes to article
-splitting. It has to create lots of files, and it also generates
-@sc{nov} databases for the incoming mails. This makes is the fastest
-backend when it comes to reading mail.
+@item a
+At date.
-Virtual server settings:
+@item n
+This date.
+@end table
-@table @code
-@item nnml-directory
-@vindex nnml-directory
-All @code{nnml} directories will be placed under this directory.
+@item number
+@table @kbd
-@item nnml-active-file
-@vindex nnml-active-file
-The active file for the @code{nnml} server.
+@item <
+Less than number.
-@item nnml-newsgroups-file
-@vindex nnml-newsgroups-file
-The @code{nnml} group descriptions file. @xref{Newsgroups File
-Format}.
+@item =
+Equal to number.
-@item nnml-get-new-mail
-@vindex nnml-get-new-mail
-If non-@code{nil}, @code{nnml} will read incoming mail.
+@item >
+Greater than number.
+@end table
+@end table
-@item nnml-nov-is-evil
-@vindex nnml-nov-is-evil
-If non-@code{nil}, this backend will ignore any @sc{nov} files.
+@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 nnml-nov-file-name
-@vindex nnml-nov-file-name
-The name of the @sc{nov} files. The default is @file{.overview}.
+@item t
+Temporary score entry.
-@item nnml-prepare-save-mail-hook
-@vindex nnml-prepare-save-mail-hook
-Hook run narrowed to an article before saving.
+@item p
+Permanent score entry.
+@item i
+Immediately scoring.
@end table
-@findex nnml-generate-nov-databases
-If your @code{nnml} groups and @sc{nov} files get totally out of whack,
-you can do a complete update by typing @kbd{M-x
-nnml-generate-nov-databases}. This command will trawl through the
-entire @code{nnml} hierarchy, looking at each and every article, so it
-might take a while to complete.
+@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 MH Spool
-@subsubsection MH Spool
-@cindex nnmh
-@cindex mh-e mail spool
+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}.
-@code{nnmh} is just like @code{nnml}, except that is doesn't generate
-@sc{nov} databases and it doesn't keep an active file. This makes
-@code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
-makes it easier to write procmail scripts for.
+@vindex gnus-score-mimic-keymap
+The @code{gnus-score-mimic-keymap} says whether these commands will
+pretend they are keymaps or not.
-Virtual server settings:
-@table @code
-@item nnmh-directory
-@vindex nnmh-directory
-All @code{nnmh} directories will be located under this directory.
+@node Group Score Commands
+@section Group Score Commands
+@cindex group score commands
-@item nnmh-get-new-mail
-@vindex nnmh-get-new-mail
-If non-@code{nil}, @code{nnmh} will read incoming mail.
+There aren't many of these as yet, I'm afraid.
-@item nnmh-be-safe
-@vindex nnmh-be-safe
-If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
-sure that the articles in the folder are actually what Gnus thinks they
-are. It will check date stamps and stat everything in sight, so
-setting this to @code{t} will mean a serious slow-down. If you never
-use anything but Gnus to read the @code{nnmh} articles, you do not have
-to set this variable to @code{t}.
-@end table
+@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}).
-@node Mail Folders
-@subsubsection Mail Folders
-@cindex nnfolder
-@cindex mbox folders
-@cindex mail folders
+@end table
-@code{nnfolder} is a backend for storing each mail group in a separate
-file. Each file is in the standard Un*x mbox format. @code{nnfolder}
-will add extra headers to keep track of article numbers and arrival
-dates.
-Virtual server settings:
+@node Score Variables
+@section Score Variables
+@cindex score variables
@table @code
-@item nnfolder-directory
-@vindex nnfolder-directory
-All the @code{nnfolder} mail boxes will be stored under this directory.
-@item nnfolder-active-file
-@vindex nnfolder-active-file
-The name of the active file.
+@item gnus-use-scoring
+@vindex gnus-use-scoring
+If @code{nil}, Gnus will not check for score files, and will not, in
+general, do any score-related work. This is @code{t} by default.
-@item nnfolder-newsgroups-file
-@vindex nnfolder-newsgroups-file
-The name of the group descriptions file. @xref{Newsgroups File Format}.
+@item gnus-kill-killed
+@vindex gnus-kill-killed
+If this variable is @code{nil}, Gnus will never apply score files to
+articles that have already been through the kill process. While this
+may save you lots of time, it also means that if you apply a kill file
+to a group, and then change the kill file and want to run it over you
+group again to kill more articles, it won't work. You have to set this
+variable to @code{t} to do that. (It is @code{t} by default.)
-@item nnfolder-get-new-mail
-@vindex nnfolder-get-new-mail
-If non-@code{nil}, @code{nnfolder} will read incoming mail.
-@end table
+@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 @code{SAVEDIR} environment variable by default.
+This is @file{~/News/} by default.
-@findex nnfolder-generate-active-file
-@kindex M-x nnfolder-generate-active-file
-If you have lots of @code{nnfolder}-like files you'd like to read with
-@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
-command to make @code{nnfolder} aware of all likely files in
-@code{nnfolder-directory}.
+@item gnus-score-file-suffix
+@vindex gnus-score-file-suffix
+Suffix to add to the group name to arrive at the score file name
+(@samp{SCORE} by default.)
+
+@item gnus-score-uncacheable-files
+@vindex gnus-score-uncacheable-files
+@cindex score cache
+All score files are normally cached to avoid excessive re-loading of
+score files. However, if this might make you Emacs grow big and
+bloated, so this regexp can be used to weed out score files that are
+unlikely to be needed again. It would be a bad idea to deny caching of
+@file{all.SCORE}, while it might be a good idea to not cache
+@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
+variable is @samp{ADAPT$} by default, so no adaptive score files will
+be cached.
+@item gnus-save-score
+@vindex gnus-save-score
+If you have really complicated score files, and do lots of batch
+scoring, then you might set this variable to @code{t}. This will make
+Gnus save the scores into the @file{.newsrc.eld} file.
-@node Other Sources
-@section Other Sources
+@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.
-Gnus can do more than just read news or mail. The methods described
-below allow Gnus to view directories and files as if they were
-newsgroups.
+@item gnus-summary-default-score
+@vindex gnus-summary-default-score
+Default score of an article, which is 0 by default.
-@menu
-* Directory Groups:: You can read a directory as if it was a newsgroup.
-* Anything Groups:: Dired? Who needs dired?
-* Document Groups:: Single files can be the basis of a group.
-* SOUP:: Reading @sc{SOUP} packets ``offline''.
-@end menu
+@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{-}.
-@node Directory Groups
-@subsection Directory Groups
-@cindex nndir
-@cindex directory groups
+@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.
-If you have a directory that has lots of articles in separate files in
-it, you might treat it as a newsgroup. The files have to have numerical
-names, of course.
+Predefined functions available are:
+@table @code
-This might be an opportune moment to mention @code{ange-ftp}, that most
-wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
-didn't think much about it---a backend to read directories. Big deal.
+@item gnus-score-find-single
+@findex gnus-score-find-single
+Only apply the group's own score file.
-@code{ange-ftp} changes that picture dramatically. For instance, if you
-enter @file{"/ftp.hpc.uh.edu:/pub/emacs/ding-list/"} as the the
-directory name, ange-ftp will actually allow you to read this directory
-over at @samp{sina} as a newsgroup. Distributed news ahoy!
+@item gnus-score-find-bnews
+@findex gnus-score-find-bnews
+Apply all score files that match, using bnews syntax. This is the
+default. If the current group is @samp{gnu.emacs.gnus}, for instance,
+@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
+@file{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.
-@code{nndir} will use @sc{nov} files if they are present.
+This means that if you have some score entries that you want to apply to
+all groups, then you put those entries in the @file{all.SCORE} file.
-@code{nndir} is a ``read-only'' backend---you can't delete or expire
-articles with this method. You can use @code{nnmh} or @code{nnml} for
-whatever you use @code{nndir} for, so you could switch to any of those
-methods if you feel the need to have a non-read-only @code{nndir}.
+The score files are applied in a semi-random order, although Gnus will
+try to apply the more general score files before the more specific score
+files. It does this by looking at the number of elements in the score
+file names---discarding the @samp{all} elements.
+@item gnus-score-find-hierarchical
+@findex gnus-score-find-hierarchical
+Apply all score files from all the parent groups. This means that you
+can't have score files like @file{all.SCORE}, but you can have
+@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE}.
-@node Anything Groups
-@subsection Anything Groups
-@cindex nneething
+@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.
-From the @code{nndir} backend (which reads a single spool-like
-directory), it's just a hop and a skip to @code{nneething}, which
-pretends that any arbitrary directory is a newsgroup. Strange, but
-true.
+@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. If this variable is @code{nil}, no score file entries
+are expired. It's 7 by default.
-When @code{nneething} is presented with a directory, it will scan this
-directory and assign article numbers to each file. When you enter such
-a group, @code{nneething} must create ``headers'' that Gnus can use.
-After all, Gnus is a newsreader, in case you're
-forgetting. @code{nneething} does this in a two-step process. First, it
-snoops each file in question. If the file looks like an article (i.e.,
-the first few lines look like headers), it will use this as the head.
-If this is just some arbitrary file without a head (eg. a C source
-file), @code{nneething} will cobble up a header out of thin air. It
-will use file ownership, name and date and do whatever it can with these
-elements.
+@item gnus-update-score-entry-dates
+@vindex gnus-update-score-entry-dates
+If this variable is non-@code{nil}, matching score entries will have
+their dates updated. (This is how Gnus controls expiry---all
+non-matching entries will become too old while matching entries will
+stay fresh and young.) However, if you set this variable to @code{nil},
+even matching entries will grow old and will have to face that oh-so
+grim reaper.
-All this should happen automatically for you, and you will be presented
-with something that looks very much like a newsgroup. Totally like a
-newsgroup, to be precise. If you select an article, it will be displayed
-in the article buffer, just as usual.
+@item gnus-score-after-write-file-function
+@vindex gnus-score-after-write-file-function
+Function called with the name of the score file just written.
-If you select a line that represents a directory, Gnus will pop you into
-a new summary buffer for this @code{nneething} group. And so on. You can
-traverse the entire disk this way, if you feel like, but remember that
-Gnus is not dired, really, and does not intend to be, either.
+@end table
-There are two overall modes to this action---ephemeral or solid. When
-doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
-will not store information on what files you have read, and what files
-are new, and so on. If you create a solid @code{nneething} group the
-normal way with @kbd{G m}, Gnus will store a mapping table between
-article numbers and file names, and you can treat this group like any
-other groups. When you activate a solid @code{nneething} group, you will
-be told how many unread articles it contains, etc., etc.
-Some variables:
+@node Score File Format
+@section Score File Format
+@cindex score file format
-@table @code
-@item nneething-map-file-directory
-@vindex nneething-map-file-directory
-All the mapping files for solid @code{nneething} groups will be stored
-in this directory, which defaults to @file{~/.nneething/}.
+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.
-@item nneething-exclude-files
-@vindex nneething-exclude-files
-All files that match this regexp will be ignored. Nice to use to exclude
-auto-save files and the like, which is what it does by default.
+Anyway, if you'd like to dig into it yourself, here's an example:
-@item nneething-map-file
-@vindex nneething-map-file
-Name of the map files.
-@end table
+@lisp
+(("from"
+ ("Lars Ingebrigtsen" -10000)
+ ("Per Abrahamsen")
+ ("larsi\\|lmi" -50000 nil R))
+ ("subject"
+ ("Ding is Badd" nil 728373))
+ ("xref"
+ ("alt.politics" -1000 728372 s))
+ ("lines"
+ (2 -100 nil <))
+ (mark 0)
+ (expunge -1000)
+ (mark-and-expunge -10)
+ (read-only nil)
+ (orphan -10)
+ (adapt t)
+ (files "/hom/larsi/News/gnu.SCORE")
+ (exclude-files "all.SCORE")
+ (local (gnus-newsgroup-auto-expire t)
+ (gnus-summary-make-false-root 'empty))
+ (eval (ding)))
+@end lisp
+This example demonstrates absolutely everything about a score file.
-@node Document Groups
-@subsection Document Groups
-@cindex nndoc
-@cindex documentation group
-@cindex help group
+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.
-@code{nndoc} is a cute little thing that will let you read a single file
-as a newsgroup. Several files types are supported:
+Six keys are supported by this alist:
@table @code
-@cindex babyl
-@cindex rmail mbox
-@item babyl
-The babyl (rmail) mail box.
-@cindex mbox
-@cindex Unix mbox
+@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:
+@code{From}, @code{Subject}, @code{References}, @code{Message-ID},
+@code{Xref}, @code{Lines}, @code{Chars} and @code{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: @code{Body}
+will perform the match on the body of the article, @code{Head} will
+perform the match on the head of the article, and @code{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 @code{Followup}. These score
+entries will result in new score entries being added for all follow-ups
+to articles that matches these score entries.
-@item mbox
-The standard Unix mbox file.
+Following this key is a arbitrary number of score entries, where each
+score entry has one to four elements.
+@enumerate
-@cindex MMDF mail box
-@item mmdf
-The MMDF mail box format.
+@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 news
-Several news articles appended into a file.
+@item
+If the second element is present, it should be a number---the @dfn{score
+element}. This number should be an integer in the neginf to posinf
+interval. This number is added to the score of the article if the match
+is successful. If this element is not present, the
+@code{gnus-score-interactive-default-score} number will be used
+instead. This is 1000 by default.
-@item rnews
-@cindex rnews batch files
-The rnews batch transport format.
-@cindex forwarded messages
+@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 forward
-Forwarded articles.
+@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 mime-digest
-@cindex digest
-@cindex MIME digest
-@cindex 1153 digest
-@cindex RFC 1153 digest
-@cindex RFC 341 digest
-MIME (RFC 1341) digest format.
+@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), and @code{w} (word match) types. If this
+element is not present, Gnus will assume that substring matching should
+be used. @code{R}, @code{S}, and @code{E} differ from the others 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}, @code{exact}, and @code{word} types, which you can use
+instead, if you feel like.
-@item standard-digest
-The standard (RFC 1153) digest format.
+@item Lines, Chars
+These two headers use different match types: @code{<}, @code{>},
+@code{=}, @code{>=} and @code{<=}.
-@item slack-digest
-Non-standard digest format---matches most things, but does it badly.
+@item Date
+For the Date header we have three kinda silly 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. (I have been told that at least one person, and I
+quote, ``found this function indispensable'', however.)
+
+@cindex ISO8601
+@cindex date
+A more useful match type is @code{regexp}. With it, you can match the
+date string using a regular expression. The date is normalized to
+ISO8601 compact format first---@samp{YYYYMMDDTHHMMSS}. If you want to
+match all articles that have been posted on April 1st in every year, you
+could use @samp{....0401.........} as a match string, for instance.
+(Note that the date is kept in its original time zone, so this will
+match articles that were posted when it was April 1st where the article
+was posted from. Time zones are such wholesome fun for the whole
+family, eh?)
+
+@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 is somewhat special, in that it will match the
+@code{From} header, and affect the score of not only the matching
+articles, but also all followups to the matching articles. This allows
+you e.g. increase the score of followups to your own articles, or
+decrease the score of followups to the articles of some known
+trouble-maker. Uses the same match types as the @code{From} header
+uses.
+
+@item Thread
+This match key works along the same lines as the @code{Followup} match
+key. If you say that you want to score on a (sub-)thread that is
+started by an article with a @code{Message-ID} @var{X}, then you add a
+@samp{thread} match. This will add a new @samp{thread} match for each
+article that has @var{X} in its @code{References} header. (These new
+@samp{thread} matches will use the @code{Message-ID}s of these matching
+articles.) This will ensure that you can raise/lower the score of an
+entire thread, even though some articles in the thread may not have
+complete @code{References} headers. Note that using this may lead to
+undeterministic scores of the articles in the thread.
@end table
+@end enumerate
-You can also use the special ``file type'' @code{guess}, which means
-that @code{nndoc} will try to guess what file type it is looking at.
-@code{digest} means that @code{nndoc} should guess what digest type the
-file is.
+@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.
-@code{nndoc} will not try to change the file or insert any extra headers into
-it---it will simply, like, let you use the file as the basis for a
-group. And that's it.
+@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.
-If you have some old archived articles that you want to insert into your
-new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
-that. Say you have an old @file{RMAIL} file with mail that you now want
-to split into your new @code{nnml} groups. You look at that file using
-@code{nndoc}, set the process mark on all the articles in the buffer
-(@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) using
-@code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
-now also stored in lots of @code{nnml} directories, and you can delete
-that pesky @file{RMAIL} file. If you have the guts!
+@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.
-Virtual server variables:
+@item thread-mark-and-expunge
+The value of this entry should be a number. All articles that belong to
+a thread that has a total score below this number will be marked as read
+and removed from the summary buffer. @code{gnus-thread-score-function}
+says how to compute the total score for a thread.
-@table @code
-@item nndoc-article-type
-@vindex nndoc-article-type
-This should be one of @code{mbox}, @code{babyl}, @code{digest},
-@code{mmdf}, @code{forward}, @code{news}, @code{rnews},
-@code{mime-digest}, @code{clari-briefs}, or @code{guess}.
+@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 nndoc-post-type
-@vindex nndoc-post-type
-This variable says whether Gnus is to consider the group a news group or
-a mail group. There are two legal values: @code{mail} (the default)
-and @code{news}.
-@end table
+@item exclude-files
+The clue of this entry should be any number of files. These 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}).
-@node SOUP
-@subsection SOUP
-@cindex SOUP
-@cindex offline
+@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. Imagine you follow
+some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
+will only follow a few of the threads, also want to see any new threads.
-In the PC world people often talk about ``offline'' newsreaders. These
-are thingies that are combined reader/news transport monstrosities.
-With built-in modem programs. Yecchh!
+You can do this with the following two score file entries:
-Of course, us Unix Weenie types of human beans use things like
-@code{uucp} and, like, @code{nntpd} and set up proper news and mail
-transport things like Ghod intended. And then we just use normal
-newsreaders.
+@example
+ (orphan -500)
+ (mark-and-expunge -100)
+@end example
-However, it can sometimes be convenient to do something a that's a bit
-easier on the brain if you have a very slow modem, and you're not really
-that interested in doing things properly.
+When you enter the group the first time, you will only see the new
+threads. You then raise the score of the threads that you find
+interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
+rest. Next time you enter the group, you will see new articles in the
+interesting threads, plus any new threads.
-A file format called @sc{soup} has been developed for transporting news
-and mail from servers to home machines and back again. It can be a bit
-fiddly.
+I.e.---the orphan score atom is for high-volume groups where there
+exist a few interesting threads which can't be found automatically by
+ordinary scoring rules.
-@enumerate
+@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
-You log in on the server and create a @sc{soup} packet. You can either
-use a dedicated @sc{soup} thingie, or you can use Gnus to create the
-packet with the @kbd{O s} command.
+@item adapt-file
+All adaptive score entries will go to the file named by this entry. It
+will also be applied when entering the group. This atom might be handy
+if you want to adapt on several groups at once, using the same adaptive
+file for a number of groups.
-@item
-You transfer the packet home. Rail, boat, car or modem will do fine.
+@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
-@item
-You put the packet in your home directory.
-@item
-You fire up Gnus using the @code{nnsoup} backend as the native server.
+@node Score File Editing
+@section Score File Editing
-@item
-You read articles and mail and answer and followup to the things you
-want.
+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
-You do the @kbd{G s r} command to pack these replies into a @sc{soup}
-packet.
+It's simply a slightly customized @code{emacs-lisp} mode, with these
+additional commands:
-@item
-You transfer this packet to the server.
+@table @kbd
-@item
-You use Gnus to mail this packet out with the @kbd{G s s} command.
+@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
-You then repeat until you die.
+@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 enumerate
+@item C-c C-p
+@kindex C-c C-p (Score)
+@findex gnus-score-pretty-print
+The adaptive score files are saved in an unformatted fashion. If you
+intend to read one of these files, you want to @dfn{pretty print} it
+first. This command (@code{gnus-score-pretty-print}) does that for
+you.
-So you basically have a bipartite system---you use @code{nnsoup} for
-reading and Gnus for packing/sending these @sc{soup} packets.
+@end table
-@menu
-* SOUP Commands:: Commands for creating and sending @sc{soup} packets
-* SOUP Groups:: A backend for reading @sc{soup} packets.
-* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
-@end menu
+Type @kbd{M-x gnus-score-mode} to use this mode.
+@vindex gnus-score-mode-hook
+@code{gnus-score-menu-hook} is run in score mode buffers.
-@node SOUP Commands
-@subsubsection SOUP Commands
+In the summary buffer you can use commands like @kbd{V f} and @kbd{V
+e} to begin editing score files.
-@table @kbd
-@item G s b
-@kindex G s b (Group)
-@findex gnus-group-brew-soup
-Pack all unread articles in the current group
-(@code{gnus-group-brew-soup}). This command understands the
-process/prefix convention.
-@item G s w
-@kindex G s w (Group)
-@findex gnus-soup-save-areas
-Save all data files (@code{gnus-soup-save-areas}).
+@node Adaptive Scoring
+@section Adaptive Scoring
+@cindex adaptive scoring
-@item G s s
-@kindex G s s (Group)
-@findex gnus-soup-send-replies
-Send all replies from the replies packet
-(@code{gnus-soup-send-replies}).
+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.
-@item G s p
-@kindex G s p (Group)
-@findex gnus-soup-pack-packet
-Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
+@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} or @code{(line)}. If you want score adaptively on separate
+words appearing in the subjects, you should set this variable to
+@code{(word)}. If you want to use both adaptive methods, set this
+variable to @code{(word line)}.
-@item G s r
-@kindex G s r (Group)
-@findex nnsoup-pack-replies
-Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
+@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. For instance, it
+might look something like this:
-@item O s
-@kindex O s (Summary)
-@findex gnus-soup-add-article
-This summary-mode command adds the current article to a @sc{soup} packet
-(@code{gnus-soup-add-article}). It understands the process/prefix
-convention.
+@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-ancient-mark)
+ (gnus-low-score-mark)
+ (gnus-catchup-mark (from -1) (subject -1))))
+@end lisp
-@end table
+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 arbitrary number of header/score pairs. If there are no header/score
+pairs following the key, no adaptive scoring will be done on articles
+that have that key as the article mark. For instance, articles with
+@code{gnus-unread-mark} in the example above will not get adaptive score
+entries.
+Each article can have only one mark, so just a single of these rules
+will be applied to each article.
-There are a few variables to customize where Gnus will put all these
-thingies:
+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
+If you have marked 10 articles with the same subject with
+@code{gnus-del-mark}, the rule for that mark will be applied ten times.
+That means that that subject will get a score of ten times -1, which
+should be, unless I'm much mistaken, -10.
-@item gnus-soup-directory
-@vindex gnus-soup-directory
-Directory where Gnus will save intermediate files while composing
-@sc{soup} packets. The default is @file{~/SoupBrew/}.
+If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all
+the read articles will be marked with the @samp{E} mark. This'll
+probably make adaptive scoring slightly impossible, so auto-expiring and
+adaptive scoring doesn't really mix very well.
-@item gnus-soup-replies-directory
-@vindex gnus-soup-replies-directory
-This is what Gnus will use as a temporary directory while sending our
-reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
+The headers you can score on are @code{from}, @code{subject},
+@code{message-id}, @code{references}, @code{xref}, @code{lines},
+@code{chars} and @code{date}. In addition, you can score on
+@code{followup}, which will create an adaptive score entry that matches
+on the @code{References} header using the @code{Message-ID} of the
+current article, thereby matching the following thread.
-@item gnus-soup-prefix-file
-@vindex gnus-soup-prefix-file
-Name of the file where Gnus stores the last used prefix. The default is
-@samp{gnus-prefix}.
+You can also score on @code{thread}, which will try to score all
+articles that appear in a thread. @code{thread} matches uses a
+@code{Message-ID} to match on the @code{References} header of the
+article. If the match is made, the @code{Message-ID} of the article is
+added to the @code{thread} rule. (Think about it. I'd recommend two
+aspirins afterwards.)
-@item gnus-soup-packer
-@vindex gnus-soup-packer
-A format string command for packing a @sc{soup} packet. The default is
-@samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
+If you use this scheme, you should set the score file atom @code{mark}
+to something small---like -300, perhaps, to avoid having small random
+changes result in articles getting marked as read.
-@item gnus-soup-unpacker
-@vindex gnus-soup-unpacker
-Format string command for unpacking a @sc{soup} packet. The default is
-@samp{gunzip -c %s | tar xvf -}.
+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.
-@item gnus-soup-packet-directory
-@vindex gnus-soup-packet-directory
-Where Gnus will look for reply packets. The default is @file{~/}.
+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.
-@item gnus-soup-packet-regexp
-@vindex gnus-soup-packet-regexp
-Regular expression matching @sc{soup} reply packets in
-@code{gnus-soup-packet-directory}.
+@vindex gnus-adaptive-file-suffix
+The adaptive score entries will be put into a file where the name is the
+group name with @code{gnus-adaptive-file-suffix} appended. The default
+is @samp{ADAPT}.
-@end table
-
+@vindex gnus-score-exact-adapt-limit
+When doing adaptive scoring, substring or fuzzy matching would probably
+give you the best results in most cases. However, if the header one
+matches is short, the possibility for false positives is great, so if
+the length of the match is less than
+@code{gnus-score-exact-adapt-limit}, exact matching will be used. If
+this variable is @code{nil}, exact matching will always be used to avoid
+this problem.
-@node SOUP Groups
-@subsubsection @sc{soup} Groups
-@cindex nnsoup
+@vindex gnus-default-adaptive-word-score-alist
+As mentioned above, you can adapt either on individual words or entire
+headers. If you adapt on words, the
+@code{gnus-default-adaptive-word-score-alist} variable says what score
+each instance of a word should add given a mark.
-@code{nnsoup} is the backend for reading @sc{soup} packets. It will
-read incoming packets, unpack them, and put them in a directory where
-you can read them at leisure.
+@lisp
+(setq gnus-default-adaptive-word-score-alist
+ `((,gnus-read-mark . 30)
+ (,gnus-catchup-mark . -10)
+ (,gnus-killed-mark . -20)
+ (,gnus-del-mark . -15)))
+@end lisp
-These are the variables you can use to customize its behavior:
+This is the default value. If you have adaption on words enabled, every
+word that appears in subjects of articles that are marked with
+@code{gnus-read-mark} will result in a score rule that increase the
+score with 30 points.
-@table @code
+@vindex gnus-default-ignored-adaptive-words
+@vindex gnus-ignored-adaptive-words
+Words that appear in the @code{gnus-default-ignored-adaptive-words} list
+will be ignored. If you wish to add more words to be ignored, use the
+@code{gnus-ignored-adaptive-words} list instead.
-@item nnsoup-tmp-directory
-@vindex nnsoup-tmp-directory
-When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
-directory. (@file{/tmp/} by default.)
+@vindex gnus-adaptive-word-syntax-table
+When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the
+syntax table in effect. It is similar to the standard syntax table, but
+it considers numbers to be non-word-constituent characters.
-@item nnsoup-directory
-@vindex nnsoup-directory
-@code{nnsoup} then moves each message and index file to this directory.
-The default is @file{~/SOUP/}.
+After using this scheme for a while, it might be nice to write a
+@code{gnus-psychoanalyze-user} command to go through the rules and see
+what words you like and what words you don't like. Or perhaps not.
-@item nnsoup-replies-directory
-@vindex nnsoup-replies-directory
-All replies will stored in this directory before being packed into a
-reply packet. The default is @file{~/SOUP/replies/"}.
-@item nnsoup-replies-format-type
-@vindex nnsoup-replies-format-type
-The @sc{soup} format of the replies packets. The default is @samp{?n}
-(rnews), and I don't think you should touch that variable. I probably
-shouldn't even have documented it. Drats! Too late!
+@node Home Score File
+@section Home Score File
-@item nnsoup-replies-index-type
-@vindex nnsoup-replies-index-type
-The index type of the replies packet. The is @samp{?n}, which means
-``none''. Don't fiddle with this one either!
+The score file where new score file entries will go is called the
+@dfn{home score file}. This is normally (and by default) the score file
+for the group itself. For instance, the home score file for
+@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}.
-@item nnsoup-active-file
-@vindex nnsoup-active-file
-Where @code{nnsoup} stores lots of information. This is not an ``active
-file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
-this file or mess it up in any way, you're dead. The default is
-@file{~/SOUP/active}.
+However, this may not be what you want. It is often convenient to share
+a common home score file among many groups---all @samp{emacs} groups
+could perhaps use the same home score file.
-@item nnsoup-packer
-@vindex nnsoup-packer
-Format string command for packing a reply @sc{soup} packet. The default
-is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
+@vindex gnus-home-score-file
+The variable that controls this is @code{gnus-home-score-file}. It can
+be:
-@item nnsoup-unpacker
-@vindex nnsoup-unpacker
-Format string command for unpacking incoming @sc{soup} packets. The
-default is @samp{gunzip -c %s | tar xvf -}.
+@enumerate
+@item
+A string. Then this file will be used as the home score file for all
+groups.
-@item nnsoup-packet-directory
-@vindex nnsoup-packet-directory
-Where @code{nnsoup} will look for incoming packets. The default is
-@file{~/}.
+@item
+A function. The result of this function will be used as the home score
+file. The function will be called with the name of the group as the
+parameter.
-@item nnsoup-packet-regexp
-@vindex nnsoup-packet-regexp
-Regular expression matching incoming @sc{soup} packets. The default is
-@samp{Soupout}.
+@item
+A list. The elements in this list can be:
-@end table
+@enumerate
+@item
+@var{(regexp file-name)}. If the @var{regexp} matches the group name,
+the @var{file-name} will will be used as the home score file.
+@item
+A function. If the function returns non-nil, the result will be used as
+the home score file.
-@node SOUP Replies
-@subsubsection SOUP Replies
+@item
+A string. Use the string as the home score file.
+@end enumerate
-Just using @code{nnsoup} won't mean that your postings and mailings end
-up in @sc{soup} reply packets automagically. You have to work a bit
-more for that to happen.
+The list will be traversed from the beginning towards the end looking
+for matches.
-@findex nnsoup-set-variables
-The @code{nnsoup-set-variables} command will set the appropriate
-variables to ensure that all your followups and replies end up in the
-@sc{soup} system.
+@end enumerate
-In specific, this is what it does:
+So, if you want to use just a single score file, you could say:
@lisp
-(setq gnus-inews-article-function 'nnsoup-request-post)
-(setq send-mail-function 'nnsoup-request-mail)
+(setq gnus-home-score-file
+ "my-total-score-file.SCORE")
@end lisp
-And that's it, really. If you only want news to go into the @sc{soup}
-system you just use the first line. If you only want mail to be
-@sc{soup}ed you use the second.
-
+If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and
+@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say:
-@node Combined Groups
-@section Combined Groups
+@lisp
+(setq gnus-home-score-file
+ 'gnus-hierarchial-home-score-file)
+@end lisp
-Gnus allows combining a mixture of all the other group types into bigger
-groups.
+This is a ready-made function provided for your convenience.
-@menu
-* Virtual Groups:: Combining articles from many groups.
-* Kibozed Groups:: Looking through parts of the newsfeed for articles.
-@end menu
+If you want to have one score file for the @samp{emacs} groups and
+another for the @samp{comp} groups, while letting all other groups use
+their own home score files:
+@lisp
+(setq gnus-home-score-file
+ ;; All groups that match the regexp "\\.emacs"
+ '("\\.emacs" "emacs.SCORE")
+ ;; All the comp groups in one score file
+ ("^comp" "comp.SCORE"))
+@end lisp
+
+@vindex gnus-home-adapt-file
+@code{gnus-home-adapt-file} works exactly the same way as
+@code{gnus-home-score-file}, but says what the home adaptive score file
+is instead. All new adaptive file entries will go into the file
+specified by this variable, and the same syntax is allowed.
-@node Virtual Groups
-@subsection Virtual Groups
-@cindex nnvirtual
-@cindex virtual groups
+In addition to using @code{gnus-home-score-file} and
+@code{gnus-home-adapt-file}, you can also use group parameters
+(@pxref{Group Parameters}) and topic parameters (@pxref{Topic
+Parameters}) to achieve much the same. Group and topic parameters take
+precedence over this variable.
-An @dfn{nnvirtual group} is really nothing more than a collection of
-other groups.
-For instance, if you are tired of reading many small group, you can
-put them all in one big group, and then grow tired of reading one
-big, unwieldy group. The joys of computing!
+@node Followups To Yourself
+@section Followups To Yourself
-You specify @code{nnvirtual} as the method. The address should be a
-regexp to match component groups.
+Gnus offers two commands for picking out the @code{Message-ID} header in
+the current buffer. Gnus will then add a score rule that scores using
+this @code{Message-ID} on the @code{References} header of other
+articles. This will, in effect, increase the score of all articles that
+respond to the article in the current buffer. Quite useful if you want
+to easily note when people answer what you've said.
-All marks in the virtual group will stick to the articles in the
-component groups. So if you tick an article in a virtual group, the
-article will also be ticked in the component group from whence it came.
-(And vice versa---marks from the component groups will also be shown in
-the virtual group.)
+@table @code
-Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
-newsgroups into one, big, happy newsgroup:
+@item gnus-score-followup-article
+@findex gnus-score-followup-article
+This will add a score to articles that directly follow up your own
+article.
-@lisp
-(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
-@end lisp
+@item gnus-score-followup-thread
+@findex gnus-score-followup-thread
+This will add a score to all articles that appear in a thread ``below''
+your own article.
+@end table
-The component groups can be native or foreign; everything should work
-smoothly, but if your computer explodes, it was probably my fault.
+@vindex message-sent-hook
+These two functions are both primarily meant to be used in hooks like
+@code{message-sent-hook}.
-Collecting the same group from several servers might actually be a good
-idea if users have set the Distribution header to limit distribution.
-If you would like to read @samp{soc.motss} both from a server in Japan
-and a server in Norway, you could use the following as the group regexp:
+If you look closely at your own @code{Message-ID}, you'll notice that
+the first two or three characters are always the same. Here's two of
+mine:
@example
-"^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
+<x6u3u47icf.fsf@@eyesore.no>
+<x6sp9o7ibw.fsf@@eyesore.no>
@end example
-This should work kinda smoothly---all articles from both groups should
-end up in this one, and there should be no duplicates. Threading (and
-the rest) will still work as usual, but there might be problems with the
-sequence of articles. Sorting on date might be an option here
-(@pxref{Selecting a Group}.
+So ``my'' ident on this machine is @samp{x6}. This can be
+exploited---the following rule will raise the score on all followups to
+myself:
-One limitation, however---all groups that are included in a virtual
-group has to be alive (i.e., subscribed or unsubscribed). Killed or
-zombie groups can't be component groups for @code{nnvirtual} groups.
+@lisp
+("references"
+ "<x6[0-9a-z]+\\.fsf@@.*eyesore.no>" 1000 nil r)
+@end lisp
-@vindex nnvirtual-always-rescan
-If the @code{nnvirtual-always-rescan} is non-@code{nil},
-@code{nnvirtual} will always scan groups for unread articles when
-entering a virtual group. If this variable is @code{nil} (which is the
-default) and you read articles in a component group after the virtual
-group has been activated, the read articles from the component group
-will show up when you enter the virtual group. You'll also see this
-effect if you have two virtual groups that contain the same component
-group. If that's the case, you should set this variable to @code{t}.
-Or you can just tap @code{M-g} on the virtual group every time before
-you enter it---it'll have much the same effect.
+Whether it's the first two or first three characters that are ``yours''
+is system-dependent.
-@node Kibozed Groups
-@subsection Kibozed Groups
-@cindex nnkiboze
-@cindex kibozing
+@node Scoring Tips
+@section Scoring Tips
+@cindex scoring tips
-@dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
-the news feed''. @code{nnkiboze} is a backend that will do this for
-you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
-with useless requests! Oh happiness!
+@table @dfn
-The address field of the @code{nnkiboze} method is, as with
-@code{nnvirtual}, a regexp to match groups to be ``included'' in the
-@code{nnkiboze} group. There most similarities between @code{nnkiboze}
-and @code{nnvirtual} ends.
+@item Crossposts
+@cindex crossposts
+@cindex scoring 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
-In addition to this regexp detailing component groups, an @code{nnkiboze} group
-must have a score file to say what articles that are to be included in
-the group (@pxref{Scoring}).
+@item Multiple crossposts
+If you want to lower the score of articles that have been crossposted to
+more than, say, 3 groups:
+@lisp
+("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
+@end lisp
-@kindex M-x nnkiboze-generate-groups
-@findex nnkiboze-generate-groups
-You must run @kbd{M-x nnkiboze-generate-groups} after creating the
-@code{nnkiboze} groups you want to have. This command will take time. Lots of
-time. Oodles and oodles of time. Gnus has to fetch the headers from
-all the articles in all the components groups and run them through the
-scoring process to determine if there are any articles in the groups
-that are to be part of the @code{nnkiboze} groups.
+@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.
-Please limit the number of component groups by using restrictive
-regexps. Otherwise your sysadmin may become annoyed with you, and the
-@sc{nntp} site may throw you off and never let you back in again.
-Stranger things have happened.
+@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}.
-@code{nnkiboze} component groups do not have to be alive---they can be dead,
-and they can be foreign. No restrictions.
+@item Negated character 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
-@vindex nnkiboze-directory
-The generation of an @code{nnkiboze} group means writing two files in
-@code{nnkiboze-directory}, which is @file{~/News/} by default. One
-contains the @sc{nov} header lines for all the articles in the group,
-and the other is an additional @file{.newsrc} file to store information
-on what groups that have been searched through to find component
-articles.
-Articles that are marked as read in the @code{nnkiboze} group will have their
-@sc{nov} lines removed from the @sc{nov} file.
+@node Reverse Scoring
+@section Reverse Scoring
+@cindex reverse scoring
+
+If you want to keep just articles that have @samp{Sex with Emacs} in the
+subject header, and expunge all other articles, you could put something
+like this in your score file:
+
+@lisp
+(("subject"
+ ("Sex with Emacs" 2))
+ (mark 1)
+ (expunge 1))
+@end lisp
+So, you raise all articles that match @samp{Sex with Emacs} and mark the
+rest as read, and expunge them to boot.
-@node Scoring
-@chapter Scoring
-@cindex scoring
-Other people use @dfn{kill files}, but we here at Gnus Towers like
-scoring better than killing, so we'd rather switch than fight. They do
-something completely different as well, so sit up straight and pay
-attention!
+@node Global Score Files
+@section Global Score Files
+@cindex global score files
-@vindex gnus-summary-mark-below
-All articles have a default score (@code{gnus-summary-default-score}),
-which is 0 by default. This score may be raised or lowered either
-interactively or by score files. Articles that have a score lower than
-@code{gnus-summary-mark-below} are marked as read.
+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!
-Gnus will read any @dfn{score files} that apply to the current group
-before generating the summary 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!
-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.
+@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.
-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.
+Say you want to use the score file
+@file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE} and
+all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory:
-@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.
-* Followups To Yourself:: Having Gnus notice when people answer you.
-* 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.
-* GroupLens:: Getting predictions on what you like to read.
-@end menu
+@lisp
+(setq gnus-global-score-files
+ '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
+ "/ftp@@ftp.some-where:/pub/score/"))
+@end lisp
+@findex gnus-score-search-global-directories
+Simple, eh? Directory names must end with a @samp{/}. These
+directories are typically scanned only once during each Gnus session.
+If you feel the need to manually re-scan the remote directories, you can
+use the @code{gnus-score-search-global-directories} command.
-@node Summary Score Commands
-@section Summary Score Commands
-@cindex score commands
+Note that, at present, using this option will slow down group entry
+somewhat. (That is---a lot.)
-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.
+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!
-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.
+Here are some tips for the would-be retro-moderator, off the top of my
+head:
-General score commands that don't actually change the score file:
+@itemize @bullet
-@table @kbd
+@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 V s
-@kindex V s (Summary)
-@findex gnus-summary-set-score
-Set the score of the current article (@code{gnus-summary-set-score}).
+@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
-@item V S
-@kindex V S (Summary)
-@findex gnus-summary-current-score
-Display the score of the current article
-(@code{gnus-summary-current-score}).
+... 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?
-@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 R
-@cindex V R (Summary)
-@findex gnus-summary-rescore
-Run the current summary through the scoring process
-(@code{gnus-summary-rescore}). This might be useful if you're playing
-around with your score files behind Gnus' back and want to see the
-effect you're having.
+@node Kill Files
+@section Kill Files
+@cindex kill files
-@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}).
+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.
-@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}).
+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.
-@item V e
-@kindex V e (Summary)
-@findex gnus-score-edit-current-scores
-Edit the current score file (@code{gnus-score-edit-current-scores}).
-You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
-File Editing}).
+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.
-@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}).
+Normal kill files look like this:
-@item V C
-@kindex V C (Summary)
-@findex gnus-score-customize
-Customize a score file in a visually pleasing manner
-(@code{gnus-score-customize}).
+@lisp
+(gnus-kill "From" "Lars Ingebrigtsen")
+(gnus-kill "Subject" "ding")
+(gnus-expunge "X")
+@end lisp
-@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}).
+This will mark every article written by me as read, and remove them from
+the summary buffer. Very useful, you'll agree.
-@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
+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.
-The rest of these commands modify the local score file.
+Two summary functions for editing a GNUS kill file:
@table @kbd
-@item V m
-@kindex V m (Summary)
-@findex gnus-score-set-mark-below
-Prompt for a score, and mark all articles with a score below this as
-read (@code{gnus-score-set-mark-below}).
+@item 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 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}).
+@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
-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.)
+Two group mode functions for editing the kill files:
-@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 M-k
+@kindex M-k (Group)
+@findex gnus-group-edit-local-kill
+Edit this group's kill file (@code{gnus-group-edit-local-kill}).
-@item s
-Score on the subject line.
+@item M-K
+@kindex M-K (Group)
+@findex gnus-group-edit-global-kill
+Edit the general kill file (@code{gnus-group-edit-global-kill}).
+@end table
-@item x
-Score on the Xref line---i.e., the cross-posting line.
+Kill file variables:
-@item t
-Score on thread---the References line.
+@table @code
+@item gnus-kill-file-name
+@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}.
-@item d
-Score on the date.
+@vindex gnus-kill-save-kill-file
+@item gnus-kill-save-kill-file
+If this variable is non-@code{nil}, Gnus will save the
+kill file after processing, which is necessary if you use expiring
+kills.
-@item l
-Score on the number of lines.
+@item gnus-apply-kill-hook
+@vindex gnus-apply-kill-hook
+@findex gnus-apply-kill-file-unless-scored
+@findex gnus-apply-kill-file
+A hook called to apply kill files to a group. It is
+@code{(gnus-apply-kill-file)} by default. If you want to ignore the
+kill file if you have a score file for the same group, you can set this
+hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
+kill files to be processed, you should set this variable to @code{nil}.
-@item i
-Score on the Message-ID.
+@item gnus-kill-file-mode-hook
+@vindex gnus-kill-file-mode-hook
+A hook called in kill-file mode buffers.
-@item f
-Score on followups.
+@end table
-@item b
-Score on the body.
-@item h
-Score on the head.
-@end table
+@node GroupLens
+@section GroupLens
+@cindex GroupLens
-@item
-The third key is the match type. Which match types are legal depends on
-what headers you are scoring on.
+GroupLens is a collaborative filtering system that helps you work
+together with other people to find the quality news articles out of the
+huge volume of news articles generated every day.
-@table @code
+To accomplish this the GroupLens system combines your opinions about
+articles you have already read with the opinions of others who have done
+likewise and gives you a personalized prediction for each unread news
+article. Think of GroupLens as a matchmaker. GroupLens watches how you
+rate articles, and finds other people that rate articles the same way.
+Once it has found for you some people you agree with it tells you, in
+the form of a prediction, what they thought of the article. You can use
+this prediction to help you decide whether or not you want to read the
+article.
-@item strings
+@menu
+* Using GroupLens:: How to make Gnus use GroupLens.
+* Rating Articles:: Letting GroupLens know how you rate articles.
+* Displaying Predictions:: Displaying predictions given by GroupLens.
+* GroupLens Variables:: Customizing GroupLens.
+@end menu
-@table @kbd
-@item e
-Exact matching.
+@node Using GroupLens
+@subsection Using GroupLens
-@item s
-Substring matching.
+To use GroupLens you must register a pseudonym with your local Better
+Bit Bureau (BBB).
+@samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html} is the only
+better bit in town is at the moment.
-@item f
-Fuzzy matching.
+Once you have registered you'll need to set a couple of variables.
-@item r
-Regexp matching
-@end table
+@table @code
-@item date
-@table @kbd
+@item gnus-use-grouplens
+@vindex gnus-use-grouplens
+Setting this variable to a non-@code{nil} value will make Gnus hook into
+all the relevant GroupLens functions.
-@item b
-Before date.
+@item grouplens-pseudonym
+@vindex grouplens-pseudonym
+This variable should be set to the pseudonym you got when registering
+with the Better Bit Bureau.
-@item a
-At date.
+@item grouplens-newsgroups
+@vindex grouplens-newsgroups
+A list of groups that you want to get GroupLens predictions for.
-@item n
-This date.
@end table
-@item number
-@table @kbd
+Thats the minimum of what you need to get up and running with GroupLens.
+Once you've registered, GroupLens will start giving you scores for
+articles based on the average of what other people think. But, to get
+the real benefit of GroupLens you need to start rating articles
+yourself. Then the scores GroupLens gives you will be personalized for
+you, based on how the people you usually agree with have already rated.
-@item <
-Less than number.
-@item =
-Equal to number.
+@node Rating Articles
+@subsection Rating Articles
-@item >
-Greater than number.
-@end table
-@end table
+In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
+Where 1 means something like this article is a waste of bandwidth and 5
+means that the article was really good. The basic question to ask
+yourself is, "on a scale from 1 to 5 would I like to see more articles
+like this one?"
+
+There are four ways to enter a rating for an article in GroupLens.
-@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 r
+@kindex r (GroupLens)
+@findex bbb-summary-rate-article
+This function will prompt you for a rating on a scale of one to five.
-@item p
-Permanent score entry.
+@item k
+@kindex k (GroupLens)
+@findex grouplens-score-thread
+This function will prompt you for a rating, and rate all the articles in
+the thread. This is really useful for some of those long running giant
+threads in rec.humor.
-@item i
-Immediately scoring.
@end table
-@end enumerate
+The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
+the score of the article you're reading.
-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.
+@table @kbd
-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}.
+@item 1-5 n
+@kindex n (GroupLens)
+@findex grouplens-next-unread-article
+Rate the article and go to the next unread article.
-@vindex gnus-score-mimic-keymap
-The @code{gnus-score-mimic-keymap} says whether these commands will
-pretend they are keymaps or not.
+@item 1-5 ,
+@kindex , (GroupLens)
+@findex grouplens-best-unread-article
+Rate the article and go to the next unread article with the highest score.
+@end table
-@node Group Score Commands
-@section Group Score Commands
-@cindex group score commands
+If you want to give the current article a score of 4 and then go to the
+next article, just type @kbd{4 n}.
-There aren't many of these as yet, I'm afraid.
-@table @kbd
+@node Displaying Predictions
+@subsection Displaying Predictions
-@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}).
+GroupLens makes a prediction for you about how much you will like a
+news article. The predictions from GroupLens are on a scale from 1 to
+5, where 1 is the worst and 5 is the best. You can use the predictions
+from GroupLens in one of three ways controlled by the variable
+@code{gnus-grouplens-override-scoring}.
-@end table
+@vindex gnus-grouplens-override-scoring
+There are three ways to display predictions in grouplens. You may
+choose to have the GroupLens scores contribute to, or override the
+regular gnus scoring mechanism. override is the default; however, some
+people prefer to see the Gnus scores plus the grouplens scores. To get
+the separate scoring behavior you need to set
+@code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
+GroupLens predictions combined with the grouplens scores set it to
+@code{'override} and to combine the scores set
+@code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
+the combine option you will also want to set the values for
+@code{grouplens-prediction-offset} and
+@code{grouplens-score-scale-factor}.
+@vindex grouplens-prediction-display
+In either case, GroupLens gives you a few choices for how you would like
+to see your predictions displayed. The display of predictions is
+controlled by the @code{grouplens-prediction-display} variable.
-@node Score Variables
-@section Score Variables
-@cindex score variables
+The following are legal values for that variable.
@table @code
+@item prediction-spot
+The higher the prediction, the further to the right an @samp{*} is
+displayed.
-@item gnus-use-scoring
-@vindex gnus-use-scoring
-If @code{nil}, Gnus will not check for score files, and will not, in
-general, do any score-related work. This is @code{t} by default.
-
-@item gnus-kill-killed
-@vindex gnus-kill-killed
-If this variable is @code{nil}, Gnus will never apply score files to
-articles that have already been through the kill process. While this
-may save you lots of time, it also means that if you apply a kill file
-to a group, and then change the kill file and want to run it over you
-group again to kill more articles, it won't work. You have to set this
-variable to @code{t} to do that. (It is @code{t} by default.)
-
-@item gnus-kill-files-directory
-@vindex gnus-kill-files-directory
-All kill and score files will be stored in this directory, which is
-initialized from the @code{SAVEDIR} environment variable by default.
-This is @file{~/News/} by default.
-
-@item gnus-score-file-suffix
-@vindex gnus-score-file-suffix
-Suffix to add to the group name to arrive at the score file name
-(@samp{SCORE} by default.)
+@item confidence-interval
+A numeric confidence interval.
-@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 prediction-bar
+The higher the prediction, the longer the bar.
-@item gnus-save-score
-@vindex gnus-save-score
-If you have really complicated score files, and do lots of batch
-scoring, then you might set this variable to @code{t}. This will make
-Gnus save the scores into the @file{.newsrc.eld} file.
+@item confidence-bar
+Numerical confidence.
-@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 confidence-spot
+The spot gets bigger with more confidence.
-@item gnus-summary-default-score
-@vindex gnus-summary-default-score
-Default score of an article, which is 0 by default.
+@item prediction-num
+Plain-old numeric value.
-@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 confidence-plus-minus
+Prediction +/i confidence.
-@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{-}.
+@end table
-@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:
+@node GroupLens Variables
+@subsection GroupLens Variables
+
@table @code
-@item gnus-score-find-single
-@findex gnus-score-find-single
-Only apply the group's own score file.
+@item gnus-summary-grouplens-line-format
+The summary line format used in summary buffers that are GroupLens
+enhanced. It accepts the same specs as the normal summary line format
+(@pxref{Summary Buffer Lines}). The default is
+@samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%) %s\n}.
-@item gnus-score-find-bnews
-@findex gnus-score-find-bnews
-Apply all score files that match, using bnews syntax. This is the
-default. For instance, if the current group is @samp{gnu.emacs.gnus},
-@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
-@file{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 grouplens-bbb-host
+Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the
+default.
-This means that if you have some score entries that you want to apply to
-all groups, then you put those entries in the @file{all.SCORE} file.
+@item grouplens-bbb-port
+Port of the host running the bbbd server. The default is 9000.
-@item gnus-score-find-hierarchical
-@findex gnus-score-find-hierarchical
-Apply all score files from all the parent groups. This means that you
-can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
-but you can have @file{SCORE}, @file{comp.SCORE} and
-@file{comp.emacs.SCORE}.
+@item grouplens-score-offset
+Offset the prediction by this value. In other words, subtract the
+prediction value by this number to arrive at the effective score. The
+default is 0.
+
+@item grouplens-score-scale-factor
+This variable allows the user to magnify the effect of GroupLens scores.
+The scale factor is applied after the offset. The default is 1.
@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. If this variable is @code{nil}, no score file entries
-are expired. It's 7 by default.
-@item gnus-update-score-entry-dates
-@vindex gnus-update-score-entry-dates
-If this variable is non-@code{nil}, matching score entries will have
-their dates updated. (This is how Gnus controls expiry---all
-non-matching entries will become too old while matching entries will
-stay fresh and young.) However, if you set this variable to @code{nil},
-even matching entries will grow old and will have to face that oh-so
-grim reaper.
+@node Advanced Scoring
+@section Advanced Scoring
-@item gnus-score-after-write-file-function
-@vindex gnus-score-after-write-file-function
-Function called with the name of the score file just written.
+Scoring on Subjects and From headers is nice enough, but what if you're
+really interested in what a person has to say only when she's talking
+about a particular subject? Or what about if you really don't want to
+read what person A has to say when she's following up to person B, but
+want to read what she says when she's following up to person C?
-@end table
+By using advanced scoring rules you may create arbitrarily complex
+scoring patterns.
+@menu
+* Advanced Scoring Syntax:: A definition.
+* Advanced Scoring Examples:: What they look like.
+* Advanced Scoring Tips:: Getting the most out of it.
+@end menu
-@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.
+@node Advanced Scoring Syntax
+@subsection Advanced Scoring Syntax
-Anyway, if you'd like to dig into it yourself, here's an example:
+Ordinary scoring rules have a string as the first element in the rule.
+Advanced scoring rules have a list as the first element. The second
+element is the score to be applied if the first element evaluated to a
+non-@code{nil} value.
-@lisp
-(("from"
- ("Lars Ingebrigtsen" -10000)
- ("Per Abrahamsen")
- ("larsi\\|lmi" -50000 nil R))
- ("subject"
- ("Ding is Badd" nil 728373))
- ("xref"
- ("alt.politics" -1000 728372 s))
- ("lines"
- (2 -100 nil <))
- (mark 0)
- (expunge -1000)
- (mark-and-expunge -10)
- (read-only nil)
- (orphan -10)
- (adapt t)
- (files "/hom/larsi/News/gnu.SCORE")
- (exclude-files "all.SCORE")
- (local (gnus-newsgroup-auto-expire t)
- (gnus-summary-make-false-root 'empty))
- (eval (ding)))
-@end lisp
+These lists may consist of three logical operators, one redirection
+operator, and various match operators.
-This example demonstrates absolutely everything about a score file.
+Logical operators:
-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.
+@table @code
+@item &
+@itemx and
+This logical operator will evaluate each of its arguments until it finds
+one that evaluates to @code{false}, and then it'll stop. If all arguments
+evaluate to @code{true} values, then this operator will return
+@code{true}.
+
+@item |
+@itemx or
+This logical operator will evaluate each of its arguments until it finds
+one that evaluates to @code{true}. If no arguments are @code{true},
+then this operator will return @code{false}.
-Six keys are supported by this alist:
+@item !
+@itemx not
+@itemx ¬
+This logical operator only takes a single argument. It returns the
+inverse of the value of its argument.
-@table @code
+@end table
-@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:
-@code{From}, @code{Subject}, @code{References}, @code{Message-ID},
-@code{Xref}, @code{Lines}, @code{Chars} and @code{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: @code{Body}
-will perform the match on the body of the article, @code{Head} will
-perform the match on the head of the article, and @code{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 @code{Followup}. These score
-entries will result in new score entries being added for all follow-ups
-to articles that matches these score entries.
+There is an @dfn{indirection operator} that will make its arguments
+apply to the ancestors of the current article being scored. For
+instance, @code{1-} will make score rules apply to the parent of the
+current article. @code{2-} will make score fules apply to the
+grandparent of the current article. Alternatively, you can write
+@code{^^}, where the number of @code{^}s (carets) say how far back into
+the ancestry you want to go.
-Following this key is a arbitrary number of score entries, where each
-score entry has one to four elements.
-@enumerate
+Finally, we have the match operators. These are the ones that do the
+real work. Match operators are header name strings followed by a match
+and a match type. A typical match operator looks like @samp{("from"
+"Lars Ingebrigtsen" s)}. The header names are the same as when using
+simple scoring, and the match types are also the same.
-@item
-The first element is the @dfn{match element}. On most headers this will
-be a string, but on the Lines and Chars headers, this must be an
-integer.
-@item
-If the second element is present, it should be a number---the @dfn{score
-element}. This number should be an integer in the neginf to posinf
-interval. This number is added to the score of the article if the match
-is successful. If this element is not present, the
-@code{gnus-score-interactive-default-score} number will be used
-instead. This is 1000 by default.
+@node Advanced Scoring Examples
+@subsection Advanced Scoring Examples
-@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.
+Let's say you want to increase the score of articles written by Lars
+when he's talking about Gnus:
-@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
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ ("subject" "Gnus"))
+ 1000)
+@end example
-@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.
+Quite simple, huh?
-@item Lines, Chars
-These two headers use different match types: @code{<}, @code{>},
-@code{=}, @code{>=} and @code{<=}.
+When he writes long articles, he sometimes has something nice to say:
-@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.
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ (|
+ ("subject" "Gnus")
+ ("lines" 100 >)))
+ 1000)
+@end example
-@item Head, Body, All
-These three match keys use the same match types as the @code{From} (etc)
-header uses.
+However, when he responds to things written by Reig Eigil Logge, you
+really don't want to read what he's written:
-@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.
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ (1- ("from" "Reig Eigir Logge")))
+ -100000)
+@end example
-@item Thread
-This match key will add a score entry on all articles that are part of
-a thread. Uses the same match types as the @code{References} header
-uses.
-@end table
-@end enumerate
+Everybody that follows up Redmondo when he writes about disappearing
+socks should have their scores raised, but only when they talk about
+white socks. However, when Lars talks about socks, it's usually not
+very interesting:
-@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.
+@example
+((&
+ (1-
+ (&
+ ("from" "redmondo@@.*no" r)
+ ("body" "disappearing.*socks" t)))
+ (! ("from" "Lars Ingebrigtsen"))
+ ("body" "white.*socks"))
+ 1000)
+@end example
-@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.
+The possibilities are endless.
-@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 thread-mark-and-expunge
-The value of this entry should be a number. All articles that belong to
-a thread that has a total score below this number will be marked as read
-and removed from the summary buffer. @code{gnus-thread-score-function}
-says how to compute the total score for a thread.
+@node Advanced Scoring Tips
+@subsection Advanced Scoring Tips
-@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.
+The @code{&} and @code{|} logical operators do short-circuit logic.
+That is, they stop processing their arguments when it's clear what the
+result of the operation will be. For instance, if one of the arguments
+of an @code{&} evaluates to @code{false}, there's no point in evaluating
+the rest of the arguments. This means that you should put slow matches
+(@samp{body}, @code{header}) last and quick matches (@samp{from},
+@samp{subject}) first.
-@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.
+The indirection arguments (@code{1-} and so on) will make their
+arguments work on previous generations of the thread. If you say
+something like:
-@item eval
-The value of this entry will be @code{eval}el. This element will be
-ignored when handling global score files.
+@example
+...
+(1-
+ (1-
+ ("from" "lars")))
+...
+@end example
-@item read-only
-Read-only score files will not be updated or saved. Global score files
-should feature this atom (@pxref{Global Score Files}).
+Then that means "score on the from header of the grandparent of the
+current article". An indirection is quite fast, but it's better to say:
-@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. Imagine you follow
-some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
-will only follow a few of the threads, also want to see any new threads.
+@example
+(1-
+ (&
+ ("from" "Lars")
+ ("subject" "Gnus")))
+@end example
-You can do this with the following two score file entries:
+than it is to say:
@example
- (orphan -500)
- (mark-and-expunge -100)
+(&
+ (1- ("from" "Lars"))
+ (1- ("subject" "Gnus")))
@end example
-When you enter the group the first time, you will only see the new
-threads. You then raise the score of the threads that you find
-interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
-rest. Next time you enter the group, you will see new articles in the
-interesting threads, plus any new threads.
-I.e. -- the orphan score atom is for high-volume groups where there
-exist a few interesting threads which can't be found automatically by
-ordinary scoring rules.
+@node Score Decays
+@section Score Decays
+@cindex score decays
+@cindex decays
-@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.
+You may find that your scores have a tendency to grow without
+bounds, especially if you're using adaptive scoring. If scores get too
+big, they lose all meaning---they simply max out and it's difficult to
+use them in any sensible way.
-@item adapt-file
-All adaptive score entries will go to the file named by this entry. It
-will also be applied when entering the group. This atom might be handy
-if you want to adapt on several groups at once, using the same adaptive
-file for a number of groups.
+@vindex gnus-decay-scores
+@findex gnus-decay-score
+@vindex gnus-score-decay-function
+Gnus provides a mechanism for decaying scores to help with this problem.
+When score files are loaded and @code{gnus-decay-scores} is
+non-@code{nil}, Gnus will run the score files through the decaying
+mechanism thereby lowering the scores of all non-permanent score rules.
+The decay itself if performed by the @code{gnus-score-decay-function}
+function, which is @code{gnus-decay-score} by default. Here's the
+definition of that function:
-@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
+@lisp
+(defun gnus-decay-score (score)
+ (floor
+ (- score
+ (* (if (< score 0) 1 -1)
+ (min score
+ (max gnus-score-decay-constant
+ (* (abs score)
+ gnus-score-decay-scale)))))))
+@end lisp
+@vindex gnus-score-decay-scale
+@vindex gnus-score-decay-constant
+@code{gnus-score-decay-constant} is 3 by default and
+@code{gnus-score-decay-scale} is 0.05. This should cause the following:
-@node Score File Editing
-@section Score File Editing
+@enumerate
+@item
+Scores between -3 and 3 will be set to 0 when this function is called.
+
+@item
+Scores with magnitudes between 3 and 60 will be shrunk by 3.
+
+@item
+Scores with magnitudes greater than 60 will be shrunk by 5% of the
+score.
+@end enumerate
+
+If you don't like this decay function, write your own. It is called
+with the score to be decayed as its only parameter, and it should return
+the new score, which should be an integer.
-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.
+Gnus will try to decay scores once a day. If you haven't run Gnus for
+four days, Gnus will decay the scores four times, for instance.
-It's simply a slightly customized @code{emacs-lisp} mode, with these
-additional commands:
-@table @kbd
+@node Various
+@chapter Various
-@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}).
+@menu
+* Process/Prefix:: A convention used by many treatment commands.
+* Interactive:: Making Gnus ask you many questions.
+* Formatting Variables:: You can specify what buffers should look like.
+* Windows Configuration:: Configuring the Gnus buffer windows.
+* Compilation:: How to speed Gnus up.
+* Mode Lines:: Displaying information in the mode lines.
+* Highlighting and Menus:: Making buffers look all nice and cozy.
+* Buttons:: Get tendonitis in ten easy steps!
+* Daemons:: Gnus can do things behind your back.
+* NoCeM:: How to avoid spam and other fatty foods.
+* Picons:: How to display pictures of what your reading.
+* Undo:: Some actions can be undone.
+* Moderation:: What to do if you're a moderator.
+* XEmacs Enhancements:: There are more pictures and stuff under XEmacs.
+* Various Various:: Things that are really various.
+@end menu
-@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.
-@item C-c C-p
-@kindex C-c C-p (Score)
-@findex gnus-score-pretty-print
-The adaptive score files are saved in an unformatted fashion. If you
-intend to read one of these files, you want to @dfn{pretty print} it
-first. This command (@code{gnus-score-pretty-print}) does that for
-you.
+@node Process/Prefix
+@section Process/Prefix
+@cindex process/prefix convention
-@end table
+Many functions, among them functions for moving, decoding and saving
+articles, use what is known as the @dfn{Process/Prefix convention}.
-Type @kbd{M-x gnus-score-mode} to use this mode.
+This is a method for figuring out what articles that the user wants the
+command to be performed on.
-@vindex gnus-score-mode-hook
-@code{gnus-score-menu-hook} is run in score mode buffers.
+It goes like this:
-In the summary buffer you can use commands like @kbd{V f} and @kbd{V
-e} to begin editing score files.
+If the numeric prefix is N, perform the operation on the next N
+articles, starting with the current one. If the numeric prefix is
+negative, perform the operation on the previous N articles, starting
+with the current one.
+@vindex transient-mark-mode
+If @code{transient-mark-mode} in non-@code{nil} and the region is
+active, all articles in the region will be worked upon.
-@node Adaptive Scoring
-@section Adaptive Scoring
-@cindex adaptive scoring
+If there is no numeric prefix, but some articles are marked with the
+process mark, perform the operation on the articles that are marked with
+the process mark.
-If 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.
+If there is neither a numeric prefix nor any articles marked with the
+process mark, just perform the operation on the current article.
-@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}.
+Quite simple, really, but it needs to be made clear so that surprises
+are avoided.
-@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. For instance, it
-might look something like this:
+Commands that react to the process mark will push the current list of
+process marked articles onto a stack and will then clear all process
+marked articles. You can restore the previous configuration with the
+@kbd{M P y} command (@pxref{Setting Process Marks}).
-@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-ancient-mark)
- (gnus-low-score-mark)
- (gnus-catchup-mark (from -1) (subject -1))))
-@end lisp
+@vindex gnus-summary-goto-unread
+One thing that seems to shock & horrify lots of people is that, for
+instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
+Since each @kbd{d} (which marks the current article as read) by default
+goes to the next unread article after marking, this means that @kbd{3 d}
+will mark the next three unread articles as read, no matter what the
+summary buffer looks like. Set @code{gnus-summary-goto-unread} to
+@code{nil} for a more straightforward action.
-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 arbitrary number of header/score pairs. If there are no header/score
-pairs following the key, no adaptive scoring will be done on articles
-that have that key as the article mark. For instance, articles with
-@code{gnus-unread-mark} in the example above will not get adaptive score
-entries.
-Each article can have only one mark, so just a single of these rules
-will be applied to each article.
+@node Interactive
+@section Interactive
+@cindex interaction
-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
-If you have marked 10 articles with the same subject with
-@code{gnus-del-mark}, the rule for that mark will be applied ten times.
-That means that that subject will get a score of ten times -1, which
-should be, unless I'm much mistaken, -10.
+@item gnus-novice-user
+@vindex gnus-novice-user
+If this variable is non-@code{nil}, you are either a newcomer to the
+World of Usenet, or you are very cautious, which is a nice thing to be,
+really. You will be given questions of the type ``Are you sure you want
+to do this?'' before doing anything dangerous. This is @code{t} by
+default.
-The headers you can score on are @code{from}, @code{subject},
-@code{message-id}, @code{references}, @code{xref}, @code{lines},
-@code{chars} and @code{date}. In addition, you can score on
-@code{followup}, which will create an adaptive score entry that matches
-on the @code{References} header using the @code{Message-ID} of the
-current article, thereby matching the following thread.
+@item gnus-expert-user
+@vindex gnus-expert-user
+If this variable is non-@code{nil}, you will never ever be asked any
+questions by Gnus. It will simply assume you know what you're doing, no
+matter how strange.
-You can also score on @code{thread}, which will try to score all
-articles that appear in a thread. @code{thread} matches uses a
-@code{Message-ID} to match on the @code{References} header of the
-article. If the match is made, the @code{Message-ID} of the article is
-added to the @code{thread} rule. (Think about it. I'd recommend two
-aspirins afterwards.)
+@item gnus-interactive-catchup
+@vindex gnus-interactive-catchup
+Require confirmation before catching up a group if non-@code{nil}. It
+is @code{t} by default.
-If you use this scheme, you should set the score file atom @code{mark}
-to something small---like -300, perhaps, to avoid having small random
-changes result in articles getting marked as read.
+@item gnus-interactive-exit
+@vindex gnus-interactive-exit
+Require confirmation before exiting Gnus. This variable is @code{t} by
+default.
+@end table
-After using adaptive scoring for a week or so, Gnus should start to
-become properly trained and enhance the authors you like best, and kill
-the authors you like least, without you having to say so explicitly.
-You can control what groups the adaptive scoring is to be performed on
-by using the score files (@pxref{Score File Format}). This will also
-let you use different rules in different groups.
+@node Formatting Variables
+@section Formatting Variables
+@cindex formatting variables
-@vindex gnus-adaptive-file-suffix
-The adaptive score entries will be put into a file where the name is the
-group name with @code{gnus-adaptive-file-suffix} appended. The default
-is @samp{ADAPT}.
+Throughout this manual you've probably noticed lots of variables that
+are called things like @code{gnus-group-line-format} and
+@code{gnus-summary-mode-line-format}. These control how Gnus is to
+output lines in the various buffers. There's quite a lot of them.
+Fortunately, they all use the same syntax, so there's not that much to
+be annoyed by.
-@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.
+Here's an example format spec (from the group buffer): @samp{%M%S%5y:
+%(%g%)\n}. We see that it is indeed extremely ugly, and that there are
+lots of percentages everywhere.
+@menu
+* Formatting Basics:: A formatting variable is basically a format string.
+* Advanced Formatting:: Modifying output in various ways.
+* User-Defined Specs:: Having Gnus call your own functions.
+* Formatting Fonts:: Making the formatting look colorful and nice.
+@end menu
-@node Followups To Yourself
-@section Followups To Yourself
+Currently Gnus uses the following formatting variables:
+@code{gnus-group-line-format}, @code{gnus-summary-line-format},
+@code{gnus-server-line-format}, @code{gnus-topic-line-format},
+@code{gnus-group-mode-line-format},
+@code{gnus-summary-mode-line-format},
+@code{gnus-article-mode-line-format},
+@code{gnus-server-mode-line-format}, and
+@code{gnus-summary-pick-line-format}.
-Gnus offers two commands for picking out the @code{Message-ID} header in
-the current buffer. Gnus will then add a score rule that scores using
-this @code{Message-ID} on the @code{References} header of other
-articles. This will, in effect, increase the score of all articles that
-respond to the article in the current buffer. Quite useful if you want
-to easily note when people answer what you've said.
+All these format variables can also be arbitrary elisp forms. In that
+case, they will be @code{eval}ed to insert the required lines.
-@table @code
+@kindex M-x gnus-update-format
+@findex gnus-update-format
+Gnus includes a command to help you while creating your own format
+specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
+update the spec in question and pop you to a buffer where you can
+examine the resulting lisp code to be run to generate the line.
-@item gnus-score-followup-article
-@findex gnus-score-followup-article
-This will add a score to articles that directly follow up your own
-article.
-@item gnus-score-followup-thread
-@findex gnus-score-followup-thread
-This will add a score to all articles that appear in a thread ``below''
-your own article.
-@end table
-@vindex gnus-inews-article-hook
-These two functions are both primarily meant to be used in hooks like
-@code{gnus-inews-article-hook}.
+@node Formatting Basics
+@subsection Formatting Basics
+Each @samp{%} element will be replaced by some string or other when the
+buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
+spec, and pad with spaces to get a 5-character field''.
-@node Scoring Tips
-@section Scoring Tips
-@cindex scoring tips
+As with normal C and Emacs Lisp formatting strings, the numerical
+modifier between the @samp{%} and the formatting type character will
+@dfn{pad} the output so that it is always at least that long.
+@samp{%5y} will make the field always (at least) five characters wide by
+padding with spaces to the left. If you say @samp{%-5y}, it will pad to
+the right instead.
-@table @dfn
+You may also wish to limit the length of the field to protect against
+particularly wide values. For that you can say @samp{%4,6y}, which
+means that the field will never be more than 6 characters wide and never
+less than 4 characters wide.
-@item Crossposts
-@cindex crossposts
-@cindex scoring crossposts
-If you want to lower the score of crossposts, the line to match on is
-the @code{Xref} header.
-@lisp
-("xref" (" talk.politics.misc:" -1000))
-@end lisp
-@item Multiple crossposts
-If you want to lower the score of articles that have been crossposted to
-more than, say, 3 groups:
-@lisp
-("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
-@end lisp
+@node Advanced Formatting
+@subsection Advanced Formatting
-@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.
+It is frequently useful to post-process the fields in some way.
+Padding, limiting, cutting off parts and suppressing certain values can
+be achieved by using @dfn{tilde modifiers}. A typical tilde spec might
+look like @samp{%~(cut 3)~(ignore "0")y}.
-@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}.
+These are the legal modifiers:
-@item Negated character 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
+@table @code
+@item pad
+@itemx pad-left
+Pad the field to the left with spaces until it reaches the required
+length.
+@item pad-right
+Pad the field to the right with spaces until it reaches the required
+length.
-@node Reverse Scoring
-@section Reverse Scoring
-@cindex reverse scoring
+@item max
+@itemx max-left
+Cut off characters from the left until it reaches the specified length.
-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:
+@item max-right
+Cut off characters from the right until it reaches the specified
+length.
-@lisp
-(("subject"
- ("Sex with Emacs" 2))
- (mark 1)
- (expunge 1))
-@end lisp
+@item cut
+@itemx cut-left
+Cut off the specified number of characters from the left.
-So, you raise all articles that match @samp{Sex with Emacs} and mark the
-rest as read, and expunge them to boot.
+@item cut-right
+Cut off the specified number of characters from the right.
+@item ignore
+Return an empty string if the field is equal to the specified value.
-@node Global Score Files
-@section Global Score Files
-@cindex global score files
+@item form
+Use the specified form as the field value when the @samp{@@} spec is
+used.
+@end table
-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!
+Let's take an example. The @samp{%o} spec in the summary mode lines
+will return a date in compact ISO8601 format---@samp{19960809T230410}.
+This is quite a mouthful, so we want to shave off the century number and
+the time, leaving us with a six-character date. That would be
+@samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before
+maxing, and we need the padding to ensure that the date is never less
+than 6 characters to make it look nice in columns.)
-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!
+Ignoring is done first; then cutting; then maxing; and then as the very
+last operation, padding.
-@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.
+If you use lots of these advanced thingies, you'll find that Gnus gets
+quite slow. This can be helped enormously by running @kbd{M-x
+gnus-compile} when you are satisfied with the look of your lines.
+@xref{Compilation}.
-Say you want to use all score files in the
-@file{/ftp@@ftp.some-where:/pub/score} directory and the single score
-file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
-@lisp
-(setq gnus-global-score-files
- '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
- "/ftp@@ftp.some-where:/pub/score/"))
-@end lisp
+@node User-Defined Specs
+@subsection User-Defined Specs
-@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.
+All the specs allow for inserting user defined specifiers---@samp{u}.
+The next character in the format string should be a letter. Gnus
+will call the function @code{gnus-user-format-function-}@samp{X}, where
+@samp{X} is the letter following @samp{%u}. The function will be passed
+a single parameter---what the parameter means depends on what buffer
+it's being called from. The function should return a string, which will
+be inserted into the buffer just like information from any other
+specifier. This function may also be called with dummy values, so it
+should protect against that.
-Note that, at present, using this option will slow down group entry
-somewhat. (That is---a lot.)
+You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve
+much the same without defining new functions. Here's an example:
+@samp{%~(form (count-lines (point-min) (point)))@@}. The form
+given here will be evaluated to yield the current line number, and then
+inserted.
-If you want to start maintaining score files for other people to use,
-just put your score file up for anonymous ftp and announce it to the
-world. Become a retro-moderator! Participate in the retro-moderator
-wars sure to ensue, where retro-moderators battle it out for the
-sympathy of the people, luring them to use their score files on false
-premises! Yay! The net is saved!
-Here are some tips for the would-be retro-moderator, off the top of my
-head:
+@node Formatting Fonts
+@subsection Formatting Fonts
-@itemize @bullet
+There are specs for highlighting, and these are shared by all the format
+variables. Text inside the @samp{%(} and @samp{%)} specifiers will get
+the special @code{mouse-face} property set, which means that it will be
+highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer
+over it.
-@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.
+Text inside the @samp{%[} and @samp{%]} specifiers will have their
+normal faces set using @code{gnus-face-0}, which is @code{bold} by
+default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
+instead, and so on. Create as many faces as you wish. The same goes
+for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
+@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
-@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
+Here's an alternative recipe for the group buffer:
-... 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
+;; Create three face types.
+(setq gnus-face-1 'bold)
+(setq gnus-face-3 'italic)
+;; We want the article count to be in
+;; a bold and green face. So we create
+;; a new face called `my-green-bold'.
+(copy-face 'bold 'my-green-bold)
+;; Set the color.
+(set-face-foreground 'my-green-bold "ForestGreen")
+(setq gnus-face-2 'my-green-bold)
-@node Kill Files
-@section Kill Files
-@cindex kill files
+;; Set the new & fancy format.
+(setq gnus-group-line-format
+ "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
+@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.
+I'm sure you'll be able to use this scheme to create totally unreadable
+and extremely vulgar displays. Have fun!
-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.
+Note that the @samp{%(} specs (and friends) do not make any sense on the
+mode-line variables.
-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:
+@node Windows Configuration
+@section Windows Configuration
+@cindex windows configuration
+
+No, there's nothing here about X, so be quiet.
+
+@vindex gnus-use-full-window
+If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
+other windows and occupy the entire Emacs screen by itself. It is
+@code{t} by default.
+
+@vindex gnus-buffer-configuration
+@code{gnus-buffer-configuration} describes how much space each Gnus
+buffer should be given. Here's an excerpt of this variable:
@lisp
-(gnus-kill "From" "Lars Ingebrigtsen")
-(gnus-kill "Subject" "ding")
-(gnus-expunge "X")
+((group (vertical 1.0 (group 1.0 point)
+ (if gnus-carpal (group-carpal 4))))
+ (article (vertical 1.0 (summary 0.25 point)
+ (article 1.0))))
@end lisp
-This will mark every article written by me as read, and remove them from
-the summary buffer. Very useful, you'll agree.
+This is an alist. The @dfn{key} is a symbol that names some action or
+other. For instance, when displaying the group buffer, the window
+configuration function will use @code{group} as the key. A full list of
+possible names is listed below.
-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.
+The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer
+should occupy. To take the @code{article} split as an example -
-Two summary functions for editing a GNUS kill file:
+@lisp
+(article (vertical 1.0 (summary 0.25 point)
+ (article 1.0)))
+@end lisp
-@table @kbd
+This @dfn{split} says that the summary buffer should occupy 25% of upper
+half of the screen, and that it is placed over the article buffer. As
+you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
+reaching for that calculator there). However, the special number
+@code{1.0} is used to signal that this buffer should soak up all the
+rest of the space available after the rest of the buffers have taken
+whatever they need. There should be only one buffer with the @code{1.0}
+size spec per split.
-@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}).
+Point will be put in the buffer that has the optional third element
+@code{point}.
-@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
+Here's a more complicated example:
-Two group mode functions for editing the kill files:
+@lisp
+(article (vertical 1.0 (group 4)
+ (summary 0.25 point)
+ (if gnus-carpal (summary-carpal 4))
+ (article 1.0)))
+@end lisp
-@table @kbd
+If the size spec is an integer instead of a floating point number,
+then that number will be used to say how many lines a buffer should
+occupy, not a percentage.
-@item M-k
-@kindex M-k (Group)
-@findex gnus-group-edit-local-kill
-Edit this group's kill file (@code{gnus-group-edit-local-kill}).
+If the @dfn{split} looks like something that can be @code{eval}ed (to be
+precise---if the @code{car} of the split is a function or a subr), this
+split will be @code{eval}ed. If the result is non-@code{nil}, it will
+be used as a split. This means that there will be three buffers if
+@code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
+is non-@code{nil}.
-@item M-K
-@kindex M-K (Group)
-@findex gnus-group-edit-global-kill
-Edit the general kill file (@code{gnus-group-edit-global-kill}).
-@end table
+Not complicated enough for you? Well, try this on for size:
-Kill file variables:
+@lisp
+(article (horizontal 1.0
+ (vertical 0.5
+ (group 1.0)
+ (gnus-carpal 4))
+ (vertical 1.0
+ (summary 0.25 point)
+ (summary-carpal 4)
+ (article 1.0))))
+@end lisp
-@table @code
-@item gnus-kill-file-name
-@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}.
+Whoops. Two buffers with the mystery 100% tag. And what's that
+@code{horizontal} thingie?
-@vindex gnus-kill-save-kill-file
-@item gnus-kill-save-kill-file
-If this variable is non-@code{nil}, Gnus will save the
-kill file after processing, which is necessary if you use expiring
-kills.
+If the first element in one of the split is @code{horizontal}, Gnus will
+split the window horizontally, giving you two windows side-by-side.
+Inside each of these strips you may carry on all you like in the normal
+fashion. The number following @code{horizontal} says what percentage of
+the screen is to be given to this strip.
+
+For each split, there @emph{must} be one element that has the 100% tag.
+The splitting is never accurate, and this buffer will eat any leftover
+lines from the splits.
+
+To be slightly more formal, here's a definition of what a legal split
+may look like:
+
+@example
+split = frame | horizontal | vertical | buffer | form
+frame = "(frame " size *split ")"
+horizontal = "(horizontal " size *split ")"
+vertical = "(vertical " size *split ")"
+buffer = "(" buffer-name " " size *[ "point" ] ")"
+size = number | frame-params
+buffer-name = group | article | summary ...
+@end example
-@item gnus-apply-kill-hook
-@vindex gnus-apply-kill-hook
-@findex gnus-apply-kill-file-unless-scored
-@findex gnus-apply-kill-file
-A hook called to apply kill files to a group. It is
-@code{(gnus-apply-kill-file)} by default. If you want to ignore the
-kill file if you have a score file for the same group, you can set this
-hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
-kill files to be processed, you should set this variable to @code{nil}.
+The limitations are that the @code{frame} split can only appear as the
+top-level split. @var{form} should be an Emacs Lisp form that should
+return a valid split. We see that each split is fully recursive, and
+may contain any number of @code{vertical} and @code{horizontal} splits.
-@item gnus-kill-file-mode-hook
-@vindex gnus-kill-file-mode-hook
-A hook called in kill-file mode buffers.
+@vindex gnus-window-min-width
+@vindex gnus-window-min-height
+@cindex window height
+@cindex window width
+Finding the right sizes can be a bit complicated. No window may be less
+than @code{gnus-window-min-height} (default 1) characters high, and all
+windows must be at least @code{gnus-window-min-width} (default 1)
+characters wide. Gnus will try to enforce this before applying the
+splits. If you want to use the normal Emacs window width/height limit,
+you can just set these two variables to @code{nil}.
-@end table
+If you're not familiar with Emacs terminology, @code{horizontal} and
+@code{vertical} splits may work the opposite way of what you'd expect.
+Windows inside a @code{horizontal} split are shown side-by-side, and
+windows within a @code{vertical} split are shown above each other.
+@findex gnus-configure-frame
+If you want to experiment with window placement, a good tip is to call
+@code{gnus-configure-frame} directly with a split. This is the function
+that does all the real work when splitting buffers. Below is a pretty
+nonsensical configuration with 5 windows; two for the group buffer and
+three for the article buffer. (I said it was nonsensical.) If you
+@code{eval} the statement below, you can get an idea of how that would
+look straight away, without going through the normal Gnus channels.
+Play with it until you're satisfied, and then use
+@code{gnus-add-configuration} to add your new creation to the buffer
+configuration list.
-@node GroupLens
-@section GroupLens
-@cindex GroupLens
+@lisp
+(gnus-configure-frame
+ '(horizontal 1.0
+ (vertical 10
+ (group 1.0)
+ (article 0.3 point))
+ (vertical 1.0
+ (article 1.0)
+ (horizontal 4
+ (group 1.0)
+ (article 10)))))
+@end lisp
-GroupLens is a collaborative filtering system that helps you work
-together with other people to find the quality news articles out of the
-huge volume of news articles generated every day.
+You might want to have several frames as well. No prob---just use the
+@code{frame} split:
-To accomplish this the GroupLens system combines your opinions about
-articles you have already read with the opinions of others who have done
-likewise and gives you a personalized prediction for each unread news
-article. Think of GroupLens as a matchmaker. GroupLens watches how you
-rate articles, and finds other people that rate articles the same way.
-Once it has found for you some people you agree with it tells you, in
-the form of a prediction, what they thought of the article. You can use
-this prediction to help you decide whether or not you want to read the
-article.
+@lisp
+(gnus-configure-frame
+ '(frame 1.0
+ (vertical 1.0
+ (summary 0.25 point)
+ (article 1.0))
+ (vertical ((height . 5) (width . 15)
+ (user-position . t)
+ (left . -1) (top . 1))
+ (picon 1.0))))
-@menu
-* Using GroupLens:: How to make Gnus use GroupLens.
-* Rating Articles:: Letting GroupLens know how you rate articles.
-* Displaying Predictions:: Displaying predictions given by GroupLens.
-* GroupLens Variables:: Customizing GroupLens.
-@end menu
+@end lisp
+This split will result in the familiar summary/article window
+configuration in the first (or ``main'') frame, while a small additional
+frame will be created where picons will be shown. As you can see,
+instead of the normal @code{1.0} top-level spec, each additional split
+should have a frame parameter alist as the size spec.
+@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp
+Reference Manual}.
-@node Using GroupLens
-@subsection Using GroupLens
+Here's a list of all possible keys for
+@code{gnus-buffer-configuration}:
-To use GroupLens you must register a pseudonym with your local Better
-Bit Bureau (BBB). At the moment the only better bit in town is at
-@samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html}.
+@code{group}, @code{summary}, @code{article}, @code{server},
+@code{browse}, @code{message}, @code{pick}, @code{info},
+@code{summary-faq}, @code{edit-group}, @code{edit-server},
+@code{edit-score}, @code{post}, @code{reply}, @code{forward},
+@code{reply-yank}, @code{mail-bounce}, @code{draft},
+@code{pipe}, @code{bug}, @code{compose-bounce}.
-Once you have registered you'll need to set a couple of variables.
+Note that the @code{message} key is used for both
+@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If
+it is desirable to distinguish between the two, something like this
+might be used:
-@table @code
+@lisp
+(message (horizontal 1.0
+ (vertical 1.0 (message 1.0 point))
+ (vertical 0.24
+ (if (buffer-live-p gnus-summary-buffer)
+ '(summary 0.5))
+ (group 1.0)))))
+@end lisp
-@item gnus-use-grouplens
-@vindex gnus-use-grouplens
-Setting this variable to a non-@code{nil} value will make Gnus hook into
-all the relevant GroupLens functions.
+@findex gnus-add-configuration
+Since the @code{gnus-buffer-configuration} variable is so long and
+complicated, there's a function you can use to ease changing the config
+of a single setting: @code{gnus-add-configuration}. If, for instance,
+you want to change the @code{article} setting, you could say:
-@item grouplens-pseudonym
-@vindex grouplens-pseudonym
-This variable should be set to the pseudonum you got when registering
-with the Better Bit Bureau.
+@lisp
+(gnus-add-configuration
+ '(article (vertical 1.0
+ (group 4)
+ (summary .25 point)
+ (article 1.0))))
+@end lisp
-@item grouplens-newsgroups
-@vindex grouplens-newsgroups
-A list of groups that you want to get GroupLens predictions for.
+You'd typically stick these @code{gnus-add-configuration} calls in your
+@file{.gnus.el} file or in some startup hook---they should be run after
+Gnus has been loaded.
-@end table
+@vindex gnus-always-force-window-configuration
+If all windows mentioned in the configuration are already visible, Gnus
+won't change the window configuration. If you always want to force the
+``right'' window configuration, you can set
+@code{gnus-always-force-window-configuration} to non-@code{nil}.
-Thats the minimum of what you need to get up and running with GroupLens.
-Once you've registered, GroupLens will start giving you scores for
-articles based on the average of what other people think. But, to get
-the real benefit of GroupLens you need to start rating articles
-yourself. Then the scores GroupLens gives you will be personalized for
-you, based on how the people you usually agree with have already rated.
+@node Compilation
+@section Compilation
+@cindex compilation
+@cindex byte-compilation
-@node Rating Articles
-@subsection Rating Articles
+@findex gnus-compile
-In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
-Where 1 means something like this article is a waste of bandwidth and 5
-means that the article was really good. The basic question to ask
-yourself is, "on a scale from 1 to 5 would I like to see more articles
-like this one?"
+Remember all those line format specification variables?
+@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
+on. Now, Gnus will of course heed whatever these variables are, but,
+unfortunately, changing them will mean a quite significant slow-down.
+(The default values of these variables have byte-compiled functions
+associated with them, while the user-generated versions do not, of
+course.)
-There are four ways to enter a rating for an article in GroupLens.
+To help with this, you can run @kbd{M-x gnus-compile} after you've
+fiddled around with the variables and feel that you're (kind of)
+satisfied. This will result in the new specs being byte-compiled, and
+you'll get top speed again. Gnus will save these compiled specs in the
+@file{.newsrc.eld} file. (User-defined functions aren't compiled by
+this function, though---you should compile them yourself by sticking
+them into the @code{.gnus.el} file and byte-compiling that file.)
-@table @kbd
-@item r
-@kindex r (GroupLens)
-@findex bbb-summary-rate-article
-This function will prompt you for a rating on a scale of one to five.
+@node Mode Lines
+@section Mode Lines
+@cindex mode lines
-@item k
-@kindex k (GroupLens)
-@findex grouplens-score-thread
-This function will prompt you for a rating, and rate all the articles in
-the thread. This is really useful for some of those long running giant
-threads in rec.humor.
+@vindex gnus-updated-mode-lines
+@code{gnus-updated-mode-lines} says what buffers should keep their mode
+lines updated. It is a list of symbols. Supported symbols include
+@code{group}, @code{article}, @code{summary}, @code{server},
+@code{browse}, and @code{tree}. If the corresponding symbol is present,
+Gnus will keep that mode line updated with information that may be
+pertinent. If this variable is @code{nil}, screen refresh may be
+quicker.
-@end table
+@cindex display-time
-The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
-the score of the article you're reading.
+@vindex gnus-mode-non-string-length
+By default, Gnus displays information on the current article in the mode
+lines of the summary and article buffers. The information Gnus wishes
+to display (e.g. the subject of the article) is often longer than the
+mode lines, and therefore have to be cut off at some point. The
+@code{gnus-mode-non-string-length} variable says how long the other
+elements on the line is (i.e., the non-info part). If you put
+additional elements on the mode line (e.g. a clock), you should modify
+this variable:
-@table @kbd
+@c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
+@lisp
+(add-hook 'display-time-hook
+ (lambda () (setq gnus-mode-non-string-length
+ (+ 21
+ (if line-number-mode 5 0)
+ (if column-number-mode 4 0)
+ (length display-time-string)))))
+@end lisp
-@item 1-5 n
-@kindex n (GroupLens)
-@findex grouplens-next-unread-article
-Rate the article and go to the next unread article.
+If this variable is @code{nil} (which is the default), the mode line
+strings won't be chopped off, and they won't be padded either.
-@item 1-5 ,
-@kindex , (GroupLens)
-@findex grouplens-best-unread-article
-Rate the article and go to the next unread article with the highest score.
-@end table
+@node Highlighting and Menus
+@section Highlighting and Menus
+@cindex visual
+@cindex highlighting
+@cindex menus
-If you want to give the current article a score of 4 and then go to the
-next article, just type @kbd{4 n}.
+@vindex gnus-visual
+The @code{gnus-visual} variable controls most of the prettifying Gnus
+aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
+colors or fonts. This will also inhibit loading the @file{gnus-vis.el}
+file.
+This variable can be a list of visual properties that are enabled. The
+following elements are legal, and are all included by default:
-@node Displaying Predictions
-@subsection Displaying Predictions
+@table @code
+@item group-highlight
+Do highlights in the group buffer.
+@item summary-highlight
+Do highlights in the summary buffer.
+@item article-highlight
+Do highlights 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 buffers.
+@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 score-menu
+Create menus in the score buffers.
+@item menu
+Create menus in all buffers.
+@end table
-GroupLens makes a prediction for you about how much you will like a
-news article. The predictions from GroupLens are on a scale from 1 to
-5, where 1 is the worst and 5 is the best. You can use the predictions
-from GroupLens in one of three ways controlled by the variable
-@code{gnus-grouplens-override-scoring}.
+So if you only want highlighting in the article buffer and menus in all
+buffers, you could say something like:
+
+@lisp
+(setq gnus-visual '(article-highlight menu))
+@end lisp
-@vindex gnus-grouplens-override-scoring
-There are three ways to display predictions in grouplens. You may
-choose to have the GroupLens scores contribute to, or override the
-regular gnus scoring mechanism. override is the default; however, some
-people prefer to see the Gnus scores plus the grouplens scores. To get
-the separate scoring behavior you need to set
-@code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
-GroupLens predictions combined with the grouplens scores set it to
-@code{'override} and to combine the scores set
-@code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
-the combine option you will also want to set the values for
-@code{grouplens-prediction-offset} and
-@code{grouplens-score-scale-factor}.
+If you want only highlighting and no menus whatsoever, you'd say:
-@vindex grouplens-prediction-display
-In either case, GroupLens gives you a few choices for how you would like
-to see your predictions displayed. The display of predictions is
-controlled by the @code{grouplens-prediction-display} variable.
+@lisp
+(setq gnus-visual '(highlight))
+@end lisp
-The following are legal values for that variable.
+If @code{gnus-visual} is @code{t}, highlighting and menus will be used
+in all Gnus buffers.
+
+Other general variables that influence the look of all buffers include:
@table @code
-@item prediction-spot
-The higher the prediction, the further to the right an @samp{*} is
-displayed.
+@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 confidence-interval
-A numeric confidence interval.
+@item gnus-display-type
+@vindex gnus-display-type
+This variable is symbol indicating the display type 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 prediction-bar
-The higher the prediction, the longer the bar.
+@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'.
+@end table
-@item confidence-bar
-Numerical confidence.
+There are hooks associated with the creation of all the different menus:
-@item confidence-spot
-The spot gets bigger with more confidence.
+@table @code
-@item prediction-num
-Plain-old numeric value.
+@item gnus-article-menu-hook
+@vindex gnus-article-menu-hook
+Hook called after creating the article mode menu.
-@item confidence-plus-minus
-Prediction +/i confidence.
+@item gnus-group-menu-hook
+@vindex gnus-group-menu-hook
+Hook called after creating the group mode menu.
-@end table
+@item gnus-summary-menu-hook
+@vindex gnus-summary-menu-hook
+Hook called after creating the summary mode menu.
+@item gnus-server-menu-hook
+@vindex gnus-server-menu-hook
+Hook called after creating the server mode menu.
-@node GroupLens Variables
-@subsection GroupLens Variables
+@item gnus-browse-menu-hook
+@vindex gnus-browse-menu-hook
+Hook called after creating the browse mode menu.
-@table @code
+@item gnus-score-menu-hook
+@vindex gnus-score-menu-hook
+Hook called after creating the score mode menu.
-@item gnus-summary-grouplens-line-format
-The summary line format used in summary buffers that are GroupLens
-enhanced. It accepts the same specs as the normal summary line format
-(@pxref{ Summary Buffer Lines}). The default is
-@samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%) %s\n}.
+@end table
-@item grouplens-bbb-host
-Host running the bbbd server. The default is
-@samp{grouplens.cs.umn.edu}.
-@item grouplens-bbb-port
-Port of the host running the bbbd server. The default is 9000.
+@node Buttons
+@section Buttons
+@cindex buttons
+@cindex mouse
+@cindex click
-@item grouplens-score-offset
-Offset the prediction by this value. In other words, subtract the
-prediction value by this number to arrive at the effective score. The
-default is 0.
+Those new-fangled @dfn{mouse} contraptions is very popular with the
+young, hep kids who don't want to learn the proper way to do things
+these days. Why, I remember way back in the summer of '89, when I was
+using Emacs on a Tops 20 system. Three hundred users on one single
+machine, and every user was running Simula compilers. Bah!
-@item grouplens-score-scale-factor
-This variable allows the user to magnify the effect of GroupLens scores.
-The scale factor is applied after the offset. The default is 1.
+Right.
-@end table
+@vindex gnus-carpal
+Well, you can make Gnus display bufferfuls of buttons you can click to
+do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
+really. Tell the chiropractor I sent you.
+@table @code
-@node Various
-@chapter Various
+@item gnus-carpal-mode-hook
+@vindex gnus-carpal-mode-hook
+Hook run in all carpal mode buffers.
-@menu
-* Process/Prefix:: A convention used by many treatment commands.
-* Interactive:: Making Gnus ask you many questions.
-* Formatting Variables:: You can specify what buffers should look like.
-* Windows Configuration:: Configuring the Gnus buffer windows.
-* Compilation:: How to speed Gnus up.
-* Mode Lines:: Displaying information in the mode lines.
-* Highlighting and Menus:: Making buffers look all nice and cozy.
-* Buttons:: Get tendonitis in ten easy steps!
-* Daemons:: Gnus can do things behind your back.
-* NoCeM:: How to avoid spam and other fatty foods.
-* Picons:: How to display pictures of what your reading.
-* Various Various:: Things that are really various.
-@end menu
+@item gnus-carpal-button-face
+@vindex gnus-carpal-button-face
+Face used on buttons.
+@item gnus-carpal-header-face
+@vindex gnus-carpal-header-face
+Face used on carpal buffer headers.
-@node Process/Prefix
-@section Process/Prefix
-@cindex process/prefix convention
+@item gnus-carpal-group-buffer-buttons
+@vindex gnus-carpal-group-buffer-buttons
+Buttons in the group buffer.
-Many functions, among them functions for moving, decoding and saving
-articles, use what is known as the @dfn{Process/Prefix convention}.
+@item gnus-carpal-summary-buffer-buttons
+@vindex gnus-carpal-summary-buffer-buttons
+Buttons in the summary buffer.
-This is a method for figuring out what articles that the user wants the
-command to be performed on.
+@item gnus-carpal-server-buffer-buttons
+@vindex gnus-carpal-server-buffer-buttons
+Buttons in the server buffer.
-It goes like this:
+@item gnus-carpal-browse-buffer-buttons
+@vindex gnus-carpal-browse-buffer-buttons
+Buttons in the browse buffer.
+@end table
-If the numeric prefix is N, perform the operation on the next N
-articles, starting with the current one. If the numeric prefix is
-negative, perform the operation on the previous N articles, starting
-with the current one.
+All the @code{buttons} variables are lists. The elements in these list
+is either a cons cell where the car contains a text to be displayed and
+the cdr contains a function symbol, or a simple string.
-@vindex transient-mark-mode
-If @code{transient-mark-mode} in non-@code{nil} and the region is
-active, all articles in the region will be worked upon.
-If there is no numeric prefix, but some articles are marked with the
-process mark, perform the operation on the articles that are marked with
-the process mark.
+@node Daemons
+@section Daemons
+@cindex demons
+@cindex daemons
-If there is neither a numeric prefix nor any articles marked with the
-process mark, just perform the operation on the current article.
+Gnus, being larger than any program ever written (allegedly), does lots
+of strange stuff that you may wish to have done while you're not
+present. For instance, you may want it to check for new mail once in a
+while. Or you may want it to close down all connections to all servers
+when you leave Emacs idle. And stuff like that.
-Quite simple, really, but it needs to be made clear so that surprises
-are avoided.
+Gnus will let you do stuff like that by defining various
+@dfn{handlers}. Each handler consists of three elements: A
+@var{function}, a @var{time}, and an @var{idle} parameter.
-@vindex gnus-summary-goto-unread
-One thing that seems to shock & horrify lots of people is that, for
-instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
-Since each @kbd{d} (which marks the current article as read) by default
-goes to the next unread article after marking, this means that @kbd{3 d}
-will mark the next three unread articles as read, no matter what the
-summary buffer looks like. Set @code{gnus-summary-goto-unread} to
-@code{nil} for a more straightforward action.
+Here's an example of a handler that closes connections when Emacs has
+been idle for thirty minutes:
+@lisp
+(gnus-demon-close-connections nil 30)
+@end lisp
-@node Interactive
-@section Interactive
-@cindex interaction
+Here's a handler that scans for PGP headers every hour when Emacs is
+idle:
-@table @code
+@lisp
+(gnus-demon-scan-pgp 60 t)
+@end lisp
-@item gnus-novice-user
-@vindex gnus-novice-user
-If this variable is non-@code{nil}, you are either a newcomer to the
-World of Usenet, or you are very cautious, which is a nice thing to be,
-really. You will be given questions of the type ``Are you sure you want
-to do this?'' before doing anything dangerous. This is @code{t} by
-default.
+This @var{time} parameter and than @var{idle} parameter works together
+in a strange, but wonderful fashion. Basically, if @var{idle} is
+@code{nil}, then the function will be called every @var{time} minutes.
-@item gnus-expert-user
-@vindex gnus-expert-user
-If this variable is non-@code{nil}, you will never ever be asked any
-questions by Gnus. It will simply assume you know what you're doing, no
-matter how strange.
+If @var{idle} is @code{t}, then the function will be called after
+@var{time} minutes only if Emacs is idle. So if Emacs is never idle,
+the function will never be called. But once Emacs goes idle, the
+function will be called every @var{time} minutes.
-@item gnus-interactive-catchup
-@vindex gnus-interactive-catchup
-Require confirmation before catching up a group if non-@code{nil}. It
-is @code{t} by default.
+If @var{idle} is a number and @var{time} is a number, the function will
+be called every @var{time} minutes only when Emacs has been idle for
+@var{idle} minutes.
-@item gnus-interactive-post
-@vindex gnus-interactive-post
-If non-@code{nil}, the user will be prompted for a group name when
-posting an article. It is @code{t} by default.
+If @var{idle} is a number and @var{time} is @code{nil}, the function
+will be called once every time Emacs has been idle for @var{idle}
+minutes.
-@item gnus-interactive-exit
-@vindex gnus-interactive-exit
-Require confirmation before exiting Gnus. This variable is @code{t} by
-default.
-@end table
+And if @var{time} is a string, it should look like @samp{07:31}, and
+the function will then be called once every day somewhere near that
+time. Modified by the @var{idle} parameter, of course.
+@vindex gnus-demon-timestep
+(When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
+seconds. This is 60 by default. If you change that variable,
+all the timings in the handlers will be affected.)
-@node Formatting Variables
-@section Formatting Variables
-@cindex formatting variables
+@vindex gnus-use-demon
+To set the whole thing in motion, though, you have to set
+@code{gnus-use-demon} to @code{t}.
-Throughout this manual you've probably noticed lots of variables that
-are called things like @code{gnus-group-line-format} and
-@code{gnus-summary-mode-line-format}. These control how Gnus is to
-output lines in the various buffers. There's quite a lot of them.
-Fortunately, they all use the same syntax, so there's not that much to
-be annoyed by.
+So, if you want to add a handler, you could put something like this in
+your @file{.gnus} file:
-Here's an example format spec (from the group buffer): @samp{%M%S%5y:
-%(%g%)\n}. We see that it is indeed extremely ugly, and that there are
-lots of percentages everywhere.
+@findex gnus-demon-add-handler
+@lisp
+(gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
+@end lisp
-Each @samp{%} element will be replaced by some string or other when the
-buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
-spec, and pad with spaces to get a 5-character field''. Just like a
-normal format spec, almost.
+@findex gnus-demon-add-nocem
+@findex gnus-demon-add-scanmail
+@findex gnus-demon-add-rescan
+@findex gnus-demon-add-disconnection
+Some ready-made functions to do this has been created:
+@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection},
+@code{gnus-demon-add-rescan}, and @code{gnus-demon-add-scanmail}. Just
+put those functions in your @file{.gnus} if you want those abilities.
-You can also say @samp{%6,4y}, which means that the field will never be
-more than 6 characters wide and never less than 4 characters wide.
+@findex gnus-demon-init
+@findex gnus-demon-cancel
+@vindex gnus-demon-handlers
+If you add handlers to @code{gnus-demon-handlers} directly, you should
+run @code{gnus-demon-init} to make the changes take hold. To cancel all
+daemons, you can use the @code{gnus-demon-cancel} function.
-There are also specs for highlighting, and these are shared by all the
-format variables. Text inside the @samp{%(} and @samp{%)} specifiers
-will get the special @code{mouse-face} property set, which means that it
-will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
-pointer over it.
+Note that adding daemons can be pretty naughty if you overdo it. Adding
+functions that scan all news and mail from all servers every two seconds
+is a sure-fire way of getting booted off any respectable system. So
+behave.
-Text inside the @samp{%[} and @samp{%]} specifiers will have their
-normal faces set using @code{gnus-face-0}, which is @code{bold} by
-default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
-instead, and so on. Create as many faces as you wish. The same goes
-for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
-@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
-Here's an alternative recipe for the group buffer:
+@node NoCeM
+@section NoCeM
+@cindex nocem
+@cindex spam
-@lisp
-;; Create three face types.
-(setq gnus-face-1 'bold)
-(setq gnus-face-3 'italic)
+@dfn{Spamming} is posting the same article lots and lots of times.
+Spamming is bad. Spamming is evil.
-;; We want the article count to be in
-;; a bold and green face. So we create
-;; a new face called `my-green-bold'.
-(copy-face 'bold 'my-green-bold)
-;; Set the color.
-(set-face-foreground 'my-green-bold "ForestGreen")
-(setq gnus-face-2 'my-green-bold)
+Spamming is usually canceled within a day or so by various anti-spamming
+agencies. These agencies usually also send out @dfn{NoCeM} messages.
+NoCeM is pronounced ``no see-'em'', and means what the name
+implies---these are messages that make the offending articles, like, go
+away.
-;; Set the new & fancy format.
-(setq gnus-group-line-format
- "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
-@end lisp
+What use are these NoCeM messages if the articles are canceled anyway?
+Some sites do not honor cancel messages and some sites just honor cancels
+from a select few people. Then you may wish to make use of the NoCeM
+messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
-I'm sure you'll be able to use this scheme to create totally unreadable
-and extremely vulgar displays. Have fun!
+Gnus can read and parse the messages in this group automatically, and
+this will make spam disappear.
-Currently Gnus uses the following formatting variables:
-@code{gnus-group-line-format}, @code{gnus-summary-line-format},
-@code{gnus-server-line-format}, @code{gnus-topic-line-format},
-@code{gnus-group-mode-line-format},
-@code{gnus-summary-mode-line-format},
-@code{gnus-article-mode-line-format},
-@code{gnus-server-mode-line-format}.
+There are some variables to customize, of course:
-Note that the @samp{%(} specs (and friends) do not make any sense on the
-mode-line variables.
+@table @code
+@item gnus-use-nocem
+@vindex gnus-use-nocem
+Set this variable to @code{t} to set the ball rolling. It is @code{nil}
+by default.
-All these format variables can also be arbitrary elisp forms. In that
-case, they will be @code{eval}ed to insert the required lines.
+@item gnus-nocem-groups
+@vindex gnus-nocem-groups
+Gnus will look for NoCeM messages in the groups in this list. The
+default is @code{("alt.nocem.misc" "news.admin.net-abuse.announce")}.
-@kindex M-x gnus-update-format
-@findex gnus-update-format
-Gnus includes a command to help you while creating your own format
-specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
-update the spec in question and pop you to a buffer where you can
-examine the resulting lisp code to be run to generate the line.
+@item gnus-nocem-issuers
+@vindex gnus-nocem-issuers
+There are many people issuing NoCeM messages. This list says what
+people you want to listen to. The default is @code{("Automoose-1"
+"clewis@@ferret.ocunix.on.ca;" "jem@@xpat.com;" "red@@redpoll.mrfs.oh.us
+(Richard E. Depew)")}; fine, upstanding citizens all of them.
+Known despammers that you can put in this list include:
-@node Windows Configuration
-@section Windows Configuration
-@cindex windows configuration
+@table @samp
+@item clewis@@ferret.ocunix.on.ca;
+@cindex Chris Lewis
+Chris Lewis---Major Canadian despammer who has probably canceled more
+usenet abuse than anybody else.
-No, there's nothing here about X, so be quiet.
+@item Automoose-1
+@cindex CancelMoose[tm]
+The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be
+Norwegian, and was the person(s) who invented NoCeM.
-@vindex gnus-use-full-window
-If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
-other windows and occupy the entire Emacs screen by itself. It is
-@code{t} by default.
+@item jem@@xpat.com;
+@cindex Jem
+John Milburn---despammer located in Korea who is getting very busy these
+days.
-@vindex gnus-buffer-configuration
-@code{gnus-buffer-configuration} describes how much space each Gnus
-buffer should be given. Here's an excerpt of this variable:
+@item red@@redpoll.mrfs.oh.us (Richard E. Depew)
+Richard E. Depew---lone American despammer. He mostly cancels binary
+postings to non-binary groups and removes spews (regurgitated articles).
+@end table
-@lisp
-((group (vertical 1.0 (group 1.0 point)
- (if gnus-carpal (group-carpal 4))))
- (article (vertical 1.0 (summary 0.25 point)
- (article 1.0))))
-@end lisp
+You do not have to heed NoCeM messages from all these people---just the
+ones you want to listen to.
-This is an alist. The @dfn{key} is a symbol that names some action or
-other. For instance, when displaying the group buffer, the window
-configuration function will use @code{group} as the key. A full list of
-possible names is listed below.
+@item gnus-nocem-directory
+@vindex gnus-nocem-directory
+This is where Gnus will store its NoCeM cache files. The default is
+@file{~/News/NoCeM/}.
-The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
-should occupy. To take the @code{article} split as an example -
+@item gnus-nocem-expiry-wait
+@vindex gnus-nocem-expiry-wait
+The number of days before removing old NoCeM entries from the cache.
+The default is 15. If you make it shorter Gnus will be faster, but you
+might then see old spam.
-@lisp
-(article (vertical 1.0 (summary 0.25 point)
- (article 1.0)))
-@end lisp
+@end table
-This @dfn{split} says that the summary buffer should occupy 25% of upper
-half of the screen, and that it is placed over the article buffer. As
-you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
-reaching for that calculator there). However, the special number
-@code{1.0} is used to signal that this buffer should soak up all the
-rest of the space available after the rest of the buffers have taken
-whatever they need. There should be only one buffer with the @code{1.0}
-size spec per split.
-Point will be put in the buffer that has the optional third element
-@code{point}.
+@node Picons
+@section Picons
-Here's a more complicated example:
+So... You want to slow down your news reader even more! This is a
+good way to do so. Its also a great way to impress people staring
+over your shoulder as you read news.
-@lisp
-(article (vertical 1.0 (group 4)
- (summary 0.25 point)
- (if gnus-carpal (summary-carpal 4))
- (article 1.0)))
-@end lisp
+@menu
+* Picon Basics:: What are picons and How do I get them.
+* Picon Requirements:: Don't go further if you aren't using XEmacs.
+* Easy Picons:: Displaying Picons---the easy way.
+* Hard Picons:: The way you should do it. You'll learn something.
+* Picon Configuration:: Other variables you can trash/tweak/munge/play with.
+@end menu
-If the size spec is an integer instead of a floating point number,
-then that number will be used to say how many lines a buffer should
-occupy, not a percentage.
-If the @dfn{split} looks like something that can be @code{eval}ed (to be
-precise---if the @code{car} of the split is a function or a subr), this
-split will be @code{eval}ed. If the result is non-@code{nil}, it will
-be used as a split. This means that there will be three buffers if
-@code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
-is non-@code{nil}.
+@node Picon Basics
+@subsection Picon Basics
-Not complicated enough for you? Well, try this on for size:
+What are Picons? To quote directly from the Picons Web site:
-@lisp
-(article (horizontal 1.0
- (vertical 0.5
- (group 1.0)
- (gnus-carpal 4))
- (vertical 1.0
- (summary 0.25 point)
- (summary-carpal 4)
- (article 1.0))))
-@end lisp
+@quotation
+@dfn{Picons} is short for ``personal icons''. They're small,
+constrained images used to represent users and domains on the net,
+organized into databases so that the appropriate image for a given
+e-mail address can be found. Besides users and domains, there are picon
+databases for Usenet newsgroups and weather forecasts. The picons are
+in either monochrome @code{XBM} format or color @code{XPM} and
+@code{GIF} formats.
+@end quotation
-Whoops. Two buffers with the mystery 100% tag. And what's that
-@code{horizontal} thingie?
+For instructions on obtaining and installing the picons databases, point
+your Web browser at
+@file{http://www.cs.indiana.edu/picons/ftp/index.html}.
-If the first element in one of the split is @code{horizontal}, Gnus will
-split the window horizontally, giving you two windows side-by-side.
-Inside each of these strips you may carry on all you like in the normal
-fashion. The number following @code{horizontal} says what percentage of
-the screen is to be given to this strip.
+@vindex gnus-picons-database
+Gnus expects picons to be installed into a location pointed to by
+@code{gnus-picons-database}.
-For each split, there @emph{must} be one element that has the 100% tag.
-The splitting is never accurate, and this buffer will eat any leftover
-lines from the splits.
-To be slightly more formal, here's a definition of what a legal split
-may look like:
+@node Picon Requirements
+@subsection Picon Requirements
-@example
-split = frame | horizontal | vertical | buffer | form
-frame = "(frame " size *split ")"
-horizontal = "(horizontal " size *split ")"
-vertical = "(vertical " size *split ")"
-buffer = "(" buffer-name " " size *[ "point" ] ")"
-size = number | frame-params
-buffer-name = group | article | summary ...
-@end example
+To use have Gnus display Picons for you, you must be running XEmacs
+19.13 or greater since all other versions of Emacs aren't yet able to
+display images.
-The limitations are that the @code{frame} split can only appear as the
-top-level split. @var{form} should be an Emacs Lisp form that should
-return a valid split. We see that each split is fully recursive, and
-may contain any number of @code{vertical} and @code{horizontal} splits.
+Additionally, you must have @code{xpm} support compiled into XEmacs.
-@vindex gnus-window-min-width
-@vindex gnus-window-min-height
-@cindex window height
-@cindex window width
-Finding the right sizes can be a bit complicated. No window may be less
-than @code{gnus-window-min-height} (default 2) characters high, and all
-windows must be at least @code{gnus-window-min-width} (default 1)
-characters wide. Gnus will try to enforce this before applying the
-splits. If you want to use the normal Emacs window width/height limit,
-you can just set these two variables to @code{nil}.
+@vindex gnus-picons-convert-x-face
+If you want to display faces from @code{X-Face} headers, you must have
+the @code{netpbm} utilities installed, or munge the
+@code{gnus-picons-convert-x-face} variable to use something else.
-If you're not familiar with Emacs terminology, @code{horizontal} and
-@code{vertical} splits may work the opposite way of what you'd expect.
-Windows inside a @code{horizontal} split are shown side-by-side, and
-windows within a @code{vertical} split are shown above each other.
-@findex gnus-configure-frame
-If you want to experiment with window placement, a good tip is to call
-@code{gnus-configure-frame} directly with a split. This is the function
-that does all the real work when splitting buffers. Below is a pretty
-nonsensical configuration with 5 windows; two for the group buffer and
-three for the article buffer. (I said it was nonsensical.) If you
-@code{eval} the statement below, you can get an idea of how that would
-look straight away, without going through the normal Gnus channels.
-Play with it until you're satisfied, and then use
-@code{gnus-add-configuration} to add your new creation to the buffer
-configuration list.
+@node Easy Picons
+@subsection Easy Picons
+
+To enable displaying picons, simply put the following line in your
+@file{~/.gnus} file and start Gnus.
@lisp
-(gnus-configure-frame
- '(horizontal 1.0
- (vertical 10
- (group 1.0)
- (article 0.3 point))
- (vertical 1.0
- (article 1.0)
- (horizontal 4
- (group 1.0)
- (article 10)))))
+(setq gnus-use-picons t)
+(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
+(add-hook 'gnus-summary-prepare-hook 'gnus-group-display-picons t)
+(add-hook 'gnus-article-display-hook 'gnus-picons-article-display-x-face)
@end lisp
-You might want to have several frames as well. No prob---just use the
-@code{frame} split:
-@lisp
-(gnus-configure-frame
- '(frame 1.0
- (vertical 1.0
- (summary 0.25 point)
- (article 1.0))
- (vertical ((height . 5) (width . 15)
- (user-position . t)
- (left . -1) (top . 1))
- (picon 1.0))))
+@node Hard Picons
+@subsection Hard Picons
-@end lisp
+Gnus can display picons for you as you enter and leave groups and
+articles. It knows how to interact with three sections of the picons
+database. Namely, it can display the picons newsgroup pictures,
+author's face picture(s), and the authors domain. To enable this
+feature, you need to first decide where to display them.
-This split will result in the familiar summary/article window
-configuration in the first (or ``main'') frame, while a small additional
-frame will be created where picons will be shown. As you can see,
-instead of the normal @code{1.0} top-level spec, each additional split
-should have a frame parameter alist as the size spec.
-@xref{(elisp)Frame Parameters}.
+@table @code
-Here's a list of all possible keys for
-@code{gnus-buffer-configuration}:
+@item gnus-picons-display-where
+@vindex gnus-picons-display-where
+Where the picon images should be displayed. It is @code{picons} by
+default (which by default maps to the buffer @samp{*Picons*}). Other
+valid places could be @code{article}, @code{summary}, or
+@samp{*scratch*} for all I care. Just make sure that you've made the
+buffer visible using the standard Gnus window configuration
+routines---@pxref{Windows Configuration}.
-@code{group}, @code{summary}, @code{article}, @code{server},
-@code{browse}, @code{group-mail}, @code{summary-mail},
-@code{summary-reply}, @code{info}, @code{summary-faq},
-@code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
-@code{followup}, @code{followup-yank}, @code{edit-score}.
+@end table
-@findex gnus-add-configuration
-Since the @code{gnus-buffer-configuration} variable is so long and
-complicated, there's a function you can use to ease changing the config
-of a single setting: @code{gnus-add-configuration}. If, for instance,
-you want to change the @code{article} setting, you could say:
+Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
+window configuration for you to include the @code{picons} buffer.
+
+Now that you've made that decision, you need to add the following
+functions to the appropriate hooks so these pictures will get
+displayed at the right time.
+
+@vindex gnus-article-display-hook
+@vindex gnus-picons-display-where
+@table @code
+@item gnus-article-display-picons
+@findex gnus-article-display-picons
+Looks up and display the picons for the author and the author's domain
+in the @code{gnus-picons-display-where} buffer. Should be added to
+the @code{gnus-article-display-hook}.
+
+@item gnus-group-display-picons
+@findex gnus-article-display-picons
+Displays picons representing the current group. This function should
+be added to the @code{gnus-summary-prepare-hook} or to the
+@code{gnus-article-display-hook} if @code{gnus-picons-display-where}
+is set to @code{article}.
+
+@item gnus-picons-article-display-x-face
+@findex gnus-article-display-picons
+Decodes and displays the X-Face header if present. This function
+should be added to @code{gnus-article-display-hook}.
+
+@end table
+
+Note: You must append them to the hook, so make sure to specify 't'
+to the append flag of @code{add-hook}:
@lisp
-(gnus-add-configuration
- '(article (vertical 1.0
- (group 4)
- (summary .25 point)
- (article 1.0))))
+(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
@end lisp
-You'd typically stick these @code{gnus-add-configuration} calls in your
-@file{.gnus} file or in some startup hook -- they should be run after
-Gnus has been loaded.
+@node Picon Configuration
+@subsection Picon Configuration
-@node Compilation
-@section Compilation
-@cindex compilation
-@cindex byte-compilation
+The following variables offer further control over how things are
+done, where things are located, and other useless stuff you really
+don't need to worry about.
-@findex gnus-compile
+@table @code
+@item gnus-picons-database
+@vindex gnus-picons-database
+The location of the picons database. Should point to a directory
+containing the @file{news}, @file{domains}, @file{users} (and so on)
+subdirectories. Defaults to @file{/usr/local/faces}.
-Remember all those line format specification variables?
-@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
-on. Now, Gnus will of course heed whatever these variables are, but,
-unfortunately, changing them will mean a quite significant slow-down.
-(The default values of these variables have byte-compiled functions
-associated with them, while the user-generated versions do not, of
-course.)
+@item gnus-picons-news-directory
+@vindex gnus-picons-news-directory
+Sub-directory of the faces database containing the icons for
+newsgroups.
-To help with this, you can run @kbd{M-x gnus-compile} after you've
-fiddled around with the variables and feel that you're (kind of)
-satisfied. This will result in the new specs being byte-compiled, and
-you'll get top speed again.
+@item gnus-picons-user-directories
+@vindex gnus-picons-user-directories
+List of subdirectories to search in @code{gnus-picons-database} for user
+faces. @code{("local" "users" "usenix" "misc/MISC")} is the default.
+@item gnus-picons-domain-directories
+@vindex gnus-picons-domain-directories
+List of subdirectories to search in @code{gnus-picons-database} for
+domain name faces. Defaults to @code{("domains")}. Some people may
+want to add @samp{unknown} to this list.
-@node Mode Lines
-@section Mode Lines
-@cindex mode lines
+@item gnus-picons-convert-x-face
+@vindex gnus-picons-convert-x-face
+The command to use to convert the @code{X-Face} header to an X bitmap
+(@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
+Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
+gnus-picons-x-face-file-name)}
-@vindex gnus-updated-mode-lines
-@code{gnus-updated-mode-lines} says what buffers should keep their mode
-lines updated. It is a list of symbols. Supported symbols include
-@code{group}, @code{article}, @code{summary}, @code{server},
-@code{browse}, and @code{tree}. If the corresponding symbol is present,
-Gnus will keep that mode line updated with information that may be
-pertinent. If this variable is @code{nil}, screen refresh may be
-quicker.
+@item gnus-picons-x-face-file-name
+@vindex gnus-picons-x-face-file-name
+Names a temporary file to store the @code{X-Face} bitmap in. Defaults
+to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
-@cindex display-time
+@item gnus-picons-buffer
+@vindex gnus-picons-buffer
+The name of the buffer that @code{picons} points to. Defaults to
+@samp{*Icon Buffer*}.
-@vindex gnus-mode-non-string-length
-By default, Gnus displays information on the current article in the mode
-lines of the summary and article buffers. The information Gnus wishes
-to display (eg. the subject of the article) is often longer than the
-mode lines, and therefore have to be cut off at some point. The
-@code{gnus-mode-non-string-length} variable says how long the other
-elements on the line is (i.e., the non-info part). If you put
-additional elements on the mode line (eg. a clock), you should modify
-this variable:
+@end table
-@c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
-@lisp
-(add-hook 'display-time-hook
- (lambda () (setq gnus-mode-non-string-length
- (+ 21
- (if line-number-mode 5 0)
- (if column-number-mode 4 0)
- (length display-time-string)))))
-@end lisp
-If this variable is @code{nil} (which is the default), the mode line
-strings won't be chopped off, and they won't be padded either.
+@node Undo
+@section Undo
+@cindex undo
+It is very useful to be able to undo actions one has done. In normal
+Emacs buffers, it's easy enough---you just push the @code{undo} button.
+In Gnus buffers, however, it isn't that simple.
-@node Highlighting and Menus
-@section Highlighting and Menus
-@cindex visual
-@cindex highlighting
-@cindex menus
+The things Gnus displays in its buffer is of no value whatsoever to
+Gnus---it's all just data that is designed to look nice to the user.
+Killing a group in the group buffer with @kbd{C-k} makes the line
+disappear, but that's just a side-effect of the real action---the
+removal of the group in question from the internal Gnus structures.
+Undoing something like that can't be done by the normal Emacs
+@code{undo} function.
-@vindex gnus-visual
-The @code{gnus-visual} variable controls most of the prettifying Gnus
-aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
-colors or fonts. This will also inhibit loading the @file{gnus-vis.el}
-file.
+Gnus tries to remedy this somewhat by keeping track of what the user
+does and coming up with actions that would reverse the actions the user
+takes. When the user then presses the @code{undo} key, Gnus will run
+the code to reverse the previous action, or the previous actions.
+However, not all actions are easily reversible, so Gnus currently offers
+a few key functions to be undoable. These include killing groups,
+yanking groups, and changing the list of read articles of groups.
+That's it, really. More functions may be added in the future, but each
+added function means an increase in data to be stored, so Gnus will
+never be totally undoable.
-This variable can be a list of visual properties that are enabled. The
-following elements are legal, and are all included by default:
+@findex gnus-undo-mode
+@vindex gnus-use-undo
+@findex gnus-undo
+The undoability is provided by the @code{gnus-undo-mode} minor mode. It
+is used if @code{gnus-use-undo} is non-@code{nil}, which is the
+default. The @kbd{M-C-_} key performs the @code{gnus-undo} command
+command, which should feel kinda like the normal Emacs @code{undo}
+command.
-@table @code
-@item group-highlight
-Do highlights in the group buffer.
-@item summary-highlight
-Do highlights in the summary buffer.
-@item article-highlight
-Do highlights 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 buffers.
-@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 score-menu
-Create menus in the score buffers.
-@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 could say something like:
+@node Moderation
+@section Moderation
+@cindex moderation
+
+If you are a moderator, you can use the @file{gnus-mdrtn.el} package.
+It is not included in the standard Gnus package. Write a mail to
+@samp{larsi@@ifi.uio.no} and state what group you moderate, and you'll
+get a copy.
+
+The moderation package is implemented as a minor mode for summary
+buffers. Put
@lisp
-(setq gnus-visual '(article-highlight menu))
+(add-hook 'gnus-summary-mode-hook 'gnus-moderate)
@end lisp
-If you want only highlighting and no menus whatsoever, you'd say:
+in your @file{.gnus.el} file.
+
+If you are the moderation of @samp{rec.zoofle}, this is how it's
+supposed to work:
+
+@enumerate
+@item
+You split your incoming mail by matching on
+@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted
+articles in some mail group---for instance, @samp{nnml:rec.zoofle}.
+
+@item
+You enter that group once in a while and post articles using the @kbd{e}
+(edit-and-post) or @kbd{s} (just send unedited) commands.
+
+@item
+If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some
+articles that weren't approved by you, you can cancel them with the
+@kbd{c} command.
+@end enumerate
+
+To use moderation mode in these two groups, say:
@lisp
-(setq gnus-visual '(highlight))
+(setq gnus-moderated-list
+ "^nnml:rec.zoofle$\\|^rec.zoofle$")
@end lisp
-If @code{gnus-visual} is @code{t}, highlighting and menus will be used
-in all Gnus buffers.
-Other general variables that influence the look of all buffers include:
+@node XEmacs Enhancements
+@section XEmacs Enhancements
+@cindex XEmacs
-@table @code
-@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}.
+XEmacs is able to display pictures and stuff, so Gnus has taken
+advantage of that. Relevant variables include:
-@item gnus-display-type
-@vindex gnus-display-type
-This variable is symbol indicating the display type 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}.
+@table @code
+@item gnus-xmas-glyph-directory
+@vindex gnus-xmas-glyph-directory
+This is where Gnus will look for pictures. Gnus will normally
+auto-detect this directory, but you may set it manually if you have an
+unusual directory structure.
+
+@item gnus-xmas-logo-color-alist
+@vindex gnus-xmas-logo-color-alist
+This is an alist where the key is a type symbol and the values are the
+foreground and background color of the splash page glyph.
+
+@item gnus-xmas-logo-color-style
+@vindex gnus-xmas-logo-color-style
+This is the key used to look up the color in the alist described above.
+Legal values include @code{flame}, @code{pine}, @code{moss},
+@code{irish}, @code{sky}, @code{tin}, @code{velvet}, @code{grape},
+@code{labia}, @code{berry}, @code{neutral}, and @code{september}.
+
+@item gnus-use-toolbar
+@vindex gnus-use-toolbar
+If @code{nil}, don't display toolbars. If non-@code{nil}, it should be
+one of @code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar},
+@code{right-toolbar}, or @code{left-toolbar}.
+
+@item gnus-group-toolbar
+@vindex gnus-group-toolbar
+The toolbar in the group buffer.
+
+@item gnus-summary-toolbar
+@vindex gnus-summary-toolbar
+The toolbar in the summary buffer.
+
+@item gnus-summary-mail-toolbar
+@vindex gnus-summary-mail-toolbar
+The toolbar in the summary buffer of mail groups.
+
+@item gnus-xmas-modeline-glyph
+@vindex gnus-xmas-modeline-glyph
+A glyph displayed in all Gnus mode lines. It is a tiny gnu head by
+default.
-@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'.
@end table
-There are hooks associated with the creation of all the different menus:
+
+@node Various Various
+@section Various Various
+@cindex mode lines
+@cindex highlights
@table @code
-@item gnus-article-menu-hook
-@vindex gnus-article-menu-hook
-Hook called after creating the article mode menu.
+@item gnus-directory
+@vindex gnus-directory
+All Gnus directories will be initialized from this variable, which
+defaults to the @samp{SAVEDIR} environment variable, or @file{~/News/}
+if that variable isn't set.
+
+@item gnus-default-directory
+@vindex gnus-default-directory
+Not related to the above variable at all---this variable says what the
+default directory of all Gnus buffers should be. If you issue commands
+like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's
+default directory. If this variable is @code{nil} (which is the
+default), the default directory will be the default directory of the
+buffer you were in when you started Gnus.
-@item gnus-group-menu-hook
-@vindex gnus-group-menu-hook
-Hook called after creating the group mode menu.
+@item gnus-verbose
+@vindex gnus-verbose
+This variable is an integer between zero and ten. The higher the value,
+the more messages will be displayed. If this variable is zero, Gnus
+will never flash any messages, if it is seven (which is the default),
+most important messages will be shown, and if it is ten, Gnus won't ever
+shut up, but will flash so many messages it will make your head swim.
-@item gnus-summary-menu-hook
-@vindex gnus-summary-menu-hook
-Hook called after creating the summary mode menu.
+@item gnus-verbose-backends
+@vindex gnus-verbose-backends
+This variable works the same way as @code{gnus-verbose}, but it applies
+to the Gnus backends instead of Gnus proper.
-@item gnus-server-menu-hook
-@vindex gnus-server-menu-hook
-Hook called after creating the server mode menu.
+@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 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}.
-@item gnus-browse-menu-hook
-@vindex gnus-browse-menu-hook
-Hook called after creating the browse mode menu.
+@item nnheader-head-chop-length
+@vindex nnheader-head-chop-length
+This variable says how big a piece of each article to read when doing
+the operation described above.
-@item gnus-score-menu-hook
-@vindex gnus-score-menu-hook
-Hook called after creating the score mode menu.
+@item nnheader-file-name-translation-alist
+@vindex nnheader-file-name-translation-alist
+@cindex file names
+@cindex illegal characters in file names
+@cindex characters in file names
+This is an alist that says how to translate characters in file names.
+For instance, if @samp{:} is illegal as a file character in file names
+on your system (you OS/2 user you), you could say something like:
-@end table
+@lisp
+(setq nnheader-file-name-translation-alist
+ '((?: . ?_)))
+@end lisp
+In fact, this is the default value for this variable on OS/2 and MS
+Windows (phooey) systems.
-@node Buttons
-@section Buttons
-@cindex buttons
-@cindex mouse
-@cindex click
+@item gnus-hidden-properties
+@vindex gnus-hidden-properties
+This is a list of properties to use to hide ``invisible'' text. It is
+@code{(invisible t intangible t)} by default on most systems, which
+makes invisible text invisible and intangible.
-Those new-fangled @dfn{mouse} contraptions is very popular with the
-young, hep kids who don't want to learn the proper way to do things
-these days. Why, I remember way back in the summer of '89, when I was
-using Emacs on a Tops 20 system. Three hundred users on one single
-machine, and every user was running Simula compilers. Bah!
+@item gnus-parse-headers-hook
+@vindex gnus-parse-headers-hook
+A hook called before parsing headers. It can be used, for instance, to
+gather statistics on the headers fetched, or perhaps you'd like to prune
+some headers. I don't see why you'd want that, though.
-Right.
+@item gnus-shell-command-separator
+@vindex gnus-shell-command-separator
+String used to separate to shell commands. The default is @samp{;}.
-@vindex gnus-carpal
-Well, you can make Gnus display bufferfuls of buttons you can click to
-do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
-really. Tell the chiropractor I sent you.
+@end table
-@table @code
-@item gnus-carpal-mode-hook
-@vindex gnus-carpal-mode-hook
-Hook run in all carpal mode buffers.
+@node The End
+@chapter The End
-@item gnus-carpal-button-face
-@vindex gnus-carpal-button-face
-Face used on buttons.
+Well, that's the manual---you can get on with your life now. Keep in
+touch. Say hello to your cats from me.
-@item gnus-carpal-header-face
-@vindex gnus-carpal-header-face
-Face used on carpal buffer headers.
+My @strong{ghod}---I just can't stand goodbyes. Sniffle.
-@item gnus-carpal-group-buffer-buttons
-@vindex gnus-carpal-group-buffer-buttons
-Buttons in the group buffer.
+Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
-@item gnus-carpal-summary-buffer-buttons
-@vindex gnus-carpal-summary-buffer-buttons
-Buttons in the summary buffer.
+@quotation
+@strong{Te Deum}
-@item gnus-carpal-server-buffer-buttons
-@vindex gnus-carpal-server-buffer-buttons
-Buttons in the server buffer.
+@sp 1
+Not because of victories @*
+I sing,@*
+having none,@*
+but for the common sunshine,@*
+the breeze,@*
+the largess of the spring.
-@item gnus-carpal-browse-buffer-buttons
-@vindex gnus-carpal-browse-buffer-buttons
-Buttons in the browse buffer.
-@end table
+@sp 1
+Not for victory@*
+but for the day's work done@*
+as well as I was able;@*
+not for a seat upon the dais@*
+but at the common table.@*
+@end quotation
-All the @code{buttons} variables are lists. The elements in these list
-is either a cons cell where the car contains a text to be displayed and
-the cdr contains a function symbol, or a simple string.
+@node Appendices
+@chapter Appendices
-@node Daemons
-@section Daemons
-@cindex demons
-@cindex daemons
+@menu
+* History:: How Gnus got where it is today.
+* Terminology:: We use really difficult, like, words here.
+* Customization:: Tailoring Gnus to your needs.
+* Troubleshooting:: What you might try if things do not work.
+* A Programmers Guide to Gnus:: Rilly, rilly technical stuff.
+* Emacs for Heathens:: A short introduction to Emacsian terms.
+* Frequently Asked Questions:: A question-and-answer session.
+@end menu
-Gnus, being larger than any program ever written (allegedly), does lots
-of strange stuff that you may wish to have done while you're not
-present. For instance, you may want it to check for new mail once in a
-while. Or you may want it to close down all connections to all servers
-when you leave Emacs idle. And stuff like that.
-Gnus will let you do stuff like that by defining various
-@dfn{handlers}. Each handler consists of three elements: A
-@var{function}, a @var{time}, and an @var{idle} parameter.
+@node History
+@section History
-Here's an example of a handler that closes connections when Emacs has
-been idle for thirty minutes:
+@cindex history
+@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in
+'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
-@lisp
-(gnus-demon-close-connections nil 30)
-@end lisp
+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, and is known
+as The Site That Destroys Newsrcs And Drives People Mad.
-Here's a handler that scans for PGP headers every hour when Emacs is
-idle:
+During the first extended alpha period of development, 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 @sc{Umeda} intended, which makes it a more
+appropriate name, don't you think?)
-@lisp
-(gnus-demon-scan-pgp 60 t)
-@end lisp
+In any case, after spending all that energy on coming up with a new and
+spunky name, we decided that the name was @emph{too} spunky, so we
+renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
+``@sc{gnus}''. New vs. old.
-This @var{time} parameter and than @var{idle} parameter works together
-in a strange, but wonderful fashion. Basically, if @var{idle} is
-@code{nil}, then the function will be called every @var{time} minutes.
+The first ``proper'' release of Gnus 5 was done in November 1995 when it
+was included in the Emacs 19.30 distribution.
-If @var{idle} is @code{t}, then the function will be called after
-@var{time} minutes only if Emacs is idle. So if Emacs is never idle,
-the function will never be called. But once Emacs goes idle, the
-function will be called every @var{time} minutes.
+In May 1996 the next Gnus generation (aka. ``September Gnus'') was
+released under the name ``Gnus 5.2''.
-If @var{idle} is a number and @var{time} is a number, the function will
-be called every @var{time} minutes only when Emacs has been idle for
-@var{idle} minutes.
+On July 28th 1996 work on Red Gnus was begun.
-If @var{idle} is a number and @var{time} is @code{nil}, the function
-will be called once every time Emacs has been idle for @var{idle}
-minutes.
+@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.
+* Emacsen:: Gnus can be run on a few modern Emacsen.
+* Contributors:: Oodles of people.
+* New Features:: Pointers to some of the new stuff in Gnus.
+* Newest Features:: Features so new that they haven't been written yet.
+@end menu
+
+
+@node Why?
+@subsection 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 thousands of new articles each day? How do you
+keep track of millions of people who post?
+
+Gnus offers 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 @sc{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 could imagine useful. By doing so, I'm inviting every one
+of you to explore and invent.
-And if @var{time} is a string, it should look like @samp{07:31}, and
-the function will then be called once every day somewhere near that
-time. Modified by the @var{idle} parameter, of course.
+May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
-@vindex gnus-demon-timestep
-(When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
-seconds. This is @code{60} by default. If you change that variable,
-all the timings in the handlers will be affected.)
-@vindex gnus-use-demon
-To set the whole thing in motion, though, you have to set
-@code{gnus-use-demon} to @code{t}.
+@node Compatibility
+@subsection Compatibility
-So, if you want to add a handler, you could put something like this in
-your @file{.gnus} file:
+@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.
-@findex gnus-demon-add-handler
-@lisp
-(gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
-@end lisp
+Our motto is:
+@quotation
+@cartouche
+@center In a cloud bones of steel.
+@end cartouche
+@end quotation
-@findex gnus-demon-add-nocem
-@findex gnus-demon-add-scanmail
-@findex gnus-demon-add-disconnection
-Some ready-made functions to do this has been created:
-@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
-@code{gnus-demon-add-scanmail}. Just put those functions in your
-@file{.gnus} if you want those abilities.
+All commands have kept their names. Some internal functions have changed
+their names.
-@findex gnus-demon-init
-@findex gnus-demon-cancel
-@vindex gnus-demon-handlers
-If you add handlers to @code{gnus-demon-handlers} directly, you should
-run @code{gnus-demon-init} to make the changes take hold. To cancel all
-daemons, you can use the @code{gnus-demon-cancel} function.
+The @code{gnus-uu} package has changed drastically. @pxref{Decoding
+Articles}.
-Note that adding daemons can be pretty naughty if you overdo it. Adding
-functions that scan all news and mail from all servers every two seconds
-is a sure-fire way of getting booted off any respectable system. So
-behave.
+One major compatibility question is 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 many
+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-alist} (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 alist (which
+speeds up many functions), and changing the alist directly will lead to
+peculiar results.
-@node NoCeM
-@section NoCeM
-@cindex nocem
-@cindex spam
+@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} and @code{gnus-summary-prepare-hook}).
+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!
-@dfn{Spamming} is posting the same article lots and lots of times.
-Spamming is bad. Spamming is evil.
+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.)
-Spamming is usually canceled within a day or so by various anti-spamming
-agencies. These agencies usually also send out @dfn{NoCeM} messages.
-NoCeM is pronounced ``no see-'em'', and means what the name
-implies---these are messages that make the offending articles, like, go
-away.
+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.
-What use are these NoCeM messages if the articles are canceled anyway?
-Some sites do not honor cancel messages and some sites just honor cancels
-from a select few people. Then you may wish to make use of the NoCeM
-messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
+Gnus understands all @sc{gnus} startup files.
-Gnus can read and parse the messages in this group automatically, and
-this will make spam disappear.
+@kindex M-x gnus-bug
+@findex gnus-bug
+@cindex reporting bugs
+@cindex bugs
+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 by issuing that magic command @kbd{M-x gnus-bug}.
-There are some variables to customize, of course:
-@table @code
-@item gnus-use-nocem
-@vindex gnus-use-nocem
-Set this variable to @code{t} to set the ball rolling. It is @code{nil}
-by default.
+@node Conformity
+@subsection Conformity
-@item gnus-nocem-groups
-@vindex gnus-nocem-groups
-Gnus will look for NoCeM messages in the groups in this list. The
-default is @code{("alt.nocem.misc" "news.admin.net-abuse.announce")}.
+No rebels without a clue here, ma'am. We conform to all standards known
+to (wo)man. Except for those standards and/or conventions we disagree
+with, of course.
-@item gnus-nocem-issuers
-@vindex gnus-nocem-issuers
-There are many people issuing NoCeM messages. This list says what
-people you want to listen to. The default is @code{("Automoose-1"
-"clewis@@ferret.ocunix.on.ca;" "jem@@xpat.com;" "red@@redpoll.mrfs.oh.us
-(Richard E. Depew)")}; fine, upstanding citizens all of them.
+@table @strong
-Known despammers that you can put in this list include:
+@item RFC 822
+@cindex RFC 822
+There are no known breaches of this standard.
-@table @samp
-@item clewis@@ferret.ocunix.on.ca;
-@cindex Chris Lewis
-Chris Lewis---Major Canadian despammer who has probably canceled more
-usenet abuse than anybody else.
+@item RFC 1036
+@cindex RFC 1036
+There are no known breaches of this standard, either.
-@item Automoose-1
-@cindex CancelMoose[tm]
-The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be
-Norwegian, and was the person(s) who invented NoCeM.
+@item Good Net-Keeping Seal of Approval
+@cindex Good Net-Keeping Seal of Approval
+Gnus has been through the Seal process and failed. I think it'll pass
+the next inspection.
-@item jem@@xpat.com;
-@cindex Jem
-Jem---Korean despammer who is getting very busy these days.
+@item Son-of-RFC 1036
+@cindex Son-of-RFC 1036
+We do have some breaches to this one.
-@item red@@redpoll.mrfs.oh.us (Richard E. Depew)
-Richard E. Depew---lone American despammer. He mostly cancels binary
-postings to non-binary groups and removes spews (regurgitated articles).
-@end table
+@table @emph
-You do not have to heed NoCeM messages from all these people---just the
-ones you want to listen to.
+@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 gnus-nocem-directory
-@vindex gnus-nocem-directory
-This is where Gnus will store its NoCeM cache files. The default is
-@file{~/News/NoCeM/}.
+@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 gnus-nocem-expiry-wait
-@vindex gnus-nocem-expiry-wait
-The number of days before removing old NoCeM entries from the cache.
-The default is 15. If you make it shorter Gnus will be faster, but you
-might then see old spam.
+@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 notice Gnus acting non-compliantly with regards to the texts
+mentioned above, don't hesitate to drop a note to Gnus Towers and let us
+know.
-@node Picons
-@section Picons
-So... You want to slow down your news reader even more! This is a
-good way to do so. Its also a great way to impress people staring
-over your shoulder as you read news.
+@node Emacsen
+@subsection Emacsen
+@cindex Emacsen
+@cindex XEmacs
+@cindex Mule
+@cindex Emacs
-@menu
-* Picon Basics:: What are picons and How do I get them.
-* Picon Requirements:: Don't go further if you aren't using XEmacs.
-* Easy Picons:: Displaying Picons -- the easy way.
-* Hard Picons:: The way you should do it. You'll learn something.
-* Picon Configuration:: Other variables you can trash/tweak/munge/play with.
-@end menu
+Gnus should work on :
+@itemize @bullet
-@node Picon Basics
-@subsection Picon Basics
+@item
+Emacs 19.30 and up.
-What are Picons? To quote directly from the Picons Web site
-(@samp{http://www.cs.indiana.edu/picons/ftp/index.html}):
+@item
+XEmacs 19.13 and up.
-@quotation
-@dfn{Picons} is short for ``personal icons''. They're small,
-constrained images used to represent users and domains on the net,
-organized into databases so that the appropriate image for a given
-e-mail address can be found. Besides users and domains, there are picon
-databases for Usenet newsgroups and weather forecasts. The picons are
-in either monochrome @code{XBM} format or color @code{XPM} and
-@code{GIF} formats.
-@end quotation
+@item
+Mule versions based on Emacs 19.30 and up.
-Please see the above mentioned web site for instructions on obtaining
-and installing the picons databases, or the following ftp site:
-@samp{http://www.cs.indiana.edu/picons/ftp/index.html}.
+@end itemize
-@vindex gnus-picons-database
-Gnus expects picons to be installed into a location pointed to by
-@code{gnus-picons-database}.
+Gnus will absolutely not work on any Emacsen older than that. Not
+reliably, at least.
+There are some vague differences between Gnus on the various platforms:
-@node Picon Requirements
-@subsection Picon Requirements
+@itemize @bullet
-To use have Gnus display Picons for you, you must be running XEmacs
-19.13 or greater since all other versions of Emacs aren't yet able to
-display images.
+@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.
-Additionally, you must have @code{xpm} support compiled into XEmacs.
+@item
+The same with current-article marking---XEmacs puts an underline under
+the entire summary line while Emacs and Mule are nicer and kinder.
-@vindex gnus-picons-convert-x-face
-If you want to display faces from @code{X-Face} headers, you must have
-the @code{netpbm} utilities installed, or munge the
-@code{gnus-picons-convert-x-face} variable to use something else.
+@item
+XEmacs features more graphics---a logo and a toolbar.
+@item
+Citation highlighting us better under Emacs and Mule than under XEmacs.
-@node Easy Picons
-@subsection Easy Picons
+@item
+Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
+confusing.
-To enable displaying picons, simply put the following line in your
-@file{~/.gnus} file and start Gnus.
+@end itemize
-@lisp
-(setq gnus-use-picons t)
-(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
-(add-hook 'gnus-summary-prepare-hook 'gnus-group-display-picons t)
-(add-hook 'gnus-article-display-hook 'gnus-picons-article-display-x-face)
-@end lisp
+@node Contributors
+@subsection Contributors
+@cindex contributors
-@node Hard Picons
-@subsection Hard Picons
+The new Gnus version couldn't have been done without the help of all the
+people on the (ding) mailing list. Every day for over a year I have
+gotten billions of nice bug reports from them, filling me with joy,
+every single one of them. Smooches. The people on the list have been
+tried beyond endurance, what with my ``oh, that's a neat idea <type
+type>, yup, I'll release it right away <ship off> no wait, that doesn't
+work at all <type type>, yup, I'll ship that one off right away <ship
+off> no, wait, that absolutely does not work'' policy for releases.
+Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
+``worser''? ``much worser''? ``worsest''?)
-Gnus can display picons for you as you enter and leave groups and
-articles. It knows how to interact with three sections of the picons
-database. Namely, it can display the picons newsgroup pictures,
-author's face picture(s), and the authors domain. To enable this
-feature, you need to first decide where to display them.
+I would like to take this opportunity to thank the Academy for... oops,
+wrong show.
-@table @code
+@itemize @bullet
-@item gnus-picons-display-where
-@vindex gnus-picons-display-where
-Where the picon images should be displayed. It is @code{picons} by
-default (which by default maps to the buffer @samp{*Picons*}). Other
-valid places could be @code{article}, @code{summary}, or
-@samp{"*scratch*"} for all I care. Just make sure that you've made the
-buffer visible using the standard Gnus window configuration routines --
-@xref{Windows Configuration}.
+@item
+Masanobu @sc{Umeda}---the writer of the original @sc{gnus}.
-@end table
+@item
+Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as
+well as numerous other things).
-Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
-window configuration for you to include the @code{picons} buffer.
+@item
+Luis Fernandes---design and graphics.
-Now that you've made that decision, you need to add the following
-functions to the appropriate hooks so these pictures will get
-displayed at the right time.
+@item
+Wes Hardaker---@file{gnus-picon.el} and the manual section on
+@dfn{picons} (@pxref{Picons}).
-@vindex gnus-article-display-hook
-@vindex gnus-picons-display-where
-@table @code
-@item gnus-article-display-picons
-@findex gnus-article-display-picons
-Looks up and display the picons for the author and the author's domain
-in the @code{gnus-picons-display-where} buffer. Should be added to
-the @code{gnus-article-display-hook}.
+@item
+Brad Miller---@file{gnus-gl.el} and the GroupLens manual section
+(@pxref{GroupLens}).
-@item gnus-group-display-picons
-@findex gnus-article-display-picons
-Displays picons representing the current group. This function should
-be added to the @code{gnus-summary-prepare-hook} or to the
-@code{gnus-article-display-hook} if @code{gnus-picons-display-where}
-is set to @code{article}.
+@item
+Sudish Joseph---innumerable bug fixes.
-@item gnus-picons-article-display-x-face
-@findex gnus-article-display-picons
-Decodes and displays the X-Face header if present. This function
-should be added to @code{gnus-article-display-hook}.
+@item
+Ilja Weis---@file{gnus-topic.el}.
-@end table
+@item
+Steven L. Baur---lots and lots and lots of bugs detections and fixes.
-Note: You must append them to the hook, so make sure to specify 't'
-to the append flag of @code{add-hook}:
+@item
+Vladimir Alexiev---the refcard and reference booklets.
-@lisp
-(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
-@end lisp
+@item
+Felix Lee & Jamie Zawinsky---I stole some pieces from the XGnus
+distribution by Felix Lee and JWZ.
+@item
+Scott Byer---@file{nnfolder.el} enhancements & rewrite.
-@node Picon Configuration
-@subsection Picon Configuration
+@item
+Peter Mutsaers---orphan article scoring code.
-The following variables offer further control over how things are
-done, where things are located, and other useless stuff you really
-don't need to worry about.
+@item
+Ken Raeburn---POP mail support.
-@table @code
-@item gnus-picons-database
-@vindex gnus-picons-database
-The location of the picons database. Should point to a directory
-containing the @file{news}, @file{domains}, @file{users} (and so on)
-subdirectories. Defaults to @file{/usr/local/faces}.
+@item
+Hallvard B Furuseth---various bits and pieces, especially dealing with
+.newsrc files.
-@item gnus-picons-news-directory
-@vindex gnus-picons-news-directory
-Sub-directory of the faces database containing the icons for
-newsgroups.
+@item
+Brian Edmonds---@file{gnus-bbdb.el}.
-@item gnus-picons-user-directories
-@vindex gnus-picons-user-directories
-List of subdirectories to search in @code{gnus-picons-database} for user
-faces. Defaults to @code{("local" "users" "usenix" "misc/MISC")}.
+@item
+Ricardo Nassif, Mark Borges, and Jost Krieger---proof-reading.
-@item gnus-picons-domain-directories
-@vindex gnus-picons-domain-directories
-List of subdirectories to search in @code{gnus-picons-database} for
-domain name faces. Defaults to @code{("domains")}. Some people may
-want to add @samp{unknown} to this list.
+@item
+Kevin Davidson---came up with the name @dfn{ding}, so blame him.
-@item gnus-picons-convert-x-face
-@vindex gnus-picons-convert-x-face
-The command to use to convert the @code{X-Face} header to an X bitmap
-(@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
-Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
-gnus-picons-x-face-file-name)}
+@item
+François Pinard---many, many interesting and thorough bug reports.
-@item gnus-picons-x-face-file-name
-@vindex gnus-picons-x-face-file-name
-Names a temporary file to store the @code{X-Face} bitmap in. Defaults
-to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
+@end itemize
-@item gnus-picons-buffer
-@vindex gnus-picons-buffer
-The name of the buffer that @code{picons} points to. Defaults to
-@samp{*Icon Buffer*}.
+The following people have contributed many patches and suggestions:
-@end table
+Christopher Davis,
+Andrew Eskilsson,
+Kai Grossjohann,
+David Kågedal,
+Richard Pieri,
+Fabrice Popineau,
+Daniel Quinlan,
+Jason L. Tibbitts, III,
+and
+Jack Vinson.
+
+Also thanks to the following for patches and stuff:
+
+Peter Arius,
+Marc Auslander,
+Mark Borges,
+Lance A. Brown,
+Martin Buchholz,
+Alastair Burt,
+Joao Cachopo,
+Massimo Campostrini,
+Michael Cook,
+Glenn Coombs,
+Frank D. Cringle,
+Geoffrey T. Dairiki,
+Ulrik Dickow,
+Dave Disser,
+Paul Eggert,
+Michael Ernst,
+Luc Van Eycken,
+Sam Falkner,
+Paul Franklin,
+David S. Goldberg,
+D. Hall,
+Magnus Hammerin,
+Raja R. Harinath,
+Marc Horowitz,
+Ishikawa Ichiro, @c Ishikawa
+Francois Felix Ingrand,
+Lee Iverson,
+Fred Johansen,
+Thor Kristoffersen,
+Jens Lautenbacher,
+Christian Limpach,
+Nat Makarevitch,
+Timo Metzemakers,
+Richard Mlynarik,
+Lantz Moore,
+Morioka Tomohiko, @c Morioka
+Hrvoje Niksic,
+Andy Norman,
+Ken Olstad,
+Masaharu Onishi, @c Onishi
+Hideki Ono, @c Ono
+Ulrich Pfeifer,
+Colin Rafferty,
+Bart Robinson,
+Ralph Schleicher,
+Danny Siu,
+Paul D. Smith,
+Jeff Sparkes,
+Michael Sperber,
+Richard Stallman,
+Greg Stark,
+Kurt Swanson,
+Samuel Tardieu,
+Teddy,
+Chuck Thompson,
+Philippe Troin,
+Jan Vroonhof,
+Barry A. Warsaw,
+Christoph Wedler,
+Joe Wells,
+and
+Katsumi Yamaoka. @c Yamaoka
+Apologies to everybody that I've forgotten, of which there are many, I'm
+sure.
-@node Various Various
-@section Various Various
-@cindex mode lines
-@cindex highlights
+Gee, that's quite a list of people. I guess that must mean that there
+actually are people who are using Gnus. Who'd'a thunk it!
-@table @code
-@item gnus-verbose
-@vindex gnus-verbose
-This variable is an integer between zero and ten. The higher the value,
-the more messages will be displayed. If this variable is zero, Gnus
-will never flash any messages, if it is seven (which is the default),
-most important messages will be shown, and if it is ten, Gnus won't ever
-shut up, but will flash so many messages it will make your head swim.
+@node New Features
+@subsection New Features
+@cindex new features
-@item gnus-verbose-backends
-@vindex gnus-verbose-backends
-This variable works the same way as @code{gnus-verbose}, but it applies
-to the Gnus backends instead of Gnus proper.
+@menu
+* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus.
+* September Gnus:: The Thing Formally Known As Gnus 5.3/5.3.
+* Red Gnus:: The future.
+@end menu
-@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}.
+These lists are, of course, just @emph{short} overviews of the
+@emph{most} important new features. No, really. There are tons more.
+Yes, we have feeping creaturism in full effect.
-@item nnheader-file-name-translation-alist
-@vindex nnheader-file-name-translation-alist
-@cindex file names
-@cindex illegal characters in file names
-@cindex characters in file names
-This is an alist that says how to translate characters in file names.
-For instance, if @samp{:} is illegal as a file character in file names
-on your system (you OS/2 user you), you could say something like:
-@lisp
-(setq nnheader-file-name-translation-alist
- '((?: . ?_)))
-@end lisp
+@node ding Gnus
+@subsubsection (ding) Gnus
-In fact, this is the default value for this variable on OS/2 and MS
-Windows (phooey) systems.
+New features in Gnus 5.0/5.1:
-@item gnus-hidden-properties
-@vindex gnus-hidden-properties
-This is a list of properties to use to hide ``invisible'' text. It is
-@code{(invisible t intangible t)} by default on most systems, which
-makes invisible text invisible and intangible.
+@itemize @bullet
-@item gnus-parse-header-hook
-@vindex gnus-parse-header-hook
-A hook called before parsing headers. It can be used, for instance, to
-gather statistics on the headers fetched, or perhaps you'd like to prune
-some headers. I don't see why you'd want that, though.
+@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{Select Methods}).
-@end table
+@item
+You can combine groups into virtual groups (@pxref{Virtual Groups}).
+@item
+You can read a number of different mail formats (@pxref{Getting Mail}).
+All the mail backends implement a convenient mail expiry scheme
+(@pxref{Expiring Mail}).
-@node The End
-@chapter The End
+@item
+Gnus can use various strategies for gathering threads that have lost
+their roots (thereby gathering loose sub-threads into one thread) or it
+can go back and retrieve enough headers to build a complete thread
+(@pxref{Customizing Threading}).
-Well, that's the manual---you can get on with your life now. Keep in
-touch. Say hello to your cats from me.
+@item
+Killed groups can be displayed in the group buffer, and you can read
+them as well (@pxref{Listing Groups}).
-My @strong{ghod}---I just can't stand goodbyes. Sniffle.
+@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}).
-Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
+@item
+Gnus implements a sliding scale of subscribedness to groups
+(@pxref{Group Levels}).
-@quotation
-@strong{Te Deum}
-@sp 1
-Not because of victories @*
-I sing,@*
-having none,@*
-but for the common sunshine,@*
-the breeze,@*
-the largess of the spring.
-@sp 1
-Not for victory@*
-but for the day's work done@*
-as well as I was able;@*
-not for a seat upon the dais@*
-but at the common table.@*
-@end quotation
+@item
+You can score articles according to any number of criteria
+(@pxref{Scoring}). You can even get Gnus to find out how to score
+articles for you (@pxref{Adaptive Scoring}).
+@item
+Gnus maintains a dribble buffer that is auto-saved the normal Emacs
+manner, so it should be difficult to lose much data on what you have
+read if your machine should go down (@pxref{Auto Save}).
-@node Appendices
-@chapter Appendices
+@item
+Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
+the @file{.emacs} file.
-@menu
-* History:: How Gnus got where it is today.
-* Terminology:: We use really difficult, like, words here.
-* Customization:: Tailoring Gnus to your needs.
-* Troubleshooting:: What you might try if things do not work.
-* A Programmers Guide to Gnus:: Rilly, rilly technical stuff.
-* Emacs for Heathens:: A short introduction to Emacsian terms.
-* Frequently Asked Questions:: A question-and-answer session.
-@end menu
+@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{Kibozed Groups}).
-@node History
-@section History
+@item
+You can list subsets of groups according to, well, anything
+(@pxref{Listing Groups}).
-@cindex history
-@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in
-'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
+@item
+You can browse foreign servers and subscribe to groups from those
+servers (@pxref{Browse Foreign Server}).
-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, and is known
-as The Site That Destroys Newsrcs And Drives People Mad.
+@item
+Gnus can fetch articles asynchronously on a second connection to the
+server (@pxref{Asynchronous Fetching}).
-During the first extended alpha period of development, 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 @sc{Umeda} intended, which makes it a more
-appropriate name, don't you think?)
+@item
+You can cache articles locally (@pxref{Article Caching}).
-In any case, after spending all that energy on coming up with a new and
-spunky name, we decided that the name was @emph{too} spunky, so we
-renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
-``@sc{gnus}''. New vs. old.
+@item
+The uudecode functions have been expanded and generalized
+(@pxref{Decoding Articles}).
-The first ``proper'' release of Gnus 5 was done in November 1995 when it
-was included in the Emacs 19.30 distribution.
+@item
+You can still post uuencoded articles, which was a little-known feature
+of @sc{gnus}' past (@pxref{Uuencoding and Posting}).
-Incidentally, the next Gnus generation will be called ``September
-Gnus'', and won't be released until April 1996. Confused? You will be.
+@item
+Fetching parents (and other articles) now actually works without
+glitches (@pxref{Finding the Parent}).
-@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.
-* Emacsen:: Gnus can be run on a few modern Emacsen.
-* Contributors:: Oodles of people.
-* New Features:: Pointers to some of the new stuff in Gnus.
-* Newest Features:: Features so new that they haven't been written yet.
-* Censorship:: This manual has been censored.
-@end menu
+@item
+Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
+@item
+Digests (and other files) can be used as the basis for groups
+(@pxref{Document Groups}).
-@node Why?
-@subsection Why?
+@item
+Articles can be highlighted and customized (@pxref{Customizing
+Articles}).
-What's the point of Gnus?
+@item
+URLs and other external references can be buttonized (@pxref{Article
+Buttons}).
-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 thousands of new articles each day? How do you
-keep track of millions of people who post?
+@item
+You can do lots of strange stuff with the Gnus window & frame
+configuration (@pxref{Windows Configuration}).
-Gnus offers 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 @sc{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 could imagine useful. By doing so, I'm inviting every one
-of you to explore and invent.
+@item
+You can click on buttons instead of using the keyboard
+(@pxref{Buttons}).
-May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
+@end itemize
-@node Compatibility
-@subsection Compatibility
+@node September Gnus
+@subsubsection September Gnus
-@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.
+New features in Gnus 5.2/5.3:
-Our motto is:
-@quotation
-@cartouche
-@center In a cloud bones of steel.
-@end cartouche
-@end quotation
+@itemize @bullet
-All commands have kept their names. Some internal functions have changed
-their names.
+@item
+A new message composition mode is used. All old customization variables
+for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are
+now obsolete.
-The @code{gnus-uu} package has changed drastically. @pxref{Decoding
-Articles}.
+@item
+Gnus is now able to generate @dfn{sparse} threads---threads where
+missing articles are represented by empty nodes (@pxref{Customizing
+Threading}).
-One major compatibility question is 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 many
-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.
+@lisp
+(setq gnus-build-sparse-threads 'some)
+@end lisp
-All code that relies on knowledge of @sc{gnus} internals will probably
-fail. To take two examples: Sorting @code{gnus-newsrc-alist} (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 alist (which
-speeds up many functions), and changing the alist directly will lead to
-peculiar results.
+@item
+Outgoing articles are stored on a special archive server
+(@pxref{Archived Messages}).
-@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} and @code{gnus-summary-prepare-hook}).
-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!
+@item
+Partial thread regeneration now happens when articles are
+referred.
-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.)
+@item
+Gnus can make use of GroupLens predictions (@pxref{GroupLens}).
-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.
+@item
+Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}).
-Gnus understands all @sc{gnus} startup files.
+@item
+A @code{trn}-line tree buffer can be displayed (@pxref{Tree Display}).
-@kindex M-x gnus-bug
-@findex gnus-bug
-@cindex reporting bugs
-@cindex bugs
-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 by issuing that magic command @kbd{M-x gnus-bug}.
+@lisp
+(setq gnus-use-trees t)
+@end lisp
+@item
+An @code{nn}-like pick-and-read minor mode is available for the summary
+buffers (@pxref{Pick and Read}).
-@node Conformity
-@subsection Conformity
+@lisp
+(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
+@end lisp
-No rebels without a clue here, ma'am. We conform to all standards known
-to (wo)man. Except for those standards and/or conventions we disagree
-with, of course.
+@item
+In binary groups you can use a special binary minor mode (@pxref{Binary
+Groups}).
-@table @strong
+@item
+Groups can be grouped in a folding topic hierarchy (@pxref{Group
+Topics}).
-@item RFC 822
-@cindex RFC 822
-There are no known breaches of this standard.
+@lisp
+(add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
+@end lisp
-@item RFC 1036
-@cindex RFC 1036
-There are no known breaches of this standard, either.
+@item
+Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}).
-@item Usenet Seal of Approval
-@cindex Usenet Seal of Approval
-Gnus hasn't been formally through the Seal process, but I have read
-through the Seal text and I think Gnus would pass.
+@item
+Groups can now have a score, and bubbling based on entry frequency
+is possible (@pxref{Group Score}).
-@item Son-of-RFC 1036
-@cindex Son-of-RFC 1036
-We do have some breaches to this one.
+@lisp
+(add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group)
+@end lisp
-@table @emph
+@item
+Groups can be process-marked, and commands can be performed on
+groups of groups (@pxref{Marking Groups}).
-@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
+Caching is possible in virtual groups.
-@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
+@code{nndoc} now understands all kinds of digests, mail boxes, rnews
+news batches, ClariNet briefs collections, and just about everything
+else (@pxref{Document Groups}).
-@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
+@item
+Gnus has a new backend (@code{nnsoup}) to create/read SOUP packets
+(@pxref{SOUP}).
-@end table
+@item
+The Gnus cache is much faster.
-If you ever notice Gnus acting non-compliantly with regards to the texts
-mentioned above, don't hesitate to drop a note to Gnus Towers and let us
-know.
+@item
+Groups can be sorted according to many criteria (@pxref{Sorting
+Groups}).
+@item
+New group parameters have been introduced to set list-address and
+expiry times (@pxref{Group Parameters}).
-@node Emacsen
-@subsection Emacsen
-@cindex Emacsen
-@cindex XEmacs
-@cindex Mule
-@cindex Emacs
+@item
+All formatting specs allow specifying faces to be used
+(@pxref{Formatting Fonts}).
-Gnus should work on :
+@item
+There are several more commands for setting/removing/acting on process
+marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}).
-@itemize @bullet
+@item
+The summary buffer can be limited to show parts of the available
+articles based on a wide range of criteria. These commands have been
+bound to keys on the @kbd{/} submap (@pxref{Limiting}).
@item
-Emacs 19.30 and up.
+Articles can be made persistent with the @kbd{*} command
+(@pxref{Persistent Articles}).
@item
-XEmacs 19.13 and up.
+All functions for hiding article elements are now toggles.
-@item
-Mule versions based on Emacs 19.30 and up.
+@item
+Article headers can be buttonized (@pxref{Article Washing}).
-@end itemize
+@lisp
+(add-hook 'gnus-article-display-hook
+ 'gnus-article-add-buttons-to-head)
+@end lisp
-Gnus will absolutely not work on any Emacsen older than that. Not
-reliably, at least.
+@item
+All mail backends support fetching articles by @code{Message-ID}.
-There are some vague differences between Gnus on the various platforms:
+@item
+Duplicate mail can now be treated properly (@pxref{Duplicates}).
-@itemize @bullet
+@item
+All summary mode commands are available directly from the article
+buffer (@pxref{Article Keymap}).
@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.
+Frames can be part of @code{gnus-buffer-configuration} (@pxref{Windows
+Configuration}).
-@item
-The same with current-article marking---XEmacs puts an underline under
-the entire summary line while Emacs and Mule are nicer and kinder.
+@item
+Mail can be re-scanned by a daemonic process (@pxref{Daemons}).
@item
-XEmacs features more graphics---a logo and a toolbar.
+Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}).
+
+@lisp
+(setq gnus-use-nocem t)
+@end lisp
@item
-Citation highlighting us better under Emacs and Mule than under XEmacs.
+Groups can be made permanently visible (@pxref{Listing Groups}).
+
+@lisp
+(setq gnus-permanently-visible-groups "^nnml:")
+@end lisp
@item
-Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
-confusing.
-
-@end itemize
+Many new hooks have been introduced to make customizing easier.
+@item
+Gnus respects the @code{Mail-Copies-To} header.
-@node Contributors
-@subsection Contributors
-@cindex contributors
+@item
+Threads can be gathered by looking at the @code{References} header
+(@pxref{Customizing Threading}).
-The new Gnus version couldn't have been done without the help of all the
-people on the (ding) mailing list. Every day for over a year I have
-gotten billions of nice bug reports from them, filling me with joy,
-every single one of them. Smooches. The people on the list have been
-tried beyond endurance, what with my ``oh, that's a neat idea <type
-type>, yup, I'll release it right away <ship off> no wait, that doesn't
-work at all <type type>, yup, I'll ship that one off right away <ship
-off> no, wait, that absolutely does not work'' policy for releases.
-Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
-``worser''? ``much worser''? ``worsest''?)
+@lisp
+(setq gnus-summary-thread-gathering-function
+ 'gnus-gather-threads-by-references)
+@end lisp
-I would like to take this opportunity to thank the Academy for... oops,
-wrong show.
+@item
+Read articles can be stored in a special backlog buffer to avoid
+refetching (@pxref{Article Backlog}).
-@itemize @bullet
+@lisp
+(setq gnus-keep-backlog 50)
+@end lisp
-@item Masanobu @sc{Umeda}
-The writer of the original @sc{gnus}.
+@item
+A clean copy of the current article is always stored in a separate
+buffer to allow easier treatment.
-@item Per Abrahamsen
-Custom, scoring, highlighting and @sc{soup} code (as well as numerous
-other things).
+@item
+Gnus can suggest where to save articles (@pxref{Saving Articles}).
-@item Luis Fernandes
-Design and graphics.
+@item
+Gnus doesn't have to do as much prompting when saving (@pxref{Saving
+Articles}).
-@item Wes Hardaker
-@file{gnus-picon.el} and the manual section on @dfn{picons}
-(@pxref{Picons}).
+@lisp
+(setq gnus-prompt-before-saving t)
+@end lisp
-@item Brad Miller
-@file{gnus-gl.el} and the GroupLens manual section (@pxref{GroupLens}).
+@item
+@code{gnus-uu} can view decoded files asynchronously while fetching
+articles (@pxref{Other Decode Variables}).
-@item Sudish Joseph
-Innumerable bug fixes.
+@lisp
+(setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view)
+@end lisp
-@item Ilja Weis
-@file{gnus-topic.el}.
+@item
+Filling in the article buffer now works properly on cited text
+(@pxref{Article Washing}).
-@item Steven L. Baur
-Lots and lots of bugs detections and fixes.
+@item
+Hiding cited text adds buttons to toggle hiding, and how much
+cited text to hide is now customizable (@pxref{Article Hiding}).
-@item Vladimir Alexiev
-The refcard and reference booklets.
+@lisp
+(setq gnus-cited-lines-visible 2)
+@end lisp
-@item Felix Lee & JWZ
-I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
+@item
+Boring headers can be hidden (@pxref{Article Hiding}).
-@item Scott Byer
-@file{nnfolder.el} enhancements & rewrite.
+@lisp
+(add-hook 'gnus-article-display-hook
+ 'gnus-article-hide-boring-headers t)
+@end lisp
-@item Peter Mutsaers
-Orphan article scoring code.
+@item
+Default scoring values can now be set from the menu bar.
-@item Ken Raeburn
-POP mail support.
+@item
+Further syntax checking of outgoing articles have been added.
-@item Hallvard B Furuseth
-Various bits and pieces, especially dealing with .newsrc files.
+@end itemize
-@item Brian Edmonds
-@file{gnus-bbdb.el}.
-@item Ricardo Nassif and Mark Borges
-Proof-reading.
+@node Red Gnus
+@subsubsection Red Gnus
-@item Kevin Davidson
-Came up with the name @dfn{ding}, so blame him.
+New features in Gnus 5.4/5.5:
-@end itemize
+@itemize @bullet
-Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
-Quinlan, Frank D. Cringle, Geoffrey T. Dairiki, Fabrice Popineau and
-Andrew Eskilsson have all contributed code and suggestions.
+@item
+@file{nntp.el} has been totally rewritten in an asynchronous fashion.
+@item
+Article prefetching functionality has been moved up into
+Gnus (@pxref{Asynchronous Fetching}).
-@node New Features
-@subsection New Features
-@cindex new features
+@item
+Scoring can now be performed with logical operators like @code{and},
+@code{or}, @code{not}, and parent redirection (@pxref{Advanced
+Scoring}).
-@itemize @bullet
+@item
+Article washing status can be displayed in the
+article mode line (@pxref{Misc Article}).
@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{Select Methods}).
+@file{gnus.el} has been split into many smaller files.
-@item
-You can combine groups into virtual groups (@pxref{Virtual Groups}).
+@item
+Suppression of duplicate articles based on Message-ID can be done
+(@pxref{Duplicate Suppression}).
-@item
-You can read a number of different mail formats (@pxref{Getting Mail}).
-All the mail backends implement a convenient mail expiry scheme
-(@pxref{Expiring Mail}).
+@lisp
+(setq gnus-suppress-duplicates t)
+@end lisp
@item
-Gnus can use various strategies for gathering threads that have lost
-their roots (thereby gathering loose sub-threads into one thread) or it
-can go back and retrieve enough headers to build a complete thread
-(@pxref{Customizing Threading}).
+New variables for specifying what score and adapt files are to be
+considered home score and adapt files (@pxref{Home Score File}).
-@item
-Killed groups can be displayed in the group buffer, and you can read
-them as well (@pxref{Listing Groups}).
+@item
+@code{nndoc} was rewritten to be easily extendable (@pxref{Document
+Server Internals}).
-@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
+Groups can inherit group parameters from parent topics (@pxref{Topic
+Parameters}).
-@item
-Gnus implements a sliding scale of subscribedness to groups
-(@pxref{Group Levels}).
+@item
+Article editing has been revamped and is now actually usable.
-@item
-You can score articles according to any number of criteria
-(@pxref{Scoring}). You can even get Gnus to find out how to score
-articles for you (@pxref{Adaptive Scoring}).
+@item
+Signatures can be recognized in more intelligent fashions
+(@pxref{Article Signature}).
-@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
+Summary pick mode has been made to look more @code{nn}-like. Line
+numbers are displayed and the @kbd{.} command can be used to pick
+articles (@code{Pick and Read}).
-@item
-Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
-the @file{.emacs} file.
+@item
+Commands for moving the @file{.newsrc.eld} from one server to
+another have been added (@pxref{Changing Servers}).
-@item
-You can set the process mark on both groups and articles and perform
-operations on all the marked items (@pxref{Process/Prefix}).
+@item
+A way to specify that ``uninteresting'' fields be suppressed when
+generating lines in buffers (@pxref{Advanced Formatting}).
-@item
-You can grep through a subset of groups and create a group from the
-results (@pxref{Kibozed Groups}).
+@item
+Several commands in the group buffer can be undone with @kbd{M-C-_}
+(@pxref{Undo}).
-@item
-You can list subsets of groups according to, well, anything
-(@pxref{Listing Groups}).
+@item
+Scoring can be done on words using the new score type @code{w}
+(@pxref{Score File Format}).
-@item
-You can browse foreign servers and subscribe to groups from those
-servers (@pxref{Browse Foreign Server}).
+@item
+Adaptive scoring can be done on a Subject word-by-word basis
+(@pxref{Adaptive Scoring}).
-@item
-Gnus can fetch articles asynchronously on a second connection to the
-server (@pxref{Asynchronous Fetching}).
+@lisp
+(setq gnus-use-adaptive-scoring '(word))
+@end lisp
-@item
-You can cache articles locally (@pxref{Article Caching}).
+@item
+Scores can be decayed (@pxref{Score Decays}).
+
+@lisp
+(setq gnus-decay-scores t)
+@end lisp
-@item
-The uudecode functions have been expanded and generalized
-(@pxref{Decoding Articles}).
+@item
+Scoring can be performed using a regexp on the Date header. The Date is
+normalized to compact ISO 8601 format first (@pxref{Score File Format}).
@item
-You can still post uuencoded articles, which was a little-known feature
-of @sc{gnus}' past (@pxref{Uuencoding and Posting}).
+A new command has been added to remove all data on articles from
+the native server (@pxref{Changing Servers}).
@item
-Fetching parents (and other articles) now actually works without
-glitches (@pxref{Finding the Parent}).
+A new command for reading collections of documents
+(@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{M-C-d}
+(@pxref{Really Various Summary Commands}).
@item
-Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
+Process mark sets can be pushed and popped (@pxref{Setting Process
+Marks}).
@item
-Digests (and other files) can be used as the basis for groups
-(@pxref{Document Groups}).
+A new mail-to-news backend makes it possible to post even when the NNTP
+server doesn't allow posting (@pxref{Mail-To-News Gateways}).
-@item
-Articles can be highlighted and customized (@pxref{Customizing
-Articles}).
+@item
+A new backend for reading searches from Web search engines
+(@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added
+(@pxref{Web Searches}).
-@item
-URLs and other external references can be buttonized (@pxref{Article
-Buttons}).
+@item
+Groups inside topics can now be sorted using the standard sorting
+functions, and each topic can be sorted independently (@pxref{Topic
+Sorting}).
@item
-You can do lots of strange stuff with the Gnus window & frame
-configuration (@pxref{Windows Configuration}).
+Subsets of the groups can be sorted independently (@code{Sorting
+Groups}).
@item
-You can click on buttons instead of using the keyboard
-(@pxref{Buttons}).
+Cached articles can be pulled into the groups (@pxref{Summary Generation
+Commands}).
+
+@item
+Score files are now applied in a more reliable order (@pxref{Score
+Variables}).
-@item
-Gnus can use NoCeM files to weed out spam (@pxref{NoCeM}).
+@item
+Reports on where mail messages end up can be generated (@pxref{Splitting
+Mail}).
+@item
+More hooks and functions have been added to remove junk from incoming
+mail before saving the mail (@pxref{Washing Mail}).
+
@end itemize
-This is, of course, just a @emph{short} overview of the @emph{most}
-important new features. No, really. There are tons more. Yes, we have
-feeping creaturism in full effect, but nothing too gratuitous, I would
-hope.
-
@node Newest Features
@subsection Newest Features
@item
Native @sc{mime} support is something that should be done.
@item
-A better and simpler method for specifying mail composing methods.
-@item
-Allow posting through mail-to-news gateways.
-@item
Really do unbinhexing.
@end itemize
And much, much, much more. There is more to come than has already been
implemented. (But that's always true, isn't it?)
-@code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
+@file{<URL:http://www.ifi.uio.no/~larsi/rgnus/todo>} is where the actual
up-to-the-second todo list is located, so if you're really curious, you
could point your Web browser over that-a-way.
+@iftex
+
+@node The Manual
+@section The Manual
+@cindex colophon
+@cindex manual
+
+This manual was generated from a TeXinfo file and then run through
+either @code{texi2dvi}
+@iflatex
+or my own home-brewed TeXinfo to \LaTeX\ transformer,
+and then run through @code{latex} and @code{dvips}
+@end iflatex
+to get what you hold in your hands now.
+
+The following conventions have been used:
+
+@enumerate
+
+@item
+This is a @samp{string}
+
+@item
+This is a @kbd{keystroke}
+
+@item
+This is a @file{file}
+
+@item
+This is a @code{symbol}
+
+@end enumerate
+
+So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would
+mean:
+
+@lisp
+(setq flargnoze "yes")
+@end lisp
+
+If I say ``set @code{flumphel} to @code{yes}'', that would mean:
+
+@lisp
+(setq flumphel 'yes)
+@end lisp
-@node Censorship
-@subsection Censorship
-@cindex censorship
+@samp{yes} and @code{yes} are two @emph{very} different things---don't
+ever get them confused.
-This version of the Gnus manual (as well as Gnus itself) has been
-censored in accord with the Communications Decency Act. This law was
-described by its proponents as a ban on pornography---which was a
-deception, since it prohibits far more than that. This manual did not
-contain pornography, but part of it was prohibited nonetheless.
+@iflatex
+@c @head
+Of course, everything in this manual is of vital interest, so you should
+read it all. Several times. However, if you feel like skimming the
+manual, look for that gnu head you should see in the margin over
+there---it means that what's being discussed is of more importance than
+the rest of the stuff. (On the other hand, if everything is infinitely
+important, how can anything be more important than that? Just one more
+of the mysteries of this world, I guess.)
+@end iflatex
-For information on US government censorship of the Internet, and
-what you can do to bring back freedom of the press, see the web
-site @samp{http://www.vtw.org/}.
+@end iftex
@node Terminology
@item article
@cindex article
-A nessage that has been posted as news.
+A message that has been posted as news.
@item mail message
@cindex mail message
@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}.
+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).
@item server
@item virtual server
@cindex virtual server
A named select method. Since a select methods defines all there is to
-know about connecting to a (physical) server, taking the who things as a
+know about connecting to a (physical) server, taking the things as a
whole is a virtual server.
+@item washing
+@cindex washing
+Taking a buffer and running it through a filter of some sort. The
+result will (more often than not) be cleaner and more pleasing than the
+original.
+
+@item ephemeral groups
+@cindex ephemeral groups
+Most groups store data on what articles you have read. @dfn{Ephemeral}
+groups are groups that will have no data stored---when you exit the
+group, it'll disappear into the aether.
+
+@item solid groups
+@cindex solid groups
+This is the opposite of ephemeral groups. All groups listed in the
+group buffer are solid groups.
+
@end table
@item
Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
how-to.
+
+@item
+@vindex max-lisp-eval-depth
+Gnus works on many recursive structures, and in some extreme (and very
+rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at
+you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or
+something like that.
@end enumerate
If all else fails, report the problem as a bug.
for all of us---if I don't have all the information I need, I will just
mail you and ask for more info, and everything takes more time.
+If the problem you're seeing is very visual, and you can't quite explain
+it, copy the Emacs window to a file (with @code{xwd}, for instance), put
+it somewhere it can be reached, and include the URL of the picture in
+the bug report.
+
If you just need help, you are better off asking on
@samp{gnu.emacs.gnus}. I'm not very helpful.
@node A Programmers Guide to Gnus
-@section A Programmer's Guide to Gnus
+@section A Programmer@'s Guide to Gnus
It is my hope that other people will figure out smart stuff that Gnus
can do, and that other people will write those smart things as well. To
* Headers:: How Gnus stores headers internally.
* Ranges:: A handy format for storing mucho numbers.
* Group Info:: The group info format.
+* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen.
* Various File Formats:: Formats of files that Gnus use.
@end menu
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.
+@dfn{resulting data}, I always refer to the data in that buffer. When I
+talk about @dfn{return value}, I talk about the function value returned by
+the function call. Functions that fail should return @code{nil} as the
+return value.
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
@menu
* Required Backend Functions:: Functions that must be implemented.
* Optional Backend Functions:: Functions that need not be implemented.
+* Error Messaging:: How to get messages and report errors.
* Writing New Backends:: Extending old backends.
+* Hooking New Backends Into Gnus:: What has to be done on the Gnus end.
@end menu
There should be no data returned by this function.
-@item (nnchoke-request-group GROUP &optional SERVER)
+@item (nnchoke-request-group GROUP &optional SERVER FAST)
Get data on @var{group}. This function also has the side effect of
making @var{group} the current group.
+If @var{FAST}, don't bother to return useful data, just make @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 @code{211}. Next is the
+The first number is the status, which should be 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
@code{news} if @var{article} in @var{group} is news, @code{mail} if it
is mail and @code{unknown} if the type can't be decided. (The
@var{article} parameter is necessary in @code{nnvirtual} groups which
-might very well combine mail groups and news groups.)
+might very well combine mail groups and news groups.) Both @var{group}
+and @var{article} may be @code{nil}.
There should be no result data from this function.
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 asynchronously, 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
@end table
+@node Error Messaging
+@subsubsection Error Messaging
+
+@findex nnheader-report
+@findex nnheader-get-report
+The backends should use the function @code{nnheader-report} to report
+error conditions---they should not raise errors when they aren't able to
+perform a request. The first argument to this function is the backend
+symbol, and the rest are interpreted as arguments to @code{format} if
+there are many of them, or just a string if there is one of them.
+This function always returns @code{nil}.
+
+@lisp
+(nnheader-report 'nnchoke "You did something totally bogus")
+
+(nnheader-report 'nnchoke "Could not request group %s" group)
+@end lisp
+
+Gnus, in turn, will call @code{nnheader-get-report} when it gets a
+@code{nil} back from a server, and this function returns the most
+recently reported message for the backend in question. This function
+takes one argument---the server symbol.
+
+Internally, these function access @var{backend}@code{-status-string}, so
+the @code{nnchoke} backend will have its error message stored in
+@code{nnchoke-status-string}.
+
+
@node Writing New Backends
@subsubsection Writing New Backends
-The various backends share many similarities. @code{nnml} is just like
+Many backends are quite similar. @code{nnml} is just like
@code{nnspool}, but it allows you to edit the articles on the server.
@code{nnmh} is just like @code{nnml}, but it doesn't use an active file,
and it doesn't maintain overview databases. @code{nndir} is just like
"*Non-nil means that nndir will never retrieve NOV headers."
nnml-nov-is-evil)
-\f
-
(defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group)
(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
(defvoo nndir-status-string "" nil nnmh-status-string)
(defconst nndir-version "nndir 1.0")
-\f
-
;;; Interface functions.
(nnoo-define-basics nndir)
(deffoo nndir-open-server (server &optional defs)
(setq nndir-directory
- (or (cadr (assq 'nndir-directory defs))
- server))
+ (or (cadr (assq 'nndir-directory defs))
+ server))
(unless (assq 'nndir-directory defs)
(push `(nndir-directory ,server) defs))
(push `(nndir-current-group
- ,(file-name-nondirectory (directory-file-name nndir-directory)))
- defs)
+ ,(file-name-nondirectory (directory-file-name nndir-directory)))
+ defs)
(push `(nndir-top-directory
- ,(file-name-directory (directory-file-name nndir-directory)))
- defs)
+ ,(file-name-directory (directory-file-name nndir-directory)))
+ defs)
(nnoo-change-server 'nndir server defs))
(nnoo-map-functions nndir
@end lisp
+@node Hooking New Backends Into Gnus
+@subsubsection Hooking New Backends Into Gnus
+
+@vindex gnus-valid-select-methods
+Having Gnus start using your new backend is rather easy---you just
+declare it with the @code{gnus-declare-backend} functions. This will
+enter the backend into the @code{gnus-valid-select-methods} variable.
+
+@code{gnus-declare-backend} takes two parameters---the backend name and
+an arbitrary number of @dfn{abilities}.
+
+Here's an example:
+
+@lisp
+(gnus-declare-backend "nnchoke" 'mail 'respool 'address)
+@end lisp
+
+The abilities can be:
+
+@table @code
+@item mail
+This is a mailish backend---followups should (probably) go via mail.
+@item post
+This is a newsish backend---followups should (probably) go via news.
+@item post-mail
+This backend supports both mail and news.
+@item none
+This is neither a post or mail backend---it's something completely
+different.
+@item respool
+It supports respooling---or rather, it is able to modify its source
+articles and groups.
+@item address
+The name of the server should be in the virtual server name. This is
+true for almost all backends.
+@item prompt-address
+The user should be prompted for an address when doing commands like
+@kbd{B} in the group buffer. This is true for backends like
+@code{nntp}, but not @code{nnmbox}, for instance.
+@end table
+
+
@node Score File Syntax
@subsection Score File Syntax
just shamelessly @emph{stole} the entire thing, and one would be right.
@dfn{Header} is a severely overloaded term. ``Header'' is used in
-RFC1036 to talk about lines in the head of an article (eg.,
+RFC1036 to talk about lines in the head of an article (e.g.,
@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 internally that it calls ``header'',
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 predictable names beginning with @code{mail-header-} and
-@code{mail-header-set-}, respectively.
+@code{xref}. There are macros for accessing and setting these
+slots---they all have predictable 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.
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
+that you want to qualify 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
(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.
+The first element is the @dfn{group name}---as Gnus knows the group,
+anyway. The second element is the @dfn{subscription level}, which
+normally is a small integer. The third element is a list of ranges of
+read articles. The fourth element is a list of lists of article marks
+of various kinds. The fifth element is the select method (or virtual
+server, if you like). The sixth element is a list of @dfn{group
+parameters}, which is what this section is about.
+
+Any of the last three elements may be missing if they are not required.
+In fact, the vast majority of groups will normally only have the first
+three elements, which saves quite a lot of cons cells.
Here's a BNF definition of the group info format:
in pseudo-BNF.
+@node Emacs/XEmacs Code
+@subsection Emacs/XEmacs Code
+@cindex XEmacs
+@cindex Emacsen
+
+While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the
+platforms must be the primary one. I chose Emacs. Not because I don't
+like XEmacs or Mule, but because it comes first alphabetically.
+
+This means that Gnus will byte-compile under Emacs with nary a warning,
+while XEmacs will pump out gigabytes of warnings while byte-compiling.
+As I use byte-compilation warnings to help me root out trivial errors in
+Gnus, that's very useful.
+
+I've also consistently used Emacs function interfaces, but have used
+Gnusey aliases for the functions. To take an example: Emacs defines a
+@code{run-at-time} function while XEmacs defines a @code{start-itimer}
+function. I then define a function called @code{gnus-run-at-time} that
+takes the same parameters as the Emacs @code{run-at-time}. When running
+Gnus under Emacs, the former function is just an alias for the latter.
+However, when running under XEmacs, the former is an alias for the
+following function:
+
+@lisp
+(defun gnus-xmas-run-at-time (time repeat function &rest args)
+ (start-itimer
+ "gnus-run-at-time"
+ `(lambda ()
+ (,function ,@@args))
+ time repeat))
+@end lisp
+
+This sort of thing has been done for bunches of functions. Gnus does
+not redefine any native Emacs functions while running under XEmacs---it
+does this @code{defalias} thing with Gnus equivalents instead. Cleaner
+all over.
+
+Of course, I could have chosen XEmacs as my native platform and done
+mapping functions the other way around. But I didn't. The performance
+hit these indirections impose on Gnus under XEmacs should be slight.
+
+
@node Various File Formats
@subsection Various File Formats
projects / gnus / blobdiff