by Per Abrahamsen.
@item
Innumerable bug fixes were written by Sudish Joseph.
+@item
+@code{gnus-topic} was written by Ilja Weis.
@item
The refcard was written by Vladimir Alexiev.
@item
@item
Kevin Davidson came up with the name @dfn{ding}, so blame him.
@item
-Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel Quinlan, Ilja
-Weis, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
-all contributed code and suggestions.
+Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel Quinlan, Frank
+D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have all
+contributed code and suggestions.
@end itemize
* The First Time:: What does Gnus do the first time you start it?
* The Server is Down:: How can I read my mail then?
* Slave Gnusii:: You can have more than one Gnus active at a time.
+* Fetching a Group:: Starting Gnus just to read a group.
* New Groups:: What is Gnus supposed to do with new groups?
* Startup Files:: Those pesky startup files - @file{.newsrc}.
* Auto Save:: Recovering from a crash.
information in the normal (i. e., master) @code{.newsrc} file.
+@node Fetching a Group
+@section Fetching a Group
+
+@findex gnus-fetch-group
+It it sometime convenient to be able to just say "I want to read this
+group and I don't care whether Gnus has been started or not". This is
+perhaps more useful for people who write code than for users, but the
+command @code{gnus-fetch-group} provides this functionality in any
+case. It takes the group name as a paramenter.
+
+
@node New Groups
@section New Groups
@cindex new groups
the the new group matches the first, it will be unconditionally
subscribed, and if it matches the latter, it will be ignored.
+@vindex gnus-auto-subscribed-groups
+Yet another variable that meddles here is
+@code{gnus-auto-subscribed-groups}. It works exactly like
+@code{gnus-options-subscribe}, and is therefore really superfluos, but I
+thought it would be nice to have two of these. This variable is more
+meant for setting some ground rules, while the other variable is used
+more for user fiddling. By default this variable makes all new groups
+that come from mail backends (@code{nnml}, @code{nnbabyl},
+@code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
+don't like that, just set this variable to @code{nil}.
+
@vindex gnus-check-new-newsgroups
If you are satisfied that you really never want to see any new groups,
you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
file being whatever that one is with a @samp{.eld} appended.
@vindex gnus-save-newsrc-hook
-@code{gnus-save-newsrc-hook} is called before saving the @file{.newsrc}
-file.
+@vindex gnus-save-quick-newsrc-hook
+@vindex gnus-save-standard-newsrc-hook
+@code{gnus-save-newsrc-hook} is called before saving any of the newsrc
+files, while @code{gnus-save-quick-newsrc-hook} is called just before
+saving the @file{.newsrc.eld} file, and
+@code{gnus-save-standard-newsrc-hook} is called just before saving the
+@file{.newsrc} file. The latter two are commonly used to tern version
+control on or off.
@node Auto Save
@section Auto Save
If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
maintain a dribble buffer.
+@vindex gnus-dribble-directory
+Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
+this variable is @code{nil}, which it is by default, Gnus will dribble
+into the same directory as the @file{.newsrc} file is located. (This is
+normally the user's home directory.)
+
@node The Active File
@section The Active File
@cindex active file
* Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
* Browse Foreign Server:: You can browse a server. See what if has to offer.
* Exiting Gnus:: Stop reading news and get some work done.
+* Group Topics:: A folding group mode divided into topics.
* Misc Group Stuff:: Other stuff that you can to do.
@end menu
for a name, a method and possibly an @dfn{address}. For an easier way
to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
+@item G r
+@kindex G m (Group)
+@findex gnus-group-rename-group
+Rename the current group to something else
+(@code{gnus-group-rename-group}). This is legal only on some groups --
+mail groups mostly. This command might very well be quite slow on some
+backends.
+
@item G e
@kindex G e (Group)
@findex gnus-group-edit-group-method
name and a file type. Currently supported types are @code{babyl},
@code{mbox} and @code{digest}.
+@item G DEL
+@kindex G DEL (Group)
+@findex gnus-group-delete-group
+This function will delete the current group
+(@code{gnus-group-delete-group}). If given a prefix, this function will
+actuallt delete all the articles in the group, and forcibly remove the
+group itself from the face of the Earth. Use a prefix only if you are
+sure of what you are doing.
+
@item G V
@kindex G V (Group)
@findex gnus-group-make-empty-virtual
@findex gnus-group-expire-articles
Run all expirable articles in the current group through the expiry
process (if any) (@code{gnus-group-expire-articles}).
+
@item C-c M-C-x
@kindex C-c M-C-x (Group)
@findex gnus-group-expire-all-groups
Run all articles in all groups through the expiry process
(@code{gnus-group-expire-all-groups}).
+
@item C-c C-s
@kindex C-c C-s (Group)
@findex gnus-group-sort-groups
-@findex gnus-group-sort-by-level
-@findex gnus-group-sort-by-unread
-@findex gnus-group-sort-by-alphabet
@vindex gnus-group-sort-function
Sort the groups according to the function given by the
@code{gnus-group-sort-function} variable
-(@code{gnus-group-sort-groups}). Available sorting functions include
-@code{gnus-group-sort-by-alphabet} (the default),
-@code{gnus-group-sort-by-unread} and @code{gnus-group-sort-by-level}.
+(@code{gnus-group-sort-groups}). Available sorting functions include:
+
+@table
+
+@item gnus-group-sort-by-level
+@findex gnus-group-sort-by-level
+Sort by group level.
+
+@item gnus-group-sort-by-unread
+@findex gnus-group-sort-by-unread
+Sort by number of unread articles.
+
+@item gnus-group-sort-by-alphabet
+@findex gnus-group-sort-by-alphabet
+Sort the group names alphabetically. This is the default.
+
+@item gnus-group-sort-by-method
+@findex gnus-group-sort-by-method
+Sort by alphabetically on the select method.
+
+@end table
+
+@code{gnus-group-sort-function} can also be a list of sorting
+functions. In that case, the most significant sort key function must be
+the last one.
@end table
@node Browse Foreign Server
plastic chair.
@end quotation
+
+@node Group Topics
+@section Group Topics
+@cindex topics
+
+If you read lots and lots of groups, it might be convenient to group
+them according to topics. You put your Emacs groups over here, your sex
+groups over there, and the rest (what, two groups or so?) you put in
+some misc section that you never bother with anyway.
+
+To get this @emph{fab} functionality, you set
+@code{gnus-group-prepare-function} to @code{gnus-group-prepare-topics}.
+Go ahead, just try it. I'll still be here when you get back. La de
+dum... Nice tune, that... la la la... What, you're back? Yes, and now
+press @kbd{l}. There. All your groups are now listed under
+@samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
+bothered?
+
+@vindex gnus-group-topics
+To get an even more exciting division, you have to fiddle with
+@code{gnus-group-topics}. That is an alist where each entry looks like
+this:
+
+@lisp
+(TOPIC REGEXP SHOW)
+@end lisp
+
+As you've already guessed (only geniouses read manuals anyway), all
+groups that match @var{regexp} gets put into a section called
+@var{topic}. If @var{show} is non-@code{nil}, it overrides
+@code{gnus-group-topic-topics-only}. In specific, if @var{show} is
+@code{t}, all groups with this topic are always shown, and if it is a
+number, these groups are never shown.
+
+@vindex gnus-group-topic-topics-only
+Whoo, this is complicated. If @code{gnus-group-topic-topics-only} is
+@code{nil}, all groups and topics will be listed, as you would expect.
+If this variable is non-@code{nil}, only the topics will be listed, and
+the groups will not be listed. This makes the group buffer much shorter,
+I'm sure you'll agree. This is all modified on a topic-by-topic basis
+by the @var{show} parameter. It makes perfect sense, really.
+
+@vindex gnus-group-topic-face
+Topics are shown with @code{gnus-group-topic-face}.
+
+Now, if you select a topic, if will fold/unfold that topic, which is
+really neat, I think.
+
+Here's an example @code{gnus-group-topics}:
+
+@lisp
+(("Emacs - the Spice of Life" "^gnu.emacs\\|comp.emacs" t)
+ ("Alternativeness" "^alt" 0)
+ ("Hard Stuff" "^comp" nil)
+ ("The Rest" "." nil))
+@end lisp
+
+
@node Misc Group Stuff
@section Misc Group Stuff
Used-defined spec.
@item s
Name of the current score file.
+@item d
+Number of dormant articles.
+@item t
+Number of ticked articles.
+@item r
+Number of articles that have been marked as read in this session.
+@item E
+Number of articles expunged by the score files.
@end table
variable is neither @code{t} nor @code{nil}, Gnus will select the next
group, no matter whether it has any unread articles or not. As a
special case, if this variable is @code{quietly}, Gnus will select the
-next group without asking for confirmation. Also @xref{Group Levels}.
+next group without asking for confirmation. If this variable is
+@code{almost-quietly}, the same will happen only if you are located on
+the last article in the group. Also @xref{Group Levels}.
If Gnus asks you to press a key to confirm going to the next group, you
can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
@table @code
@item subject-cmsg
Check the subject for commands.
+@item sender
+Insert a new @code{Sender} header if the @code{From} header looks odd.
@item multiple-headers
Check for the existence of multiple equal headers.
@item sendsys
@vindex gnus-thread-hide-subtree
If non-@code{nil}, all threads will be hidden when the summary buffer is
generated.
+
@item gnus-thread-hide-killed
@vindex gnus-thread-hide-killed
if you kill a thread and this variable is non-@code{nil}, the subtree
will be hidden.
+
@item gnus-thread-ignore-subject
@vindex gnus-thread-ignore-subject
Sometimes somebody changes the subject in the middle of a thread. If
this variable is non-@code{nil}, the subject change is ignored. If it
is @code{nil}, which is the default, a change in the subject will result
in a new thread.
+
@item gnus-thread-indent-level
@vindex gnus-thread-indent-level
This is a number that says how much each sub-thread should be indented.
@cindex thread commands
@table @kbd
+
@item T k
@itemx M-C-k
@kindex T k (Summary)
(@code{gnus-summary-kill-thread}). If the prefix argument is positive,
remove all marks instead. If the prefix argument is negative, tick
articles instead.
+
@item T l
@itemx M-C-l
@kindex T l (Summary)
@findex gnus-summary-lower-thread
Lower the score of the current thread
(@code{gnus-summary-lower-thread}).
+
@item T i
@kindex T i (Summary)
@findex gnus-summary-raise-thread
Increase the score of the current thread
(@code{gnus-summary-raise-thread}).
+
@item T #
@kindex T # (Summary)
@findex gnus-uu-mark-thread
Set the process mark on the current thread
(@code{gnus-uu-mark-thread}).
+
@item T M-#
@kindex T M-# (Summary)
@findex gnus-uu-unmark-thread
Remove the process mark from the current thread
(@code{gnus-uu-unmark-thread}).
+
@item T T
@kindex T T (Summary)
@findex gnus-summary-toggle-threads
Toggle threading (@code{gnus-summary-toggle-threads}).
+
@item T s
@kindex T s (Summary)
@findex gnus-summary-show-thread
Expose the thread hidden under the current article, if any
(@code{gnus-summary-show-thread}).
+
@item T h
@kindex T h (Summary)
@findex gnus-summary-hide-thread
Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
+
@item T S
@kindex T S (Summary)
@findex gnus-summary-show-all-threads
Expose all hidden threads (@code{gnus-summary-show-all-threads}).
+
@item T H
@kindex T H (Summary)
@findex gnus-summary-hide-all-threads
Ascend the thread (@code{gnus-summary-up-thread}).
@end table
+@vindex gnus-thread-operation-ignore-subject
+If you ignore subject while threading, you'll naturally end up with
+threads that have several different subjects in them. If you then issue
+a command like `T k' (@code{gnus-summary-kill-thread}) you might not
+wish to kill the entire thread, but just those parts of the thread that
+have the same subject as the current article. If you like this idea,
+you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
+is non-@code{nil} (which it is by default), subjects will be ignored
+when doing thread commands. If this variable is @code{nil}, articles in
+the same thread with different subjects will not be included in the
+operation in question. If this variable is @code{fuzzy}, only articles
+that have subjects that are fuzzily equal will be included.
+
+
@node Asynchronous Fetching
@section Asynchronous Article Fetching
@cindex asynchronous article fetching
your connection to the @sc{nntp} server is really, really, really slow
and 2) you have a really, really, really huge disk. Seriously.
+@vindex gnus-uncacheable-groups
+It is likely that you do not want caching on some groups. For instance,
+if your @code{nnml} mail is located under your home directory, it makes no
+sense to cache it somewhere else under your home directory. Unless you
+feel that it's neat to use twice as much space. To limit the caching,
+you could set the @code{gnus-uncacheable-groups} regexp to
+@samp{"^nnml"}, for instance. This variable is @samp{"^nnvirtual"} by
+default, since caching doesn't really work in @code{nnvirtual} groups,
+since @code{nnvirtual} assigns random article numbers to its articles.
+
@node Exiting the Summary Buffer
@section Exiting the Summary Buffer
unwanted headers before saving the article.
@table @kbd
+
@item O o
@itemx o
@kindex O o (Summary)
@findex gnus-summary-save-article
Save the current article using the default article saver
(@code{gnus-summary-save-article}).
+
@item O m
@kindex O m (Summary)
@findex gnus-summary-save-article-mail
Save the current article in mail format
(@code{gnus-summary-save-article-mail}).
+
@item O r
@kindex O r (Summary)
@findex gnus-summary-save-article-mail
Save the current article in rmail format
(@code{gnus-summary-save-article-rmail}).
+
@item O f
@kindex O f (Summary)
@findex gnus-summary-save-article-file
Save the current article in plain file format
(@code{gnus-summary-save-article-file}).
+
+@item O b
+@kindex O b (Summary)
+@findex gnus-summary-save-article-body-file
+Save the current article body in plain file format
+(@code{gnus-summary-save-article-body-file}).
+
@item O h
@kindex O h (Summary)
@findex gnus-summary-save-article-folder
Save the current article in mh folder format
(@code{gnus-summary-save-article-folder}).
+
@item O p
@kindex O p (Summary)
@findex gnus-summary-pipe-output
the current article to a process (@code{gnus-summary-pipe-output}).
@end table
+@vindex gnus-prompt-before-saving
All these commands use the process/prefix convention
-(@pxref{Process/Prefix}).
+(@pxref{Process/Prefix}). If you save bunches of articles using these
+functions, you might get tired of being prompted for files to save each
+and every article in. The prompting action is controlled by
+the @code{gnus-prompt-before-saving} variable, which is @code{always} by
+default, giving you that excessive prompting action you know and
+loathe. If you set this variable to @code{t} instead, you'll be promted
+just once for each series of articles you save. If you like to really
+have Gnus do all your thinking for you, you can even set this variable
+to @code{nil}, which means that you will never be prompted for files to
+save articles in. Gnus will simply save all the articles in the default
+files.
+
@vindex gnus-default-article-saver
You can customize the @code{gnus-default-article-saver} variable to make
functions below, or you can create your own.
@table @code
+
@item gnus-summary-save-in-rmail
-@vindex gnus-summary-save-in-rmail
+@findex gnus-summary-save-in-rmail
This is the default format, @dfn{babyl}. Uses the function in the
@code{gnus-rmail-save-name} variable to get a file name to save the
article in. The default is @code{gnus-plain-save-name}.
+
@item gnus-summary-save-in-mail
-@vindex gnus-summary-save-in-mail
+@findex gnus-summary-save-in-mail
Save in a Unix mail (mbox) file. Uses the function in the
@code{gnus-mail-save-name} variable to get a file name to save the
article in. The default is @code{gnus-plain-save-name}.
+
@item gnus-summary-save-in-file
-@vindex gnus-summary-save-in-file
+@findex gnus-summary-save-in-file
Append the article straight to an ordinary file. Uses the function in
the @code{gnus-file-save-name} variable to get a file name to save the
article in. The default is @code{gnus-numeric-save-name}.
+
+@item gnus-summary-save-body-in-file
+@findex gnus-summary-save-body-in-file
+Append the article body to an ordinary file. Uses the function in the
+@code{gnus-file-save-name} variable to get a file name to save the
+article in. The default is @code{gnus-numeric-save-name}.
+
@item gnus-summary-save-in-folder
-@vindex gnus-summary-save-in-folder
+@findex gnus-summary-save-in-folder
Save the article to an MH folder using @code{rcvstore} from the MH
library.
+
@item gnus-summary-save-in-vm
-@vindex gnus-summary-save-in-vm
+@findex gnus-summary-save-in-vm
Save the article in a VM folder. You have to have the VM mail
reader to use this setting.
@end table
* Article Highlighting:: You want to make the article look like fruit salad.
* Article Hiding:: You also want to make certain info go away.
* Article Washing:: Lots of way-neat functions to make life better.
+* Article Buttons:: Clcik on URLs, Message-IDs, addresses and the like.
* Article Date:: Grumble, UT!
@end menu
argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
matches the @code{From} header, the face will not be shown.
+@item W b
+@kindex W b (Summary)
+@findex gnus-article-add-buttons
+Add clickable buttons to the article (@code{gnus-article-add-buttons}).
+
+@item W B
+@kindex W B (Summary)
+@findex gnus-article-add-buttons-to-head
+Add clickable buttons to the article headers
+(@code{gnus-article-add-buttons-to-head}).
+
+@end table
+
+
+@node Article Buttons
+@subsection Article Buttons
+@cindex buttons
+
+People often include references to other stuff in articles, and it would
+be nice if Gnus could just fetch whatever it is that people talk about
+with the minimum of fuzz.
+
+Gnus adds @dfn{buttons} to certain standard references by default:
+Well-formed URLs, mail addresses and Message-IDs. This is controlled by
+two variables, one that handles article bodies and one that handles
+article heads:
+
+@table @code
+
+@item gnus-button-alist
+@vindex gnus-header-button-alist
+This is an alist where each entry has this form:
+
+@lisp
+(REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
+@end lisp
+
+@table @var
+
+@item regexp
+All text that match this regular expression will be considered an
+external reference. Here's a typical regexp that match embedded URLs:
+@samp{"<URL:\\([^\n\r>]*\\)>"}.
+
+@item button-par
+Gnus has to know which parts of the match is to be highlighted. This is
+a number that says what sub-expression of the regexp that is to be
+highlighted. If you want it all highlighted, you use @samp{0} here.
+
+@item use-p
+This form will be @code{eval}ed, and if the result is non-@code{nil},
+this is considered a match. This is useful if you want extra sifting to
+avoid false matches.
+
+@item function
+This function will be called when you click on this button.
+
+@item data-par
+As with @var{button-par}, this is a sub-expression number, but this one
+says which part of the match is to be sent as data to @var{function}.
+
@end table
+So the full entry for buttonizing URLs is then
+
+@lisp
+("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
+@end lisp
+
+@item gnus-header-button-alist
+@vindex gnus-header-button-alist
+This is just like the other alist, except that it is applied to the
+article head only, and that each entry has an additional element that is
+used to say what headers to apply the buttonize coding to:
+
+@lisp
+(HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
+@end lisp
+
+@var{header} is a regular expression.
+
+@end table
+
+@vindex gnus-article-button-face
+@vindex gnus-article-mouse-face
+Buttons are highlighted with @code{gnus-article-button-face}, while
+@code{gnus-article-mouse-face} is used when the mouse cursor is over the
+button.
+
+
@node Article Date
@subsection Article Date
Other useful functions you might add to this hook is:
@table @code
+
@item gnus-article-hide-citation
Hide all cited text.
+
@item gnus-article-hide-signature
Umn, hides the signature.
+
@item gnus-article-treat-overstrike
Treat @samp{^H_} in a reasonable manner.
+
@item gnus-article-maybe-highlight
-Do fancy article highlighting.
+Do some fancy article highlighting.
+
+@item gnus-article-highlight
+Do lots of article highlighting.
+
@item gnus-article-remove-cr
Removes trailing carriage returns.
+
@item gnus-article-de-quoted-unreadable
Do naive decoding of articles encoded with Quoted-Printable.
+
@item gnus-article-display-x-face
-Displays any X-Face headers.
+Displays any @code{X-Face} headers.
@end table
You can, of course, write your own functions. The functions are called
@vindex gnus-use-scoring
If @code{nil}, Gnus will not check for score files, and will not, in
general, do any score-related work.
+
@item gnus-kill-killed
@vindex gnus-kill-killed
If this variable is @code{nil}, Gnus will never apply score files to
to a group, and then change the kill file and want to run it over you
group again to kill more articles, it won't work. You have to set this
variable to @code{t} to do that.
+
@item gnus-kill-files-directory
@vindex gnus-kill-files-directory
All kill and score files will be stored in this directory, which is
initialized from the @samp{SAVEDIR} environment variable by default.
+
@item gnus-score-file-suffix
@vindex gnus-score-file-suffix
Suffix to add to the group name to arrive at the score file name
(@samp{SCORE} by default.)
+
+@item gnus-score-uncacheable-files
+@vindex gnus-score-uncacheable-files
+@cindex score cache
+All score files are normally cached to avoid excessive re-loading of
+score files. However, if this might make you Emacs grow big and
+bloated, so this regexp can be used to weed out score files that are
+unlikely to be needed again. It would be a bad idea to deny caching of
+@file{all.SCORE}, while it might be a good idea to not cache
+@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
+variable is @samp{"ADAPT$"} by default, so no adaptive score files will
+be cached.
+
@item gnus-score-interactive-default-score
@vindex gnus-score-interactive-default-score
Score used by all the interactive raise/lower commands to raise/lower
ensure that the adaptive scoring scheme gets enough room to play with.
We don't want the small changes from the adaptive scoring to overwrite
manually entered data.
+
@item gnus-summary-default-score
@vindex gnus-summary-default-score
Default score of an article, which is 0 by default.
+
@item gnus-score-over-mark
@vindex gnus-score-over-mark
Mark (in the third column) used for articles with a score over the
default. Default is @samp{+}.
+
@item gnus-score-below-mark
@vindex gnus-score-below-mark
Mark (in the third column) used for articles with a score below the
default. Default is @samp{-}.
+
@item gnus-score-find-score-files-function
@vindex gnus-score-find-score-files-function
Function used to find score files for the current group. This function
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 to. If @var{respect-poster} is non-@code{nil}, the special
+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.
There should be no data returned.
+
+@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
+
+This function should delete @var{group}. If @var{force}, it should
+really delete all the articles in the group, and then delete the group
+itself. (If there is such a thing as "the group itself".)
+
+There should be no data returned.
+
+
+@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
+
+This function should rename @var{group} into @var{new-name}. All
+articles that are in @var{group} should move to @var{new-name}.
+
+There should be no data returned.
+
+
@end table