\input texinfo @c -*-texinfo-*-
-@setfilename gnus.info
-@settitle September Gnus Manual
+@setfilename gnus
+@settitle Red Gnus Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
\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 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
@end menu
+
@node Starting Up
@chapter Starting Gnus
@cindex starting up
* 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
killed. Your system administrator should have set this variable to
something useful.
-Since she hasn't, Gnus will just subscribe you to a few randomly picked
-groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
-@dfn{whatever Lars thinks you should read}.)
+Since she hasn't, Gnus will just subscribe you to a few arbitrarily
+picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is here
+defined as @dfn{whatever Lars thinks you should read}.)
You'll also be subscribed to the Gnus documentation group, which should
help you with most common problems.
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 preferrably keep no native groups on those two
+levels.)
@node Slave Gnusii
@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
Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
+@node Changing Servers
+@section Changing Servers
+
+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 flake and you want to use another.
+
+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
+reads 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
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.
control on or off. Version control is off by default when saving the
startup files.
+@vindex gnus-init-file
+When Gnus starts, it will read the @code{gnus-site-init-file} (default
+@file{.../site-lisp/gnus.el}) and @code{gnus-init-file} (default
+@file{~/.gnus.el}) 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
@section Auto Save
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-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
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
@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 switced 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
@vindex gnus-large-newsgroup
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
(@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
@node Foreign Groups
@section 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
@kindex G r (Group)
@findex gnus-group-rename-group
Rename the current group to something else
-(@code{gnus-group-rename-group}). This is legal only on some groups --
-mail groups mostly. This command might very well be quite slow on some
-backends.
+(@code{gnus-group-rename-group}). This is legal only on some
+groups---mail groups mostly. This command might very well be quite slow
+on some backends.
@item G e
@kindex G e (Group)
@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}).
+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)
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)
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
-Read a random directory as if with were a newsgroup with the
+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)
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 n
+@kindex G n (Group)
+@findex gnus-group-make-web-group
+@cindex DejaNews
+@cindex Alta Vista
+@cindex InReference
+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)
If the group parameter list contains an element like @code{(to-group
. "some.group.name")}, all posts will be sent to that group.
+@item gcc-self
+@cindex gcc-self
+If this symbol is present in the group parameter list, new composed
+messages will be @code{Gcc}'d to the current group.
+
@item auto-expire
@cindex auto-expire
If this symbol is present in the group parameter list, all articles that
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 random comment on the group.
+This parameter allows you to enter a arbitrary comment on the group.
@item @var{(variable form)}
You can use the group parameters to set variables local to the group you
@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 @xref{Topic Parameters}.
@node Listing Groups
@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
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.
+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.
(@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
+will be use the @code{gnus-browse-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
* Topic Variables:: How to customize the topics the Lisp Way.
* Topic Commands:: Interactive E-Z commands.
* 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-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}).
@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}).
@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
(@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}).
@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.
@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
@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
allowed---@code{visible} and @code{invisible}.
+@node Topic Parameters
+@subsection 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 inheretance 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
+
+Now, 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 @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
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
@item M-f
@kindex M-f (Group)
@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} will be used for fetching
+the file.
+
+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 D
@kindex D (Group)
(@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
* 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
pushes everything after it off the screen).
@item \[
Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
-for adopted articles.
+for adopted articles (@pxref{Customizing Threading}).
@item \]
Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
for adopted articles.
@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
down summary buffer generation somewhat.
@item e
A single character 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
@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
@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)
@menu
* Summary Mail Commands:: Sending mail.
* Summary Post Commands:: Sending news.
-* Summary Mail and Post Commands:: Sending both news and mail.
@end menu
@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
@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
@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.
@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.
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)
@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
that have subjects that are fuzzily equal will be included.
+@node Sorting
+@section Sorting
+
+@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 Asynchronous Fetching
@section Asynchronous Article Fetching
@cindex asynchronous article fetching
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
* 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 enhavnced hessages) 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
@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}
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
@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}).
@item B i
@kindex B i (Summary)
@findex gnus-summary-import-article
-Import a random file into the current mail newsgroup
+Import an arbitrary file into the current mail newsgroup
(@code{gnus-summary-import-article}). You will be prompted for a file
name, a @code{From} header and a @code{Subject} header.
-Something similar can be done by just starting to compose a mail
-message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
-@kbd{C-c 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
@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
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
@cindex LIST overview.fmt
@cindex overview.fmt
To check whether your @sc{nntp} server includes the @code{Xref} header
-in its overview files, try @samp{telnet your.nntp.server nntp} and then
-say @samp{LIST overview.fmt}. This may not work, but if it does, and
-the last line you get does not read @samp{Xref:full}, then you should
-shout and whine at your news admin until she includes the @code{Xref}
-header in the overview files.
+in its overview files, try @samp{telnet your.nntp.server nntp},
+@samp{MODE READER} on @code{inn} servers, and then say @samp{LIST
+overview.fmt}. This may not work, but if it does, and the last line you
+get does not read @samp{Xref:full}, then you should shout and whine at
+your news admin until she includes the @code{Xref} header in the
+overview files.
@vindex gnus-nov-is-evil
If you want Gnus to get the @code{Xref}s right all the time, you have to
C'est la vie.
+For an alternative approach, @xref{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 crossposing 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 preferrable 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
@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
@cindex post
@kindex C-c C-c (Post)
-All commands for posting and mailing will put you in a post or mail
-buffer where you can edit the article all you like, before you send the
-article by pressing @kbd{C-c C-c}. 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.
+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
* Mail:: Mailing and replying.
* 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?
+@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
Variables for customizing outgoing mail:
@table @code
-@item gnus-reply-to-function
-@vindex gnus-reply-to-function
-Gnus uses the normal methods to determine where replies are to go, but
-you can change the behavior to suit your needs by fiddling with this
-variable.
-
-If you want the replies to go to the @code{Sender} instead of the
-@code{From} in the group @samp{mail.stupid-list}, you could do something
-like this:
-
-@lisp
-(setq gnus-reply-to-function
- (lambda (group)
- (cond ((string= group "mail.stupid-list")
- (mail-fetch-field "sender"))
- (t
- nil))))
-@end lisp
-
-This function will be called narrowed to 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.
-
-@item gnus-mail-send-method
-@vindex gnus-mail-send-method
-@vindex send-mail-function
-@findex sendmail-send-it
-This variable says how a mail should be mailed. It uses the function in
-the @code{send-mail-function} variable as the default, which usually is
-@code{sendmail-send-it}.
-
@item gnus-uu-digest-headers
@vindex gnus-uu-digest-headers
List of regexps to match headers included in digested messages. The
headers will be included in the sequence they are matched.
-@item gnus-mail-hook
-@vindex gnus-mail-hook
-Hook called as the last thing after setting up a mail buffer.
-
-@item gnus-required-mail-headers
-@vindex gnus-required-mail-headers
-@cindex sendmail
-Gnus will generate headers in all outgoing mail instead of letting
-@code{sendmail} do it for us. This makes it possible to do more neat
-stuff, like putting mail without sending it, do hairy @code{Fcc}
-handling, and much more. This variable controls what headers Gnus will
-generate, and is of the exact same form as @code{gnus-required-headers},
-which does the same for news articles (@pxref{Post}).
-
-@cindex X-Mailer
-The @code{Newsgroups} header is illegal in this list, while @code{To} is
-required, and @code{X-Mailer} can be added if you so should want.
-
-@vindex gnus-forward-start-separator
-@item gnus-forward-start-separator
-Delimiter inserted before forwarded messages.
-
-@vindex gnus-forward-end-separator
-@item gnus-forward-end-separator
-Delimiter inserted after forwarded messages.
-
-@vindex gnus-signature-before-forwarded-message
-@item gnus-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.
-
-@item gnus-forward-included-headers
-@vindex gnus-forward-included-headers
-Regexp matching header lines to be included in forwarded messages. It
-uses the same regexp as @code{gnus-visible-headers} by default.
-
-@end table
-
-@kindex C-c M-C-c (Mail)
-@kindex C-c M-C-p (Mail)
-@findex gnus-put-message
-You normally send a mail message by pressing @kbd{C-c C-c}. However,
-you may wish to just put the mail message you have just written in your
-own local mail group instead of sending it. Sounds quite unlikely, but
-I found that useful, so you can now also press @kbd{C-c M-C-p} to
-@dfn{put} the article in the current mail group, or, if there is no such
-thing, you will be prompted for a mail group, and then the article will
-be put there. This means that the article is @dfn{not} mailed.
-
-@findex gnus-kill-message-buffer
-@cindex kill mail buffer
-@kindex C-x k (Mail)
-@kindex C-x k (Post)
-If enter a mail (or post) buffer and then decide not to compose a
-message after all, you'd normally just kill the buffer with @kbd{C-x k}.
-However, since the mail and post buffers are associated with articles in
-the draft group, this will leave lots of rubbish articles in the draft
-group. To avoid that problem, kill mail and post buffer with @kbd{C-c
-C-k} (@code{gnus-kill-message-buffer}) instead. This will make sure
-that everything is properly cleaned up before the buffer is killed.
-
-@vindex gnus-mail-method
-There are three ``methods'' for handling all mail. The default is
-@code{sendmail}. Some people like what @code{mh} does better, and some
-people prefer @code{vm}. Set @code{gnus-mail-method} to the one you
-think is way koolest.
-
-Three variables for customizing what to use when:
-
-@table @code
-
-@vindex gnus-mail-reply-method
-@item gnus-mail-reply-method
-This function is used to compose replies. The three functions available
-are:
-
-@findex gnus-mail-reply-using-vm
-@findex gnus-mail-reply-using-mhe
-@findex gnus-mail-reply-using-mail
-@itemize @bullet
-@item
-@code{gnus-mail-reply-using-mail} (sendmail)
-@item
-@code{gnus-mail-reply-using-mhe} (mh)
-@item
-@code{gnus-mail-reply-using-vm} (vm)
-@end itemize
-
-@vindex gnus-mail-forward-method
-@item gnus-mail-forward-method
-This function is used to forward messages. The three functions available
-are:
-
-@findex gnus-mail-forward-using-vm
-@findex gnus-mail-forward-using-mhe
-@findex gnus-mail-forward-using-mail
-@itemize @bullet
-@item
-@code{gnus-mail-forward-using-mail} (sendmail)
-@item
-@code{gnus-mail-forward-using-mhe} (mh)
-@item
-@code{gnus-mail-forward-using-vm} (vm)
-@end itemize
-
-@vindex gnus-mail-other-window-method
-@item gnus-mail-other-window-method
-This function is used to send mails. The three functions available are:
-
-@findex gnus-mail-other-window-using-vm
-@findex gnus-mail-other-window-using-mhe
-@findex gnus-mail-other-window-using-mail
-@itemize @bullet
-@item
-@code{gnus-mail-other-window-using-mail} (sendmail)
-@item
-@code{gnus-mail-other-window-using-mhe} (mh)
-@item
-@code{gnus-mail-other-window-using-vm} (vm)
-@end itemize
-
@end table
Variables for composing news articles:
-@vindex gnus-required-headers
-@code{gnus-required-headers} a list of header symbols. These headers
-will either be automatically generated, or, if that's impossible, they
-will be prompted for. The following symbols are legal:
-
-@table @code
-
-@item From
-@cindex From
-@findex gnus-inews-user-name
-@vindex gnus-user-from-line
-@vindex gnus-user-login-name
-@vindex gnus-local-domain
-@vindex user-mail-address
-This required header will be filled out with the result of the
-@code{gnus-inews-user-name} function, which depends on the
-@code{gnus-user-from-line}, @code{gnus-user-login-name},
-@code{gnus-local-domain} and @code{user-mail-address} variables.
-
-@item Subject
-@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
-@vindex gnus-local-organization
-@vindex gnus-organization-file
-This optional header will be filled out depending on the
-@code{gnus-local-organization} variable. @code{gnus-organization-file}
-will be used if that variable is nil.
-
-@item Lines
-@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 with the Gnus version numbers.
-
-@item Expires
-@vindex gnus-article-expires
-@cindex Expires
-This extremely optional header will be inserted according to the
-@code{gnus-article-expires} variable. It is highly deprecated and
-shouldn't be used unless you know what you're doing.
-
-@item Distribution
-@cindex Distribution
-@findex gnus-distribution-function
-This optional header is filled out according to the
-@code{gnus-distribution-function} variable. It is a deprecated and much
-misunderstood header.
-
-@item Path
-@cindex path
-@vindex gnus-use-generic-path
-This extremely optional header should probably not ever be used.
-However, some @emph{very} old servers require that this header is
-present. @code{gnus-use-generic-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.
-
-The list contains a cons where the car of the cons is @code{optional},
-the cdr of this cons will only be inserted if it is non-@code{nil}.
-
-Other variables for customizing outgoing articles:
-
-@table @code
-@item nntp-news-default-headers
-@vindex nntp-news-default-headers
-If non-@code{nil}, this variable will override
-@code{mail-default-headers} when posting. This variable should then be
-a string. This string will be inserted, as is, in the head of all
-outgoing articles.
-
-@item gnus-use-followup-to
-@vindex gnus-use-followup-to
-If @code{nil}, always ignore the Followup-To header. If it is @code{t},
-use its value, but ignore the special value @samp{poster}, which will
-send the followup as a reply mail to the person you are responding to.
-If it is the symbol @code{ask}, query the user before posting.
-If it is the symbol @code{use}, always use the value.
-
-@item gnus-followup-to-function
-@vindex gnus-followup-to-function
-This variable is most useful in mail groups, where ``following up''
-really means sending a mail to a list address. Gnus uses the normal
-methods to determine where follow-ups are to go, but you can change the
-behavior to suit your needs by fiddling with this variable.
-
-If you want the followups to go to the @code{Sender} instead of the
-@code{From} in the group @samp{mail.stupid-list}, you could do something
-like this:
-
-@lisp
-(setq gnus-followup-to-function
- (lambda (group)
- (cond ((string= group "mail.stupid-list")
- (mail-fetch-field "sender"))
- (t
- nil))))
-@end lisp
-
-This function will be called narrowed to header of the article that is
-being followed up.
-
-@item gnus-removable-headers
-@vindex gnus-removable-headers
-@cindex NNTP-Posting-Host
-Some headers that are generated are toxic to the @sc{nntp} server.
-These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
-so these headers are deleted if they are present in this list of
-symbols.
-
-@item gnus-deletable-headers
-@vindex gnus-deletable-headers
-Headers in this list that were previously generated by Gnus will be
-deleted before posting. Let's say you post an article. Then you decide
-to post it again to some other group, you naughty boy, so you jump back
-to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
-ship it off again. By default, this variable makes sure that the old
-generated @code{Message-ID} is deleted, and a new one generated. If
-this isn't done, the entire empire would probably crumble, anarchy would
-prevail, and cats would start walking on two legs and rule the world.
-Allegedly.
-
-@item gnus-signature-function
-@vindex gnus-signature-function
-If non-@code{nil}, this variable should be a function that returns a
-signature file name. The function will be called with the name of the
-group being posted to. If the function returns a string that doesn't
-correspond to a file, the string itself is inserted. If the function
-returns @code{nil}, the @code{gnus-signature-file} variable will be used
-instead.
-
-@item gnus-post-prepare-function
-@vindex gnus-post-prepare-function
-This function is called with the name of the current group after the
-post buffer has been initialized, and can be used for inserting a
-signature. Nice if you use different signatures in different groups.
-
-@item gnus-post-prepare-hook
-@vindex gnus-post-prepare-hook
-@findex gnus-inews-insert-signature
-This hook is called after a post buffer has been prepared. If you want
-to insert a signature at this point, you could put
-@code{gnus-inews-insert-signature} into this hook.
-
-@item news-reply-header-hook
-@vindex news-reply-header-hook
-A related variable when following up and replying is this variable,
-which inserts the @dfn{quote line}. The default value is:
-
-@lisp
-(defvar news-reply-header-hook
- (lambda ()
- (insert "In article " news-reply-yank-message-id
- " " news-reply-yank-from " writes:\n\n")))
-@end lisp
-
-This will create lines like:
-
-@example
-In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
-@end example
-
-Having the @code{Message-ID} in this line is probably overkill, so I
-would suggest this hook instead:
-
-@lisp
-(setq news-reply-header-hook
- (lambda () (insert news-reply-yank-from " writes:\n\n")))
-@end lisp
-
-@item gnus-prepare-article-hook
-@vindex gnus-prepare-article-hook
-This hook is called before the headers have been prepared.
-
-@item gnus-inews-article-function
-@vindex gnus-inews-article-function
-This function is used to do the actual article processing and header
-checking/generation.
-
-@item gnus-inews-article-hook
-@vindex gnus-inews-article-hook
-This hook is called right before the article is posted. By default it
-handles FCC processing (i.e., saving the article to a file.) You can
-also have this hook add a score to all followups to the article you've
-written (@pxref{Followups To Yourself}).
-
-@item gnus-inews-article-header-hook
-@vindex gnus-inews-article-header-hook
-@cindex *post-news*
-This hook is called after inserting the required headers in an article
-to be posted. The hook is called from the @code{*post-news*} buffer,
-narrowed to the head, and is intended for people who would like to
-insert additional headers, or just change headers in some way or other.
-
-@item gnus-check-before-posting
-@vindex gnus-check-before-posting
-If non-@code{nil}, Gnus will attempt to check the legality of the
-headers, as well as some other stuff, before posting. You can control
-the granularity of the check by adding or removing elements from this
-list. Legal elements are:
-
@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
-
-All these conditions are checked by default.
-
@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
posting:
@table @code
-@item gnus-signature-file
-@itemx mail-signature
-@vindex mail-signature
-@vindex gnus-signature-file
-@cindex double signature
-@cindex signature
-If @code{gnus-signature-file} is non-@code{nil}, it should be the name
-of a file containing a signature (@file{~/.signature} by default). This
-signature will be appended to all outgoing post. Most people find it
-more convenient to use @code{mail-signature}, which (sort of) does the
-same, but inserts the signature into the buffer before you start editing
-the post (or mail). So---if you have both of these variables set, you
-will get two signatures. Note that @code{mail-signature} does not work
-the same way as @code{gnus-signature-file}, which is a bit confusing.
-If @code{mail-signature} is @code{t}, it will insert
-@file{~/.signature}. If it is a string, this string will be inserted.
-
-Note that RFC1036 says that a signature should be preceded by the three
-characters @samp{-- } on a line by themselves. This is to make it
-easier for the recipient to automatically recognize and process the
-signature. So don't remove those characters, even though you might feel
-that they ruin you beautiful design, like, totally.
-
-Also note that no signature should be more than four lines long.
-Including ASCII graphics is an efficient way to get everybody to believe
-that you are silly and have nothing important to say.
-
-@item mail-yank-prefix
-@vindex mail-yank-prefix
-@cindex yanking
-@cindex quoting
-When you are replying to or following up an article, you normally want
-to quote the person you are answering. Inserting quoted text is done by
-@dfn{yanking}, and each quoted line you yank will have
-@code{mail-yank-prefix} prepended to it. This is @code{nil} by default,
-which isn't very pretty---the prefix will just be some spaces. Most
-everybody prefers that lines are prepended with @samp{> }, so
-@code{(setq mail-yank-prefix "> ")} in your @file{.emacs} file.
-
-@item mail-yank-ignored-headers
-@vindex mail-yank-ignored-headers
-When you yank a message, you do not want to quote any headers, so
-@code{(setq mail-yank-ignored-headers "^")}.
-
-@item user-mail-address
-@vindex user-mail-address
-@vindex gnus-user-login-name
-@vindex gnus-use-generic-from
-@vindex gnus-local-domain
-If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
-@code{gnus-local-domain} are @code{nil}, Gnus will use
-@code{user-mail-address} as the address part of the @code{From} header.
-
-@item gnus-local-domain
-@vindex gnus-local-domain
-@cindex domain
-The local domain name excluding the host name. If your host is called
-@samp{narfi.ifi.uio.no}, then this variable should be
-@samp{ifi.uio.no}.
-
-@item gnus-local-domain
-@vindex gnus-local-domain
-@cindex domain
-The local domain name excluding the host name. If your host is called
-@samp{narfi.ifi.uio.no}, then this variable should be
-@samp{ifi.uio.no}.
-
-@item gnus-user-from-line
-@vindex gnus-user-from-line
-Your full, complete e-mail address with name. This variable overrides
-the other Gnus variables if it is non-@code{nil}.
-
-Here are two example values of this variable: @samp{larsi@@ifi.uio.no
-(Lars Magne Ingebrigtsen)} and @samp{Lars Magne Ingebrigtsen
-<larsi@@ifi.uio.no>}. The latter version is recommended in news (and is
-probably illegal in mail), but the name has to be quoted if it contains
-non-alpha-numerical characters---@samp{\"Lars M. Ingebrigtsen\"
-<larsi@@ifi.uio.no>}.
-
-@item mail-default-headers
-@vindex mail-default-headers
-This is a string that will be inserted into the header of all outgoing
-mail messages and news articles. Convenient to use to insert standard
-headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
-variable will override this one when posting articles.
-
-@item gnus-auto-mail-to-author
-@vindex gnus-auto-mail-to-author
-If @code{ask}, you will be prompted for whether you want to send a mail
-copy to the author of the article you are following up. If
-non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
-all follow-ups to the authors of the articles you follow up. It's nice
-in one way---you make sure that the person you are responding to gets
-your response. Other people loathe this method and will hate you dearly
-for it, because it means that they will first get a mail, and then have
-to read the same article later when they read the news. It is
-@code{nil} by default.
-
-@item gnus-mail-courtesy-message
-@vindex gnus-mail-courtesy-message
-This is a string that will be prepended to all mails that are the result
-of using the variable described above.
-
@item gnus-mailing-list-groups
@findex gnus-mailing-list-groups
@cindex mailing lists
lists will work most of the time. Posting to these groups (@kbd{a}) is
still a pain, though.
-@item mail-citation-hook
-@vindex mail-citation-hook
-This hook is run after yanking a message, both in mail and post
-buffers. Point will be at the beginning of the yanked message and mark
-will be at the end. If this hook is non-@code{nil} the yanked text
-won't be indented automatically---you have to do that explicitly.
-
-For instance, if you want to remove signatures automatically, you could
-say something like:
-
-@lisp
-(add-hook 'mail-citation-hook 'gnus-inews-remove-signature)
-@end lisp
-
-This function indents the cited message and then removes the
-signature. If you decide you want to include the signature after all,
-you can just press the @code{undo} key.
-
@end table
You may want to do spell-checking on messages that you send out. Or, if
you don't want to spell-check by hand, you could add automatic
spell-checking via the @code{ispell} package:
-@vindex news-inews-hook
@cindex ispell
@findex ispell-message
@lisp
-(add-hook 'news-inews-hook 'ispell-message) ;For news posts
-(add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
+(add-hook 'message-send-hook 'ispell-message)
@end lisp
-@findex gnus-inews-insert-mime-headers
-If you want to insert some @sc{mime} headers into the articles you post,
-without doing any actual encoding, you could add
-@code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
-
@node Archived Messages
@section Archived 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.
+the mail. If you want to disable this completely, you should set
+@code{gnus-message-archive-group} to @code{nil}.
@vindex gnus-message-archive-method
@code{gnus-message-archive-method} says what virtual server Gnus is to
(setq gnus-message-archive-method
'(nnfolder "archive"
(nnfolder-inhibit-expiry t)
- (nnfolder-active-file "~/Mail/sent-mail/active")
+ (nnfolder-active-file "~/News/sent-mail/active")
(nnfolder-directory "~/News/sent-mail/")))
@end lisp
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
Let's illustrate:
More complex stuff:
@lisp
(setq gnus-message-archive-group
- '((if (eq major-mode news-reply-mode)
+ '((if (message-news-p)
"misc-news"
"misc-mail")))
@end lisp
-This is the default.
-
How about storing all news messages in one file, but storing all mail
messages in one file per month:
@lisp
(setq gnus-message-archive-group
- '((if (eq major-mode news-reply-mode)
+ '((if (message-news-p)
"misc-news"
(concat "mail." (format-time-string
"%Y-%m" (current-time))))))
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
+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.
That's the default method of archiving sent mail. Gnus also offers two
that case you should set @code{gnus-message-archive-group} to
@code{nil}; this will disable archiving.
-@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:
-
-@lisp
-(setq gnus-author-copy
- "|/usr/local/lib/mh/rcvstore +Article")
-@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.
+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.
-@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-mail-self-blind
-@vindex gnus-mail-self-blind
-Non-@code{nil} means insert a BCC header in all outgoing articles
-pointing to yourself. This will result you receiving a copy of the
-article mailed to yourself. The BCC header is inserted when the post
-buffer is initialized, so you can remove or alter the BCC header to
-override the default.
+@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
@end table
-@node Posting Styles
-@section Posting Styles
-@cindex posting styles
-@cindex styles
-
-All them variables, they make my head swim.
-
-So what if you want a different @code{Organization} and signature based
-on what groups you post to? And you post both from your home machine
-and your work machine, and you want different @code{From} lines, and so
-on?
-
-@vindex gnus-posting-styles
-One way to do stuff like that is to write clever hooks that change the
-variables you need to have changed. That's a bit boring, so somebody
-came up with the bright idea of letting the user specify these things in
-a handy alist. Here's an example of a @code{gnus-posting-styles}
-variable:
-
-@lisp
-((".*"
- (signature . "Peace and happiness")
- (organization . "What me?"))
- ("^comp"
- (signature . "Death to everybody"))
- ("comp.emacs.i-love-it"
- (organization . "Emacs is it")))
-@end lisp
-
-As you might surmise from this example, this alist consists of several
-@dfn{styles}. Each style will be applicable if the first element
-``matches'', in some form or other. The entire alist will be iterated
-over, from the beginning towards the end, and each match will be
-applied, which means that attributes in later styles that match override
-the same attributes in earlier matching styles. So
-@samp{comp.programming.literate} will have the @samp{Death to everybody}
-signature and the @samp{What me?} @code{Organization} header.
-
-The first element in each style is called the @code{match}. If it's a
-string, then Gnus will try to regexp match it against the group name.
-If it's a function symbol, that function will be called with no
-arguments. If it's a variable symbol, then the variable will be
-referenced. If it's a list, then that list will be @code{eval}ed. In
-any case, if this returns a non-@code{nil} value, then the style is said
-to @dfn{match}.
-
-Each style may contain a random amount of @dfn{attributes}. Each
-attribute consists of a @var{(name . value)} pair. The attribute name
-can be one of @code{signature}, @code{organization} or @code{from}.
-The attribute name can also be a string. In that case, this will be
-used as a header name, and the value will be inserted in the headers of
-the article.
-
-The attribute value can be a string (used verbatim), a function (the
-return value will be used), a variable (its value will be used) or a
-list (it will be @code{eval}ed and the return value will be used).
-
-So here's a new example:
-
-@lisp
-(setq gnus-posting-styles
- '((".*"
- (signature . "~/.signature")
- (from . "user@@foo (user)")
- ("X-Home-Page" . (getenv "WWW_HOME"))
- (organization . "People's Front Against MWM"))
- ("^rec.humor"
- (signature . my-funny-signature-randomizer))
- ((equal (system-name) "gnarly")
- (signature . my-quote-randomizer))
- (posting-from-work-p
- (signature . "~/.work-signature")
- (from . "user@@bar.foo (user)")
- (organization . "Important Work, Inc"))
- ("^nn.+:"
- (signature . "~/.mail-signature"))))
-@end lisp
-
-
-@node Drafts
-@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.
-
+@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 Select Methods
@chapter Select Methods
backend, and the second is the @dfn{address}, or @dfn{name}, if you
will.
-After these two elements, there may be a random number of @var{(variable
-form)} pairs.
+After these two elements, there may be a arbitrary number of
+@var{(variable form)} pairs.
To go back to the first example---imagine that you want to read from
port @code{15} from that machine. This is what the select method should
Mark the current server as unreachable
(@code{gnus-server-deny-server}).
+@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}).
+
+@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 R
@kindex R (Server)
@findex gnus-server-remove-denials
@cindex news backends
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.
+only two methods of getting news---it can read from an @sc{nntp} server,
+or it can read from a local spool.
@menu
* NNTP:: Reading news from an @sc{nntp} server.
@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.
+the server with the @code{nntp-send-mode-reader} function.
+
+@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 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
@menu
* Getting Started Reading Mail:: A simple cookbook example.
* Splitting Mail:: How to create mail groups.
-* Mail Variables:: Variables for customizing mail handling.
+* 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?
element is a regular expression used on the header of each mail to
determine if it belongs in this mail group.
+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
month's rent money.
-@node Mail Variables
-@subsection Mail Variables
+@node Mail Backend Variables
+@subsection Mail Backend Variables
These variables are (for the most part) pertinent to all the various
mail backends.
@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
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.
+@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.
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
This is run in a buffer that holds all the new incoming mail, and can be
used for, well, anything, really.
+@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 perfromed
+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
file after splitting mail into the proper groups. This is @code{nil} by
default for reasons of security.
+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.
+
@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
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.
+play with the @code{nnmail-split-fancy} variable.
Let's look at an example value of this variable first:
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:
+the five possible split syntaxes:
@table @dfn
@item (& SPLIT...)
If the split is a list, and the first element is @code{&}, then process
all SPLITs in the list.
+
+@item junk
+Junk this article.
@end table
In these splits, FIELD must match a complete field name. VALUE must
@node Duplicates
@subsection Duplicates
-@vindex nnmail-delete-duplicates
+@vindex nnmail-treat-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
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
+@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
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''.
+* 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
From the @code{nndir} backend (which reads a single spool-like
directory), it's just a hop and a skip to @code{nneething}, which
-pretends that any random directory is a newsgroup. Strange, but true.
+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
forgetting. @code{nneething} does this in a two-step process. First, it
snoops each file in question. If the file looks like an article (i.e.,
the first few lines look like headers), it will use this as the head.
-If this is just some random file without a head (eg. a C source file),
-@code{nneething} will cobble up a header out of thin air. It will use
-file ownership, name and date and do whatever it can with these
+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.
All this should happen automatically for you, and you will be presented
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!
+@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:
and @code{news}.
@end table
+@menu
+* Document Server Internals:: How to add your own document types.
+@end menu
+
+
+@node Document Server Internals
+@subsubsection Document Server Internals
+
+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}.
+
+First, here's an example document type definition:
+
+@example
+(mmdf
+ (article-begin . "^\^A\^A\^A\^A\n")
+ (body-end . "^\^A\^A\^A\^A\n"))
+@end example
+
+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.
+
+@item article-begin
+This setting has to be present in all document type definitions. It
+says what the beginning of each article looks like.
+
+@item head-begin-function
+If present, this should be a function that moves point to the head of
+the article.
+
+@item nndoc-head-begin
+If present, this should be a regexp that matches the head of the
+article.
+
+@item nndoc-head-end
+This should match the end of the head of the article. It defaults to
+@samp{"^$"}---the empty line.
+
+@item body-begin-function
+If present, this function should move point to the beginning of the body
+of the article.
+
+@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 spcae; 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
In specific, this is what it does:
@lisp
-(setq gnus-inews-article-function 'nnsoup-request-post)
-(setq send-mail-function 'nnsoup-request-mail)
+(setq message-send-news-function 'nnsoup-request-post)
+(setq message-send-mail-function 'nnsoup-request-mail)
@end lisp
And that's it, really. If you only want news to go into the @sc{soup}
@sc{soup}ed you use the second.
-@node Combined Groups
-@section Combined Groups
+@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 n} 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'etre} 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}.
-Gnus allows combining a mixture of all the other group types into bigger
-groups.
+Virtual server variables:
-@menu
-* Virtual Groups:: Combining articles from many groups.
-* Kibozed Groups:: Looking through parts of the newsfeed for articles.
-@end menu
+@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:
+@table @code
+@item article
+Function to decode the article and provide something that Gnus
+understands.
-@node Virtual Groups
-@subsection Virtual Groups
-@cindex nnvirtual
-@cindex virtual groups
+@item map
+Function to create an article number to message header and URL alist.
-An @dfn{nnvirtual group} is really nothing more than a collection of
-other groups.
+@item search
+Function to send the search string to the search engine.
-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!
+@item address
+The address the aforementioned function should send the search string
+to.
-You specify @code{nnvirtual} as the method. The address should be a
-regexp to match component groups.
+@item id
+Format string URL to fetch an article by @code{Message-ID}.
+@end table
-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
+@end table
+
+
+
+@node Mail-To-News Gateways
+@subsection Mail-To-News Gateways
+@cindex mail-to-news gateways
+@cindex gateways
+
+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.
+
+Note that you can't read anything from this backend---it can only be
+used to post with.
+
+Server variables:
+
+@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:
+
+@example
+Newsgroups: alt.religion.emacs
+@end example
+
+will get this @code{From} header inserted:
+
+@example
+To: alt-religion-emacs@@GATEWAY
+@end example
+
+@end table
+
+So, to use this, simply say something like:
+
+@lisp
+(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
+@end lisp
+
+
+@node Combined Groups
+@section Combined Groups
+
+Gnus allows combining a mixture of all the other group types into bigger
+groups.
+
+@menu
+* Virtual Groups:: Combining articles from many groups.
+* Kibozed Groups:: Looking through parts of the newsfeed for articles.
+@end menu
+
+
+@node Virtual Groups
+@subsection Virtual Groups
+@cindex nnvirtual
+@cindex virtual groups
+
+An @dfn{nnvirtual group} is really nothing more than a collection of
+other groups.
+
+For instance, if you are tired of reading many small group, you can
+put them all in one big group, and then grow tired of reading one
+big, unwieldy group. The joys of computing!
+
+You specify @code{nnvirtual} as the method. The address should be a
+regexp to match component groups.
+
+All marks in the virtual group will stick to the articles in the
+component groups. So if you tick an article in a virtual group, the
article will also be ticked in the component group from whence it came.
(And vice versa---marks from the component groups will also be shown in
the virtual group.)
you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
with useless requests! Oh happiness!
+@kindex G k (Group)
+To create a kibozed group, use the @kbd{G k} command in the group
+buffer.
+
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}
* 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.
+* 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
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 cahe (@code{gnus-score-flush-cache}). This is useful
+after editing score files.
+
@item V C
@kindex V C (Summary)
@findex gnus-score-customize
Prompt for a score, and mark all articles with a score below this as
read (@code{gnus-score-set-mark-below}).
-@item V E
-@kindex V E (Summary)
+@item V x
+@kindex V x (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}).
+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
The keystrokes for actually making score entries follow a very regular
entries will result in new score entries being added for all follow-ups
to articles that matches these score entries.
-Following this key is a random number of score entries, where each score
-entry has one to four elements.
+Following this key is a arbitrary number of score entries, where each
+score entry has one to four elements.
@enumerate
@item
@table @dfn
@item From, Subject, References, Xref, Message-ID
-For most header types, there are the @code{r} and @code{R} (regexp) as
-well as @code{s} and @code{S} (substring) types and @code{e} and
-@code{E} (exact match) types. If this element is not present, Gnus will
-assume that substring matching should be used. @code{R} and @code{S}
-differ from the other two in that the matches will be done in a
-case-sensitive manner. All these one-letter types are really just
-abbreviations for the @code{regexp}, @code{string} and @code{exact}
-types, which you can use instead, if you feel like.
+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 Lines, Chars
These two headers use different match types: @code{<}, @code{>},
@code{=}, @code{>=} and @code{<=}.
@item Date
-For the Date header we have three match types: @code{before}, @code{at}
-and @code{after}. I can't really imagine this ever being useful, but,
-like, it would feel kinda silly not to provide this function. Just in
-case. You never know. Better safe than sorry. Once burnt, twice shy.
-Don't judge a book by its cover. Never not have sex on a first date.
+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.)
+
+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, which looks like @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)
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
+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.
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}.
+@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)}.
@vindex gnus-default-adaptive-score-alist
To give you complete control over the scoring process, you can customize
As you see, each element in this alist has a mark as a key (either a
variable name or a ``real'' mark---a character). Following this key is
-a random number of header/score pairs. If there are no header/score
+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
this variable is @code{nil}, exact matching will always be used to avoid
this problem.
+@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.
+
+@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
+
+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.
+
+@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.
+
+@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-consituant characters.
+
+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.
+
+
+@node Home Score File
+@section Home Score File
+
+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}.
+
+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.
+
+@vindex gnus-home-score-file
+The variable that controls this is @code{gnus-home-score-file}. It can
+be:
+
+@enumerate
+@item
+A string. Then this file will be used as the home score file for all
+groups.
+
+@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
+A list. The elements in this list can be:
+
+@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.
+
+@item
+A string. Use the string as the home score file.
+@end enumerate
+
+The list will be traversed from the beginning towards the end looking
+for matches.
+
+@end enumerate
+
+So, if you want to use just a single score file, you could say:
+
+@lisp
+(setq gnus-home-score-file
+ "my-total-score-file.SCORE")
+@end lisp
+
+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:
+
+@lisp
+(setq gnus-home-score-file
+ 'gnus-hierarchial-home-score-file)
+@end lisp
+
+This is a ready-made function provided for your convenience.
+
+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.
+
+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
+presedence over this variable.
+
@node Followups To Yourself
@section Followups To Yourself
your own article.
@end table
-@vindex gnus-inews-article-hook
+@vindex message-sent-hook
These two functions are both primarily meant to be used in hooks like
-@code{gnus-inews-article-hook}.
+@code{message-sent-hook}.
+
+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
+<x6u3u47icf.fsf@@eyesore.no>
+<x6sp9o7ibw.fsf@@eyesore.no>
+@end example
+
+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:
+
+@lisp
+("references"
+ "<x6[0-9a-z]+\\.fsf@.*eyesore.no>" 1000 nil r)
+@end lisp
+
+Whether it's the first two or first three characters that are ``yours''
+is system-dependent.
@node Scoring Tips
@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 don't want kill files
-to be processed, you should set this variable to @code{nil}.
+@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 gnus-kill-file-mode-hook
@vindex gnus-kill-file-mode-hook
@end table
+@node GroupLens
+@section GroupLens
+@cindex GroupLens
+
+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.
+
+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.
+
+@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
+
+
+@node Using GroupLens
+@subsection Using GroupLens
+
+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}.
+
+Once you have registered you'll need to set a couple of variables.
+
+@table @code
+
+@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 grouplens-pseudonym
+@vindex grouplens-pseudonym
+This variable should be set to the pseudonum you got when registering
+with the Better Bit Bureau.
+
+@item grouplens-newsgroups
+@vindex grouplens-newsgroups
+A list of groups that you want to get GroupLens predictions for.
+
+@end table
+
+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 Rating Articles
+@subsection Rating Articles
+
+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.
+
+@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.
+
+@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.
+
+@end table
+
+The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
+the score of the article you're reading.
+
+@table @kbd
+
+@item 1-5 n
+@kindex n (GroupLens)
+@findex grouplens-next-unread-article
+Rate the article and go to the next unread article.
+
+@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
+
+If you want to give the current article a score of 4 and then go to the
+next article, just type @kbd{4 n}.
+
+
+@node Displaying Predictions
+@subsection Displaying Predictions
+
+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}.
+
+@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.
+
+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 confidence-interval
+A numeric confidence interval.
+
+@item prediction-bar
+The higher the prediction, the longer the bar.
+
+@item confidence-bar
+Numerical confidence.
+
+@item confidence-spot
+The spot gets bigger with more confidence.
+
+@item prediction-num
+Plain-old numeric value.
+
+@item confidence-plus-minus
+Prediction +/i confidence.
+
+@end table
+
+
+@node GroupLens Variables
+@subsection GroupLens Variables
+
+@table @code
+
+@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 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.
+
+@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
+
+
+@node Advanced Scoring
+@section Advanced Scoring
+
+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?
+
+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 Advanced Scoring Syntax
+@subsection Advanced Scoring Syntax
+
+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.
+
+These lists may consist of three logical operators, one redirection
+operator, and various match operators.
+
+Logical operators:
+
+@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}.
+
+@item !
+@itemx not
+@itemx ¬
+This logical operator only takes a single argument. It returns the
+inverse of the value of its argument.
+
+@end table
+
+There is an @dfn{indirection operator} that will make its arguments
+apply to the ancenstors 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.
+
+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.
+
+
+@node Advanced Scoring Examples
+@subsection Advanced Scoring Examples
+
+Let's say you want to increase the score of articles written by Lars
+when he's talking about Gnus:
+
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ ("subject" "Gnus"))
+ 1000)
+@end example
+
+Quite simple, huh?
+
+When he writes long articles, he sometimes has something nice to say:
+
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ (|
+ ("subject" "Gnus")
+ ("lines" 100 >)))
+ 1000)
+@end example
+
+However, when he responds to things written by Reig Eigil Logge, you
+really don't want to read what he's written:
+
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ (1- ("from" "Reig Eigir Logge")))
+ -100000)
+@end example
+
+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:
+
+@example
+((&
+ (1-
+ (&
+ ("from" "redmondo@@.*no" r)
+ ("body" "disappearing.*socks" t)))
+ (! ("from" "Lars Ingebrigtsen"))
+ ("body" "white.*socks"))
+ 1000)
+@end example
+
+The possibilities are endless.
+
+
+@node Advanced Scoring Tips
+@subsection Advanced Scoring Tips
+
+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.
+
+The indirection arguments (@code{1-} and so on) will make their
+arguments work on previous generations of the thread. If you say
+something like:
+
+@example
+...
+(1-
+ (1-
+ ("from" "lars")))
+...
+@end example
+
+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:
+
+@example
+(1-
+ (&
+ ("from" "Lars")
+ ("subject" "Gnus")))
+@end example
+
+than it is to say:
+
+@example
+(&
+ (1- ("from" "Lars"))
+ (1- ("subject" "Gnus")))
+@end example
+
+
+@node Score Decays
+@section Score Decays
+@cindex score decays
+@cindex decays
+
+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.
+
+@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:
+
+@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:
+
+@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 magnutudes 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.
+
+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.
+
+
@node Various
@chapter Various
* 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.
+* Moderation:: What to do if you're a moderator.
* Various Various:: Things that are really various.
@end menu
Quite simple, really, but it needs to be made clear so that surprises
are avoided.
+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}).
+
@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}.
Require confirmation before catching up a group if non-@code{nil}. It
is @code{t} by default.
-@item gnus-interactive-post
-@vindex gnus-interactive-post
-If non-@code{nil}, the user will be prompted for a group name when
-posting an article. It is @code{t} by default.
+@item gnus-interactive-exit
+@vindex gnus-interactive-exit
+Require confirmation before exiting Gnus. This variable is @code{t} by
+default.
+@end table
+
+
+@node Formatting Variables
+@section Formatting Variables
+@cindex formatting variables
+
+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.
+
+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
+
+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}.
+
+All these format variables can also be arbitrary elisp forms. In that
+case, they will be @code{eval}ed to insert the required lines.
+
+@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.
+
+
+
+@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''.
+
+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.
+
+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.
+
+
+@node Advanced Formatting
+@subsection Advanced Formatting
+
+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}.
+
+These are the legal modifiers:
+
+@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.
+
+@item max
+@itemx max-left
+Cut off characters from the left until it reaches the specified length.
+
+@item max-right
+Cut off characters from the right until it reaches the specified
+length.
-@item gnus-interactive-exit
-@vindex gnus-interactive-exit
-Require confirmation before exiting Gnus. This variable is @code{t} by
-default.
+@item cut
+@itemx cut-left
+Cut off the specified number of characters from the left.
+
+@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.
+
+@item form
+Use the specified form as the field value when the @samp{@@} spec is
+used.
@end table
+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.)
-@node Formatting Variables
-@section Formatting Variables
-@cindex formatting variables
+Ignoring is done first; then cutting; then maxing; and then as the very
+last operation, padding.
-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.
+If you use lots of these advanced thingies, you'll find that Gnus gets
+quite slow. This can be helped enourmously by running @kbd{M-x
+gnus-compile} when you are setisfied with the look of your lines.
+@xref{Compilation}.
-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.
-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.
+@node User-Defined Specs
+@subsection User-Defined Specs
+
+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.
+
+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.
+
-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.
+@node Formatting Fonts
+@subsection Formatting Fonts
-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.
+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.
Text inside the @samp{%[} and @samp{%]} specifiers will have their
normal faces set using @code{gnus-face-0}, which is @code{bold} by
I'm sure you'll be able to use this scheme to create totally unreadable
and extremely vulgar displays. Have fun!
-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}.
-
Note that the @samp{%(} specs (and friends) do not make any sense on the
mode-line variables.
-All these format variables can also be random elisp forms. In that
-case, they will be @code{eval}ed to insert the required lines.
-
-@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.
-
@node Windows Configuration
@section Windows Configuration
@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
+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,
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}.
+@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp
+Reference Manual}.
Here's a list of all possible keys for
@code{gnus-buffer-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}.
+@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}.
+
+Note that the @code{message} key is used for both
+@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If
+it is desireable to distinguish between the two, something like this
+might be used:
+
+@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
@findex gnus-add-configuration
Since the @code{gnus-buffer-configuration} variable is so long and
@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
+@file{.gnus} file or in some startup hook---they should be run after
Gnus has been loaded.
-@node Compilation
-@section Compilation
+@node Compilation
+@section Compilation
@cindex compilation
@cindex byte-compilation
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.
+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.)
@node Mode Lines
@end table
+@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.
+
+@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
+
+
+@node Picon Basics
+@subsection Picon Basics
+
+What are Picons? To quote directly from the Picons Web site
+(@samp{http://www.cs.indiana.edu/picons/ftp/index.html}):
+
+@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
+
+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}.
+
+@vindex gnus-picons-database
+Gnus expects picons to be installed into a location pointed to by
+@code{gnus-picons-database}.
+
+
+@node Picon Requirements
+@subsection Picon Requirements
+
+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.
+
+Additionally, you must have @code{xpm} support compiled into XEmacs.
+
+@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.
+
+
+@node Easy Picons
+@subsection Easy Picons
+
+To enable displaying picons, simply put the following line in your
+@file{~/.gnus} file and start Gnus.
+
+@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 Hard Picons
+@subsection Hard Picons
+
+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.
+
+@table @code
+
+@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}.
+
+@end table
+
+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
+(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
+@end lisp
+
+
+@node Picon Configuration
+@subsection Picon Configuration
+
+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.
+
+@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 gnus-picons-news-directory
+@vindex gnus-picons-news-directory
+Sub-directory of the faces database containing the icons for
+newsgroups.
+
+@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 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 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 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))}.
+
+@item gnus-picons-buffer
+@vindex gnus-picons-buffer
+The name of the buffer that @code{picons} points to. Defaults to
+@samp{*Icon Buffer*}.
+
+@end table
+
+
+@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
+(add-hook 'gnus-summary-mode-hook 'gnus-moderate)
+@end lisp
+
+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---@samp{nnml:rec.zoofle}, for instance.
+
+@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-moderatated-groups
+ "^nnml:rec.zoofle$\\|^rec.zoofle$")
+@end lisp
+
+
@node Various Various
@section Various Various
@cindex mode lines
@table @code
+@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-verbose
@vindex gnus-verbose
This variable is an integer between zero and ten. The higher the value,
@code{(invisible t intangible t)} by default on most systems, which
makes invisible text invisible and intangible.
-@item gnus-parse-header-hook
-@vindex gnus-parse-header-hook
+@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.
+@item gnus-shell-command-separator
+@vindex gnus-shell-command-separator
+String used to separate to shell commands. The default is @samp{;}.
+
+
@end table
The first ``proper'' release of Gnus 5 was done in November 1995 when it
was included in the Emacs 19.30 distribution.
-Incidentally, the next Gnus generation will be called ``September
-Gnus'', and won't be released until April 1996. Confused? You will be.
+In May 1996 the next Gnus generation (aka. ``September Gnus'') was
+released under the name ``Gnus 5.2''.
+
+On July 28th 1996 work on Red Gnus was begun.
@menu
* Why?:: What's the point of Gnus?
* 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
@cindex RFC 1036
There are no known breaches of this standard, either.
-@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 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 Son-of-RFC 1036
@cindex Son-of-RFC 1036
wrong show.
@itemize @bullet
-@item
-Of course, @sc{gnus} was written by Masanobu @sc{Umeda}.
-@item
-Many excellent functions, especially dealing with scoring and
-highlighting (as well as the @sc{soup} support) was written
-by Per Abrahamsen.
-@item
-Design and graphics were done by Luis Fernandes.
-@item
-Innumerable bug fixes were written by Sudish Joseph.
-@item
-@code{gnus-topic} was written by Ilja Weis.
-@item
-Lots and lots of bugs were found and fixed by Steven L. Baur.
-@item
-The refcard was written by Vladimir Alexiev.
-@item
+
+@item Masanobu @sc{Umeda}
+The writer of the original @sc{gnus}.
+
+@item Per Abrahamsen
+Custom, scoring, highlighting and @sc{soup} code (as well as numerous
+other things).
+
+@item Luis Fernandes
+Design and graphics.
+
+@item Wes Hardaker
+@file{gnus-picon.el} and the manual section on @dfn{picons}
+(@pxref{Picons}).
+
+@item Brad Miller
+@file{gnus-gl.el} and the GroupLens manual section (@pxref{GroupLens}).
+
+@item Sudish Joseph
+Innumerable bug fixes.
+
+@item Ilja Weis
+@file{gnus-topic.el}.
+
+@item Steven L. Baur
+Lots and lots of bugs detections and fixes.
+
+@item Vladimir Alexiev
+The refcard and reference booklets.
+
+@item Felix Lee & JWZ
I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
-@item
-@code{nnfolder} has been much enhanced by Scott Byer.
-@item
-The orphan scoring was written by Peter Mutsaers.
-@item
-GNU XEmacs support has been added by Fabrice Popineau.
-@item
-POP mail support was written by Ken Raeburn.
-@item
-Various bits and pieces, especially dealing with .newsrc files, were
-suggested and added by Hallvard B Furuseth.
-@item
-Brian Edmonds has written @code{gnus-bbdb}.
-@item
-Ricardo Nassif and Mark Borges did the proff-reading (sic).
-@item
-Kevin Davidson came up with the name @dfn{ding}, so blame him.
-@item
-Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
-Quinlan, Frank D. Cringle, Geoffrey T. Dairiki, and Andrew Eskilsson have
-all contributed code and suggestions.
+
+@item Scott Byer
+@file{nnfolder.el} enhancements & rewrite.
+
+@item Peter Mutsaers
+Orphan article scoring code.
+
+@item Ken Raeburn
+POP mail support.
+
+@item Hallvard B Furuseth
+Various bits and pieces, especially dealing with .newsrc files.
+
+@item Brian Edmonds
+@file{gnus-bbdb.el}.
+
+@item Ricardo Nassif and Mark Borges
+Proof-reading.
+
+@item Kevin Davidson
+Came up with the name @dfn{ding}, so blame him.
+
@end itemize
+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.
+
@node New Features
@subsection New Features
could point your Web browser over that-a-way.
-@node Censorship
-@subsection Censorship
-@cindex censorship
-
-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.
-
-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/}.
-
-
@node Terminology
@section Terminology
@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.a
+
If you just need help, you are better off asking on
@samp{gnu.emacs.gnus}. I'm not very helpful.
* 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
@item (nnchoke-close-server &optional SERVER)
Close connection to @var{server} and free all resources connected
-to it.
+to it. Return @code{nil} if the server couldn't be closed for some
+reason.
There should be no data returned.
Close connection to all servers and free all resources that the backend
have reserved. All buffers that have been created by that backend
-should be killed. (Not the @code{nntp-server-buffer}, though.)
+should be killed. (Not the @code{nntp-server-buffer}, though.) This
+function is generally only called when Gnus is shutting down.
There should be no data returned.
@item (nnchoke-server-opened &optional SERVER)
-This function should return whether @var{server} is opened, and that the
-connection to it is still alive. This function should under no
-circumstances attempt to reconnect to a server that is has lost
-connection to.
+If @var{server} is the current virtual server, and the connection to the
+physical server is alive, then this function should return a
+non-@code{nil} vlue. This function should under no circumstances
+attempt to reconnect to a server that is has lost connection to.
There should be no data returned.
another, and Gnus mainly request articles to be inserted directly into
its article buffer.
+If it is at all possible, this function should return a cons cell where
+the car is the group name the article was fetched from, and the cdr is
+the article number. This will enable Gnus to find out what the real
+group and article numbers are when fetching articles by
+@code{Message-ID}. If this isn't possible, @code{t} should be returned
+on successful article retrievement.
+
@item (nnchoke-open-group GROUP &optional SERVER)
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
There should be no result data from this function.
-
-@item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
-
-This function should return a buffer suitable for composing an article
-to be posted by @code{nnchoke-request-post}. If @var{post} is
-non-@code{nil}, this is not a followup, but a totally new article.
-@var{group} is the name of the group to be posted to. @var{subject} is
-the subject of the message. @var{article-buffer} is the buffer being
-followed up, if that is the case. @var{info} is the group info.
-@var{follow-to} is the group that one is supposed to re-direct the
-article ot. If @var{respect-poster} is non-@code{nil}, the special
-@samp{poster} value of a @code{Followup-To} header is to be respected.
-
-There should be no result data returned.
-
@end table
@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.
format. The data should be in the active buffer format.
-@item (nnchoke-request-create-groups GROUP &optional SERVER)
+@item (nnchoke-request-create-group GROUP &optional SERVER)
This function should create an empty group with name @var{group}.
that there will be more requests issued shortly, so that allows some
optimizations.
+The function should return a cons where the car is the group name and
+the cdr is the article number that the article was entered as.
+
There should be no data returned.
-@item (nnchoke-request-accept-article GROUP &optional LAST)
+@item (nnchoke-request-accept-article GROUP &optional SERVER LAST)
This function takes the current buffer and inserts it into @var{group}.
If @var{last} in @code{nil}, that means that there will be more calls to
this function in short order.
+The function should return a cons where the car is the group name and
+the cdr is the article number that the article was entered as.
+
There should be no data returned.
@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
+
+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
+@code{nnml}, but it has no concept of ``groups'', and it doesn't allow
+editing articles.
+
+It would make sense if it were possible to ``inherit'' functions from
+backends when writing new backends. And, indeed, you can do that if you
+want to. (You don't have to if you don't want to, of course.)
+
+All the backends declare their public variables and functions by using a
+package called @code{nnoo}.
+
+To inherit functions from other backends (and allow other backends to
+inherit functions from the current backend), you should use the
+following macros:
+following.
+
+@table @code
+
+@item nnoo-declare
+This macro declares the first parameter to be a child of the subsequent
+parameters. For instance:
+
+@lisp
+(nnoo-declare nndir
+ nnml nnmh)
+@end lisp
+
+@code{nndir} has here declared that it intends to inherit functions from
+both @code{nnml} and @code{nnmh}.
+
+@item defvoo
+This macro is equivalent to @code{defvar}, but registers the variable as
+a public server variable. Most state-oriented variables should be
+declared with @code{defvoo} instead of @code{defvar}.
+
+In addition to the normal @code{defvar} parameters, it takes a list of
+variables in the parent backends to map the variable to when executing
+a function in those backends.
+
+@lisp
+(defvoo nndir-directory nil
+ "Where nndir will look for groups."
+ nnml-current-directory nnmh-current-directory)
+@end lisp
+
+This means that @code{nnml-current-directory} will be set to
+@code{nndir-directory} when an @code{nnml} function is called on behalf
+of @code{nndir}. (The same with @code{nnmh}.)
+
+@item nnoo-define-basics
+This macro defines some common functions that almost all backends should
+have.
+
+@example
+(nnoo-define-basics nndir)
+@end example
+
+@item deffoo
+This macro is just like @code{defun} and takes the same parameters. In
+addition to doing the normal @code{defun} things, it registers the
+function as being public so that other backends can inherit it.
+
+@item nnoo-map-functions
+This macro allows mapping of functions from the current backend to
+functions from the parent backends.
+
+@example
+(nnoo-map-functions nndir
+ (nnml-retrieve-headers 0 nndir-current-group 0 0)
+ (nnmh-request-article 0 nndir-current-group 0 0))
+@end example
+
+This means that when @code{nndir-retrieve-headers} is called, the first,
+third, and fourth parameters will be passed on to
+@code{nnml-retrieve-headers}, while the second parameter is set to the
+value of @code{nndir-current-group}.
+
+@item nnoo-import
+This macro allows importing functions from backends. It should be the
+last thing in the source file, since it will only define functions that
+haven't already been defined.
+
+@example
+(nnoo-import nndir
+ (nnmh
+ nnmh-request-list
+ nnmh-request-newgroups)
+ (nnml))
+@end example
+
+This means that calls to @code{nndir-request-list} should just be passed
+on to @code{nnmh-request-list}, while all public functions from
+@code{nnml} that haven't been defined in @code{nndir} yet should be
+defined now.
+
+@end table
+
+Below is a slightly shortened version of the @code{nndir} backend.
+
+@lisp
+;;; nndir.el --- single directory newsgroup access for Gnus
+;; Copyright (C) 1995,96 Free Software Foundation, Inc.
+
+;;; Code:
+
+(require 'nnheader)
+(require 'nnmh)
+(require 'nnml)
+(require 'nnoo)
+(eval-when-compile (require 'cl))
+
+(nnoo-declare nndir
+ nnml nnmh)
+
+(defvoo nndir-directory nil
+ "Where nndir will look for groups."
+ nnml-current-directory nnmh-current-directory)
+
+(defvoo nndir-nov-is-evil nil
+ "*Non-nil means that nndir will never retrieve NOV headers."
+ nnml-nov-is-evil)
+
+(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")
+
+;;; Interface functions.
+
+(nnoo-define-basics nndir)
+
+(deffoo nndir-open-server (server &optional defs)
+ (setq nndir-directory
+ (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)
+ (push `(nndir-top-directory
+ ,(file-name-directory (directory-file-name nndir-directory)))
+ defs)
+ (nnoo-change-server 'nndir server defs))
+
+(nnoo-map-functions nndir
+ (nnml-retrieve-headers 0 nndir-current-group 0 0)
+ (nnmh-request-article 0 nndir-current-group 0 0)
+ (nnmh-request-group nndir-current-group 0 0)
+ (nnmh-close-group nndir-current-group 0))
+
+(nnoo-import nndir
+ (nnmh
+ nnmh-status-message
+ nnmh-request-list
+ nnmh-request-newgroups))
+
+(provide '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
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.
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
Emacs is the King of Editors because it's really a Lisp interpreter.
Each and every key you tap runs some Emacs Lisp code snippet, and since
Emacs Lisp is an interpreted language, that means that you can configure
-any key to run any random code. You just, like, do it.
+any key to run any arbitrary code. You just, like, do it.
Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
functions. (These are byte-compiled for speed, but it's still
projects / gnus / blobdiff