@documentencoding ISO-8859-1
@copying
-Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
-2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 1995-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU
-Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual. Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
@end quotation
@end copying
@end iflatex
@end iftex
-@ifnottex
-@insertcopying
-@end ifnottex
-
@dircategory Emacs
@direntry
-* Gnus: (gnus). The newsreader Gnus.
+* Gnus: (gnus). The newsreader Gnus.
@end direntry
@iftex
@finalout
@end iftex
-@setchapternewpage odd
-
@titlepage
@insertcopying
@end titlepage
+@summarycontents
+@contents
@node Top
@top The Gnus Newsreader
@c Adjust ../Makefile.in if you change the following line:
This manual corresponds to No Gnus v0.11.
+@ifnottex
+@insertcopying
+@end ifnottex
+
@end ifinfo
@iftex
* Composing Messages:: Information on sending mail and news.
* Select Methods:: Gnus reads all messages from various select methods.
* Scoring:: Assigning values to articles.
+* Searching:: Mail and News search engines.
* Various:: General purpose settings.
* The End:: Farewell and goodbye.
* Appendices:: Terminology, Emacs intro, @acronym{FAQ}, History, Internals.
Starting Gnus
* Finding the News:: Choosing a method for getting news.
-* The First Time:: What does Gnus do the first time you start it?
* The Server is Down:: How can I read my mail then?
* Slave Gnusae:: You can have more than one Gnus active at a time.
* Fetching a Group:: Starting Gnus just to read a group.
* Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
* Article Button Levels:: Controlling appearance of buttons.
* Article Date:: Grumble, UT!
-* Article Display:: Display various stuff---X-Face, Picons, Smileys
+* Article Display:: Display various stuff---X-Face, Picons, Smileys, Gravatars
* Article Signature:: What is a signature?
* Article Miscellanea:: Various other stuff.
* Server Buffer:: Making and editing virtual servers.
* Getting News:: Reading USENET news with Gnus.
+* Using IMAP:: Reading mail from @acronym{IMAP}.
* Getting Mail:: Reading your personal mail with Gnus.
* Browsing the Web:: Getting messages from a plethora of Web sources.
-* IMAP:: Using Gnus as a @acronym{IMAP} client.
-* Other Sources:: Reading directories, files, SOUP packets.
+* Other Sources:: Reading directories, files.
* Combined Groups:: Combining groups into one group.
* Email Based Diary:: Using mails to manage diary events in Gnus.
* Gnus Unplugged:: Reading news and mail offline.
Choosing a Mail Back End
* Unix Mail Box:: Using the (quite) standard Un*x mbox.
-* Rmail Babyl:: Emacs programs use the Rmail Babyl format.
+* Babyl:: Babyl was used by older versions of Rmail.
* Mail Spool:: Store your mail in a private spool?
* MH Spool:: An mhspool-like back end.
* Maildir:: Another one-file-per-message format.
* Archiving Mail::
* Web Searches:: Creating groups from articles that match a string.
-* Slashdot:: Reading the Slashdot comments.
-* Ultimate:: The Ultimate Bulletin Board systems.
-* Web Archive:: Reading mailing list archived on web.
* RSS:: Reading RDF site summary.
* Customizing W3:: Doing stuff to Emacs/W3 from Gnus.
-@acronym{IMAP}
-
-* Splitting in IMAP:: Splitting mail with nnimap.
-* Expiring in IMAP:: Expiring mail with nnimap.
-* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
-* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
-* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus.
-* Debugging IMAP:: What to do when things don't work.
-
Other Sources
* 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''.
* Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
+* The Empty Backend:: The backend that never has any news.
Document Groups
* Document Server Internals:: How to add your own document types.
-SOUP
-
-* SOUP Commands:: Commands for creating and sending @sc{soup} packets
-* SOUP Groups:: A back end for reading @sc{soup} packets.
-* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
-
Combined Groups
* Virtual Groups:: Combining articles from many groups.
-* Kibozed Groups:: Looking through parts of the newsfeed for articles.
Email Based Diary
* Advanced Scoring Examples:: What they look like.
* Advanced Scoring Tips:: Getting the most out of it.
+Searching
+
+* nnir:: Searching with various engines.
+* nnmairix:: Searching with Mairix.
+
+nnir
+
+* What is nnir?:: What does nnir do.
+* Basic Usage:: How to perform simple searches.
+* Setting up nnir:: How to set up nnir.
+
+Setting up nnir
+
+* Associating Engines:: How to associate engines.
+
Various
* Process/Prefix:: A convention used by many treatment commands.
* Compilation:: How to speed Gnus up.
* Mode Lines:: Displaying information in the mode lines.
* Highlighting and Menus:: Making buffers look all nice and cozy.
-* Buttons:: Get tendinitis in ten easy steps!
* Daemons:: Gnus can do things behind your back.
-* NoCeM:: How to avoid spam and other fatty foods.
* Undo:: Some actions can be undone.
* Predicate Specifiers:: Specifying predicates.
* Moderation:: What to do if you're a moderator.
* Fuzzy Matching:: What's the big fuzz?
* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email.
* Spam Package:: A package for filtering and processing spam.
+* The Gnus Registry:: A package for tracking messages by Message-ID.
* Other modes:: Interaction with other modes.
* Various Various:: Things that are really various.
* Smileys:: Show all those happy faces the way they were
meant to be shown.
* Picons:: How to display pictures of what you're reading.
+* Gravatars:: Display the avatar of people you read.
* XVarious:: Other XEmacsy Gnusey variables.
Thwarting Email Spam
@menu
* Finding the News:: Choosing a method for getting news.
-* The First Time:: What does Gnus do the first time you start it?
* The Server is Down:: How can I read my mail then?
* Slave Gnusae:: You can have more than one Gnus active at a time.
* New Groups:: What is Gnus supposed to do with new groups?
@section Finding the News
@cindex finding news
+First of all, you should know that there is a special buffer called
+@code{*Server*} that lists all the servers Gnus knows about. You can
+press @kbd{^} from the Group buffer to see it. In the Server buffer,
+you can press @kbd{RET} on a defined server to see all the groups it
+serves (subscribed or not!). You can also add or delete servers, edit
+a foreign server's definition, agentize or de-agentize a server, and
+do many other neat things. @xref{Server Buffer}.
+@xref{Foreign Groups}. @xref{Agent Basics}.
+
@vindex gnus-select-method
@c @head
The @code{gnus-select-method} variable says where Gnus should look for
If that fails as well, Gnus will try to use the machine running Emacs
as an @acronym{NNTP} server. That's a long shot, though.
-@vindex gnus-nntp-server
-If @code{gnus-nntp-server} is set, this variable will override
-@code{gnus-select-method}. You should therefore set
-@code{gnus-nntp-server} to @code{nil}, which is what it is by default.
-
-@vindex gnus-secondary-servers
-@vindex gnus-nntp-server
-You can also make Gnus prompt you interactively for the name of an
-@acronym{NNTP} server. If you give a non-numerical prefix to @code{gnus}
-(i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
-in the @code{gnus-secondary-servers} list (if any). You can also just
-type in the name of any server you feel like visiting. (Note that this
-will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x
-gnus} later in the same Emacs session, Gnus will contact the same
-server.)
-
@findex gnus-group-browse-foreign-server
@kindex B (Group)
However, if you use one @acronym{NNTP} server regularly and are just
new articles. @xref{NNTP marks}, for more information.
-@node The First Time
-@section The First Time
-@cindex first time usage
-
-If no startup files exist (@pxref{Startup Files}), Gnus will try to
-determine what groups should be subscribed by default.
-
-@vindex gnus-default-subscribed-newsgroups
-If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
-will subscribe you to just those groups in that list, leaving the rest
-killed. Your system administrator should have set this variable to
-something useful.
-
-Since she hasn't, Gnus will just subscribe you to a few arbitrarily
-picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is defined
-here 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.
-
-If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
-use the normal functions for handling new groups, and not do anything
-special.
-
-
@node The Server is Down
@section The Server is Down
@cindex server errors
topic parameter that looks like
@example
-"nnslashdot"
+"nnml"
@end example
will mean that all groups that match that regex will be subscribed under
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 back ends (@code{nnml}, @code{nnbabyl},
-@code{nnfolder}, @code{nnmbox}, @code{nnmh}, and @code{nnmaildir})
-subscribed. If you don't like that, just set this variable to
-@code{nil}.
-
-New groups that match this regexp are subscribed using
+@code{nnfolder}, @code{nnmbox}, @code{nnmh}, @code{nnimap}, and
+@code{nnmaildir}) subscribed. If you don't like that, just set this
+variable to @code{nil}.
+
+@vindex gnus-auto-subscribed-categories
+As if that wasn't enough, @code{gnus-auto-subscribed-categories} also
+allows you to specify that new groups should be subcribed based on the
+category their select methods belong to. The default is @samp{(mail
+post-mail)}, meaning that all new groups from mail-like backends
+should be subscribed automatically.
+
+New groups that match these variables are subscribed using
@code{gnus-subscribe-options-newsgroup-method}.
change @code{gnus-select-method}, your @file{.newsrc} file becomes
worthless.
-Gnus provides a few functions to attempt to translate a @file{.newsrc}
-file from one server to another. They all have one thing in
-common---they take a looong time to run. You don't want to use these
-functions more than absolutely necessary.
-
-@kindex M-x gnus-change-server
-@findex gnus-change-server
-If you have access to both servers, Gnus can request the headers for all
-the articles you have read and compare @code{Message-ID}s and map the
-article numbers of the read articles and article marks. The @kbd{M-x
-gnus-change-server} command will do this for all your native groups. It
-will prompt for the method you want to move to.
-
-@kindex M-x gnus-group-move-group-to-server
-@findex gnus-group-move-group-to-server
-You can also move individual groups with the @kbd{M-x
-gnus-group-move-group-to-server} command. This is useful if you want to
-move a (foreign) group from one server to another.
-
@kindex M-x gnus-group-clear-data-on-native-groups
@findex gnus-group-clear-data-on-native-groups
-If you don't have access to both the old and new server, all your marks
-and read ranges have become worthless. You can use the @kbd{M-x
-gnus-group-clear-data-on-native-groups} command to clear out all data
-that you have on your native groups. Use with caution.
+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.
@kindex M-x gnus-group-clear-data
@findex gnus-group-clear-data
@item gnus-before-startup-hook
@vindex gnus-before-startup-hook
-A hook run after starting up Gnus successfully.
+A hook called as the first thing when Gnus is started.
@item gnus-startup-hook
@vindex gnus-startup-hook
@vindex gnus-no-groups-message
Message displayed by Gnus when no groups are available.
-@item gnus-play-startup-jingle
-@vindex gnus-play-startup-jingle
-If non-@code{nil}, play the Gnus jingle at startup.
-
-@item gnus-startup-jingle
-@vindex gnus-startup-jingle
-Jingle to be played if the above variable is non-@code{nil}. The
-default is @samp{Tuxedomoon.Jingle4.au}.
+@item gnus-use-backend-marks
+@vindex gnus-use-backend-marks
+If non-@code{nil}, Gnus will store article marks both in the
+@file{.newsrc.eld} file and in the backends. This will slow down
+group operation some.
@end table
* Exiting Gnus:: Stop reading news and get some work done.
* Group Topics:: A folding group mode divided into topics.
* Non-ASCII Group Names:: Accessing groups of non-English names.
-* Searching:: Mail search engines.
* Misc Group Stuff:: Other stuff that you can to do.
@end menu
@vindex gnus-group-update-hook
@findex gnus-group-highlight-line
@code{gnus-group-update-hook} is called when a group line is changed.
-It will not be called when @code{gnus-visual} is @code{nil}. This hook
-calls @code{gnus-group-highlight-line} by default.
+It will not be called when @code{gnus-visual} is @code{nil}.
@node Group Maneuvering
@vindex gnus-auto-select-subject
If @code{gnus-auto-select-first} is non-@code{nil}, select an article
automatically when entering a group with the @kbd{SPACE} command.
-Which article this is is controlled by the
+Which article this is controlled by the
@code{gnus-auto-select-subject} variable. Valid values for this
variable are:
@section Subscription Commands
@cindex subscription
+The following commands allow for managing your subscriptions in the
+Group buffer. If you want to subscribe to many groups, it's probably
+more convenient to go to the @ref{Server Buffer}, and choose the
+server there using @kbd{RET} or @kbd{SPC}. Then you'll have the
+commands listed in @ref{Browse Foreign Server} at hand.
+
@table @kbd
@item S t
All groups with a level less than or equal to
@code{gnus-group-default-list-level} will be listed in the group buffer
by default.
+This variable can also be a function. In that case, that function will
+be called and the result will be used as value.
+
@vindex gnus-group-list-inactive-groups
If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
@section Foreign Groups
@cindex foreign groups
+If you recall how to subscribe to servers (@pxref{Finding the News})
+you will remember that @code{gnus-secondary-select-methods} and
+@code{gnus-select-method} let you write a definition in Emacs Lisp of
+what servers you want to see when you start up. The alternate
+approach is to use foreign servers and groups. ``Foreign'' here means
+they are not coming from the select methods. All foreign server
+configuration and subscriptions are stored only in the
+@file{~/.newsrc.eld} file.
+
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. All these commands insert the newly created
@findex gnus-group-make-help-group
Make the Gnus help group (@code{gnus-group-make-help-group}).
-@item G a
-@kindex G a (Group)
-@cindex (ding) archive
-@cindex archive group
-@findex gnus-group-make-archive-group
-@vindex gnus-group-archive-directory
-@vindex gnus-group-recent-archive-directory
-Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
-default a group pointing to the most recent articles will be created
-(@code{gnus-group-recent-archive-directory}), but given a prefix, a full
-group will be created from @code{gnus-group-archive-directory}.
-
-@item G k
-@kindex G k (Group)
-@findex gnus-group-make-kiboze-group
-@cindex nnkiboze
-Make a kiboze group. You will be prompted for a name, for a regexp to
-match groups to be ``included'' in the kiboze group, and a series of
-strings to match on headers (@code{gnus-group-make-kiboze-group}).
-@xref{Kibozed Groups}.
-
@item G D
@kindex G D (Group)
@findex gnus-group-enter-directory
Top, sieve, Emacs Sieve}.
@item (agent parameters)
-If the agent has been enabled, you can set any of the its parameters
-to control the behavior of the agent in individual groups. See Agent
+If the agent has been enabled, you can set any of its parameters to
+control the behavior of the agent in individual groups. See Agent
Parameters in @ref{Category Syntax}. Most users will choose to set
agent parameters in either an agent category or group topic to
minimize the configuration effort.
in the summary buffer you enter, and the form @code{nil} will be
@code{eval}ed there.
-Note that this feature sets the variable locally to the summary buffer.
+Note that this feature sets the variable locally to the summary buffer
+if and only if @var{variable} has been bound as a variable. Otherwise,
+only evaluating the form will take place. So, you may want to bind the
+variable in advance using @code{defvar} or other if the result of the
+form needs to be set to it.
+
But some variables are evaluated in the article buffer, or in the
message buffer (of a reply or followup or otherwise newly created
message). As a workaround, it might help to add the variable in
This can also be used as a group-specific hook function. If you want to
hear a beep when you enter a group, you could put something like
-@code{(dummy-variable (ding))} in the parameters of that group.
-@code{dummy-variable} will be set to the (meaningless) result of the
-@code{(ding)} form.
+@code{(dummy-variable (ding))} in the parameters of that group. If
+@code{dummy-variable} has been bound (see above), it will be set to the
+(meaningless) result of the @code{(ding)} form.
Alternatively, since the VARIABLE becomes local to the group, this
pattern can be used to temporarily change a hook. For example, if the
@item u
@kindex u (Browse)
@findex gnus-browse-unsubscribe-current-group
+@vindex gnus-browse-subscribe-newsgroup-method
Unsubscribe to the current group, or, as will be the case here,
-subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
+subscribe to it (@code{gnus-browse-unsubscribe-current-group}). You
+can affect the way the new group is entered into the Group buffer
+using the variable @code{gnus-browse-subscribe-newsgroup-method}. See
+@pxref{Subscription Methods} for available options.
@item l
@itemx q
@code{gnus-group-name-charset-group-alist}.
There is one more important variable for non-@acronym{ASCII} group
-names. @emph{XEmacs users must set this}. Emacs users necessarily need
-not do:
+names:
@table @code
@item nnmail-pathname-coding-system
-The value of this variable should be a coding system or @code{nil}
-(which is the default). The @code{nnml} back end, the @code{nnrss} back
-end, the @acronym{NNTP} marks feature (@pxref{NNTP marks}), the agent,
-and the cache use non-@acronym{ASCII} group names in those files and
-directories. This variable overrides the value of
-@code{file-name-coding-system} which specifies the coding system used
-when encoding and decoding those file names and directory names.
+@vindex nnmail-pathname-coding-system
+The value of this variable should be a coding system or @code{nil}. The
+default is @code{nil} in Emacs, or is the aliasee of the coding system
+named @code{file-name} (a certain coding system of which an alias is
+@code{file-name}) in XEmacs.
+
+The @code{nnml} back end, the @code{nnrss} back end, the @acronym{NNTP}
+marks feature (@pxref{NNTP marks}), the agent, and the cache use
+non-@acronym{ASCII} group names in those files and directories. This
+variable overrides the value of @code{file-name-coding-system} which
+specifies the coding system used when encoding and decoding those file
+names and directory names.
In XEmacs (with the @code{mule} feature), @code{file-name-coding-system}
is the only means to specify the coding system used to encode and decode
-file names. Therefore, @emph{you, XEmacs users, have to set it} to the
-coding system that is suitable to encode and decode non-@acronym{ASCII}
-group names. On the other hand, Emacs uses the value of
+file names. On the other hand, Emacs uses the value of
@code{default-file-name-coding-system} if @code{file-name-coding-system}
-is @code{nil}. Normally the value of
-@code{default-file-name-coding-system} is initialized according to the
-locale, so you will need to do nothing if the value is suitable to
-encode and decode non-@acronym{ASCII} group names.
+is @code{nil} or it is bound to the value of
+@code{nnmail-pathname-coding-system} which is @code{nil}.
+
+Normally the value of @code{default-file-name-coding-system} in Emacs or
+@code{nnmail-pathname-coding-system} in XEmacs is initialized according
+to the locale, so you will need to do nothing if the value is suitable
+to encode and decode non-@acronym{ASCII} group names.
The value of this variable (or @code{default-file-name-coding-system})
does not necessarily need to be the same value that is determined by
@code{gnus-group-name-charset-method-alist} and
@code{gnus-group-name-charset-group-alist}.
-If you want to subscribe to the groups spelled in Chinese but
-@code{default-file-name-coding-system} is initialized by default to
-@code{iso-latin-1} for example, that is the most typical case where you
-have to set @code{nnmail-pathname-coding-system} even if you are an
-Emacs user. The @code{utf-8} coding system is a good candidate for it.
-Otherwise, you may change the locale in your system so that
-@code{default-file-name-coding-system} may be initialized to an
-appropriate value, instead of specifying this variable.
+If @code{default-file-name-coding-system} or this variable is
+initialized by default to @code{iso-latin-1} for example, although you
+want to subscribe to the groups spelled in Chinese, that is the most
+typical case where you have to customize
+@code{nnmail-pathname-coding-system}. The @code{utf-8} coding system is
+a good candidate for it. Otherwise, you may change the locale in your
+system so that @code{default-file-name-coding-system} or this variable
+may be initialized to an appropriate value.
@end table
Note that when you copy or move articles from a non-@acronym{ASCII}
header will be displayed incorrectly in the article buffer.
-@node Searching
-@section Searching
+@node Misc Group Stuff
+@section Misc Group Stuff
@menu
-* nnir:: Searching on IMAP, with swish, namazu, etc.
-* nnmairix:: Searching maildir, MH or mbox with Mairix.
+* Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
+* Group Information:: Information and help on groups and Gnus.
+* Group Timestamp:: Making Gnus keep track of when you last read a group.
+* File Commands:: Reading and writing the Gnus files.
+* Sieve Commands:: Managing Sieve scripts.
@end menu
-@cindex Searching
-
-FIXME: This node is a stub.
-
-FIXME: Add a brief overview of Gnus search capabilities. A brief
-comparison of nnir, nnmairix, contrib/gnus-namazu would be nice
-as well.
-
-FIXME: Explain difference to @ref{Searching for Articles}, add reference
-and back-reference.
-
-@node nnir
-@subsection nnir
+@table @kbd
-FIXME: As a first step, convert the commentary of @file{nnir} to texi.
-@cindex nnir
+@item v
+@kindex v (Group)
+@cindex keys, reserved for users (Group)
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key. For example:
-@node nnmairix
-@subsection nnmairix
+@lisp
+(define-key gnus-group-mode-map (kbd "v j d")
+ (lambda ()
+ (interactive)
+ (gnus-group-jump-to-group "nndraft:drafts")))
+@end lisp
-@cindex mairix
-@cindex nnmairix
-This paragraph describes how to set up mairix and the back end
-@code{nnmairix} for indexing and searching your mail from within
-Gnus. Additionally, you can create permanent ``smart'' groups which are
-bound to mairix searches and are automatically updated.
+On keys reserved for users in Emacs and on keybindings in general
+@xref{Keymaps, Keymaps, , emacs, The Emacs Editor}.
-@menu
-* About mairix:: About the mairix mail search engine
-* nnmairix requirements:: What you will need for using nnmairix
-* What nnmairix does:: What does nnmairix actually do?
-* Setting up mairix:: Set up your mairix installation
-* Configuring nnmairix:: Set up the nnmairix back end
-* nnmairix keyboard shortcuts:: List of available keyboard shortcuts
-* Propagating marks:: How to propagate marks from nnmairix groups
-* nnmairix tips and tricks:: Some tips, tricks and examples
-* nnmairix caveats:: Some more stuff you might want to know
-@end menu
+@item ^
+@kindex ^ (Group)
+@findex gnus-group-enter-server-mode
+Enter the server buffer (@code{gnus-group-enter-server-mode}).
+@xref{Server Buffer}.
+@item a
+@kindex a (Group)
+@findex gnus-group-post-news
+Start composing a message (a news by default)
+(@code{gnus-group-post-news}). If given a prefix, post to the group
+under the point. If the prefix is 1, prompt for a group to post to.
+Contrary to what the name of this function suggests, the prepared
+article might be a mail instead of a news, if a mail group is specified
+with the prefix argument. @xref{Composing Messages}.
-@node About mairix
-@subsubsection About mairix
+@item m
+@kindex m (Group)
+@findex gnus-group-mail
+Mail a message somewhere (@code{gnus-group-mail}). If given a prefix,
+use the posting style of the group under the point. If the prefix is 1,
+prompt for a group name to find the posting style.
+@xref{Composing Messages}.
-Mairix is a tool for indexing and searching words in locally stored
-mail. It was written by Richard Curnow and is licensed under the
-GPL. Mairix comes with most popular Linux distributions, but it also
-runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can
-be found at
+@item i
+@kindex i (Group)
+@findex gnus-group-news
+Start composing a news (@code{gnus-group-news}). If given a prefix,
+post to the group under the point. If the prefix is 1, prompt
+for group to post to. @xref{Composing Messages}.
-@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html}
+This function actually prepares a news even when using mail groups.
+This is useful for ``posting'' messages to mail groups without actually
+sending them over the network: they're just saved directly to the group
+in question. The corresponding back end must have a request-post method
+for this to work though.
-Though mairix might not be as flexible as other search tools like
-swish++ or namazu, which you can use via the @code{nnir} back end, it
-has the prime advantage of being incredibly fast. On current systems, it
-can easily search through headers and message bodies of thousands and
-thousands of mails in well under a second. Building the database
-necessary for searching might take a minute or two, but only has to be
-done once fully. Afterwards, the updates are done incrementally and
-therefore are really fast, too. Additionally, mairix is very easy to set
-up.
+@item G z
+@kindex G z (Group)
+@findex gnus-group-compact-group
-For maximum speed though, mairix should be used with mails stored in
-@code{Maildir} or @code{MH} format (this includes the @code{nnml} back
-end), although it also works with mbox. Mairix presents the search
-results by populating a @emph{virtual} maildir/MH folder with symlinks
-which point to the ``real'' message files (if mbox is used, copies are
-made). Since mairix already presents search results in such a virtual
-mail folder, it is very well suited for using it as an external program
-for creating @emph{smart} mail folders, which represent certain mail
-searches. This is similar to a Kiboze group (@pxref{Kibozed Groups}),
-but much faster.
+Compact the group under point (@code{gnus-group-compact-group}).
+Currently implemented only in nnml (@pxref{Mail Spool}). This removes
+gaps between article numbers, hence getting a correct total article
+count.
-@node nnmairix requirements
-@subsubsection nnmairix requirements
+@end table
-Mairix searches local mail - that means, mairix absolutely must have
-direct access to your mail folders. If your mail resides on another
-server (e.g. an @acronym{IMAP} server) and you happen to have shell
-access, @code{nnmairix} supports running mairix remotely, e.g. via ssh.
+Variables for the group buffer:
-Additionally, @code{nnmairix} only supports the following Gnus back
-ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You
-@strong{must} use one of these back ends for using
-@code{nnmairix}. Other back ends, like @code{nnmbox}, @code{nnfolder} or
-@code{nnmh}, won't work.
+@table @code
-If you absolutely must use mbox and still want to use @code{nnmairix},
-you can set up a local @acronym{IMAP} server, which you then access via
-@code{nnimap}. This is a rather massive setup for accessing some mbox
-files, so just change to MH or Maildir already...
+@item gnus-group-mode-hook
+@vindex gnus-group-mode-hook
+is called after the group buffer has been
+created.
-@node What nnmairix does
-@subsubsection What nnmairix does
+@item gnus-group-prepare-hook
+@vindex gnus-group-prepare-hook
+is called after the group buffer is
+generated. It may be used to modify the buffer in some strange,
+unnatural way.
-The back end @code{nnmairix} enables you to call mairix from within Gnus,
-either to query mairix with a search term or to update the
-database. While visiting a message in the summary buffer, you can use
-several pre-defined shortcuts for calling mairix, e.g. to quickly
-search for all mails from the sender of the current message or to
-display the whole thread associated with the message, even if the
-mails are in different folders.
+@item gnus-group-prepared-hook
+@vindex gnus-group-prepare-hook
+is called as the very last thing after the group buffer has been
+generated. It may be used to move point around, for instance.
-Additionally, you can create permanent @code{nnmairix} groups which are bound
-to certain mairix searches. This way, you can easily create a group
-containing mails from a certain sender, with a certain subject line or
-even for one specific thread based on the message ID. If you check for
-new mail in these folders (e.g. by pressing @kbd{g} or @kbd{M-g}), they
-automatically update themselves by calling mairix.
+@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.
-You might ask why you need @code{nnmairix} at all, since mairix already
-creates the group, populates it with links to the mails so that you can
-then access it with Gnus, right? Well, this @emph{might} work, but often
-does not - at least not without problems. Most probably you will get
-strange article counts, and sometimes you might see mails which Gnus
-claims have already been canceled and are inaccessible. This is due to
-the fact that Gnus isn't really amused when things are happening behind
-its back. Another problem can be the mail back end itself, e.g. if you
-use mairix with an @acronym{IMAP}-Server (I had Dovecot complaining
-about corrupt index files when mairix changed the contents of the search
-group). Using @code{nnmairix} should circumvent these problems.
-
-@code{nnmairix} is not really a mail back end - it's actually more like a
-wrapper, sitting between a ``real'' mail back end where mairix stores the
-searches and the Gnus front end. You can choose between three different
-mail back ends for the mairix folders: @code{nnml}, @code{nnmaildir} or
-@code{nnimap}. @code{nnmairix} will call the mairix binary so that the
-search results are stored in folders named
-@code{zz_mairix-<NAME>-<NUMBER>} on this mail back end, but it will
-present these folders in the Gnus front end only with @code{<NAME>}. You
-can use an existing mail back end where you already store your mail, but
-if you're uncomfortable with @code{nnmairix} creating new mail groups
-alongside your other mail, you can also create e.g. a new
-@code{nnmaildir} server exclusively for mairix. However, a special case
-exists if you want to use mairix remotely on an IMAP server with
-@code{nnimap} - here the mairix folders and your other mail must be on
-the same @code{nnimap} back end.
+@end table
-@node Setting up mairix
-@subsubsection Setting up mairix
+@node Scanning New Messages
+@subsection Scanning New Messages
+@cindex new messages
+@cindex scanning new news
-First: create a backup of your mail folders (@pxref{nnmairix caveats}).
+@table @kbd
-Setting up mairix is easy: simply create a @file{.mairixrc} file with
-(at least) the following entries:
+@item g
+@kindex g (Group)
+@findex gnus-group-get-new-news
+@c @icon{gnus-group-get-new-news}
+Check the server(s) for new articles. If the numerical prefix is used,
+this command will check only groups of level @var{arg} and lower
+(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
+command will force a total re-reading of the active file(s) from the
+back end(s).
-@example
-# Your Maildir/MH base folder
-base=~/Maildir
-@end example
+@item M-g
+@kindex M-g (Group)
+@findex gnus-group-get-new-news-this-group
+@vindex gnus-goto-next-group-when-activating
+@c @icon{gnus-group-get-new-news-this-group}
+Check whether new articles have arrived in the current group
+(@code{gnus-group-get-new-news-this-group}).
+@code{gnus-goto-next-group-when-activating} says whether this command is
+to move point to the next group or not. It is @code{t} by default.
-This is the base folder for your mails. All the following paths are
-relative to this base folder. If you want to use @code{nnmairix} with
-@code{nnimap}, this base path has to point to the mail path where the
-@acronym{IMAP} server stores the mail folders!
+@findex gnus-activate-all-groups
+@cindex activating groups
+@item C-c M-g
+@kindex C-c M-g (Group)
+Activate absolutely all groups (@code{gnus-activate-all-groups}).
-@example
-maildir= ... your maildir folders which should be indexed ...
-mh= ... your nnml/mh folders which should be indexed ...
-mbox = ... your mbox files which should be indexed ...
-@end example
+@item R
+@kindex R (Group)
+@cindex restarting
+@findex gnus-group-restart
+Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc}
+file(s), closes the connection to all servers, clears up all run-time
+Gnus variables, and then starts Gnus all over again.
-Specify all your maildir/nnml folders and mbox files (relative to the
-base path!) you want to index with mairix. See the man-page for
-mairixrc for details.
+@end table
-@example
-omit=zz_mairix-*
-@end example
+@vindex gnus-get-new-news-hook
+@code{gnus-get-new-news-hook} is run just before checking for new news.
-@vindex nnmairix-group-prefix
-This should make sure that you don't accidentally index the mairix
-search results. You can change the prefix of these folders with the
-variable @code{nnmairix-group-prefix}.
+@vindex gnus-after-getting-new-news-hook
+@code{gnus-after-getting-new-news-hook} is run after checking for new
+news.
-@example
-mformat= ... 'maildir' or 'mh' ...
-database= ... location of database file ...
-@end example
-The @code{format} setting specifies the output format for the mairix
-search folder. Set this to @code{mh} if you want to access search results
-with @code{nnml}. Otherwise choose @code{maildir}.
+@node Group Information
+@subsection Group Information
+@cindex group information
+@cindex information on groups
-See the man pages for mairix and mairixrc for further options. Now
-simply call @code{mairix} to create the index for the first time.
+@table @kbd
-@node Configuring nnmairix
-@subsubsection Configuring nnmairix
-In group mode, type @kbd{G b c}
-(@code{nnmairix-create-server-and-default-group}). This will ask you for all
-necessary information and create a @code{nnmairix} server as a foreign
-server. You will have to specify the following:
-
-@itemize @bullet
-
-@item
-The @strong{name} of the @code{nnmairix} server - choose whatever you
-want.
-
-@item
-The @strong{mail back end} where mairix should stores its
-searches. Currently @code{nnmaildir}, @code{nnimap} and @code{nnml} are
-supported. As explained above, for locally stored mails, this can be an
-existing mail back end where you store your mails. However, you can also
-create e.g. a new @code{nnmaildir} server exclusively for
-@code{nnmairix} in your secondary select methods (@pxref{Finding the
-News}). If you want to use mairix remotely on an @acronym{IMAP} server,
-you have to choose the corresponding @code{nnimap} back end here.
-
-@item
-@vindex nnmairix-mairix-search-options
-The @strong{command} to call the mairix binary. This will usually just
-be @code{mairix}, but you can also choose something like @code{ssh
-SERVER mairix} if you want to call mairix remotely, e.g. on your
-@acronym{IMAP} server. If you want to add some default options to
-mairix, you could do this here, but better use the variable
-@code{nnmairix-mairix-search-options} instead.
+@item H f
+@kindex H f (Group)
+@findex gnus-group-fetch-faq
+@vindex gnus-group-faq-directory
+@cindex FAQ
+@cindex ange-ftp
+Try to fetch the @acronym{FAQ} for the current group
+(@code{gnus-group-fetch-faq}). Gnus will try to get the @acronym{FAQ}
+from @code{gnus-group-faq-directory}, which is usually a directory on
+a remote machine. This variable can also be a list of directories.
+In that case, giving a prefix to this command will allow you to choose
+between the various sites. @code{ange-ftp} (or @code{efs}) will be
+used for fetching the file.
-@item
-The name of the @strong{default search group}. This will be the group
-where all temporary mairix searches are stored, i.e. all searches which
-are not bound to permanent @code{nnmairix} groups. Choose whatever you
-like.
+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
-If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be
-asked if you work with @strong{Maildir++}, i.e. with hidden maildir
-folders (=beginning with a dot). For example, you have to answer
-@samp{yes} here if you work with the Dovecot @acronym{IMAP}
-server. Otherwise, you should answer @samp{no} here.
+@item H d
+@itemx C-c C-d
+@c @icon{gnus-group-describe-group}
+@kindex H d (Group)
+@kindex C-c C-d (Group)
+@cindex describing groups
+@cindex group description
+@findex gnus-group-describe-group
+Describe the current group (@code{gnus-group-describe-group}). If given
+a prefix, force Gnus to re-read the description from the server.
-@end itemize
+@item M-d
+@kindex M-d (Group)
+@findex gnus-group-describe-all-groups
+Describe all groups (@code{gnus-group-describe-all-groups}). If given a
+prefix, force Gnus to re-read the description file from the server.
-@node nnmairix keyboard shortcuts
-@subsubsection nnmairix keyboard shortcuts
+@item H v
+@itemx V
+@kindex V (Group)
+@kindex H v (Group)
+@cindex version
+@findex gnus-version
+Display current Gnus version numbers (@code{gnus-version}).
-In group mode:
+@item ?
+@kindex ? (Group)
+@findex gnus-group-describe-briefly
+Give a very short help message (@code{gnus-group-describe-briefly}).
-@table @kbd
+@item C-c C-i
+@kindex C-c C-i (Group)
+@cindex info
+@cindex manual
+@findex gnus-info-find-node
+Go to the Gnus info node (@code{gnus-info-find-node}).
+@end table
-@item G b c
-@kindex G b c (Group)
-@findex nnmairix-create-server-and-default-group
-Creates @code{nnmairix} server and default search group for this server
-(@code{nnmairix-create-server-and-default-group}). You should have done
-this by now (@pxref{Configuring nnmairix}).
-@item G b s
-@kindex G b s (Group)
-@findex nnmairix-search
-Prompts for query which is then sent to the mairix binary. Search
-results are put into the default search group which is automatically
-displayed (@code{nnmairix-search}).
+@node Group Timestamp
+@subsection Group Timestamp
+@cindex timestamps
+@cindex group timestamps
-@item G b m
-@kindex G b m (Group)
-@findex nnmairix-widget-search
-Allows you to create a mairix search or a permanent group more
-comfortably using graphical widgets, similar to a customization
-group. Just try it to see how it works (@code{nnmairix-widget-search}).
+It can be convenient to let Gnus keep track of when you last read a
+group. To set the ball rolling, you should add
+@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}:
-@item G b i
-@kindex G b i (Group)
-@findex nnmairix-search-interactive
-Another command for creating a mairix query more comfortably, but uses
-only the minibuffer (@code{nnmairix-search-interactive}).
+@lisp
+(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp)
+@end lisp
-@item G b g
-@kindex G b g (Group)
-@findex nnmairix-create-search-group
-Creates a permanent group which is associated with a search query
-(@code{nnmairix-create-search-group}). The @code{nnmairix} back end
-automatically calls mairix when you update this group with @kbd{g} or
-@kbd{M-g}.
+After doing this, each time you enter a group, it'll be recorded.
-@item G b q
-@kindex G b q (Group)
-@findex nnmairix-group-change-query-this-group
-Changes the search query for the @code{nnmairix} group under cursor
-(@code{nnmairix-group-change-query-this-group}).
+This information can be displayed in various ways---the easiest is to
+use the @samp{%d} spec in the group line format:
-@item G b t
-@kindex G b t (Group)
-@findex nnmairix-group-toggle-threads-this-group
-Toggles the 'threads' parameter for the @code{nnmairix} group under cursor,
-i.e. if you want see the whole threads of the found messages
-(@code{nnmairix-group-toggle-threads-this-group}).
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n")
+@end lisp
-@item G b u
-@kindex G b u (Group)
-@findex nnmairix-update-database
-@vindex nnmairix-mairix-update-options
-Calls mairix binary for updating the database
-(@code{nnmairix-update-database}). The default parameters are @code{-F}
-and @code{-Q} for making this as fast as possible (see variable
-@code{nnmairix-mairix-update-options} for defining these default
-options).
+This will result in lines looking like:
-@item G b r
-@kindex G b r (Group)
-@findex nnmairix-group-toggle-readmarks-this-group
-Keep articles in this @code{nnmairix} group always read or unread, or leave the
-marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}).
+@example
+* 0: mail.ding 19961002T012943
+ 0: custom 19961002T012713
+@end example
-@item G b d
-@kindex G b d (Group)
-@findex nnmairix-group-delete-recreate-this-group
-Recreate @code{nnmairix} group on the ``real'' mail back end
-(@code{nnmairix-group-delete-recreate-this-group}). You can do this if
-you always get wrong article counts with a @code{nnmairix} group.
+As you can see, the date is displayed in compact ISO 8601 format. This
+may be a bit too much, so to just display the date, you could say
+something like:
-@item G b a
-@kindex G b a (Group)
-@findex nnmairix-group-toggle-allowfast-this-group
-Toggles the @code{allow-fast} parameters for group under cursor
-(@code{nnmairix-group-toggle-allowfast-this-group}). The default
-behavior of @code{nnmairix} is to do a mairix search every time you
-update or enter the group. With the @code{allow-fast} parameter set,
-mairix will only be called when you explicitly update the group, but not
-upon entering. This makes entering the group faster, but it may also
-lead to dangling symlinks if something changed between updating and
-entering the group which is not yet in the mairix database.
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n")
+@end lisp
-@item G b p
-@kindex G b p (Group)
-@findex nnmairix-group-toggle-propmarks-this-group
-Toggle marks propagation for this group
-(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating
-marks}).
+If you would like greater control of the time format, you can use a
+user-defined format spec. Something like the following should do the
+trick:
-@item G b o
-@kindex G b o (Group)
-@findex nnmairix-propagate-marks
-Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when
-@code{nnmairix-propagate-marks-upon-close} is set to @code{nil}.
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %ud\n")
+(defun gnus-user-format-function-d (headers)
+ (let ((time (gnus-group-timestamp gnus-tmp-group)))
+ (if time
+ (format-time-string "%b %d %H:%M" time)
+ "")))
+@end lisp
-@end table
-In summary mode:
+@node File Commands
+@subsection File Commands
+@cindex file commands
@table @kbd
-@item $ m
-@kindex $ m (Summary)
-@findex nnmairix-widget-search-from-this-article
-Allows you to create a mairix query or group based on the current
-message using graphical widgets (same as @code{nnmairix-widget-search})
-(@code{nnmairix-widget-search-from-this-article}).
-
-@item $ g
-@kindex $ g (Summary)
-@findex nnmairix-create-search-group-from-message
-Interactively creates a new search group with query based on the current
-message, but uses the minibuffer instead of graphical widgets
-(@code{nnmairix-create-search-group-from-message}).
-
-@item $ t
-@kindex $ t (Summary)
-@findex nnmairix-search-thread-this-article
-Searches thread for the current article
-(@code{nnmairix-search-thread-this-article}). This is effectively a
-shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the
-current article and enabled threads.
-
-@item $ f
-@kindex $ f (Summary)
-@findex nnmairix-search-from-this-article
-Searches all messages from sender of the current article
-(@code{nnmairix-search-from-this-article}). This is a shortcut for
-calling @code{nnmairix-search} with @samp{f:From}.
+@item r
+@kindex r (Group)
+@findex gnus-group-read-init-file
+@vindex gnus-init-file
+@cindex reading init file
+Re-read the init file (@code{gnus-init-file}, which defaults to
+@file{~/.gnus.el}) (@code{gnus-group-read-init-file}).
-@item $ o
-@kindex $ o (Summary)
-@findex nnmairix-goto-original-article
-(Only in @code{nnmairix} groups!) Tries determine the group this article
-originally came from and displays the article in this group, so that
-e.g. replying to this article the correct posting styles/group
-parameters are applied (@code{nnmairix-goto-original-article}). This
-function will use the registry if available, but can also parse the
-article file path as a fallback method.
+@item s
+@kindex s (Group)
+@findex gnus-group-save-newsrc
+@cindex saving .newsrc
+Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
+(@code{gnus-group-save-newsrc}). If given a prefix, force saving the
+file(s) whether Gnus thinks it is necessary or not.
-@item $ u
-@kindex $ u (Summary)
-@findex nnmairix-remove-tick-mark-original-article
-Remove possibly existing tick mark from original article
-(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix
-tips and tricks}).
+@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
-@node Propagating marks
-@subsubsection Propagating marks
-First of: you really need a patched mairix binary for using the marks
-propagation feature efficiently. Otherwise, you would have to update
-the mairix database all the time. You can get the patch at
+@node Sieve Commands
+@subsection Sieve Commands
+@cindex group sieve commands
-@uref{http://m61s02.vlinux.de/mairix-maildir-patch.tar}
-
-You need the mairix v0.21 source code for this patch; everything else
-is explained in the accompanied readme file. If you don't want to use
-marks propagation, you don't have to apply these patches, but they also
-fix some annoyances regarding changing maildir flags, so it might still
-be useful to you.
-
-With the patched mairix binary, you can use @code{nnmairix} as an
-alternative to mail splitting (@pxref{Fancy Mail Splitting}). For
-example, instead of splitting all mails from @samp{david@@foobar.com}
-into a group, you can simply create a search group with the query
-@samp{f:david@@foobar.com}. This is actually what ``smart folders'' are
-all about: simply put everything in one mail folder and dynamically
-create searches instead of splitting. This is more flexible, since you
-can dynamically change your folders any time you want to. This also
-implies that you will usually read your mails in the @code{nnmairix}
-groups instead of your ``real'' mail groups.
-
-There is one problem, though: say you got a new mail from
-@samp{david@@foobar.com} - it will now show up in two groups, the
-``real'' group (your INBOX, for example) and in the @code{nnmairix}
-search group (provided you have updated the mairix database). Now you
-enter the @code{nnmairix} group and read the mail. The mail will be
-marked as read, but only in the @code{nnmairix} group - in the ``real''
-mail group it will be still shown as unread.
+Sieve is a server-side mail filtering language. In Gnus you can use
+the @code{sieve} group parameter (@pxref{Group Parameters}) to specify
+sieve rules that should apply to each group. Gnus provides two
+commands to translate all these group parameters into a proper Sieve
+script that can be transfered to the server somehow.
-You could now catch up the mail group (@pxref{Group Data}), but this is
-tedious and error prone, since you may overlook mails you don't have
-created @code{nnmairix} groups for. Of course, you could first use
-@code{nnmairix-goto-original-article} (@pxref{nnmairix keyboard
-shortcuts}) and then read the mail in the original group, but that's
-even more cumbersome.
+@vindex gnus-sieve-file
+@vindex gnus-sieve-region-start
+@vindex gnus-sieve-region-end
+The generated Sieve script is placed in @code{gnus-sieve-file} (by
+default @file{~/.sieve}). The Sieve code that Gnus generate is placed
+between two delimiters, @code{gnus-sieve-region-start} and
+@code{gnus-sieve-region-end}, so you may write additional Sieve code
+outside these delimiters that will not be removed the next time you
+regenerate the Sieve script.
-Clearly, the easiest way would be if marks could somehow be
-automatically set for the original article. This is exactly what
-@emph{marks propagation} is about.
+@vindex gnus-sieve-crosspost
+The variable @code{gnus-sieve-crosspost} controls how the Sieve script
+is generated. If it is non-@code{nil} (the default) articles is
+placed in all groups that have matching rules, otherwise the article
+is only placed in the group with the first matching rule. For
+example, the group parameter @samp{(sieve address "sender"
+"owner-ding@@hpc.uh.edu")} will generate the following piece of Sieve
+code if @code{gnus-sieve-crosspost} is @code{nil}. (When
+@code{gnus-sieve-crosspost} is non-@code{nil}, it looks the same
+except that the line containing the call to @code{stop} is removed.)
-Marks propagation is deactivated by default. You can activate it for a
-certain @code{nnmairix} group with
-@code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b
-p}). This function will warn you if you try to use it with your default
-search group; the reason is that the default search group is used for
-temporary searches, and it's easy to accidentally propagate marks from
-this group. However, you can ignore this warning if you really want to.
+@example
+if address "sender" "owner-ding@@hpc.uh.edu" @{
+ fileinto "INBOX.ding";
+ stop;
+@}
+@end example
-With marks propagation enabled, all the marks you set in a @code{nnmairix}
-group should now be propagated to the original article. For example,
-you can now tick an article (by default with @kbd{!}) and this mark should
-magically be set for the original article, too.
+@xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}.
-A few more remarks which you may or may not want to know:
+@table @kbd
-@vindex nnmairix-propagate-marks-upon-close
-Marks will not be set immediately, but only upon closing a group. This
-not only makes marks propagation faster, it also avoids problems with
-dangling symlinks when dealing with maildir files (since changing flags
-will change the file name). You can also control when to propagate marks
-via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for
-details).
+@item D g
+@kindex D g (Group)
+@findex gnus-sieve-generate
+@vindex gnus-sieve-file
+@cindex generating sieve script
+Regenerate a Sieve script from the @code{sieve} group parameters and
+put you into the @code{gnus-sieve-file} without saving it.
-Obviously, @code{nnmairix} will have to look up the original group for every
-article you want to set marks for. If available, @code{nnmairix} will first use
-the registry for determining the original group. The registry is very
-fast, hence you should really, really enable the registry when using
-marks propagation. If you don't have to worry about RAM and disc space,
-set @code{gnus-registry-max-entries} to a large enough value; to be on
-the safe side, choose roughly the amount of mails you index with mairix.
+@item D u
+@kindex D u (Group)
+@findex gnus-sieve-update
+@vindex gnus-sieve-file
+@cindex updating sieve script
+Regenerates the Gnus managed part of @code{gnus-sieve-file} using the
+@code{sieve} group parameters, save the file and upload it to the
+server using the @code{sieveshell} program.
-@vindex nnmairix-only-use-registry
-If you don't want to use the registry or the registry hasn't seen the
-original article yet, @code{nnmairix} will use an additional mairix search
-for determining the file path of the article. This, of course, is way
-slower than the registry - if you set hundreds or even thousands of
-marks this way, it might take some time. You can avoid this situation
-by setting @code{nnmairix-only-use-registry} to t.
+@end table
-Maybe you also want to propagate marks the other way round, i.e. if you
-tick an article in a "real" mail group, you'd like to have the same
-article in a @code{nnmairix} group ticked, too. For several good
-reasons, this can only be done efficiently if you use maildir. To
-immediately contradict myself, let me mention that it WON'T work with
-@code{nnmaildir}, since @code{nnmaildir} stores the marks externally and
-not in the file name. Therefore, propagating marks to @code{nnmairix}
-groups will usually only work if you use an IMAP server which uses
-maildir as its file format.
-@vindex nnmairix-propagate-marks-to-nnmairix-groups
-If you work with this setup, just set
-@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t} and see what
-happens. If you don't like what you see, just set it to @code{nil} again. One
-problem might be that you get a wrong number of unread articles; this
-usually happens when you delete or expire articles in the original
-groups. When this happens, you can recreate the @code{nnmairix} group on the
-back end using @kbd{G b d}.
+@node Summary Buffer
+@chapter Summary Buffer
+@cindex summary buffer
-@node nnmairix tips and tricks
-@subsubsection nnmairix tips and tricks
+A line for each article is displayed in the summary buffer. You can
+move around, read articles, post articles and reply to articles.
-@itemize
-@item
-Checking Mail
+The most common way to a summary buffer is to select a group from the
+group buffer (@pxref{Selecting a Group}).
-@findex nnmairix-update-groups
-I put all my important mail groups at group level 1. The mairix groups
-have group level 5, so they do not get checked at start up (@pxref{Group
-Levels}).
+You can have as many summary buffers open as you wish.
-I use the following to check for mails:
+You can customize the Summary Mode tool bar, see @kbd{M-x
+customize-apropos RET gnus-summary-tool-bar}. This feature is only
+available in Emacs.
+@kindex v (Summary)
+@cindex keys, reserved for users (Summary)
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key. For example:
@lisp
-(defun my-check-mail-mairix-update (level)
- (interactive "P")
- ;; if no prefix given, set level=1
- (gnus-group-get-new-news (or level 1))
- (nnmairix-update-groups "mairixsearch" t t)
- (gnus-group-list-groups))
-
-(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update)
+(define-key gnus-summary-mode-map (kbd "v -") "LrS") ;; lower subthread
@end lisp
-Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix}
-server. See the doc string for @code{nnmairix-update-groups} for
-details.
+@menu
+* Summary Buffer Format:: Deciding how the summary buffer is to look.
+* Summary Maneuvering:: Moving around the summary buffer.
+* Choosing Articles:: Reading articles.
+* Paging the Article:: Scrolling the current article.
+* Reply Followup and Post:: Posting articles.
+* Delayed Articles:: Send articles at a later time.
+* Marking Articles:: Marking articles as read, expirable, etc.
+* Limiting:: You can limit the summary buffer.
+* Threading:: How threads are made.
+* Sorting the Summary Buffer:: 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.
+* Sticky Articles:: Article buffers that are not reused.
+* Article Backlog:: Having already read articles hang around.
+* Saving Articles:: Ways of customizing article saving.
+* Decoding Articles:: Gnus can treat series of (uu)encoded articles.
+* Article Treatment:: The article buffer can be mangled at will.
+* MIME Commands:: Doing MIMEy things with the articles.
+* Charsets:: Character set issues.
+* Article Commands:: Doing various things with the article buffer.
+* Summary Sorting:: Sorting the summary buffer in various ways.
+* Finding the Parent:: No child support? Get the parent.
+* Alternative Approaches:: Reading using non-default summaries.
+* Tree Display:: A more visual display of threads.
+* 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,
+ or reselecting the current group.
+* Crosspost Handling:: How crossposted articles are dealt with.
+* Duplicate Suppression:: An alternative when crosspost handling fails.
+* Security:: Decrypt and Verify.
+* Mailing List:: Mailing list minor mode.
+@end menu
-@item
-Example: search group for ticked articles
-For example, you can create a group for all ticked articles, where the
-articles always stay unread:
+@node Summary Buffer Format
+@section Summary Buffer Format
+@cindex summary buffer format
-Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use
-@samp{F:f} as query and do not include threads.
+@iftex
+@iflatex
+\gnusfigure{The Summary Buffer}{180}{
+\put(0,0){\epsfig{figure=ps/summary,width=7.5cm}}
+\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-article,width=7.5cm}}}
+}
+@end iflatex
+@end iftex
-Now activate marks propagation for this group by using @kbd{G b p}. Then
-activate the always-unread feature by using @kbd{G b r} twice.
+@menu
+* Summary Buffer Lines:: You can specify how summary lines should look.
+* To From Newsgroups:: How to not display your own name.
+* Summary Buffer Mode Line:: You can say how the mode line should look.
+* Summary Highlighting:: Making the summary buffer all pretty and nice.
+@end menu
-So far so good - but how do you remove the tick marks in the @code{nnmairix}
-group? There are two options: You may simply use
-@code{nnmairix-remove-tick-mark-original-article} (bound to @kbd{$ u}) to remove
-tick marks from the original article. The other possibility is to set
-@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t}, but see the above
-comments about this option. If it works for you, the tick marks should
-also exist in the @code{nnmairix} group and you can remove them as usual,
-e.g. by marking an article as read.
+@findex mail-extract-address-components
+@findex gnus-extract-address-components
+@vindex gnus-extract-address-components
+Gnus will use the value of the @code{gnus-extract-address-components}
+variable as a function for getting the name and address parts of a
+@code{From} header. Two pre-defined functions exist:
+@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. The default function will return the wrong answer in 5% of the
+cases. If this is unacceptable to you, use the other function instead:
-When you have removed a tick mark from the original article, this
-article should vanish from the @code{nnmairix} group after you have updated the
-mairix database and updated the group. Fortunately, there is a function
-for doing exactly that: @code{nnmairix-update-groups}. See the previous code
-snippet and the doc string for details.
+@lisp
+(setq gnus-extract-address-components
+ 'mail-extract-address-components)
+@end lisp
-@item
-Dealing with auto-subscription of mail groups
-
-As described before, all @code{nnmairix} groups are in fact stored on
-the mail back end in the form @samp{zz_mairix-<NAME>-<NUMBER>}. You can
-see them when you enter the back end server in the server buffer. You
-should not subscribe these groups! Unfortunately, these groups will
-usually get @strong{auto-subscribed} when you use @code{nnmaildir} or
-@code{nnml}, i.e. you will suddenly see groups of the form
-@samp{zz_mairix*} pop up in your group buffer. If this happens to you,
-simply kill these groups with C-k. For avoiding this, turn off
-auto-subscription completely by setting the variable
-@code{gnus-auto-subscribed-groups} to @code{nil} (@pxref{Filtering New
-Groups}), or if you like to keep this feature use the following kludge
-for turning it off for all groups beginning with @samp{zz_}:
-
-@lisp
-(setq gnus-auto-subscribed-groups
- "^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*")
-@end lisp
-
-@end itemize
-
-@node nnmairix caveats
-@subsubsection nnmairix caveats
-
-@itemize
-@item
-If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize
-@code{nnmairix} groups (though I have no idea what happens if you do).
-
-@item
-If you use the Gnus registry: don't use the registry with
-@code{nnmairix} groups (put them in
-@code{gnus-registry-unfollowed-groups}). Be @strong{extra careful} if
-you use @code{gnus-registry-split-fancy-with-parent} - mails which are
-split into @code{nnmairix} groups are usually gone for good as soon as
-you check the group for new mail (yes, it has happened to me...).
-
-@item
-Therefore: @strong{Never ever} put ``real'' mails into @code{nnmairix}
-groups (you shouldn't be able to, anyway).
-
-@item
-mairix does only support us-ascii characters.
-
-@item
-@code{nnmairix} uses a rather brute force method to force Gnus to
-completely reread the group on the mail back end after mairix was
-called - it simply deletes and re-creates the group on the mail
-back end. So far, this has worked for me without any problems, and I
-don't see how @code{nnmairix} could delete other mail groups than its
-own, but anyway: you really should have a backup of your mail
-folders.
-
-@item
-All necessary information is stored in the group parameters
-(@pxref{Group Parameters}). This has the advantage that no active file
-is needed, but also implies that when you kill a @code{nnmairix} group,
-it is gone for good.
-
-@item
-@findex nnmairix-purge-old-groups
-If you create and kill a lot of @code{nnmairix} groups, the
-``zz_mairix-*'' groups will accumulate on the mail back end server. To
-delete old groups which are no longer needed, call
-@code{nnmairix-purge-old-groups}. Note that this assumes that you don't
-save any ``real'' mail in folders of the form
-@code{zz_mairix-<NAME>-<NUMBER>}. You can change the prefix of
-@code{nnmairix} groups by changing the variable
-@code{nnmairix-group-prefix}.
-
-@item
-The following only applies if you @strong{don't} use the mentioned patch
-for mairix (@pxref{Propagating marks}):
-
-A problem can occur when using @code{nnmairix} with maildir folders and
-comes with the fact that maildir stores mail flags like @samp{Seen} or
-@samp{Replied} by appending chars @samp{S} and @samp{R} to the message
-file name, respectively. This implies that currently you would have to
-update the mairix database not only when new mail arrives, but also when
-mail flags are changing. The same applies to new mails which are indexed
-while they are still in the @samp{new} folder but then get moved to
-@samp{cur} when Gnus has seen the mail. If you don't update the database
-after this has happened, a mairix query can lead to symlinks pointing to
-non-existing files. In Gnus, these messages will usually appear with
-``(none)'' entries in the header and can't be accessed. If this happens
-to you, using @kbd{G b u} and updating the group will usually fix this.
-
-@end itemize
-
-@node Misc Group Stuff
-@section Misc Group Stuff
-
-@menu
-* Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
-* Group Information:: Information and help on groups and Gnus.
-* Group Timestamp:: Making Gnus keep track of when you last read a group.
-* File Commands:: Reading and writing the Gnus files.
-* Sieve Commands:: Managing Sieve scripts.
-@end menu
-
-@table @kbd
-
-@item v
-@kindex v (Group)
-@cindex keys, reserved for users (Group)
-The key @kbd{v} is reserved for users. You can bind it to some
-command or better use it as a prefix key. For example:
-
-@lisp
-(define-key gnus-group-mode-map (kbd "v j d")
- (lambda ()
- (interactive)
- (gnus-group-jump-to-group "nndraft:drafts")))
-@end lisp
-
-On keys reserved for users in Emacs and on keybindings in general
-@xref{Keymaps, Keymaps, , emacs, The Emacs Editor}.
-
-@item ^
-@kindex ^ (Group)
-@findex gnus-group-enter-server-mode
-Enter the server buffer (@code{gnus-group-enter-server-mode}).
-@xref{Server Buffer}.
-
-@item a
-@kindex a (Group)
-@findex gnus-group-post-news
-Start composing a message (a news by default)
-(@code{gnus-group-post-news}). If given a prefix, post to the group
-under the point. If the prefix is 1, prompt for a group to post to.
-Contrary to what the name of this function suggests, the prepared
-article might be a mail instead of a news, if a mail group is specified
-with the prefix argument. @xref{Composing Messages}.
-
-@item m
-@kindex m (Group)
-@findex gnus-group-mail
-Mail a message somewhere (@code{gnus-group-mail}). If given a prefix,
-use the posting style of the group under the point. If the prefix is 1,
-prompt for a group name to find the posting style.
-@xref{Composing Messages}.
-
-@item i
-@kindex i (Group)
-@findex gnus-group-news
-Start composing a news (@code{gnus-group-news}). If given a prefix,
-post to the group under the point. If the prefix is 1, prompt
-for group to post to. @xref{Composing Messages}.
-
-This function actually prepares a news even when using mail groups.
-This is useful for ``posting'' messages to mail groups without actually
-sending them over the network: they're just saved directly to the group
-in question. The corresponding back end must have a request-post method
-for this to work though.
-
-@item G z
-@kindex G z (Group)
-@findex gnus-group-compact-group
-
-Compact the group under point (@code{gnus-group-compact-group}).
-Currently implemented only in nnml (@pxref{Mail Spool}). This removes
-gaps between article numbers, hence getting a correct total article
-count.
-
-@end table
-
-Variables for the group buffer:
-
-@table @code
-
-@item gnus-group-mode-hook
-@vindex gnus-group-mode-hook
-is called after the group buffer has been
-created.
-
-@item gnus-group-prepare-hook
-@vindex gnus-group-prepare-hook
-is called after the group buffer is
-generated. It may be used to modify the buffer in some strange,
-unnatural way.
-
-@item gnus-group-prepared-hook
-@vindex gnus-group-prepare-hook
-is called as the very last thing after the group buffer has been
-generated. It may be used to move point around, for instance.
-
-@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
-
-@node Scanning New Messages
-@subsection Scanning New Messages
-@cindex new messages
-@cindex scanning new news
-
-@table @kbd
-
-@item g
-@kindex g (Group)
-@findex gnus-group-get-new-news
-@c @icon{gnus-group-get-new-news}
-Check the server(s) for new articles. If the numerical prefix is used,
-this command will check only groups of level @var{arg} and lower
-(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
-command will force a total re-reading of the active file(s) from the
-back end(s).
-
-@item M-g
-@kindex M-g (Group)
-@findex gnus-group-get-new-news-this-group
-@vindex gnus-goto-next-group-when-activating
-@c @icon{gnus-group-get-new-news-this-group}
-Check whether new articles have arrived in the current group
-(@code{gnus-group-get-new-news-this-group}).
-@code{gnus-goto-next-group-when-activating} says whether this command is
-to move point to the next group or not. It is @code{t} by default.
-
-@findex gnus-activate-all-groups
-@cindex activating groups
-@item C-c M-g
-@kindex C-c M-g (Group)
-Activate absolutely all groups (@code{gnus-activate-all-groups}).
-
-@item R
-@kindex R (Group)
-@cindex restarting
-@findex gnus-group-restart
-Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc}
-file(s), closes the connection to all servers, clears up all run-time
-Gnus variables, and then starts Gnus all over again.
-
-@end table
-
-@vindex gnus-get-new-news-hook
-@code{gnus-get-new-news-hook} is run just before checking for new news.
-
-@vindex gnus-after-getting-new-news-hook
-@code{gnus-after-getting-new-news-hook} is run after checking for new
-news.
-
-
-@node Group Information
-@subsection Group Information
-@cindex group information
-@cindex information on groups
-
-@table @kbd
-
-
-@item H f
-@kindex H f (Group)
-@findex gnus-group-fetch-faq
-@vindex gnus-group-faq-directory
-@cindex FAQ
-@cindex ange-ftp
-Try to fetch the @acronym{FAQ} for the current group
-(@code{gnus-group-fetch-faq}). Gnus will try to get the @acronym{FAQ}
-from @code{gnus-group-faq-directory}, which is usually a directory on
-a remote machine. This variable can also be a list of directories.
-In that case, giving a prefix to this command will allow you to choose
-between the various sites. @code{ange-ftp} (or @code{efs}) 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 H c
-@kindex H c (Group)
-@findex gnus-group-fetch-charter
-@vindex gnus-group-charter-alist
-@cindex charter
-Try to open the charter for the current group in a web browser
-(@code{gnus-group-fetch-charter}). Query for a group if given a
-prefix argument.
-
-Gnus will use @code{gnus-group-charter-alist} to find the location of
-the charter. If no location is known, Gnus will fetch the control
-messages for the group, which in some cases includes the charter.
-
-@item H C
-@kindex H C (Group)
-@findex gnus-group-fetch-control
-@vindex gnus-group-fetch-control-use-browse-url
-@cindex control message
-Fetch the control messages for the group from the archive at
-@code{ftp.isc.org} (@code{gnus-group-fetch-control}). Query for a
-group if given a prefix argument.
-
-If @code{gnus-group-fetch-control-use-browse-url} is non-@code{nil},
-Gnus will open the control messages in a browser using
-@code{browse-url}. Otherwise they are fetched using @code{ange-ftp}
-and displayed in an ephemeral group.
-
-Note that the control messages are compressed. To use this command
-you need to turn on @code{auto-compression-mode} (@pxref{Compressed
-Files, ,Compressed Files, emacs, The Emacs Manual}).
-
-@item H d
-@itemx C-c C-d
-@c @icon{gnus-group-describe-group}
-@kindex H d (Group)
-@kindex C-c C-d (Group)
-@cindex describing groups
-@cindex group description
-@findex gnus-group-describe-group
-Describe the current group (@code{gnus-group-describe-group}). If given
-a prefix, force Gnus to re-read the description from the server.
-
-@item M-d
-@kindex M-d (Group)
-@findex gnus-group-describe-all-groups
-Describe all groups (@code{gnus-group-describe-all-groups}). If given a
-prefix, force Gnus to re-read the description file from the server.
-
-@item H v
-@itemx V
-@kindex V (Group)
-@kindex H v (Group)
-@cindex version
-@findex gnus-version
-Display current Gnus version numbers (@code{gnus-version}).
-
-@item ?
-@kindex ? (Group)
-@findex gnus-group-describe-briefly
-Give a very short help message (@code{gnus-group-describe-briefly}).
-
-@item C-c C-i
-@kindex C-c C-i (Group)
-@cindex info
-@cindex manual
-@findex gnus-info-find-node
-Go to the Gnus info node (@code{gnus-info-find-node}).
-@end table
-
-
-@node Group Timestamp
-@subsection Group Timestamp
-@cindex timestamps
-@cindex group timestamps
-
-It can be convenient to let Gnus keep track of when you last read a
-group. To set the ball rolling, you should add
-@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}:
-
-@lisp
-(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp)
-@end lisp
-
-After doing this, each time you enter a group, it'll be recorded.
-
-This information can be displayed in various ways---the easiest is to
-use the @samp{%d} spec in the group line format:
-
-@lisp
-(setq gnus-group-line-format
- "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n")
-@end lisp
-
-This will result in lines looking like:
-
-@example
-* 0: mail.ding 19961002T012943
- 0: custom 19961002T012713
-@end example
-
-As you can see, the date is displayed in compact ISO 8601 format. This
-may be a bit too much, so to just display the date, you could say
-something like:
-
-@lisp
-(setq gnus-group-line-format
- "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n")
-@end lisp
-
-If you would like greater control of the time format, you can use a
-user-defined format spec. Something like the following should do the
-trick:
-
-@lisp
-(setq gnus-group-line-format
- "%M\%S\%p\%P\%5y: %(%-40,40g%) %ud\n")
-(defun gnus-user-format-function-d (headers)
- (let ((time (gnus-group-timestamp gnus-tmp-group)))
- (if time
- (format-time-string "%b %d %H:%M" time)
- "")))
-@end lisp
-
-
-@node File Commands
-@subsection File Commands
-@cindex file commands
-
-@table @kbd
-
-@item r
-@kindex r (Group)
-@findex gnus-group-read-init-file
-@vindex gnus-init-file
-@cindex reading init file
-Re-read the init file (@code{gnus-init-file}, which defaults to
-@file{~/.gnus.el}) (@code{gnus-group-read-init-file}).
-
-@item s
-@kindex s (Group)
-@findex gnus-group-save-newsrc
-@cindex saving .newsrc
-Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
-(@code{gnus-group-save-newsrc}). If given a prefix, force saving the
-file(s) whether Gnus thinks it is necessary or not.
-
-@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
-
-
-@node Sieve Commands
-@subsection Sieve Commands
-@cindex group sieve commands
-
-Sieve is a server-side mail filtering language. In Gnus you can use
-the @code{sieve} group parameter (@pxref{Group Parameters}) to specify
-sieve rules that should apply to each group. Gnus provides two
-commands to translate all these group parameters into a proper Sieve
-script that can be transfered to the server somehow.
-
-@vindex gnus-sieve-file
-@vindex gnus-sieve-region-start
-@vindex gnus-sieve-region-end
-The generated Sieve script is placed in @code{gnus-sieve-file} (by
-default @file{~/.sieve}). The Sieve code that Gnus generate is placed
-between two delimiters, @code{gnus-sieve-region-start} and
-@code{gnus-sieve-region-end}, so you may write additional Sieve code
-outside these delimiters that will not be removed the next time you
-regenerate the Sieve script.
-
-@vindex gnus-sieve-crosspost
-The variable @code{gnus-sieve-crosspost} controls how the Sieve script
-is generated. If it is non-@code{nil} (the default) articles is
-placed in all groups that have matching rules, otherwise the article
-is only placed in the group with the first matching rule. For
-example, the group parameter @samp{(sieve address "sender"
-"owner-ding@@hpc.uh.edu")} will generate the following piece of Sieve
-code if @code{gnus-sieve-crosspost} is @code{nil}. (When
-@code{gnus-sieve-crosspost} is non-@code{nil}, it looks the same
-except that the line containing the call to @code{stop} is removed.)
-
-@example
-if address "sender" "owner-ding@@hpc.uh.edu" @{
- fileinto "INBOX.ding";
- stop;
-@}
-@end example
-
-@xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}.
-
-@table @kbd
-
-@item D g
-@kindex D g (Group)
-@findex gnus-sieve-generate
-@vindex gnus-sieve-file
-@cindex generating sieve script
-Regenerate a Sieve script from the @code{sieve} group parameters and
-put you into the @code{gnus-sieve-file} without saving it.
-
-@item D u
-@kindex D u (Group)
-@findex gnus-sieve-update
-@vindex gnus-sieve-file
-@cindex updating sieve script
-Regenerates the Gnus managed part of @code{gnus-sieve-file} using the
-@code{sieve} group parameters, save the file and upload it to the
-server using the @code{sieveshell} program.
-
-@end table
-
-
-@node Summary Buffer
-@chapter Summary Buffer
-@cindex summary buffer
-
-A line for each article is displayed in the summary buffer. You can
-move around, read articles, post articles and reply to articles.
-
-The most common way to a summary buffer is to select a group from the
-group buffer (@pxref{Selecting a Group}).
-
-You can have as many summary buffers open as you wish.
-
-You can customize the Summary Mode tool bar, see @kbd{M-x
-customize-apropos RET gnus-summary-tool-bar}. This feature is only
-available in Emacs.
-
-@kindex v (Summary)
-@cindex keys, reserved for users (Summary)
-The key @kbd{v} is reserved for users. You can bind it to some
-command or better use it as a prefix key. For example:
-@lisp
-(define-key gnus-summary-mode-map (kbd "v -") "LrS") ;; lower subthread
-@end lisp
-
-@menu
-* Summary Buffer Format:: Deciding how the summary buffer is to look.
-* Summary Maneuvering:: Moving around the summary buffer.
-* Choosing Articles:: Reading articles.
-* Paging the Article:: Scrolling the current article.
-* Reply Followup and Post:: Posting articles.
-* Delayed Articles:: Send articles at a later time.
-* Marking Articles:: Marking articles as read, expirable, etc.
-* Limiting:: You can limit the summary buffer.
-* Threading:: How threads are made.
-* Sorting the Summary Buffer:: 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.
-* Sticky Articles:: Article buffers that are not reused.
-* Article Backlog:: Having already read articles hang around.
-* Saving Articles:: Ways of customizing article saving.
-* Decoding Articles:: Gnus can treat series of (uu)encoded articles.
-* Article Treatment:: The article buffer can be mangled at will.
-* MIME Commands:: Doing MIMEy things with the articles.
-* Charsets:: Character set issues.
-* Article Commands:: Doing various things with the article buffer.
-* Summary Sorting:: Sorting the summary buffer in various ways.
-* Finding the Parent:: No child support? Get the parent.
-* Alternative Approaches:: Reading using non-default summaries.
-* Tree Display:: A more visual display of threads.
-* 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,
- or reselecting the current group.
-* Crosspost Handling:: How crossposted articles are dealt with.
-* Duplicate Suppression:: An alternative when crosspost handling fails.
-* Security:: Decrypt and Verify.
-* Mailing List:: Mailing list minor mode.
-@end menu
-
-
-@node Summary Buffer Format
-@section Summary Buffer Format
-@cindex summary buffer format
-
-@iftex
-@iflatex
-\gnusfigure{The Summary Buffer}{180}{
-\put(0,0){\epsfig{figure=ps/summary,width=7.5cm}}
-\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-article,width=7.5cm}}}
-}
-@end iflatex
-@end iftex
-
-@menu
-* Summary Buffer Lines:: You can specify how summary lines should look.
-* To From Newsgroups:: How to not display your own name.
-* Summary Buffer Mode Line:: You can say how the mode line should look.
-* Summary Highlighting:: Making the summary buffer all pretty and nice.
-@end menu
-
-@findex mail-extract-address-components
-@findex gnus-extract-address-components
-@vindex gnus-extract-address-components
-Gnus will use the value of the @code{gnus-extract-address-components}
-variable as a function for getting the name and address parts of a
-@code{From} header. Two pre-defined functions exist:
-@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. The default function will return the wrong answer in 5% of the
-cases. If this is unacceptable to you, use the other function instead:
-
-@lisp
-(setq gnus-extract-address-components
- 'mail-extract-address-components)
-@end lisp
-
-@vindex gnus-summary-same-subject
-@code{gnus-summary-same-subject} is a string indicating that the current
-article has the same subject as the previous. This string will be used
-with those specs that require it. The default is @code{""}.
+@vindex gnus-summary-same-subject
+@code{gnus-summary-same-subject} is a string indicating that the current
+article has the same subject as the previous. This string will be used
+with those specs that require it. The default is @code{""}.
@node Summary Buffer Lines
Desired cursor position (instead of after first colon).
@item &user-date;
Age sensitive date format. Various date format is defined in
-@code{gnus-user-date-format-alist}.
+@code{gnus-summary-user-date-format-alist}.
@item u
User defined specifier. The next character in the format string should
be a letter. Gnus will call the function
This variable can also be a number. In that case, center the window at
the given number of lines from the top.
+@item gnus-summary-stop-at-end-of-message
+@vindex gnus-summary-stop-at-end-of-message
+If non-@code{nil}, don't go to the next article when hitting
+@kbd{SPC}, and you're at the end of the article.
+
@end table
@findex gnus-summary-show-article
@vindex gnus-summary-show-article-charset-alist
(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.
+given a prefix, show a completely ``raw'' article, just the way it
+came from the server. If given a prefix twice (i.e., @kbd{C-u C-u
+g'}), fetch the current article, but don't run any of the article
+treatment functions.
+@cindex charset, view article with different charset
If given a numerical prefix, you can do semi-manual charset stuff.
@kbd{C-u 0 g cn-gb-2312 RET} will decode the message as if it were
encoded in the @code{cn-gb-2312} charset. If you have
@findex gnus-summary-wide-reply-with-original
Mail a wide reply to the current article and include the original
message (@code{gnus-summary-wide-reply-with-original}). This command uses
-the process/prefix convention.
+the process/prefix convention, but only uses the headers from the
+first article to determine the recipients.
@item S v
@kindex S v (Summary)
If the prefix is 1, prompt for a group name to find the posting style.
@item S i
-@itemx i
-@kindex i (Summary)
@kindex S i (Summary)
@findex gnus-summary-news-other-window
Prepare a news (@code{gnus-summary-news-other-window}). By default,
Just don't forget to set that up :-)
@end table
+When delaying an article with @kbd{C-c C-j}, Message mode will
+automatically add a @code{"Date"} header with the current time. In
+many cases you probably want the @code{"Date"} header to reflect the
+time the message is sent instead. To do this, you have to delete
+@code{Date} from @code{message-draft-headers}.
+
@node Marking Articles
@section Marking Articles
@vindex gnus-canceled-mark
Canceled article (@code{gnus-canceled-mark})
-@item F
-@vindex 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}). @xref{Customizing
commands have is to remove a few (or many) articles from the summary
buffer.
-All limiting commands work on subsets of the articles already fetched
-from the servers. None of these commands query the server for
-additional articles.
+Limiting commands work on subsets of the articles already fetched from
+the servers. These commands don't query the server for additional
+articles.
@table @kbd
@kindex / c (Summary)
@findex gnus-summary-limit-exclude-childless-dormant
Exclude all dormant articles that have no children from the limit@*
-(@code{gnus-summary-limit-exclude-childless-dormant}).
-
-@item / C
-@kindex / C (Summary)
-@findex gnus-summary-limit-mark-excluded-as-read
-Mark all excluded unread articles as read
-(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
-also mark excluded ticked and dormant articles as read.
-
-@item / N
-@kindex / N (Summary)
-@findex gnus-summary-insert-new-articles
-Insert all new articles in the summary buffer. It scans for new emails
-if @var{back-end}@code{-get-new-mail} is non-@code{nil}.
-
-@item / o
-@kindex / o (Summary)
-@findex gnus-summary-insert-old-articles
-Insert all old articles in the summary buffer. If given a numbered
-prefix, fetch this number of articles.
+(@code{gnus-summary-limit-exclude-childless-dormant}).
+
+@item / C
+@kindex / C (Summary)
+@findex gnus-summary-limit-mark-excluded-as-read
+Mark all excluded unread articles as read
+(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
+also mark excluded ticked and dormant articles as read.
@item / b
@kindex / b (Summary)
@end table
+The following commands aren't limiting commands, but use the @kbd{/}
+prefix as well.
+
+@table @kbd
+@item / N
+@kindex / N (Summary)
+@findex gnus-summary-insert-new-articles
+Insert all new articles in the summary buffer. It scans for new emails
+if @var{back-end}@code{-get-new-mail} is non-@code{nil}.
+
+@item / o
+@kindex / o (Summary)
+@findex gnus-summary-insert-old-articles
+Insert all old articles in the summary buffer. If given a numbered
+prefix, fetch this number of articles.
+
+@end table
+
+
@node Threading
@section Threading
@cindex threading
intended for those non-news newsgroups where the back end has to fetch
quite a lot to present the summary buffer, and where it's impossible to
go back to parents of articles. This is mostly the case in the
-web-based groups, like the @code{nnultimate} groups.
+web-based groups.
If you don't use those, then it's safe to leave this as the default
@code{nil}. If you want to use this variable, it should be a regexp
@findex gnus-article-sort-functions
@findex gnus-article-sort-by-date
+@findex gnus-article-sort-by-most-recent-date
@findex gnus-article-sort-by-score
@findex gnus-article-sort-by-subject
@findex gnus-article-sort-by-author
@findex gnus-article-sort-by-random
@findex gnus-article-sort-by-number
+@findex gnus-article-sort-by-most-recent-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
preferably be short and sweet to avoid slowing down Gnus too much.
It's probably a good idea to byte-compile things like this.
+@vindex gnus-async-post-fetch-function
+@findex gnus-html-prefetch-images
+After an article has been prefetched, this
+@code{gnus-async-post-fetch-function} will be called. The buffer will
+be narrowed to the region of the article that was fetched. A useful
+value would be @code{gnus-html-prefetch-images}, which will prefetch
+and store images referenced in the article, so that you don't have to
+wait for them to be fetched when you read the article. This is useful
+for @acronym{HTML} messages that have external images.
+
@vindex gnus-prefetched-article-deletion-strategy
Articles have to be removed from the asynch buffer sooner or later. The
@code{gnus-prefetched-article-deletion-strategy} says when to remove
@kindex O r (Summary)
@findex gnus-summary-save-article-rmail
Save the current article in Rmail format
-(@code{gnus-summary-save-article-rmail}).
+(@code{gnus-summary-save-article-rmail}). This is mbox since Emacs 23,
+Babyl in older versions.
@item O f
@kindex O f (Summary)
@kindex O p (Summary)
@kindex | (Summary)
@findex gnus-summary-pipe-output
+@vindex gnus-summary-pipe-output-default-command
Save the current article in a pipe. Uhm, like, what I mean is---Pipe
the current article to a process (@code{gnus-summary-pipe-output}).
If given a symbolic prefix (@pxref{Symbolic Prefixes}), include the
-complete headers in the piped output.
+complete headers in the piped output. The symbolic prefix @code{r} is
+special; it lets this command pipe a raw article including all headers.
+The @code{gnus-summary-pipe-output-default-command} variable can be set
+to a string containing the default command and options (default
+@code{nil}).
@item O P
@kindex O P (Summary)
@findex gnus-summary-save-in-rmail
@vindex gnus-rmail-save-name
@findex gnus-plain-save-name
-This is the default format, @dfn{Babyl}. Uses the function in the
+This is the default format, that used by the Rmail package. Since Emacs
+23, Rmail uses standard mbox format. Before this, it used the
+@dfn{Babyl} format. Accordingly, this command writes mbox format since
+Emacs 23, unless appending to an existing Babyl file. In older versions
+of Emacs, it always uses Babyl format. 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}.
@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.
+
+@item gnus-summary-save-in-pipe
+@findex gnus-summary-save-in-pipe
+Pipe the article to a shell command. This function takes optional two
+arguments COMMAND and RAW. Valid values for COMMAND include:
+
+@itemize @bullet
+@item a string@*
+The executable command name and possibly arguments.
+@item @code{nil}@*
+You will be prompted for the command in the minibuffer.
+@item the symbol @code{default}@*
+It will be replaced with the command which the variable
+@code{gnus-summary-pipe-output-default-command} holds or the command
+last used for saving.
+@end itemize
+
+Non-@code{nil} value for RAW overrides @code{:decode} and
+@code{:headers} properties (see below) and the raw article including all
+headers will be piped.
@end table
The symbol of each function may have the following properties:
The value non-@code{nil} means save decoded articles. This is
meaningful only with @code{gnus-summary-save-in-file},
@code{gnus-summary-save-body-in-file},
-@code{gnus-summary-write-to-file}, and
-@code{gnus-summary-write-body-to-file}.
+@code{gnus-summary-write-to-file},
+@code{gnus-summary-write-body-to-file}, and
+@code{gnus-summary-save-in-pipe}.
@item :function
The value specifies an alternative function which appends, not
* Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
* Article Button Levels:: Controlling appearance of buttons.
* Article Date:: Grumble, UT!
-* Article Display:: Display various stuff---X-Face, Picons, Smileys
+* Article Display:: Display various stuff:
+ X-Face, Picons, Gravatars, Smileys.
* Article Signature:: What is a signature?
* Article Miscellanea:: Various other stuff.
@end menu
corresponding regular expression in @code{gnus-article-banner-alist} is
used.
+For instance:
+
+@lisp
+(setq gnus-article-banner-alist
+ ((googleGroups .
+ "^\n*--~--~---------\\(.+\n\\)+")))
+@end lisp
+
Regardless of a group, you can hide things like advertisements only when
the sender of an article has a certain mail address specified in
@code{gnus-article-address-banner-alist}.
like @code{\222} or @code{\264} where you're expecting some kind of
apostrophe or quotation mark, then try this wash.
+@item W U
+@kindex W U (Summary)
+@findex gnus-article-treat-non-ascii
+@cindex Unicode
+@cindex Non-@acronym{ASCII}
+Translate many non-@acronym{ASCII} characters into their
+@acronym{ASCII} equivalents (@code{gnus-article-treat-non-ascii}).
+This is mostly useful if you're on a terminal that has a limited font
+and does't show accented characters, ``advanced'' punctuation, and the
+like. For instance, @samp{»} is tranlated into @samp{>>}, and so on.
+
@item W Y f
@kindex W Y f (Summary)
@findex gnus-article-outlook-deuglify-article
the charset defined in @code{gnus-summary-show-article-charset-alist}
(@pxref{Paging the Article}) will be used.
-@vindex gnus-article-wash-function
The default is to use the function specified by
@code{mm-text-html-renderer} (@pxref{Display Customization, ,Display
Customization, emacs-mime, The Emacs MIME Manual}) to convert the
-@acronym{HTML}, but this is controlled by the
-@code{gnus-article-wash-function} variable. Pre-defined functions you
-can use include:
+@acronym{HTML}. Pre-defined functions you can use include:
@table @code
+@item shr
+Use Gnus simple html renderer.
+
+@item gnus-w3m
+Use Gnus rendered based on w3m.
+
@item w3
Use Emacs/W3.
An alist of @code{(RATE . REGEXP)} pairs used by the function
@code{gnus-button-mid-or-mail-heuristic}.
-@c Stuff related to gnus-button-tex-level
-
-@item gnus-button-ctan-handler
-@findex gnus-button-ctan-handler
-The function to use for displaying CTAN links. It must take one
-argument, the string naming the URL.
-
-@item gnus-ctan-url
-@vindex gnus-ctan-url
-Top directory of a CTAN (Comprehensive TeX Archive Network) archive used
-by @code{gnus-button-ctan-handler}.
-
@c Misc stuff
@item gnus-article-button-face
@code{gnus-button-mid-or-mail-heuristic}, and
@code{gnus-button-mid-or-mail-heuristic-alist}.
-@item gnus-button-tex-level
-@vindex gnus-button-tex-level
-Controls the display of references to @TeX{} or LaTeX stuff, e.g. for CTAN
-URLs. See the variables @code{gnus-ctan-url},
-@code{gnus-button-ctan-handler},
-@code{gnus-button-ctan-directory-regexp}, and
-@code{gnus-button-handle-ctan-bogus-regexp}.
-
@end table
(@code{gnus-article-date-lapsed}). It looks something like:
@example
-X-Sent: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago
+Date: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago
@end example
-@vindex gnus-article-date-lapsed-new-header
-The value of @code{gnus-article-date-lapsed-new-header} determines
-whether this header will just be added below the old Date one, or will
-replace it.
-
-An advantage of using Gnus to read mail is that it converts simple bugs
-into wonderful absurdities.
-
-If you want to have this line updated continually, you can put
+This line is updated continually by default. If you wish to switch
+that off, say:
+@vindex gnus-article-update-date-headers
@lisp
-(gnus-start-date-timer)
+(setq gnus-article-update-date-headers nil)
@end lisp
-in your @file{~/.gnus.el} file, or you can run it off of some hook. If
-you want to stop the timer, you can use the @code{gnus-stop-date-timer}
-command.
+in your @file{~/.gnus.el} file.
@item W T o
@kindex W T o (Summary)
@cindex picons
@cindex x-face
@cindex smileys
+@cindex gravatars
These commands add various frivolous display gimmicks to the article
buffer in Emacs versions that support them.
Picons, on the other hand, reside on your own system, and Gnus will
try to match the headers to what you have (@pxref{Picons}).
+Gravatars reside on-line and are fetched from
+@uref{http://www.gravatar.com/} (@pxref{Gravatars}).
+
All these functions are toggles---if the elements already exist,
they'll be removed.
Piconify all news headers (i. e., @code{Newsgroups} and
@code{Followup-To}) (@code{gnus-treat-newsgroups-picon}).
+@item W D g
+@kindex W D g (Summary)
+@findex gnus-treat-from-gravatar
+Gravatarify the @code{From} header (@code{gnus-treat-from-gravatar}).
+
+@item W D h
+@kindex W D h (Summary)
+@findex gnus-treat-mail-gravatar
+Gravatarify all mail headers (i. e., @code{Cc}, @code{To})
+(@code{gnus-treat-from-gravatar}).
+
@item W D D
@kindex W D D (Summary)
@findex gnus-article-remove-images
Remove all images from the article buffer
(@code{gnus-article-remove-images}).
+@item W D W
+@kindex W D W (Summary)
+@findex gnus-html-show-images
+If you're reading an @acronym{HTML} article rendered with
+@code{gnus-article-html}, then you can insert any blocked images in
+the buffer with this command.
+(@code{gnus-html-show-images}).
+
@end table
@kindex K H (Summary)
@findex gnus-article-browse-html-article
View @samp{text/html} parts of the current article with a WWW browser.
-The message header is added to the beginning of every html part unless
-the prefix argument is given.
+Inline images embedded in a message using the @code{cid} scheme, as they
+are generally considered to be safe, will be processed properly. The
+message header is added to the beginning of every @acronym{HTML} part
+unless the prefix argument is given.
-Warning: Spammers use links to images in HTML articles to verify whether
-you have read the message. As this command passes the @acronym{HTML}
-content to the browser without eliminating these ``web bugs'' you should
-only use it for mails from trusted senders.
+Warning: Spammers use links to images (using the @code{http} scheme) in
+@acronym{HTML} articles to verify whether you have read the message. As
+this command passes the @acronym{HTML} content to the browser without
+eliminating these ``web bugs'' you should only use it for mails from
+trusted senders.
If you always want to display @acronym{HTML} parts in the browser, set
@code{mm-text-html-renderer} to @code{nil}.
+This command creates temporary files to pass @acronym{HTML} contents
+including images if any to the browser, and deletes them when exiting
+the group (if you want).
+
@item K b
@kindex K b (Summary)
Make all the @acronym{MIME} parts have buttons in front of them. This is
be run just before printing the buffer. An alternative way to print
article is to use Muttprint (@pxref{Saving Articles}).
+@item A C
+@vindex gnus-fetch-partial-articles
+@findex gnus-summary-show-complete-article
+If @code{<backend>-fetch-partial-articles} is non-@code{nil}, Gnus will
+fetch partial articles, if the backend it fetches them from supports
+it. Currently only @code{nnimap} does. If you're looking at a
+partial article, and want to see the complete article instead, then
+the @kbd{A C} command (@code{gnus-summary-show-complete-article}) will
+do so.
+
@end table
@findex gnus-summary-sort-by-number
Sort by article number (@code{gnus-summary-sort-by-number}).
+@item C-c C-s C-m C-n
+@kindex C-c C-s C-n (Summary)
+@findex gnus-summary-sort-by-most-recent-number
+Sort by most recent article number
+(@code{gnus-summary-sort-by-most-recent-number}).
+
@item C-c C-s C-a
@kindex C-c C-s C-a (Summary)
@findex gnus-summary-sort-by-author
@findex gnus-summary-sort-by-date
Sort by date (@code{gnus-summary-sort-by-date}).
+@item C-c C-s C-m C-d
+@kindex C-c C-s C-m C-d (Summary)
+@findex gnus-summary-sort-by-most-recent-date
+Sort by most recent date (@code{gnus-summary-sort-by-most-recent-date}).
+
@item C-c C-s C-l
@kindex C-c C-s C-l (Summary)
@findex gnus-summary-sort-by-lines
toggle whether to use threading, type @kbd{T T} (@pxref{Thread
Commands}).
+If a prefix argument if given, the sort order is reversed.
+
@node Finding the Parent
@section Finding the Parent
@code{nnbabyl}, @code{nnmaildir}, @code{nnml}, are able to locate
articles from any groups, while @code{nnfolder}, and @code{nnimap} are
only able to locate articles that have been posted to the current
-group. (Anything else would be too time consuming.) @code{nnmh} does
-not support this at all.
+group. @code{nnmh} does not support this at all.
+Fortunately, the special @code{nnregistry} back end is able to locate
+articles in any groups, regardless of their back end (@pxref{Registry
+Article Refer Method, fetching by @code{Message-ID} using the
+registry}).
@node Alternative Approaches
@section Alternative Approaches
@item B DEL
@kindex B DEL (Summary)
+@cindex deleting mail
@findex gnus-summary-delete-article
@c @icon{gnus-summary-mail-delete}
Delete the mail article. This is ``delete'' as in ``delete it from your
@table @kbd
-@item H f
-@kindex H f (Summary)
-@findex gnus-summary-fetch-faq
-@vindex gnus-group-faq-directory
-Try to fetch the @acronym{FAQ} (list of frequently asked questions)
-for the current group (@code{gnus-summary-fetch-faq}). Gnus will try
-to get the @acronym{FAQ} from @code{gnus-group-faq-directory}, which
-is usually a directory on a remote machine. This variable can also be
-a list of directories. In that case, giving a prefix to this command
-will allow you to choose between the various sites. @code{ange-ftp}
-or @code{efs} will probably be used for fetching the file.
-
@item H d
@kindex H d (Summary)
@findex gnus-summary-describe-group
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. You may want to try NoCeM handling to filter out spam
-(@pxref{NoCeM}).
+heinous crime.
Remember: Cross-posting is kinda ok, but posting the same article
separately to several groups is not. Massive cross-posting (aka.
@item
To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to
install an OpenPGP implementation such as GnuPG. The Lisp interface
-to GnuPG included with Gnus is called PGG (@pxref{Top, ,PGG, pgg, PGG
-Manual}), but Mailcrypt and gpg.el are also supported.
+to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG,
+epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg,
+PGG Manual}), and Mailcrypt are also supported.
@item
To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6
@end enumerate
-The variables that control security functionality on reading messages
-include:
+The variables that control security functionality on reading/composing
+messages include:
@table @code
@item mm-verify-option
@code{always}, always decrypt; @code{known}, only decrypt known
protocols. Otherwise, ask user.
+@item mm-sign-option
+@vindex mm-sign-option
+Option of creating signed parts. @code{nil}, use default signing
+keys; @code{guided}, ask user to select signing keys from the menu.
+
+@item mm-encrypt-option
+@vindex mm-encrypt-option
+Option of creating encrypted parts. @code{nil}, use the first
+public-key matching the @samp{From:} header as the recipient;
+@code{guided}, ask user to select recipient keys from the menu.
+
@item mml1991-use
@vindex mml1991-use
Symbol indicating elisp interface to OpenPGP implementation for
-@acronym{PGP} messages. The default is @code{pgg}, but
-@code{mailcrypt} and @code{gpg} are also supported although
-deprecated.
+@acronym{PGP} messages. The default is @code{epg}, but @code{pgg},
+and @code{mailcrypt} are also supported although
+deprecated. By default, Gnus uses the first available interface in
+this order.
@item mml2015-use
@vindex mml2015-use
Symbol indicating elisp interface to OpenPGP implementation for
-@acronym{PGP/MIME} messages. The default is @code{pgg}, but
-@code{mailcrypt} and @code{gpg} are also supported although
-deprecated.
+@acronym{PGP/MIME} messages. The default is @code{epg}, but
+@code{pgg}, and @code{mailcrypt} are also supported
+although deprecated. By default, Gnus uses the first available
+interface in this order.
@end table
@menu
* Hiding Headers:: Deciding what headers should be displayed.
* Using MIME:: Pushing articles through @acronym{MIME} before reading them.
+* HTML:: Reading @acronym{HTML} messages.
* Customizing Articles:: Tailoring the look of the articles.
* Article Keymap:: Keystrokes available in the article buffer.
* Misc Article:: Other stuff.
Also @pxref{MIME Commands}.
+@node HTML
+@section @acronym{HTML}
+@cindex @acronym{HTML}
+
+If you have @code{w3m} installed on your system, Gnus can display
+@acronym{HTML} articles in the article buffer. There are many Gnus
+add-ons for doing this, using various approaches, but there's one
+(sort of) built-in method that's used by default.
+
+For a complete overview, consult @xref{Display Customization,
+,Display Customization, emacs-mime, The Emacs MIME Manual}. This
+section only describes the default method.
+
+@table @code
+@item mm-text-html-renderer
+@vindex mm-text-html-renderer
+If set to @code{gnus-article-html}, Gnus will use the built-in method,
+that's based on @code{w3m}.
+
+@item gnus-blocked-images
+@vindex gnus-blocked-images
+External images that have @acronym{URL}s that match this regexp won't
+be fetched and displayed. For instance, do block all @acronym{URL}s
+that have the string ``ads'' in them, do the following:
+
+@lisp
+(setq gnus-blocked-images "ads")
+@end lisp
+
+This can also be a function to be evaluated. If so, it will be
+called with the group name as the parameter. The default value is
+@code{gnus-block-private-groups}, which will return @samp{"."} for
+anything that isn't a newsgroup. This means that no external images
+will be fetched as a result of reading mail, so that nobody can use
+web bugs (and the like) to track whether you've read email.
+
+Also @pxref{Misc Article} for @code{gnus-inhibit-images}.
+
+@item gnus-html-cache-directory
+@vindex gnus-html-cache-directory
+Gnus will download and cache images according to how
+@code{gnus-blocked-images} is set. These images will be stored in
+this directory.
+
+@item gnus-html-cache-size
+@vindex gnus-html-cache-size
+When @code{gnus-html-cache-size} bytes have been used in that
+directory, the oldest files will be deleted. The default is 500MB.
+
+@item gnus-html-frame-width
+@vindex gnus-html-frame-width
+The width to use when rendering HTML. The default is 70.
+
+@item gnus-max-image-proportion
+@vindex gnus-max-image-proportion
+How big pictures displayed are in relation to the window they're in.
+A value of 0.7 (the default) means that they are allowed to take up
+70% of the width and height of the window. If they are larger than
+this, and Emacs supports it, then the images will be rescaled down to
+fit these criteria.
+
+@end table
+
+To use this, make sure that you have @code{w3m} and @code{curl}
+installed. If you have, then Gnus should display @acronym{HTML}
+automatically.
+
+
+
@node Customizing Articles
@section Customizing Articles
@cindex article customization
@vindex gnus-treat-strip-trailing-blank-lines
@vindex gnus-treat-unsplit-urls
@vindex gnus-treat-wash-html
-@vindex gnus-treat-date-english
-@vindex gnus-treat-date-iso8601
-@vindex gnus-treat-date-lapsed
-@vindex gnus-treat-date-local
-@vindex gnus-treat-date-original
-@vindex gnus-treat-date-user-defined
-@vindex gnus-treat-date-ut
+@vindex gnus-treat-date
@vindex gnus-treat-from-picon
@vindex gnus-treat-mail-picon
@vindex gnus-treat-newsgroups-picon
+@vindex gnus-treat-from-gravatar
+@vindex gnus-treat-mail-gravatar
@vindex gnus-treat-display-smileys
@vindex gnus-treat-body-boundary
@vindex gnus-treat-display-x-face
@vindex gnus-treat-highlight-headers
@vindex gnus-treat-highlight-signature
@vindex gnus-treat-play-sounds
-@vindex gnus-treat-translate
@vindex gnus-treat-x-pgp-sig
@vindex gnus-treat-unfold-headers
@vindex gnus-treat-fold-headers
@xref{Article Washing}.
-@item gnus-treat-date-english (head)
-@item gnus-treat-date-iso8601 (head)
-@item gnus-treat-date-lapsed (head)
-@item gnus-treat-date-local (head)
-@item gnus-treat-date-original (head)
-@item gnus-treat-date-user-defined (head)
-@item gnus-treat-date-ut (head)
+@item gnus-treat-date (head)
+
+This will transform/add date headers according to the
+@code{gnus-article-date-headers} variable. This is a list of Date
+headers to display. The formats available are:
+
+@table @code
+@item ut
+Universal time, aka GMT, aka ZULU.
+
+@item local
+The user's local time zone.
+
+@item english
+A semi-readable English sentence.
+
+@item lapsed
+The time elapsed since the message was posted.
+
+@item combined-lapsed
+Both the original date header and a (shortened) elapsed time.
+
+@item original
+The original date header.
+
+@item iso8601
+ISO8601 format, i.e., ``2010-11-23T22:05:21''.
+
+@item user-defined
+A format done according to the @code{gnus-article-time-format}
+variable.
+
+@end table
@xref{Article Date}.
@xref{Picons}.
+@item gnus-treat-from-gravatar (head)
+@item gnus-treat-mail-gravatar (head)
+
+@xref{Gravatars}.
+
@item gnus-treat-display-smileys (t, integer)
@item gnus-treat-body-boundary (head)
@vindex gnus-treat-play-sounds
@item gnus-treat-play-sounds
-@vindex gnus-treat-translate
-@item gnus-treat-translate
@item gnus-treat-ansi-sequences (t)
@vindex gnus-treat-x-pgp-sig
@item gnus-treat-x-pgp-sig (head)
(This is the default.) If @code{nil}, each group will have its own
article buffer.
+@item gnus-widen-article-window
+@cindex gnus-widen-article-window
+If non-@code{nil}, selecting the article buffer with the @kbd{h}
+command will ``widen'' the article window to take the entire frame.
+
@vindex gnus-article-decode-hook
@item gnus-article-decode-hook
@cindex @acronym{MIME}
Displayed when Gnus has treated overstrike characters in the article buffer.
@item e
-Displayed when Gnus has treated emphasised strings in the article buffer.
+Displayed when Gnus has treated emphasized strings in the article buffer.
@end table
@uref{http://www.gnu.org/software/libidn/, GNU Libidn}, and this
variable is only enabled if you have installed it.
+@vindex gnus-inhibit-images
+@item gnus-inhibit-images
+If this is non-@code{nil}, inhibit displaying of images inline in the
+article body. It is effective to images that are in articles as
+@acronym{MIME} parts, and images in @acronym{HTML} articles rendered
+when @code{mm-text-html-renderer} (@pxref{Display Customization,
+,Display Customization, emacs-mime, The Emacs MIME Manual}) is
+@code{shr} or @code{gnus-w3m}.
+
@end table
(concat "mail." (format-time-string "%Y-%m")))))
@end lisp
-@c (XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to
-@c use a different value for @code{gnus-message-archive-group} there.)
-
Now, when you send a message off, it will be stored in the appropriate
group. (If you want to disable storing for just one particular message,
you can just remove the @code{Gcc} header that has been inserted.) The
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 messages. Gnus offers a
-different way for the people who don't like the default method. In that
-case you should set @code{gnus-message-archive-group} to @code{nil};
-this will disable archiving.
-
@table @code
-@item gnus-outgoing-message-group
-@vindex gnus-outgoing-message-group
-All outgoing messages will be put in this group. If you want to store
-all your outgoing mail and articles in the group @samp{nnml:archive},
-you set this variable to that value. This variable can also be a list of
-group names.
-
-If you want to have greater control over what group to put each
-message in, you can set this variable to a function that checks the
-current newsgroup name and then returns a suitable group name (or list
-of names).
-
-This variable can be used instead of @code{gnus-message-archive-group},
-but the latter is the preferred method.
-
@item gnus-gcc-mark-as-read
@vindex gnus-gcc-mark-as-read
If non-@code{nil}, automatically mark @code{Gcc} articles as read.
name will be removed. If the attribute name is @code{eval}, the form
is evaluated, and the result is thrown away.
-The attribute value can be a string (used verbatim), a function with
-zero arguments (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). The functions and sexps are called/@code{eval}ed in the
-message buffer that is being set up. The headers of the current article
-are available through the @code{message-reply-headers} variable, which
-is a vector of the following headers: number subject from date id
-references chars lines xref extra.
+The attribute value can be a string, a function with zero arguments
+(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). The functions and sexps are called/@code{eval}ed in the
+message buffer that is being set up. The headers of the current
+article are available through the @code{message-reply-headers}
+variable, which is a vector of the following headers: number subject
+from date id references chars lines xref extra.
+
+In the case of a string value, if the @code{match} is a regular
+expression, a @samp{gnus-match-substitute-replacement} is proceed on
+the value to replace the positional parameters @samp{\@var{n}} by the
+corresponding parenthetical matches (see @xref{Replacing the Text that
+Matched, , Text Replacement, elisp, The Emacs Lisp Reference Manual}.)
@vindex message-reply-headers
(body "You are fired.\n\nSincerely, your boss.")
(organization "Important Work, Inc"))
("nnml:.*"
- (From (save-excursion
- (set-buffer gnus-article-buffer)
+ (From (with-current-buffer gnus-article-buffer
(message-fetch-field "to"))))
("^nn.+:"
(signature-file "~/.mail-signature"))))
@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message
as unsendable. This is a toggling command.
+Finally, if you want to delete a draft, use the normal @kbd{B DEL}
+command (@pxref{Mail Group Commands}).
+
@node Rejected Articles
@section Rejected Articles
@menu
* Server Buffer:: Making and editing virtual servers.
* Getting News:: Reading USENET news with Gnus.
+* Using IMAP:: Reading mail from @acronym{IMAP}.
* Getting Mail:: Reading your personal mail with Gnus.
* Browsing the Web:: Getting messages from a plethora of Web sources.
-* IMAP:: Using Gnus as a @acronym{IMAP} client.
-* Other Sources:: Reading directories, files, SOUP packets.
+* Other Sources:: Reading directories, files.
* Combined Groups:: Combining groups into one group.
* Email Based Diary:: Using mails to manage diary events in Gnus.
* Gnus Unplugged:: Reading news and mail offline.
@findex gnus-server-edit-server
Edit a server (@code{gnus-server-edit-server}).
+@item S
+@kindex S (Server)
+@findex gnus-server-show-server
+Show the definition of a server (@code{gnus-server-show-server}).
+
@item SPACE
@kindex SPACE (Server)
@findex gnus-server-read-server
@end table
+Some more commands for closing, disabling, and re-opening servers are
+listed in @ref{Unavailable Servers}.
+
@node Example Methods
@subsection Example Methods
Remove all marks to whether Gnus was denied connection from any servers
(@code{gnus-server-remove-denials}).
+@item c
+@kindex c (Server)
+@findex gnus-server-copy-server
+Copy a server and give it a new name
+(@code{gnus-server-copy-server}). This can be useful if you have a
+complex method definition, and want to use the same definition towards
+a different (physical) server.
+
@item L
@kindex L (Server)
@findex gnus-server-offline-server
Note that not all servers support the recommended ID. This works for
INN versions 2.3.0 and later, for instance.
+@item nntp-server-list-active-group
+If @code{nil}, then always use @samp{GROUP} instead of @samp{LIST
+ACTIVE}. This is usually slower, but on misconfigured servers that
+don't update their active files often, this can help.
+
+
@end table
@menu
@findex nntp-open-network-stream
@item nntp-open-network-stream
This is the default, and simply connects to some port or other on the
-remote system.
+remote system. If both Emacs and the server supports it, the
+connection will be upgraded to an encrypted @acronym{STARTTLS}
+connection automatically.
+
+@item network-only
+The same as the above, but don't do automatic @acronym{STARTTLS} upgrades.
@findex nntp-open-tls-stream
@item nntp-open-tls-stream
;;
(nntp "snews.bar.com"
(nntp-open-connection-function nntp-open-tls-stream)
- (nntp-port-number )
+ (nntp-port-number 563)
(nntp-address "snews.bar.com"))
@end lisp
Does essentially the same, but uses @code{telnet} instead of @samp{netcat}
to connect to the real @acronym{NNTP} server from the intermediate host.
@code{telnet} is a bit less robust because of things like
-line-end-conversion, but sometimes @code{netcat} is simply not available.
+line-end-conversion, but sometimes @code{netcat} is simply not available.
@code{nntp-open-via-rlogin-and-telnet}-specific variables:
@end table
+@node Using IMAP
+@section Using IMAP
+@cindex imap
+
+The most popular mail backend is probably @code{nnimap}, which
+provides access to @acronym{IMAP} servers. @acronym{IMAP} servers
+store mail remotely, so the client doesn't store anything locally.
+This means that it's a convenient choice when you're reading your mail
+from different locations, or with different user agents.
+
+@menu
+* Connecting to an IMAP Server:: Getting started with @acronym{IMAP}.
+* Customizing the IMAP Connection:: Variables for @acronym{IMAP} connection.
+* Client-Side IMAP Splitting:: Put mail in the correct mail box.
+@end menu
+
+
+@node Connecting to an IMAP Server
+@subsection Connecting to an IMAP Server
+
+Connecting to an @acronym{IMAP} can be very easy. Type @kbd{B} in the
+group buffer, or (if your primary interest is reading email), say
+something like:
+
+@example
+(setq gnus-select-method
+ '(nnimap "imap.gmail.com"))
+@end example
+
+You'll be prompted for a user name and password. If you grow tired of
+that, then add the following to your @file{~/.authinfo} file:
+
+@example
+machine imap.gmail.com login <username> password <password> port imap
+@end example
+
+That should basically be it for most users.
+
+
+@node Customizing the IMAP Connection
+@subsection Customizing the IMAP Connection
+
+Here's an example method that's more complex:
+
+@example
+(nnimap "imap.gmail.com"
+ (nnimap-inbox "INBOX")
+ (nnimap-split-methods default)
+ (nnimap-expunge t)
+ (nnimap-stream ssl))
+@end example
+
+@table @code
+@item nnimap-address
+The address of the server, like @samp{imap.gmail.com}.
+
+@item nnimap-server-port
+If the server uses a non-standard port, that can be specified here. A
+typical port would be @code{"imap"} or @code{"imaps"}.
+
+@item nnimap-stream
+How @code{nnimap} should connect to the server. Possible values are:
+
+@table @code
+@item undecided
+This is the default, and this first tries the @code{ssl} setting, and
+then tries the @code{network} setting.
+
+@item ssl
+This uses standard @acronym{TLS}/@acronym{SSL} connections.
+
+@item network
+Non-encrypted and unsafe straight socket connection, but will upgrade
+to encrypted @acronym{STARTTLS} if both Emacs and the server
+supports it.
+
+@item starttls
+Encrypted @acronym{STARTTLS} over the normal @acronym{IMAP} port.
+
+@item shell
+If you need to tunnel via other systems to connect to the server, you
+can use this option, and customize @code{nnimap-shell-program} to be
+what you need.
+
+@end table
+
+@item nnimap-authenticator
+Some @acronym{IMAP} servers allow anonymous logins. In that case,
+this should be set to @code{anonymous}.
+
+@item nnimap-expunge
+If non-@code{nil}, expunge articles after deleting them. This is always done
+if the server supports UID EXPUNGE, but it's not done by default on
+servers that doesn't support that command.
+
+@item nnimap-streaming
+Virtually all @code{IMAP} server support fast streaming of data. If
+you have problems connecting to the server, try setting this to @code{nil}.
+
+@item nnimap-fetch-partial-articles
+If non-@code{nil}, fetch partial articles from the server. If set to
+a string, then it's interpreted as a regexp, and parts that have
+matching types will be fetched. For instance, @samp{"text/"} will
+fetch all textual parts, while leaving the rest on the server.
+
+@end table
+
+
+@node Client-Side IMAP Splitting
+@subsection Client-Side IMAP Splitting
+
+Many people prefer to do the sorting/splitting of mail into their mail
+boxes on the @acronym{IMAP} server. That way they don't have to
+download the mail they're not all that interested in.
+
+If you do want to do client-side mail splitting, then the following
+variables are relevant:
+
+@table @code
+@item nnimap-inbox
+This is the @acronym{IMAP} mail box that will be scanned for new mail.
+
+@item nnimap-split-methods
+Uses the same syntax as @code{nnmail-split-methods} (@pxref{Splitting
+Mail}), except the symbol @code{default}, which means that it should
+use the value of the @code{nnmail-split-methods} variable.
+
+@item nnimap-split-fancy
+Uses the same syntax as @code{nnmail-split-fancy}.
+
+@item nnimap-unsplittable-articles
+List of flag symbols to ignore when doing splitting. That is,
+articles that have these flags won't be considered when splitting.
+The default is @samp{(%Deleted %Seen)}.
+
+@end table
+
+Here's a complete example @code{nnimap} backend with a client-side
+``fancy'' splitting method:
+
+@example
+(nnimap "imap.example.com"
+ (nnimap-inbox "INBOX")
+ (nnimap-split-methods
+ (| ("MailScanner-SpamCheck" "spam" "spam.detected")
+ (to "foo@@bar.com" "foo")
+ "undecided")))
+@end example
+
+
@node Getting Mail
@section Getting Mail
@cindex reading mail
message. The function should return a list of group names that it
thinks should carry this mail message.
+This variable can also be a fancy split method. For the syntax,
+see @ref{Fancy Mail Splitting}.
+
Note that the mail back ends are free to maul the poor, innocent,
incoming headers all they want to. They all add @code{Lines} headers;
some add @code{X-Gnus-Group} headers; most rename the Unix mbox
@acronym{IMAP} as intended, as a network mail reading protocol (ie
with nnimap), for some reason or other, Gnus let you treat it similar
to a @acronym{POP} server and fetches articles from a given
-@acronym{IMAP} mailbox. @xref{IMAP}, for more information.
-
-Note that for the Kerberos, GSSAPI, @acronym{TLS}/@acronym{SSL} and STARTTLS support you
-may need external programs and libraries, @xref{IMAP}.
+@acronym{IMAP} mailbox. @xref{Using IMAP}, for more information.
Keywords:
:fetchflag "\\Seen")
@end lisp
-@item webmail
-Get mail from a webmail server, such as @uref{http://www.hotmail.com/},
-@uref{http://webmail.netscape.com/}, @uref{http://www.netaddress.com/},
-@uref{http://mail.yahoo.com/}.
-
-NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is
-required for url "4.0pre.46".
-
-WARNING: Mails may be lost. NO WARRANTY.
-
-Keywords:
-
-@table @code
-@item :subtype
-The type of the webmail server. The default is @code{hotmail}. The
-alternatives are @code{netscape}, @code{netaddress}, @code{my-deja}.
-
-@item :user
-The user name to give to the webmail server. The default is the login
-name.
-
-@item :password
-The password to give to the webmail server. If not specified, the user is
-prompted.
-
-@item :dontexpunge
-If non-@code{nil}, only fetch unread articles and don't move them to
-trash folder after finishing the fetch.
-
-@end table
-
-An example webmail source:
-
-@lisp
-(webmail :subtype 'hotmail
- :user "user-name"
- :password "secret")
-@end lisp
-
@item group
Get the actual mail source from the @code{mail-source} group parameter,
@xref{Group Parameters}.
(the deletion will only happen when receiving new mail). You may also
set @code{mail-source-delete-incoming} to @code{nil} and call
@code{mail-source-delete-old-incoming} from a hook or interactively.
-@code{mail-source-delete-incoming} defaults to @code{2} in alpha Gnusae
-and @code{10} in released Gnusae. @xref{Gnus Development}.
+@code{mail-source-delete-incoming} defaults to @code{10} in alpha Gnusae
+and @code{2} in released Gnusae. @xref{Gnus Development}.
@item mail-source-delete-old-incoming-confirm
@vindex mail-source-delete-old-incoming-confirm
above. Also note that with the nnimap backend, message bodies will
not be downloaded by default. You need to set
@code{nnimap-split-download-body} to @code{t} to do that
-(@pxref{Splitting in IMAP}).
+(@pxref{Client-Side IMAP Splitting}).
@item (! @var{func} @var{split})
If the split is a list, and the first element is @code{!}, then
commands will not mark an article as expirable, even if the group has
auto-expire turned on.
+@vindex gnus-mark-copied-or-moved-articles-as-expirable
+The expirable marks of articles will be removed when copying or moving
+them to a group in which auto-expire is not turned on. This is for
+preventing articles from being expired unintentionally. On the other
+hand, to a group that has turned auto-expire on, the expirable marks of
+articles that are copied or moved will not be changed by default. I.e.,
+when copying or moving to such a group, articles that were expirable
+will be left expirable and ones that were not expirable will not be
+marked as expirable. So, even though in auto-expire groups, some
+articles will never get expired (unless you read them again). If you
+don't side with that behavior that unexpirable articles may be mixed
+into auto-expire groups, you can set
+@code{gnus-mark-copied-or-moved-articles-as-expirable} to a
+non-@code{nil} value. In that case, articles that have been read will
+be marked as expirable automatically when being copied or moved to a
+group that has auto-expire turned on. The default value is @code{nil}.
+
@node Washing Mail
@subsection Washing Mail
@vindex nnmh-get-new-mail
@vindex nnfolder-get-new-mail
This might be too much, if, for instance, you are reading mail quite
-happily with @code{nnml} and just want to peek at some old Rmail
-file you have stashed away with @code{nnbabyl}. All back ends have
+happily with @code{nnml} and just want to peek at some old (pre-Emacs
+23) Rmail file you have stashed away with @code{nnbabyl}. All back ends have
variables called back-end-@code{get-new-mail}. If you want to disable
the @code{nnbabyl} mail reading, you edit the virtual server for the
group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
@menu
* Unix Mail Box:: Using the (quite) standard Un*x mbox.
-* Rmail Babyl:: Emacs programs use the Rmail Babyl format.
+* Babyl:: Babyl was used by older versions of Rmail.
* Mail Spool:: Store your mail in a private spool?
* MH Spool:: An mhspool-like back end.
* Maildir:: Another one-file-per-message format.
@end menu
+
@node Unix Mail Box
@subsubsection Unix Mail Box
@cindex nnmbox
@end table
-@node Rmail Babyl
-@subsubsection Rmail Babyl
+@node Babyl
+@subsubsection Babyl
@cindex nnbabyl
-@cindex Rmail mbox
@vindex nnbabyl-active-file
@vindex nnbabyl-mbox-file
-The @dfn{nnbabyl} back end will use a Babyl mail box (aka. @dfn{Rmail
-mbox}) to store mail. @code{nnbabyl} will add extra headers to each
-mail article to say which group it belongs in.
+The @dfn{nnbabyl} back end will use a Babyl mail box to store mail.
+@code{nnbabyl} will add extra headers to each mail article to say which
+group it belongs in.
Virtual server settings:
@table @code
@item nnbabyl-mbox-file
@vindex nnbabyl-mbox-file
-The name of the Rmail mbox file. The default is @file{~/RMAIL}
+The name of the Babyl file. The default is @file{~/RMAIL}
@item nnbabyl-active-file
@vindex nnbabyl-active-file
-The name of the active file for the rmail box. The default is
+The name of the active file for the Babyl file. The default is
@file{~/.rmail-active}
@item nnbabyl-get-new-mail
VM, for that matter) continue to support this format because it's
perceived as having some good qualities in those mailer-specific
headers/status bits stuff. Rmail itself still exists as well, of
-course, and is still maintained by Stallman.
+course, and is still maintained within Emacs. Since Emacs 23, it
+uses standard mbox format rather than Babyl.
Both of the above forms leave your mail in a single file on your
file system, and they must parse that entire file each time you take a
mail back ends.
@code{nnmaildir} is largely similar to @code{nnml}, with some notable
-differences. Each message is stored in a separate file, but the
-filename is unrelated to the article number in Gnus. @code{nnmaildir}
+differences. Each message is stored in a separate file, but the
+filename is unrelated to the article number in Gnus. @code{nnmaildir}
also stores the equivalent of @code{nnml}'s overview files in one file
-per article, so it uses about twice as many inodes as @code{nnml}. (Use
-@code{df -i} to see how plentiful your inode supply is.) If this slows
-you down or takes up very much space, consider switching to
-@uref{http://www.namesys.com/, ReiserFS} or another non-block-structured
+per article, so it uses about twice as many inodes as @code{nnml}.
+(Use @code{df -i} to see how plentiful your inode supply is.) If this
+slows you down or takes up very much space, a non-block-structured
file system.
Since maildirs don't require locking for delivery, the maildirs you use
@menu
* Archiving Mail::
* Web Searches:: Creating groups from articles that match a string.
-* Slashdot:: Reading the Slashdot comments.
-* Ultimate:: The Ultimate Bulletin Board systems.
-* Web Archive:: Reading mailing list archived on web.
* RSS:: Reading RDF site summary.
* Customizing W3:: Doing stuff to Emacs/W3 from Gnus.
@end menu
The address the aforementioned function should send the search string
to.
-@item id
-Format string URL to fetch an article by @code{Message-ID}.
-@end table
-
-@end table
-
-
-@node Slashdot
-@subsection Slashdot
-@cindex Slashdot
-@cindex nnslashdot
-
-@uref{http://slashdot.org/, Slashdot} is a popular news site, with
-lively discussion following the news articles. @code{nnslashdot} will
-let you read this forum in a convenient manner.
-
-The easiest way to read this source is to put something like the
-following in your @file{~/.gnus.el} file:
-
-@lisp
-(setq gnus-secondary-select-methods
- '((nnslashdot "")))
-@end lisp
-
-This will make Gnus query the @code{nnslashdot} back end for new comments
-and groups. The @kbd{F} command will subscribe each new news article as
-a new Gnus group, and you can read the comments by entering these
-groups. (Note that the default subscription method is to subscribe new
-groups as zombies. Other methods are available (@pxref{Subscription
-Methods}).
-
-If you want to remove an old @code{nnslashdot} group, the @kbd{G DEL}
-command is the most handy tool (@pxref{Foreign Groups}).
-
-When following up to @code{nnslashdot} comments (or posting new
-comments), some light @acronym{HTML}izations will be performed. In
-particular, text quoted with @samp{> } will be quoted with
-@samp{blockquote} instead, and signatures will have @samp{br} added to
-the end of each line. Other than that, you can just write @acronym{HTML}
-directly into the message buffer. Note that Slashdot filters out some
-@acronym{HTML} forms.
-
-The following variables can be altered to change its behavior:
-
-@table @code
-@item nnslashdot-threaded
-Whether @code{nnslashdot} should display threaded groups or not. The
-default is @code{t}. To be able to display threads, @code{nnslashdot}
-has to retrieve absolutely all comments in a group upon entry. If a
-threaded display is not required, @code{nnslashdot} will only retrieve
-the comments that are actually wanted by the user. Threading is nicer,
-but much, much slower than unthreaded.
-
-@item nnslashdot-login-name
-@vindex nnslashdot-login-name
-The login name to use when posting.
-
-@item nnslashdot-password
-@vindex nnslashdot-password
-The password to use when posting.
-
-@item nnslashdot-directory
-@vindex nnslashdot-directory
-Where @code{nnslashdot} will store its files. The default is
-@file{~/News/slashdot/}.
-
-@item nnslashdot-active-url
-@vindex nnslashdot-active-url
-The @acronym{URL} format string that will be used to fetch the
-information on news articles and comments. The default is@*
-@samp{http://slashdot.org/search.pl?section=&min=%d}.
-
-@item nnslashdot-comments-url
-@vindex nnslashdot-comments-url
-The @acronym{URL} format string that will be used to fetch comments.
-
-@item nnslashdot-article-url
-@vindex nnslashdot-article-url
-The @acronym{URL} format string that will be used to fetch the news
-article. The default is
-@samp{http://slashdot.org/article.pl?sid=%s&mode=nocomment}.
-
-@item nnslashdot-threshold
-@vindex nnslashdot-threshold
-The score threshold. The default is -1.
-
-@item nnslashdot-group-number
-@vindex nnslashdot-group-number
-The number of old groups, in addition to the ten latest, to keep
-updated. The default is 0.
-
-@end table
-
-
-
-@node Ultimate
-@subsection Ultimate
-@cindex nnultimate
-@cindex Ultimate Bulletin Board
-
-@uref{http://www.ultimatebb.com/, The Ultimate Bulletin Board} is
-probably the most popular Web bulletin board system used. It has a
-quite regular and nice interface, and it's possible to get the
-information Gnus needs to keep groups updated.
-
-The easiest way to get started with @code{nnultimate} is to say
-something like the following in the group buffer: @kbd{B nnultimate RET
-http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @acronym{URL}
-(not including @samp{Ultimate.cgi} or the like at the end) for a forum
-you're interested in; there's quite a list of them on the Ultimate web
-site.) Then subscribe to the groups you're interested in from the
-server buffer, and read them from the group buffer.
-
-The following @code{nnultimate} variables can be altered:
-
-@table @code
-@item nnultimate-directory
-@vindex nnultimate-directory
-The directory where @code{nnultimate} stores its files. The default is@*
-@file{~/News/ultimate/}.
-@end table
-
-
-@node Web Archive
-@subsection Web Archive
-@cindex nnwarchive
-@cindex Web Archive
-
-Some mailing lists only have archives on Web servers, such as
-@uref{http://www.egroups.com/} and
-@uref{http://www.mail-archive.com/}. It has a quite regular and nice
-interface, and it's possible to get the information Gnus needs to keep
-groups updated.
-
-@findex gnus-group-make-warchive-group
-The easiest way to get started with @code{nnwarchive} is to say
-something like the following in the group buffer: @kbd{M-x
-gnus-group-make-warchive-group RET @var{an_egroup} RET egroups RET
-www.egroups.com RET @var{your@@email.address} RET}. (Substitute the
-@var{an_egroup} with the mailing list you subscribed, the
-@var{your@@email.address} with your email address.), or to browse the
-back end by @kbd{B nnwarchive RET mail-archive RET}.
-
-The following @code{nnwarchive} variables can be altered:
-
-@table @code
-@item nnwarchive-directory
-@vindex nnwarchive-directory
-The directory where @code{nnwarchive} stores its files. The default is@*
-@file{~/News/warchive/}.
-
-@item nnwarchive-login
-@vindex nnwarchive-login
-The account name on the web server.
+@item id
+Format string URL to fetch an article by @code{Message-ID}.
+@end table
-@item nnwarchive-passwd
-@vindex nnwarchive-passwd
-The password for your account on the web server.
@end table
+
@node RSS
@subsection RSS
@cindex nnrss
@code{nnrss-directory} (see below) for each @code{nnrss} group. File
names containing non-@acronym{ASCII} characters will be encoded by the
coding system specified with the @code{nnmail-pathname-coding-system}
-variable. If it is @code{nil}, in Emacs the coding system defaults to
-the value of @code{default-file-name-coding-system}. If you are using
-XEmacs and want to use non-@acronym{ASCII} group names, you should set
-the value for the @code{nnmail-pathname-coding-system} variable properly.
+variable or other. Also @xref{Non-ASCII Group Names}, for more
+information.
The @code{nnrss} back end generates @samp{multipart/alternative}
@acronym{MIME} articles in which each contains a @samp{text/plain} part
the feeds from local files in @code{nnrss-directory}. You can use
the command @code{nnrss-generate-download-script} to generate a
download script using @command{wget}.
-
-@item nnrss-wash-html-in-text-plain-parts
-Non-@code{nil} means that @code{nnrss} renders text in @samp{text/plain}
-parts as @acronym{HTML}. The function specified by the
-@code{mm-text-html-renderer} variable (@pxref{Display Customization,
-,Display Customization, emacs-mime, The Emacs MIME Manual}) will be used
-to render text. If it is @code{nil}, which is the default, text will
-simply be folded. Leave it @code{nil} if you prefer to see
-@samp{text/html} parts.
@end table
The following code may be helpful, if you want to show the description in
follow the link.
-@node IMAP
-@section IMAP
-@cindex nnimap
-@cindex @acronym{IMAP}
-
-@acronym{IMAP} is a network protocol for reading mail (or news, or @dots{}),
-think of it as a modernized @acronym{NNTP}. Connecting to a @acronym{IMAP}
-server is much similar to connecting to a news server, you just
-specify the network address of the server.
-
-@acronym{IMAP} has two properties. First, @acronym{IMAP} can do
-everything that @acronym{POP} can, it can hence be viewed as a
-@acronym{POP++}. Secondly, @acronym{IMAP} is a mail storage protocol,
-similar to @acronym{NNTP} being a news storage protocol---however,
-@acronym{IMAP} offers more features than @acronym{NNTP} because news
-is more or less read-only whereas mail is read-write.
-
-If you want to use @acronym{IMAP} as a @acronym{POP++}, use an imap
-entry in @code{mail-sources}. With this, Gnus will fetch mails from
-the @acronym{IMAP} server and store them on the local disk. This is
-not the usage described in this section---@xref{Mail Sources}.
-
-If you want to use @acronym{IMAP} as a mail storage protocol, use an nnimap
-entry in @code{gnus-secondary-select-methods}. With this, Gnus will
-manipulate mails stored on the @acronym{IMAP} server. This is the kind of
-usage explained in this section.
-
-A server configuration in @file{~/.gnus.el} with a few @acronym{IMAP}
-servers might look something like the following. (Note that for
-@acronym{TLS}/@acronym{SSL}, you need external programs and libraries,
-see below.)
-
-@lisp
-(setq gnus-secondary-select-methods
- '((nnimap "simpleserver") ; @r{no special configuration}
- ; @r{perhaps a ssh port forwarded server:}
- (nnimap "dolk"
- (nnimap-address "localhost")
- (nnimap-server-port 1430))
- ; @r{a UW server running on localhost}
- (nnimap "barbar"
- (nnimap-server-port 143)
- (nnimap-address "localhost")
- (nnimap-list-pattern ("INBOX" "mail/*")))
- ; @r{anonymous public cyrus server:}
- (nnimap "cyrus.andrew.cmu.edu"
- (nnimap-authenticator anonymous)
- (nnimap-list-pattern "archive.*")
- (nnimap-stream network))
- ; @r{a ssl server on a non-standard port:}
- (nnimap "vic20"
- (nnimap-address "vic20.somewhere.com")
- (nnimap-server-port 9930)
- (nnimap-stream ssl))))
-@end lisp
-
-After defining the new server, you can subscribe to groups on the
-server using normal Gnus commands such as @kbd{U} in the Group Buffer
-(@pxref{Subscription Commands}) or via the Server Buffer
-(@pxref{Server Buffer}).
-
-The following variables can be used to create a virtual @code{nnimap}
-server:
-
-@table @code
-
-@item nnimap-address
-@vindex nnimap-address
-
-The address of the remote @acronym{IMAP} server. Defaults to the virtual
-server name if not specified.
-
-@item nnimap-server-port
-@vindex nnimap-server-port
-Port on server to contact. Defaults to port 143, or 993 for @acronym{TLS}/@acronym{SSL}.
-
-Note that this should be an integer, example server specification:
-
-@lisp
-(nnimap "mail.server.com"
- (nnimap-server-port 4711))
-@end lisp
-
-@item nnimap-list-pattern
-@vindex nnimap-list-pattern
-String or list of strings of mailboxes to limit available groups to.
-This is used when the server has very many mailboxes and you're only
-interested in a few---some servers export your home directory via
-@acronym{IMAP}, you'll probably want to limit the mailboxes to those in
-@file{~/Mail/*} then.
+@node Other Sources
+@section Other Sources
-The string can also be a cons of REFERENCE and the string as above, what
-REFERENCE is used for is server specific, but on the University of
-Washington server it's a directory that will be concatenated with the
-mailbox.
+Gnus can do more than just read news or mail. The methods described
+below allow Gnus to view directories and files as if they were
+newsgroups.
-Example server specification:
+@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.
+* Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
+* The Empty Backend:: The backend that never has any news.
+@end menu
-@lisp
-(nnimap "mail.server.com"
- (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*"
- ("~friend/Mail/" . "list/*"))))
-@end lisp
-@item nnimap-stream
-@vindex nnimap-stream
-The type of stream used to connect to your server. By default, nnimap
-will detect and automatically use all of the below, with the exception
-of @acronym{TLS}/@acronym{SSL}. (@acronym{IMAP} over
-@acronym{TLS}/@acronym{SSL} is being replaced by STARTTLS, which can
-be automatically detected, but it's not widely deployed yet.)
+@node Directory Groups
+@subsection Directory Groups
+@cindex nndir
+@cindex directory groups
-Example server specification:
+If you have a directory that has lots of articles in separate files in
+it, you might treat it as a newsgroup. The files have to have numerical
+names, of course.
-@lisp
-(nnimap "mail.server.com"
- (nnimap-stream ssl))
-@end lisp
+This might be an opportune moment to mention @code{ange-ftp} (and its
+successor @code{efs}), that most wonderful of all wonderful Emacs
+packages. When I wrote @code{nndir}, I didn't think much about it---a
+back end to read directories. Big deal.
-Please note that the value of @code{nnimap-stream} is a symbol!
+@code{ange-ftp} changes that picture dramatically. For instance, if you
+enter the @code{ange-ftp} file name
+@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name,
+@code{ange-ftp} or @code{efs} will actually allow you to read this
+directory over at @samp{sina} as a newsgroup. Distributed news ahoy!
-@itemize @bullet
-@item
-@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the
-@samp{gsasl} or @samp{imtest} program.
-@item
-@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program.
-@item
-@dfn{starttls:} Connect via the STARTTLS extension (similar to
-@acronym{TLS}/@acronym{SSL}). Requires the external library @samp{starttls.el} and program
-@samp{starttls}.
-@item
-@dfn{tls:} Connect through @acronym{TLS}. Requires GNUTLS (the program
-@samp{gnutls-cli}).
-@item
-@dfn{ssl:} Connect through @acronym{SSL}. Requires OpenSSL (the program
-@samp{openssl}) or SSLeay (@samp{s_client}).
-@item
-@dfn{shell:} Use a shell command to start @acronym{IMAP} connection.
-@item
-@dfn{network:} Plain, TCP/IP network connection.
-@end itemize
+@code{nndir} will use @acronym{NOV} files if they are present.
-@vindex imap-kerberos4-program
-The @samp{imtest} program is shipped with Cyrus IMAPD. If you're
-using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version
-1.5.x and 1.6.x) you need to frob @code{imap-process-connection-type}
-to make @code{imap.el} use a pty instead of a pipe when communicating
-with @samp{imtest}. You will then suffer from a line length
-restrictions on @acronym{IMAP} commands, which might make Gnus seem to hang
-indefinitely if you have many articles in a mailbox. The variable
-@code{imap-kerberos4-program} contain parameters to pass to the imtest
-program.
-
-For @acronym{TLS} connection, the @code{gnutls-cli} program from GNUTLS is
-needed. It is available from
-@uref{http://www.gnu.org/software/gnutls/}.
-
-@vindex imap-gssapi-program
-This parameter specifies a list of command lines that invoke a GSSAPI
-authenticated @acronym{IMAP} stream in a subshell. They are tried
-sequentially until a connection is made, or the list has been
-exhausted. By default, @samp{gsasl} from GNU SASL, available from
-@uref{http://www.gnu.org/software/gsasl/}, and the @samp{imtest}
-program from Cyrus IMAPD (see @code{imap-kerberos4-program}), are
-tried.
-
-@vindex imap-ssl-program
-For @acronym{SSL} connections, the OpenSSL program is available from
-@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay,
-and nnimap support it too---although the most recent versions of
-SSLeay, 0.9.x, are known to have serious bugs making it
-useless. Earlier versions, especially 0.8.x, of SSLeay are known to
-work. The variable @code{imap-ssl-program} contain parameters to pass
-to OpenSSL/SSLeay.
-
-@vindex imap-shell-program
-@vindex imap-shell-host
-For @acronym{IMAP} connections using the @code{shell} stream, the
-variable @code{imap-shell-program} specify what program to call. Make
-sure nothing is interfering with the output of the program, e.g., don't
-forget to redirect the error output to the void.
+@code{nndir} is a ``read-only'' back end---you can't delete or expire
+articles with this method. You can use @code{nnmh} or @code{nnml} for
+whatever you use @code{nndir} for, so you could switch to any of those
+methods if you feel the need to have a non-read-only @code{nndir}.
-@item nnimap-authenticator
-@vindex nnimap-authenticator
-The authenticator used to connect to the server. By default, nnimap
-will use the most secure authenticator your server is capable of.
+@node Anything Groups
+@subsection Anything Groups
+@cindex nneething
-Example server specification:
+From the @code{nndir} back end (which reads a single spool-like
+directory), it's just a hop and a skip to @code{nneething}, which
+pretends that any arbitrary directory is a newsgroup. Strange, but
+true.
-@lisp
-(nnimap "mail.server.com"
- (nnimap-authenticator anonymous))
-@end lisp
+When @code{nneething} is presented with a directory, it will scan this
+directory and assign article numbers to each file. When you enter such
+a group, @code{nneething} must create ``headers'' that Gnus can use.
+After all, Gnus is a newsreader, in case you're forgetting.
+@code{nneething} does this in a two-step process. First, it snoops each
+file in question. If the file looks like an article (i.e., the first
+few lines look like headers), it will use this as the head. If this is
+just some arbitrary file without a head (e.g. a C source file),
+@code{nneething} will cobble up a header out of thin air. It will use
+file ownership, name and date and do whatever it can with these
+elements.
-Please note that the value of @code{nnimap-authenticator} is a symbol!
+All this should happen automatically for you, and you will be presented
+with something that looks very much like a newsgroup. Totally like a
+newsgroup, to be precise. If you select an article, it will be displayed
+in the article buffer, just as usual.
-@itemize @bullet
-@item
-@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires
-external program @code{gsasl} or @code{imtest}.
-@item
-@dfn{kerberos4:} Kerberos 4 authentication. Requires external program
-@code{imtest}.
-@item
-@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Requires
-external library @code{digest-md5.el}.
-@item
-@dfn{cram-md5:} Encrypted username/password via CRAM-MD5.
-@item
-@dfn{login:} Plain-text username/password via LOGIN.
-@item
-@dfn{anonymous:} Login as ``anonymous'', supplying your email address as password.
-@end itemize
+If you select a line that represents a directory, Gnus will pop you into
+a new summary buffer for this @code{nneething} group. And so on. You can
+traverse the entire disk this way, if you feel like, but remember that
+Gnus is not dired, really, and does not intend to be, either.
-@item nnimap-expunge-on-close
-@cindex expunging
-@vindex nnimap-expunge-on-close
-Unlike Parmenides the @acronym{IMAP} designers have decided things that
-don't exist actually do exist. More specifically, @acronym{IMAP} has
-this concept of marking articles @code{Deleted} which doesn't actually
-delete them, and this (marking them @code{Deleted}, that is) is what
-nnimap does when you delete an article in Gnus (with @kbd{B DEL} or
-similar).
-
-Since the articles aren't really removed when we mark them with the
-@code{Deleted} flag we'll need a way to actually delete them. Feel like
-running in circles yet?
-
-Traditionally, nnimap has removed all articles marked as @code{Deleted}
-when closing a mailbox but this is now configurable by this server
-variable.
+There are two overall modes to this action---ephemeral or solid. When
+doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
+will not store information on what files you have read, and what files
+are new, and so on. If you create a solid @code{nneething} group the
+normal way with @kbd{G m}, Gnus will store a mapping table between
+article numbers and file names, and you can treat this group like any
+other groups. When you activate a solid @code{nneething} group, you will
+be told how many unread articles it contains, etc., etc.
-The possible options are:
+Some variables:
@table @code
+@item nneething-map-file-directory
+@vindex nneething-map-file-directory
+All the mapping files for solid @code{nneething} groups will be stored
+in this directory, which defaults to @file{~/.nneething/}.
-@item always
-The default behavior, delete all articles marked as ``Deleted'' when
-closing a mailbox.
-@item never
-Never actually delete articles. Currently there is no way of showing
-the articles marked for deletion in nnimap, but other @acronym{IMAP} clients
-may allow you to do this. If you ever want to run the EXPUNGE command
-manually, @xref{Expunging mailboxes}.
-@item ask
-When closing mailboxes, nnimap will ask if you wish to expunge deleted
-articles or not.
-
-@end table
-
-@item nnimap-importantize-dormant
-@vindex nnimap-importantize-dormant
-
-If non-@code{nil} (the default), marks dormant articles as ticked (as
-well), for other @acronym{IMAP} clients. Within Gnus, dormant articles will
-naturally still (only) be marked as dormant. This is to make dormant
-articles stand out, just like ticked articles, in other @acronym{IMAP}
-clients. (In other words, Gnus has two ``Tick'' marks and @acronym{IMAP}
-has only one.)
-
-Probably the only reason for frobbing this would be if you're trying
-enable per-user persistent dormant flags, using something like:
-
-@lisp
-(setcdr (assq 'dormant nnimap-mark-to-flag-alist)
- (format "gnus-dormant-%s" (user-login-name)))
-(setcdr (assq 'dormant nnimap-mark-to-predicate-alist)
- (format "KEYWORD gnus-dormant-%s" (user-login-name)))
-@end lisp
-
-In this case, you would not want the per-user dormant flag showing up
-as ticked for other users.
-
-@item nnimap-expunge-search-string
-@cindex expunging
-@vindex nnimap-expunge-search-string
-@cindex expiring @acronym{IMAP} mail
-
-This variable contain the @acronym{IMAP} search command sent to server when
-searching for articles eligible for expiring. The default is
-@code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by
-UID set and the second @code{%s} is replaced by a date.
-
-Probably the only useful value to change this to is
-@code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in
-messages instead of the internal article date. See section 6.4.4 of
-RFC 2060 for more information on valid strings.
-
-However, if @code{nnimap-search-uids-not-since-is-evil}
-is true, this variable has no effect since the search logic
-is reversed, as described below.
-
-@item nnimap-authinfo-file
-@vindex nnimap-authinfo-file
-
-A file containing credentials used to log in on servers. The format is
-(almost) the same as the @code{ftp} @file{~/.netrc} file. See the
-variable @code{nntp-authinfo-file} for exact syntax; also see
-@ref{NNTP}. An example of an .authinfo line for an IMAP server, is:
-
-@example
-machine students.uio.no login larsi password geheimnis port imap
-@end example
-
-Note that it should be @code{port imap}, or @code{port 143}, if you
-use a @code{nnimap-stream} of @code{tls} or @code{ssl}, even if the
-actual port number used is port 993 for secured IMAP. For
-convenience, Gnus will accept @code{port imaps} as a synonym of
-@code{port imap}.
-
-@item nnimap-need-unselect-to-notice-new-mail
-@vindex nnimap-need-unselect-to-notice-new-mail
-
-Unselect mailboxes before looking for new mail in them. Some servers
-seem to need this under some circumstances; it was reported that
-Courier 1.7.1 did.
-
-@item nnimap-nov-is-evil
-@vindex nnimap-nov-is-evil
-@cindex Courier @acronym{IMAP} server
-@cindex @acronym{NOV}
-
-Never generate or use a local @acronym{NOV} database. Defaults to the
-value of @code{gnus-agent}.
-
-Using a @acronym{NOV} database usually makes header fetching much
-faster, but it uses the @code{UID SEARCH UID} command, which is very
-slow on some servers (notably some versions of Courier). Since the Gnus
-Agent caches the information in the @acronym{NOV} database without using
-the slow command, this variable defaults to true if the Agent is in use,
-and false otherwise.
-
-@item nnimap-search-uids-not-since-is-evil
-@vindex nnimap-search-uids-not-since-is-evil
-@cindex Courier @acronym{IMAP} server
-@cindex expiring @acronym{IMAP} mail
-
-Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE
-@var{date}} command, which is slow on some @acronym{IMAP} servers
-(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE
-@var{date}} and prune the list of expirable articles within Gnus.
-
-When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a
-list of expirable articles and asks the IMAP server questions like ``Of
-these articles, which ones are older than a week?'' While this seems
-like a perfectly reasonable question, some IMAP servers take a long time
-to answer it, since they seemingly go looking into every old article to
-see if it is one of the expirable ones. Curiously, the question ``Of
-@emph{all} articles, which ones are newer than a week?'' seems to be
-much faster to answer, so setting this variable causes Gnus to ask this
-question and figure out the answer to the real question itself.
-
-This problem can really sneak up on you: when you first configure Gnus,
-everything works fine, but once you accumulate a couple thousand
-messages, you start cursing Gnus for being so slow. On the other hand,
-if you get a lot of email within a week, setting this variable will
-cause a lot of network traffic between Gnus and the IMAP server.
-
-@item nnimap-logout-timeout
-@vindex nnimap-logout-timeout
-
-There is a case where a connection to a @acronym{IMAP} server is unable
-to close, when connecting to the server via a certain kind of network,
-e.g. @acronym{VPN}. In that case, it will be observed that a connection
-between Emacs and the local network looks alive even if the server has
-closed a connection for some reason (typically, a timeout).
-Consequently, Emacs continues waiting for a response from the server for
-the @code{LOGOUT} command that Emacs sent, or hangs in other words. If
-you are in such a network, setting this variable to a number of seconds
-will be helpful. If it is set, a hung connection will be closed
-forcibly, after this number of seconds from the time Emacs sends the
-@code{LOGOUT} command. It should not be too small value but too large
-value will be inconvenient too. Perhaps the value 1.0 will be a good
-candidate but it might be worth trying some other values.
-
-Example server specification:
+@item nneething-exclude-files
+@vindex nneething-exclude-files
+All files that match this regexp will be ignored. Nice to use to exclude
+auto-save files and the like, which is what it does by default.
-@lisp
-(nnimap "mail.server.com"
- (nnimap-logout-timeout 1.0))
-@end lisp
+@item nneething-include-files
+@vindex nneething-include-files
+Regexp saying what files to include in the group. If this variable is
+non-@code{nil}, only files matching this regexp will be included.
+@item nneething-map-file
+@vindex nneething-map-file
+Name of the map files.
@end table
-@menu
-* Splitting in IMAP:: Splitting mail with nnimap.
-* Expiring in IMAP:: Expiring mail with nnimap.
-* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
-* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
-* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus.
-* Debugging IMAP:: What to do when things don't work.
-@end menu
-
-
-
-@node Splitting in IMAP
-@subsection Splitting in IMAP
-@cindex splitting imap mail
-
-Splitting is something Gnus users have loved and used for years, and now
-the rest of the world is catching up. Yeah, dream on, not many
-@acronym{IMAP} servers have server side splitting and those that have
-splitting seem to use some non-standard protocol. This means that
-@acronym{IMAP} support for Gnus has to do its own splitting.
-And it does.
-
-(Incidentally, people seem to have been dreaming on, and Sieve has
-gaining a market share and is supported by several IMAP servers.
-Fortunately, Gnus support it too, @xref{Sieve Commands}.)
+@node Document Groups
+@subsection Document Groups
+@cindex nndoc
+@cindex documentation group
+@cindex help group
-Here are the variables of interest:
+@code{nndoc} is a cute little thing that will let you read a single file
+as a newsgroup. Several files types are supported:
@table @code
+@cindex Babyl
+@item babyl
+The Babyl format.
-@item nnimap-split-crosspost
-@cindex splitting, crosspost
-@cindex crosspost
-@vindex nnimap-split-crosspost
-
-If non-@code{nil}, do crossposting if several split methods match the
-mail. If @code{nil}, the first match in @code{nnimap-split-rule}
-found will be used.
-
-Nnmail equivalent: @code{nnmail-crosspost}.
-
-@item nnimap-split-inbox
-@cindex splitting, inbox
-@cindex inbox
-@vindex nnimap-split-inbox
-
-A string or a list of strings that gives the name(s) of @acronym{IMAP}
-mailboxes to split from. Defaults to @code{nil}, which means that
-splitting is disabled!
-
-@lisp
-(setq nnimap-split-inbox
- '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))
-@end lisp
-
-No nnmail equivalent.
-
-@item nnimap-split-rule
-@cindex splitting, rules
-@vindex nnimap-split-rule
-
-New mail found in @code{nnimap-split-inbox} will be split according to
-this variable.
-
-This variable contains a list of lists, where the first element in the
-sublist gives the name of the @acronym{IMAP} mailbox to move articles
-matching the regexp in the second element in the sublist. Got that?
-Neither did I, we need examples.
-
-@lisp
-(setq nnimap-split-rule
- '(("INBOX.nnimap"
- "^Sender: owner-nnimap@@vic20.globalcom.se")
- ("INBOX.junk" "^Subject:.*MAKE MONEY")
- ("INBOX.private" "")))
-@end lisp
-
-This will put all articles from the nnimap mailing list into mailbox
-INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line
-into INBOX.junk and everything else in INBOX.private.
-
-The first string may contain @samp{\\1} forms, like the ones used by
-replace-match to insert sub-expressions from the matched text. For
-instance:
-
-@lisp
-("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@")
-@end lisp
-
-The first element can also be the symbol @code{junk} to indicate that
-matching messages should simply be deleted. Use with care.
-
-The second element can also be a function. In that case, it will be
-called with the first element of the rule as the argument, in a buffer
-containing the headers of the article. It should return a
-non-@code{nil} value if it thinks that the mail belongs in that group.
-
-Nnmail users might recollect that the last regexp had to be empty to
-match all articles (like in the example above). This is not required in
-nnimap. Articles not matching any of the regexps will not be moved out
-of your inbox. (This might affect performance if you keep lots of
-unread articles in your inbox, since the splitting code would go over
-them every time you fetch new mail.)
+@cindex mbox
+@cindex Unix mbox
+@item mbox
+The standard Unix mbox file.
-These rules are processed from the beginning of the alist toward the
-end. The first rule to make a match will ``win'', unless you have
-crossposting enabled. In that case, all matching rules will ``win''.
+@cindex MMDF mail box
+@item mmdf
+The MMDF mail box format.
-This variable can also have a function as its value, the function will
-be called with the headers narrowed and should return a group where it
-thinks the article should be split to. See @code{nnimap-split-fancy}.
+@item news
+Several news articles appended into a file.
-The splitting code tries to create mailboxes if it needs to.
+@cindex rnews batch files
+@item rnews
+The rnews batch transport format.
-To allow for different split rules on different virtual servers, and
-even different split rules in different inboxes on the same server,
-the syntax of this variable have been extended along the lines of:
+@item nsmail
+Netscape mail boxes.
-@lisp
-(setq nnimap-split-rule
- '(("my1server" (".*" (("ding" "ding@@gnus.org")
- ("junk" "From:.*Simon"))))
- ("my2server" ("INBOX" nnimap-split-fancy))
- ("my[34]server" (".*" (("private" "To:.*Simon")
- ("junk" my-junk-func))))))
-@end lisp
+@item mime-parts
+@acronym{MIME} multipart messages.
-The virtual server name is in fact a regexp, so that the same rules
-may apply to several servers. In the example, the servers
-@code{my3server} and @code{my4server} both use the same rules.
-Similarly, the inbox string is also a regexp. The actual splitting
-rules are as before, either a function, or a list with group/regexp or
-group/function elements.
+@item standard-digest
+The standard (RFC 1153) digest format.
-Nnmail equivalent: @code{nnmail-split-methods}.
+@item mime-digest
+A @acronym{MIME} digest of messages.
-@item nnimap-split-predicate
-@cindex splitting
-@vindex nnimap-split-predicate
+@item lanl-gov-announce
+Announcement messages from LANL Gov Announce.
-Mail matching this predicate in @code{nnimap-split-inbox} will be
-split, it is a string and the default is @samp{UNSEEN UNDELETED}.
+@cindex git commit messages
+@item git
+@code{git} commit messages.
-This might be useful if you use another @acronym{IMAP} client to read mail in
-your inbox but would like Gnus to split all articles in the inbox
-regardless of readedness. Then you might change this to
-@samp{UNDELETED}.
+@cindex forwarded messages
+@item rfc822-forward
+A message forwarded according to RFC822.
-@item nnimap-split-fancy
-@cindex splitting, fancy
-@findex nnimap-split-fancy
-@vindex nnimap-split-fancy
+@item outlook
+The Outlook mail box.
-It's possible to set @code{nnimap-split-rule} to
-@code{nnmail-split-fancy} if you want to use fancy
-splitting. @xref{Fancy Mail Splitting}.
+@item oe-dbx
+The Outlook Express dbx mail box.
-However, to be able to have different fancy split rules for nnmail and
-nnimap back ends you can set @code{nnimap-split-rule} to
-@code{nnimap-split-fancy} and define the nnimap specific fancy split
-rule in @code{nnimap-split-fancy}.
+@item exim-bounce
+A bounce message from the Exim MTA.
-Example:
+@item forward
+A message forwarded according to informal rules.
-@lisp
-(setq nnimap-split-rule 'nnimap-split-fancy
- nnimap-split-fancy ...)
-@end lisp
+@item rfc934
+An RFC934-forwarded message.
-Nnmail equivalent: @code{nnmail-split-fancy}.
+@item mailman
+A mailman digest.
-@item nnimap-split-download-body
-@findex nnimap-split-download-body
-@vindex nnimap-split-download-body
+@item clari-briefs
+A digest of Clarinet brief news items.
-Set to non-@code{nil} to download entire articles during splitting.
-This is generally not required, and will slow things down
-considerably. You may need it if you want to use an advanced
-splitting function that analyzes the body to split the article.
+@item slack-digest
+Non-standard digest format---matches most things, but does it badly.
+@item mail-in-mail
+The last resort.
@end table
-@node Expiring in IMAP
-@subsection Expiring in IMAP
-@cindex expiring @acronym{IMAP} mail
+You can also use the special ``file type'' @code{guess}, which means
+that @code{nndoc} will try to guess what file type it is looking at.
+@code{digest} means that @code{nndoc} should guess what digest type the
+file is.
-Even though @code{nnimap} is not a proper @code{nnmail} derived back
-end, it supports most features in regular expiring (@pxref{Expiring
-Mail}). Unlike splitting in @acronym{IMAP} (@pxref{Splitting in
-IMAP}) it does not clone the @code{nnmail} variables (i.e., creating
-@var{nnimap-expiry-wait}) but reuse the @code{nnmail} variables. What
-follows below are the variables used by the @code{nnimap} expiry
-process.
+@code{nndoc} will not try to change the file or insert any extra headers into
+it---it will simply, like, let you use the file as the basis for a
+group. And that's it.
-A note on how the expire mark is stored on the @acronym{IMAP} server is
-appropriate here as well. The expire mark is translated into a
-@code{imap} client specific mark, @code{gnus-expire}, and stored on the
-message. This means that likely only Gnus will understand and treat
-the @code{gnus-expire} mark properly, although other clients may allow
-you to view client specific flags on the message. It also means that
-your server must support permanent storage of client specific flags on
-messages. Most do, fortunately.
+If you have some old archived articles that you want to insert into your
+new & spiffy Gnus mail back end, @code{nndoc} can probably help you with
+that. Say you have an old @file{RMAIL} file with mail that you now want
+to split into your new @code{nnml} groups. You look at that file using
+@code{nndoc} (using the @kbd{G f} command in the group buffer
+(@pxref{Foreign Groups})), set the process mark on all the articles in
+the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r})
+using @code{nnml}. If all goes well, all the mail in the @file{RMAIL}
+file is now also stored in lots of @code{nnml} directories, and you can
+delete that pesky @file{RMAIL} file. If you have the guts!
-If expiring @acronym{IMAP} mail seems very slow, try setting the server
-variable @code{nnimap-search-uids-not-since-is-evil}.
+Virtual server variables:
@table @code
+@item nndoc-article-type
+@vindex nndoc-article-type
+This should be one of @code{mbox}, @code{babyl}, @code{digest},
+@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934},
+@code{rfc822-forward}, @code{mime-parts}, @code{standard-digest},
+@code{slack-digest}, @code{clari-briefs}, @code{nsmail}, @code{outlook},
+@code{oe-dbx}, @code{mailman}, and @code{mail-in-mail} or @code{guess}.
-@item nnmail-expiry-wait
-@item nnmail-expiry-wait-function
-
-These variables are fully supported. The expire value can be a
-number, the symbol @code{immediate} or @code{never}.
+@item nndoc-post-type
+@vindex nndoc-post-type
+This variable says whether Gnus is to consider the group a news group or
+a mail group. There are two valid values: @code{mail} (the default)
+and @code{news}.
+@end table
-@item nnmail-expiry-target
+@menu
+* Document Server Internals:: How to add your own document types.
+@end menu
-This variable is supported, and internally implemented by calling the
-@code{nnmail} functions that handle this. It contains an optimization
-that if the destination is a @acronym{IMAP} group on the same server, the
-article is copied instead of appended (that is, uploaded again).
-@end table
+@node Document Server Internals
+@subsubsection Document Server Internals
-@node Editing IMAP ACLs
-@subsection Editing IMAP ACLs
-@cindex editing imap acls
-@cindex Access Control Lists
-@cindex Editing @acronym{IMAP} ACLs
-@kindex G l (Group)
-@findex gnus-group-nnimap-edit-acl
+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}.
-ACL stands for Access Control List. ACLs are used in @acronym{IMAP} for
-limiting (or enabling) other users access to your mail boxes. Not all
-@acronym{IMAP} servers support this, this function will give an error if it
-doesn't.
+First, here's an example document type definition:
-To edit an ACL for a mailbox, type @kbd{G l}
-(@code{gnus-group-edit-nnimap-acl}) and you'll be presented with an ACL
-editing window with detailed instructions.
+@example
+(mmdf
+ (article-begin . "^\^A\^A\^A\^A\n")
+ (body-end . "^\^A\^A\^A\^A\n"))
+@end example
-Some possible uses:
+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:
-@itemize @bullet
-@item
-Giving ``anyone'' the ``lrs'' rights (lookup, read, keep seen/unseen flags)
-on your mailing list mailboxes enables other users on the same server to
-follow the list without subscribing to it.
-@item
-At least with the Cyrus server, you are required to give the user
-``anyone'' posting ("p") capabilities to have ``plussing'' work (that is,
-mail sent to user+mailbox@@domain ending up in the @acronym{IMAP} mailbox
-INBOX.mailbox).
-@end itemize
+@table @code
+@item first-article
+If present, @code{nndoc} will skip past all text until it finds
+something that match this regexp. All text before this will be
+totally ignored.
-@node Expunging mailboxes
-@subsection Expunging mailboxes
-@cindex expunging
-
-@cindex expunge
-@cindex manual expunging
-@kindex G x (Group)
-@findex gnus-group-nnimap-expunge
-
-If you're using the @code{never} setting of @code{nnimap-expunge-on-close},
-you may want the option of expunging all deleted articles in a mailbox
-manually. This is exactly what @kbd{G x} does.
-
-Currently there is no way of showing deleted articles, you can just
-delete them.
-
-@node A note on namespaces
-@subsection A note on namespaces
-@cindex IMAP namespace
-@cindex namespaces
-
-The @acronym{IMAP} protocol has a concept called namespaces, described
-by the following text in the RFC2060:
-
-@display
-5.1.2. Mailbox Namespace Naming Convention
-
- By convention, the first hierarchical element of any mailbox name
- which begins with "#" identifies the "namespace" of the remainder of
- the name. This makes it possible to disambiguate between different
- types of mailbox stores, each of which have their own namespaces.
-
- For example, implementations which offer access to USENET
- newsgroups MAY use the "#news" namespace to partition the USENET
- newsgroup namespace from that of other mailboxes. Thus, the
- comp.mail.misc newsgroup would have an mailbox name of
- "#news.comp.mail.misc", and the name "comp.mail.misc" could refer
- to a different object (e.g. a user's private mailbox).
-@end display
-
-While there is nothing in this text that warrants concern for the
-@acronym{IMAP} implementation in Gnus, some servers use namespace
-prefixes in a way that does not work with how Gnus uses mailbox names.
-
-Specifically, University of Washington's @acronym{IMAP} server uses
-mailbox names like @code{#driver.mbx/read-mail} which are valid only
-in the @sc{create} and @sc{append} commands. After the mailbox is
-created (or a messages is appended to a mailbox), it must be accessed
-without the namespace prefix, i.e. @code{read-mail}. Since Gnus do
-not make it possible for the user to guarantee that user entered
-mailbox names will only be used with the CREATE and APPEND commands,
-you should simply not use the namespace prefixed mailbox names in
-Gnus.
-
-See the UoW IMAPD documentation for the @code{#driver.*/} prefix
-for more information on how to use the prefixes. They are a power
-tool and should be used only if you are sure what the effects are.
-
-@node Debugging IMAP
-@subsection Debugging IMAP
-@cindex IMAP debugging
-@cindex protocol dump (IMAP)
-
-@acronym{IMAP} is a complex protocol, more so than @acronym{NNTP} or
-@acronym{POP3}. Implementation bugs are not unlikely, and we do our
-best to fix them right away. If you encounter odd behavior, chances
-are that either the server or Gnus is buggy.
-
-If you are familiar with network protocols in general, you will
-probably be able to extract some clues from the protocol dump of the
-exchanges between Gnus and the server. Even if you are not familiar
-with network protocols, when you include the protocol dump in
-@acronym{IMAP}-related bug reports you are helping us with data
-critical to solving the problem. Therefore, we strongly encourage you
-to include the protocol dump when reporting IMAP bugs in Gnus.
-
-
-@vindex imap-log
-Because the protocol dump, when enabled, generates lots of data, it is
-disabled by default. You can enable it by setting @code{imap-log} as
-follows:
+@item article-begin
+This setting has to be present in all document type definitions. It
+says what the beginning of each article looks like. To do more
+complicated things that cannot be dealt with a simple regexp, you can
+use @code{article-begin-function} instead of this.
-@lisp
-(setq imap-log t)
-@end lisp
+@item article-begin-function
+If present, this should be a function that moves point to the beginning
+of each article. This setting overrides @code{article-begin}.
-This instructs the @code{imap.el} package to log any exchanges with
-the server. The log is stored in the buffer @samp{*imap-log*}. Look
-for error messages, which sometimes are tagged with the keyword
-@code{BAD}---but when submitting a bug, make sure to include all the
-data.
+@item head-begin
+If present, this should be a regexp that matches the head of the
+article. To do more complicated things that cannot be dealt with a
+simple regexp, you can use @code{head-begin-function} instead of this.
-@node Other Sources
-@section Other Sources
+@item head-begin-function
+If present, this should be a function that moves point to the head of
+the article. This setting overrides @code{head-begin}.
-Gnus can do more than just read news or mail. The methods described
-below allow Gnus to view directories and files as if they were
-newsgroups.
+@item head-end
+This should match the end of the head of the article. It defaults to
+@samp{^$}---the empty line.
-@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''.
-* Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
-@end menu
+@item body-begin
+This should match the beginning of the body of the article. It defaults
+to @samp{^\n}. To do more complicated things that cannot be dealt with
+a simple regexp, you can use @code{body-begin-function} instead of this.
+@item body-begin-function
+If present, this function should move point to the beginning of the body
+of the article. This setting overrides @code{body-begin}.
-@node Directory Groups
-@subsection Directory Groups
-@cindex nndir
-@cindex directory groups
+@item body-end
+If present, this should match the end of the body of the article. To do
+more complicated things that cannot be dealt with a simple regexp, you
+can use @code{body-end-function} instead of this.
-If you have a directory that has lots of articles in separate files in
-it, you might treat it as a newsgroup. The files have to have numerical
-names, of course.
+@item body-end-function
+If present, this function should move point to the end of the body of
+the article. This setting overrides @code{body-end}.
-This might be an opportune moment to mention @code{ange-ftp} (and its
-successor @code{efs}), that most wonderful of all wonderful Emacs
-packages. When I wrote @code{nndir}, I didn't think much about it---a
-back end to read directories. Big deal.
+@item file-begin
+If present, this should match the beginning of the file. All text
+before this regexp will be totally ignored.
-@code{ange-ftp} changes that picture dramatically. For instance, if you
-enter the @code{ange-ftp} file name
-@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name,
-@code{ange-ftp} or @code{efs} will actually allow you to read this
-directory over at @samp{sina} as a newsgroup. Distributed news ahoy!
+@item file-end
+If present, this should match the end of the file. All text after this
+regexp will be totally ignored.
-@code{nndir} will use @acronym{NOV} files if they are present.
+@end table
-@code{nndir} is a ``read-only'' back end---you can't delete or expire
-articles with this method. You can use @code{nnmh} or @code{nnml} for
-whatever you use @code{nndir} for, so you could switch to any of those
-methods if you feel the need to have a non-read-only @code{nndir}.
+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.
-@node Anything Groups
-@subsection Anything Groups
-@cindex nneething
+@item article-transform-function
+If present, this function is called when requesting an article. It's
+meant to be used for more wide-ranging transformation of both head and
+body of the article.
-From the @code{nndir} back end (which reads a single spool-like
-directory), it's just a hop and a skip to @code{nneething}, which
-pretends that any arbitrary directory is a newsgroup. Strange, but
-true.
+@item 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.
-When @code{nneething} is presented with a directory, it will scan this
-directory and assign article numbers to each file. When you enter such
-a group, @code{nneething} must create ``headers'' that Gnus can use.
-After all, Gnus is a newsreader, in case you're forgetting.
-@code{nneething} does this in a two-step process. First, it snoops each
-file in question. If the file looks like an article (i.e., the first
-few lines look like headers), it will use this as the head. If this is
-just some arbitrary file without a head (e.g. a C source file),
-@code{nneething} will cobble up a header out of thin air. It will use
-file ownership, name and date and do whatever it can with these
-elements.
+@item generate-article-function
+If present, this function is called to generate an entire article that
+Gnus can understand. It is called with the article number as a
+parameter when requesting all articles.
-All this should happen automatically for you, and you will be presented
-with something that looks very much like a newsgroup. Totally like a
-newsgroup, to be precise. If you select an article, it will be displayed
-in the article buffer, just as usual.
+@item dissection-function
+If present, this function is called to dissect a document by itself,
+overriding @code{first-article}, @code{article-begin},
+@code{article-begin-function}, @code{head-begin},
+@code{head-begin-function}, @code{head-end}, @code{body-begin},
+@code{body-begin-function}, @code{body-end}, @code{body-end-function},
+@code{file-begin}, and @code{file-end}.
-If you select a line that represents a directory, Gnus will pop you into
-a new summary buffer for this @code{nneething} group. And so on. You can
-traverse the entire disk this way, if you feel like, but remember that
-Gnus is not dired, really, and does not intend to be, either.
+@end table
-There are two overall modes to this action---ephemeral or solid. When
-doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
-will not store information on what files you have read, and what files
-are new, and so on. If you create a solid @code{nneething} group the
-normal way with @kbd{G m}, Gnus will store a mapping table between
-article numbers and file names, and you can treat this group like any
-other groups. When you activate a solid @code{nneething} group, you will
-be told how many unread articles it contains, etc., etc.
+Let's look at the most complicated example I can come up with---standard
+digests:
-Some variables:
+@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
-@table @code
-@item nneething-map-file-directory
-@vindex nneething-map-file-directory
-All the mapping files for solid @code{nneething} groups will be stored
-in this directory, which defaults to @file{~/.nneething/}.
+We see that all text before a 70-width line of dashes is ignored; all
+text after a line that starts with that @samp{^End of} is also ignored;
+each article begins with a 30-width line of dashes; the line separating
+the head from the body may contain a single space; and that the body is
+run through @code{nndoc-unquote-dashes} before being delivered.
-@item nneething-exclude-files
-@vindex nneething-exclude-files
-All files that match this regexp will be ignored. Nice to use to exclude
-auto-save files and the like, which is what it does by default.
+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-@var{type}-type-p} is called for a given type @var{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 valid number.
-@item nneething-include-files
-@vindex nneething-include-files
-Regexp saying what files to include in the group. If this variable is
-non-@code{nil}, only files matching this regexp will be included.
-@item nneething-map-file
-@vindex nneething-map-file
-Name of the map files.
-@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} back end provides the interface.
-@node Document Groups
-@subsection Document Groups
-@cindex nndoc
-@cindex documentation group
-@cindex help group
+Note that you can't read anything from this back end---it can only be
+used to post with.
-@code{nndoc} is a cute little thing that will let you read a single file
-as a newsgroup. Several files types are supported:
+Server variables:
@table @code
-@cindex Babyl
-@cindex Rmail mbox
-@item babyl
-The Babyl (Rmail) mail box.
+@item nngateway-address
+@vindex nngateway-address
+This is the address of the mail-to-news gateway.
-@cindex mbox
-@cindex Unix mbox
-@item mbox
-The standard Unix mbox file.
+@item nngateway-header-transformation
+@vindex nngateway-header-transformation
+News headers 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.
-@cindex MMDF mail box
-@item mmdf
-The MMDF mail box format.
+This default function just inserts a new @code{To} header based on the
+@code{Newsgroups} header and the gateway address.
+For instance, an article with this @code{Newsgroups} header:
-@item news
-Several news articles appended into a file.
+@example
+Newsgroups: alt.religion.emacs
+@end example
-@cindex rnews batch files
-@item rnews
-The rnews batch transport format.
+will get this @code{To} header inserted:
-@item nsmail
-Netscape mail boxes.
+@example
+To: alt-religion-emacs@@GATEWAY
+@end example
-@item mime-parts
-@acronym{MIME} multipart messages.
+The following pre-defined functions exist:
-@item standard-digest
-The standard (RFC 1153) digest format.
+@findex nngateway-simple-header-transformation
+@table @code
-@item mime-digest
-A @acronym{MIME} digest of messages.
+@item nngateway-simple-header-transformation
+Creates a @code{To} header that looks like
+@var{newsgroup}@@@code{nngateway-address}.
-@item lanl-gov-announce
-Announcement messages from LANL Gov Announce.
+@findex nngateway-mail2news-header-transformation
-@cindex forwarded messages
-@item rfc822-forward
-A message forwarded according to RFC822.
+@item nngateway-mail2news-header-transformation
+Creates a @code{To} header that looks like
+@code{nngateway-address}.
+@end table
-@item outlook
-The Outlook mail box.
+@end table
-@item oe-dbx
-The Outlook Express dbx mail box.
+Here's an example:
-@item exim-bounce
-A bounce message from the Exim MTA.
+@lisp
+(setq gnus-post-method
+ '(nngateway
+ "mail2news@@replay.com"
+ (nngateway-header-transformation
+ nngateway-mail2news-header-transformation)))
+@end lisp
-@item forward
-A message forwarded according to informal rules.
+So, to use this, simply say something like:
-@item rfc934
-An RFC934-forwarded message.
+@lisp
+(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
+@end lisp
-@item mailman
-A mailman digest.
-@item clari-briefs
-A digest of Clarinet brief news items.
+@node The Empty Backend
+@subsection The Empty Backend
+@cindex nnnil
-@item slack-digest
-Non-standard digest format---matches most things, but does it badly.
+@code{nnnil} is a backend that can be used as a placeholder if you
+have to specify a backend somewhere, but don't really want to. The
+classical example is if you don't want to have a primary select
+methods, but want to only use secondary ones:
-@item mail-in-mail
-The last resort.
-@end table
+@lisp
+(setq gnus-select-method '(nnnil ""))
+(setq gnus-secondary-select-methods
+ '((nnimap "foo")
+ (nnml "")))
+@end lisp
-You can also use the special ``file type'' @code{guess}, which means
-that @code{nndoc} will try to guess what file type it is looking at.
-@code{digest} means that @code{nndoc} should guess what digest type the
-file is.
-@code{nndoc} will not try to change the file or insert any extra headers into
-it---it will simply, like, let you use the file as the basis for a
-group. And that's it.
+@node Combined Groups
+@section Combined Groups
-If you have some old archived articles that you want to insert into your
-new & spiffy Gnus mail back end, @code{nndoc} can probably help you with
-that. Say you have an old @file{RMAIL} file with mail that you now want
-to split into your new @code{nnml} groups. You look at that file using
-@code{nndoc} (using the @kbd{G f} command in the group buffer
-(@pxref{Foreign Groups})), set the process mark on all the articles in
-the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r})
-using @code{nnml}. If all goes well, all the mail in the @file{RMAIL}
-file is now also stored in lots of @code{nnml} directories, and you can
-delete that pesky @file{RMAIL} file. If you have the guts!
+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.
+@end menu
-@table @code
-@item nndoc-article-type
-@vindex nndoc-article-type
-This should be one of @code{mbox}, @code{babyl}, @code{digest},
-@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934},
-@code{rfc822-forward}, @code{mime-parts}, @code{standard-digest},
-@code{slack-digest}, @code{clari-briefs}, @code{nsmail}, @code{outlook},
-@code{oe-dbx}, @code{mailman}, and @code{mail-in-mail} or @code{guess}.
-@item nndoc-post-type
-@vindex nndoc-post-type
-This variable says whether Gnus is to consider the group a news group or
-a mail group. There are two valid values: @code{mail} (the default)
-and @code{news}.
-@end table
+@node Virtual Groups
+@subsection Virtual Groups
+@cindex nnvirtual
+@cindex virtual groups
+@cindex merging groups
-@menu
-* Document Server Internals:: How to add your own document types.
-@end menu
+An @dfn{nnvirtual group} is really nothing more than a collection of
+other groups.
+For instance, if you are tired of reading many small groups, you can
+put them all in one big group, and then grow tired of reading one
+big, unwieldy group. The joys of computing!
-@node Document Server Internals
-@subsubsection Document Server Internals
+You specify @code{nnvirtual} as the method. The address should be a
+regexp to match component groups.
-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}.
+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.). To create an empty virtual group, run
+@kbd{G V} (@code{gnus-group-make-empty-virtual}) in the group buffer
+and edit the method regexp with @kbd{M-e}
+(@code{gnus-group-edit-group-method})
-First, here's an example document type definition:
+Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
+newsgroups into one, big, happy newsgroup:
+
+@lisp
+(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
+@end lisp
+
+The component groups can be native or foreign; everything should work
+smoothly, but if your computer explodes, it was probably my fault.
+
+Collecting the same group from several servers might actually be a good
+idea if users have set the Distribution header to limit distribution.
+If you would like to read @samp{soc.motss} both from a server in Japan
+and a server in Norway, you could use the following as the group regexp:
@example
-(mmdf
- (article-begin . "^\^A\^A\^A\^A\n")
- (body-end . "^\^A\^A\^A\^A\n"))
+"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$"
@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:
+(Remember, though, that if you're creating the group with @kbd{G m}, you
+shouldn't double the backslashes, and you should leave off the quote
+characters at the beginning and the end of the string.)
-@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.
+This should work kinda smoothly---all articles from both groups should
+end up in this one, and there should be no duplicates. Threading (and
+the rest) will still work as usual, but there might be problems with the
+sequence of articles. Sorting on date might be an option here
+(@pxref{Selecting a Group}).
-@item article-begin
-This setting has to be present in all document type definitions. It
-says what the beginning of each article looks like. To do more
-complicated things that cannot be dealt with a simple regexp, you can
-use @code{article-begin-function} instead of this.
+One limitation, however---all groups included in a virtual
+group have to be alive (i.e., subscribed or unsubscribed). Killed or
+zombie groups can't be component groups for @code{nnvirtual} groups.
-@item article-begin-function
-If present, this should be a function that moves point to the beginning
-of each article. This setting overrides @code{article-begin}.
+@vindex nnvirtual-always-rescan
+If the @code{nnvirtual-always-rescan} variable is non-@code{nil} (which
+is the default), @code{nnvirtual} will always scan groups for unread
+articles when entering a virtual group. If this variable is @code{nil}
+and you read articles in a component group after the virtual group has
+been activated, the read articles from the component group will show up
+when you enter the virtual group. You'll also see this effect if you
+have two virtual groups that have a component group in common. If
+that's the case, you should set this variable to @code{t}. Or you can
+just tap @code{M-g} on the virtual group every time before you enter
+it---it'll have much the same effect.
-@item head-begin
-If present, this should be a regexp that matches the head of the
-article. To do more complicated things that cannot be dealt with a
-simple regexp, you can use @code{head-begin-function} instead of this.
+@code{nnvirtual} can have both mail and news groups as component groups.
+When responding to articles in @code{nnvirtual} groups, @code{nnvirtual}
+has to ask the back end of the component group the article comes from
+whether it is a news or mail back end. However, when you do a @kbd{^},
+there is typically no sure way for the component back end to know this,
+and in that case @code{nnvirtual} tells Gnus that the article came from a
+not-news back end. (Just to be on the safe side.)
-@item head-begin-function
-If present, this should be a function that moves point to the head of
-the article. This setting overrides @code{head-begin}.
+@kbd{C-c C-n} in the message buffer will insert the @code{Newsgroups}
+line from the article you respond to in these cases.
+
+@code{nnvirtual} groups do not inherit anything but articles and marks
+from component groups---group parameters, for instance, are not
+inherited.
-@item head-end
-This should match the end of the head of the article. It defaults to
-@samp{^$}---the empty line.
-@item body-begin
-This should match the beginning of the body of the article. It defaults
-to @samp{^\n}. To do more complicated things that cannot be dealt with
-a simple regexp, you can use @code{body-begin-function} instead of this.
+@node Email Based Diary
+@section Email Based Diary
+@cindex diary
+@cindex email based diary
+@cindex calendar
-@item body-begin-function
-If present, this function should move point to the beginning of the body
-of the article. This setting overrides @code{body-begin}.
+This section describes a special mail back end called @code{nndiary},
+and its companion library @code{gnus-diary}. It is ``special'' in the
+sense that it is not meant to be one of the standard alternatives for
+reading mail with Gnus. See @ref{Choosing a Mail Back End} for that.
+Instead, it is used to treat @emph{some} of your mails in a special way,
+namely, as event reminders.
-@item body-end
-If present, this should match the end of the body of the article. To do
-more complicated things that cannot be dealt with a simple regexp, you
-can use @code{body-end-function} instead of this.
+Here is a typical scenario:
-@item body-end-function
-If present, this function should move point to the end of the body of
-the article. This setting overrides @code{body-end}.
+@itemize @bullet
+@item
+You've got a date with Andy Mc Dowell or Bruce Willis (select according
+to your sexual preference) in one month. You don't want to forget it.
+@item
+So you send a ``reminder'' message (actually, a diary one) to yourself.
+@item
+You forget all about it and keep on getting and reading new mail, as usual.
+@item
+From time to time, as you type `g' in the group buffer and as the date
+is getting closer, the message will pop up again to remind you of your
+appointment, just as if it were new and unread.
+@item
+Read your ``new'' messages, this one included, and start dreaming again
+of the night you're gonna have.
+@item
+Once the date is over (you actually fell asleep just after dinner), the
+message will be automatically deleted if it is marked as expirable.
+@end itemize
-@item file-begin
-If present, this should match the beginning of the file. All text
-before this regexp will be totally ignored.
+The Gnus Diary back end has the ability to handle regular appointments
+(that wouldn't ever be deleted) as well as punctual ones, operates as a
+real mail back end and is configurable in many ways. All of this is
+explained in the sections below.
-@item file-end
-If present, this should match the end of the file. All text after this
-regexp will be totally ignored.
+@menu
+* The NNDiary Back End:: Basic setup and usage.
+* The Gnus Diary Library:: Utility toolkit on top of nndiary.
+* Sending or Not Sending:: A final note on sending diary messages.
+@end menu
-@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:
+@node The NNDiary Back End
+@subsection The NNDiary Back End
+@cindex nndiary
+@cindex the nndiary back end
-@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.
+@code{nndiary} is a back end very similar to @code{nnml} (@pxref{Mail
+Spool}). Actually, it could appear as a mix of @code{nnml} and
+@code{nndraft}. If you know @code{nnml}, you're already familiar with
+the message storing scheme of @code{nndiary}: one file per message, one
+directory per group.
-@item article-transform-function
-If present, this function is called when requesting an article. It's
-meant to be used for more wide-ranging transformation of both head and
-body of the article.
+ Before anything, there is one requirement to be able to run
+@code{nndiary} properly: you @emph{must} use the group timestamp feature
+of Gnus. This adds a timestamp to each group's parameters. @ref{Group
+Timestamp} to see how it's done.
-@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.
+@menu
+* Diary Messages:: What makes a message valid for nndiary.
+* Running NNDiary:: NNDiary has two modes of operation.
+* Customizing NNDiary:: Bells and whistles.
+@end menu
-@item generate-article-function
-If present, this function is called to generate an entire article that
-Gnus can understand. It is called with the article number as a
-parameter when requesting all articles.
+@node Diary Messages
+@subsubsection Diary Messages
+@cindex nndiary messages
+@cindex nndiary mails
-@item dissection-function
-If present, this function is called to dissect a document by itself,
-overriding @code{first-article}, @code{article-begin},
-@code{article-begin-function}, @code{head-begin},
-@code{head-begin-function}, @code{head-end}, @code{body-begin},
-@code{body-begin-function}, @code{body-end}, @code{body-end-function},
-@code{file-begin}, and @code{file-end}.
+@code{nndiary} messages are just normal ones, except for the mandatory
+presence of 7 special headers. These headers are of the form
+@code{X-Diary-<something>}, @code{<something>} being one of
+@code{Minute}, @code{Hour}, @code{Dom}, @code{Month}, @code{Year},
+@code{Time-Zone} and @code{Dow}. @code{Dom} means ``Day of Month'', and
+@code{dow} means ``Day of Week''. These headers actually behave like
+crontab specifications and define the event date(s):
-@end table
+@itemize @bullet
+@item
+For all headers except the @code{Time-Zone} one, a header value is
+either a star (meaning all possible values), or a list of fields
+(separated by a comma).
+@item
+A field is either an integer, or a range.
+@item
+A range is two integers separated by a dash.
+@item
+Possible integer values are 0--59 for @code{Minute}, 0--23 for
+@code{Hour}, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971
+for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday).
+@item
+As a special case, a star in either @code{Dom} or @code{Dow} doesn't
+mean ``all possible values'', but ``use only the other field''. Note
+that if both are star'ed, the use of either one gives the same result.
+@item
+The @code{Time-Zone} header is special in that it can only have one
+value (@code{GMT}, for instance). A star doesn't mean ``all possible
+values'' (because it makes no sense), but ``the current local time
+zone''. Most of the time, you'll be using a star here. However, for a
+list of available time zone values, see the variable
+@code{nndiary-headers}.
+@end itemize
-Let's look at the most complicated example I can come up with---standard
-digests:
+As a concrete example, here are the diary headers to add to your message
+for specifying ``Each Monday and each 1st of month, at 12:00, 20:00,
+21:00, 22:00, 23:00 and 24:00, from 1999 to 2010'' (I'll let you find
+what to do then):
@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))
+X-Diary-Minute: 0
+X-Diary-Hour: 12, 20-24
+X-Diary-Dom: 1
+X-Diary-Month: *
+X-Diary-Year: 1999-2010
+X-Diary-Dow: 1
+X-Diary-Time-Zone: *
@end example
-We see that all text before a 70-width line of dashes is ignored; all
-text after a line that starts with that @samp{^End of} is also ignored;
-each article begins with a 30-width line of dashes; the line separating
-the head from the body may contain a single space; and that the body is
-run through @code{nndoc-unquote-dashes} before being delivered.
+@node Running NNDiary
+@subsubsection Running NNDiary
+@cindex running nndiary
+@cindex nndiary operation modes
-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-@var{type}-type-p} is called for a given type @var{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 valid number.
+@code{nndiary} has two modes of operation: ``traditional'' (the default)
+and ``autonomous''. In traditional mode, @code{nndiary} does not get new
+mail by itself. You have to move (@kbd{B m}) or copy (@kbd{B c}) mails
+from your primary mail back end to nndiary groups in order to handle them
+as diary messages. In autonomous mode, @code{nndiary} retrieves its own
+mail and handles it independently from your primary mail back end.
+
+One should note that Gnus is not inherently designed to allow several
+``master'' mail back ends at the same time. However, this does make
+sense with @code{nndiary}: you really want to send and receive diary
+messages to your diary groups directly. So, @code{nndiary} supports
+being sort of a ``second primary mail back end'' (to my knowledge, it is
+the only back end offering this feature). However, there is a limitation
+(which I hope to fix some day): respooling doesn't work in autonomous
+mode.
+In order to use @code{nndiary} in autonomous mode, you have several
+things to do:
-@node SOUP
-@subsection SOUP
-@cindex SOUP
-@cindex offline
+@itemize @bullet
+@item
+Allow @code{nndiary} to retrieve new mail by itself. Put the following
+line in your @file{~/.gnus.el} file:
+
+@lisp
+(setq nndiary-get-new-mail t)
+@end lisp
+@item
+You must arrange for diary messages (those containing @code{X-Diary-*}
+headers) to be split in a private folder @emph{before} Gnus treat them.
+Again, this is needed because Gnus cannot (yet ?) properly handle
+multiple primary mail back ends. Getting those messages from a separate
+source will compensate this misfeature to some extent.
+
+As an example, here's my procmailrc entry to store diary files in
+@file{~/.nndiary} (the default @code{nndiary} mail source file):
-In the PC world people often talk about ``offline'' newsreaders. These
-are thingies that are combined reader/news transport monstrosities.
-With built-in modem programs. Yecchh!
+@example
+:0 HD :
+* ^X-Diary
+.nndiary
+@end example
+@end itemize
+
+Once this is done, you might want to customize the following two options
+that affect the diary mail retrieval and splitting processes:
-Of course, us Unix Weenie types of human beans use things like
-@code{uucp} and, like, @code{nntpd} and set up proper news and mail
-transport things like Ghod intended. And then we just use normal
-newsreaders.
+@defvar nndiary-mail-sources
+This is the diary-specific replacement for the standard
+@code{mail-sources} variable. It obeys the same syntax, and defaults to
+@code{(file :path "~/.nndiary")}.
+@end defvar
-However, it can sometimes be convenient to do something that's a bit
-easier on the brain if you have a very slow modem, and you're not really
-that interested in doing things properly.
+@defvar nndiary-split-methods
+This is the diary-specific replacement for the standard
+@code{nnmail-split-methods} variable. It obeys the same syntax.
+@end defvar
-A file format called @sc{soup} has been developed for transporting news
-and mail from servers to home machines and back again. It can be a bit
-fiddly.
+ Finally, you may add a permanent @code{nndiary} virtual server
+(something like @code{(nndiary "diary")} should do) to your
+@code{gnus-secondary-select-methods}.
-First some terminology:
+ Hopefully, almost everything (see the TODO section in
+@file{nndiary.el}) will work as expected when you restart Gnus: in
+autonomous mode, typing @kbd{g} and @kbd{M-g} in the group buffer, will
+also get your new diary mails and split them according to your
+diary-specific rules, @kbd{F} will find your new diary groups etc.
-@table @dfn
+@node Customizing NNDiary
+@subsubsection Customizing NNDiary
+@cindex customizing nndiary
+@cindex nndiary customization
-@item server
-This is the machine that is connected to the outside world and where you
-get news and/or mail from.
+Now that @code{nndiary} is up and running, it's time to customize it.
+The custom group is called @code{nndiary} (no, really ?!). You should
+browse it to figure out which options you'd like to tweak. The following
+two variables are probably the only ones you will want to change:
-@item home machine
-This is the machine that you want to do the actual reading and responding
-on. It is typically not connected to the rest of the world in any way.
+@defvar nndiary-reminders
+This is the list of times when you want to be reminded of your
+appointments (e.g. 3 weeks before, then 2 days before, then 1 hour
+before and that's it). Remember that ``being reminded'' means that the
+diary message will pop up as brand new and unread again when you get new
+mail.
+@end defvar
-@item packet
-Something that contains messages and/or commands. There are two kinds
-of packets:
+@defvar nndiary-week-starts-on-monday
+Rather self-explanatory. Otherwise, Sunday is assumed (this is the
+default).
+@end defvar
-@table @dfn
-@item message packets
-These are packets made at the server, and typically contain lots of
-messages for you to read. These are called @file{SoupoutX.tgz} by
-default, where @var{x} is a number.
-@item response packets
-These are packets made at the home machine, and typically contains
-replies that you've written. These are called @file{SoupinX.tgz} by
-default, where @var{x} is a number.
+@node The Gnus Diary Library
+@subsection The Gnus Diary Library
+@cindex gnus-diary
+@cindex the gnus diary library
-@end table
+Using @code{nndiary} manually (I mean, writing the headers by hand and
+so on) would be rather boring. Fortunately, there is a library called
+@code{gnus-diary} written on top of @code{nndiary}, that does many
+useful things for you.
-@end table
+ In order to use it, add the following line to your @file{~/.gnus.el} file:
+@lisp
+(require 'gnus-diary)
+@end lisp
-@enumerate
+ Also, you shouldn't use any @code{gnus-user-format-function-[d|D]}
+(@pxref{Summary Buffer Lines}). @code{gnus-diary} provides both of these
+(sorry if you used them before).
-@item
-You log in on the server and create a @sc{soup} packet. You can either
-use a dedicated @sc{soup} thingie (like the @code{awk} program), or you
-can use Gnus to create the packet with its @sc{soup} commands (@kbd{O
-s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}).
-@item
-You transfer the packet home. Rail, boat, car or modem will do fine.
+@menu
+* Diary Summary Line Format:: A nicer summary buffer line format.
+* Diary Articles Sorting:: A nicer way to sort messages.
+* Diary Headers Generation:: Not doing it manually.
+* Diary Group Parameters:: Not handling them manually.
+@end menu
-@item
-You put the packet in your home directory.
+@node Diary Summary Line Format
+@subsubsection Diary Summary Line Format
+@cindex diary summary buffer line
+@cindex diary summary line format
-@item
-You fire up Gnus on your home machine using the @code{nnsoup} back end as
-the native or secondary server.
+Displaying diary messages in standard summary line format (usually
+something like @samp{From Joe: Subject}) is pretty useless. Most of
+the time, you're the one who wrote the message, and you mostly want to
+see the event's date.
-@item
-You read articles and mail and answer and followup to the things you
-want (@pxref{SOUP Replies}).
+ @code{gnus-diary} provides two supplemental user formats to be used in
+summary line formats. @code{D} corresponds to a formatted time string
+for the next occurrence of the event (e.g. ``Sat, Sep 22 01, 12:00''),
+while @code{d} corresponds to an approximative remaining time until the
+next occurrence of the event (e.g. ``in 6 months, 1 week'').
-@item
-You do the @kbd{G s r} command to pack these replies into a @sc{soup}
-packet.
+ For example, here's how Joe's birthday is displayed in my
+@code{nndiary+diary:birthdays} summary buffer (note that the message is
+expirable, but will never be deleted, as it specifies a periodic event):
-@item
-You transfer this packet to the server.
+@example
+ E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week)
+@end example
-@item
-You use Gnus to mail this packet out with the @kbd{G s s} command.
+In order to get something like the above, you would normally add the
+following line to your diary groups'parameters:
-@item
-You then repeat until you die.
+@lisp
+(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n")
+@end lisp
-@end enumerate
+However, @code{gnus-diary} does it automatically (@pxref{Diary Group
+Parameters}). You can however customize the provided summary line format
+with the following user options:
-So you basically have a bipartite system---you use @code{nnsoup} for
-reading and Gnus for packing/sending these @sc{soup} packets.
+@defvar gnus-diary-summary-line-format
+Defines the summary line format used for diary groups (@pxref{Summary
+Buffer Lines}). @code{gnus-diary} uses it to automatically update the
+diary groups'parameters.
+@end defvar
-@menu
-* SOUP Commands:: Commands for creating and sending @sc{soup} packets
-* SOUP Groups:: A back end for reading @sc{soup} packets.
-* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
-@end menu
+@defvar gnus-diary-time-format
+Defines the format to display dates in diary summary buffers. This is
+used by the @code{D} user format. See the docstring for details.
+@end defvar
+@defvar gnus-diary-delay-format-function
+Defines the format function to use for displaying delays (remaining
+times) in diary summary buffers. This is used by the @code{d} user
+format. There are currently built-in functions for English and French;
+you can also define your own. See the docstring for details.
+@end defvar
-@node SOUP Commands
-@subsubsection SOUP Commands
+@node Diary Articles Sorting
+@subsubsection Diary Articles Sorting
+@cindex diary articles sorting
+@cindex diary summary lines sorting
+@findex gnus-summary-sort-by-schedule
+@findex gnus-thread-sort-by-schedule
+@findex gnus-article-sort-by-schedule
-These are commands for creating and manipulating @sc{soup} packets.
+@code{gnus-diary} provides new sorting functions (@pxref{Sorting the
+Summary Buffer} ) called @code{gnus-summary-sort-by-schedule},
+@code{gnus-thread-sort-by-schedule} and
+@code{gnus-article-sort-by-schedule}. These functions let you organize
+your diary summary buffers from the closest event to the farthest one.
-@table @kbd
-@item G s b
-@kindex G s b (Group)
-@findex gnus-group-brew-soup
-Pack all unread articles in the current group
-(@code{gnus-group-brew-soup}). This command understands the
-process/prefix convention.
+@code{gnus-diary} automatically installs
+@code{gnus-summary-sort-by-schedule} as a menu item in the summary
+buffer's ``sort'' menu, and the two others as the primary (hence
+default) sorting functions in the group parameters (@pxref{Diary Group
+Parameters}).
-@item G s w
-@kindex G s w (Group)
-@findex gnus-soup-save-areas
-Save all @sc{soup} data files (@code{gnus-soup-save-areas}).
-
-@item G s s
-@kindex G s s (Group)
-@findex gnus-soup-send-replies
-Send all replies from the replies packet
-(@code{gnus-soup-send-replies}).
-
-@item G s p
-@kindex G s p (Group)
-@findex gnus-soup-pack-packet
-Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
-
-@item G s r
-@kindex G s r (Group)
-@findex nnsoup-pack-replies
-Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
-
-@item O s
-@kindex O s (Summary)
-@findex gnus-soup-add-article
-This summary-mode command adds the current article to a @sc{soup} packet
-(@code{gnus-soup-add-article}). It understands the process/prefix
-convention (@pxref{Process/Prefix}).
+@node Diary Headers Generation
+@subsubsection Diary Headers Generation
+@cindex diary headers generation
+@findex gnus-diary-check-message
-@end table
+@code{gnus-diary} provides a function called
+@code{gnus-diary-check-message} to help you handle the @code{X-Diary-*}
+headers. This function ensures that the current message contains all the
+required diary headers, and prompts you for values or corrections if
+needed.
+ This function is hooked into the @code{nndiary} back end, so that
+moving or copying an article to a diary group will trigger it
+automatically. It is also bound to @kbd{C-c C-f d} in
+@code{message-mode} and @code{article-edit-mode} in order to ease the
+process of converting a usual mail to a diary one.
-There are a few variables to customize where Gnus will put all these
-thingies:
+ This function takes a prefix argument which will force prompting of
+all diary headers, regardless of their presence or validity. That way,
+you can very easily reschedule an already valid diary message, for
+instance.
-@table @code
+@node Diary Group Parameters
+@subsubsection Diary Group Parameters
+@cindex diary group parameters
-@item gnus-soup-directory
-@vindex gnus-soup-directory
-Directory where Gnus will save intermediate files while composing
-@sc{soup} packets. The default is @file{~/SoupBrew/}.
+When you create a new diary group, or visit one, @code{gnus-diary}
+automatically checks your group parameters and if needed, sets the
+summary line format to the diary-specific value, installs the
+diary-specific sorting functions, and also adds the different
+@code{X-Diary-*} headers to the group's posting-style. It is then easier
+to send a diary message, because if you use @kbd{C-u a} or @kbd{C-u m}
+on a diary group to prepare a message, these headers will be inserted
+automatically (although not filled with proper values yet).
-@item gnus-soup-replies-directory
-@vindex gnus-soup-replies-directory
-This is what Gnus will use as a temporary directory while sending our
-reply packets. @file{~/SoupBrew/SoupReplies/} is the default.
+@node Sending or Not Sending
+@subsection Sending or Not Sending
-@item gnus-soup-prefix-file
-@vindex gnus-soup-prefix-file
-Name of the file where Gnus stores the last used prefix. The default is
-@samp{gnus-prefix}.
+Well, assuming you've read all of the above, here are two final notes on
+mail sending with @code{nndiary}:
-@item gnus-soup-packer
-@vindex gnus-soup-packer
-A format string command for packing a @sc{soup} packet. The default is
-@samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
+@itemize @bullet
+@item
+@code{nndiary} is a @emph{real} mail back end. You really send real diary
+messsages for real. This means for instance that you can give
+appointments to anybody (provided they use Gnus and @code{nndiary}) by
+sending the diary message to them as well.
+@item
+However, since @code{nndiary} also has a @code{request-post} method, you
+can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the
+message won't actually be sent; just stored locally in the group. This
+comes in very handy for private appointments.
+@end itemize
-@item gnus-soup-unpacker
-@vindex gnus-soup-unpacker
-Format string command for unpacking a @sc{soup} packet. The default is
-@samp{gunzip -c %s | tar xvf -}.
+@node Gnus Unplugged
+@section Gnus Unplugged
+@cindex offline
+@cindex unplugged
+@cindex agent
+@cindex Gnus agent
+@cindex Gnus unplugged
-@item gnus-soup-packet-directory
-@vindex gnus-soup-packet-directory
-Where Gnus will look for reply packets. The default is @file{~/}.
+In olden times (ca. February '88), people used to run their newsreaders
+on big machines with permanent connections to the net. News transport
+was dealt with by news servers, and all the newsreaders had to do was to
+read news. Believe it or not.
-@item gnus-soup-packet-regexp
-@vindex gnus-soup-packet-regexp
-Regular expression matching @sc{soup} reply packets in
-@code{gnus-soup-packet-directory}.
+Nowadays most people read news and mail at home, and use some sort of
+modem to connect to the net. To avoid running up huge phone bills, it
+would be nice to have a way to slurp down all the news and mail, hang up
+the phone, read for several hours, and then upload any responses you
+have to make. And then you repeat the procedure.
-@end table
+Of course, you can use news servers for doing this as well. I've used
+@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail}
+for some years, but doing that's a bore. Moving the news server
+functionality up to the newsreader makes sense if you're the only person
+reading news on a machine.
+Setting up Gnus as an ``offline'' newsreader is quite simple. In
+fact, you don't have to configure anything as the agent is now enabled
+by default (@pxref{Agent Variables, gnus-agent}).
-@node SOUP Groups
-@subsubsection SOUP Groups
-@cindex nnsoup
+Of course, to use it as such, you have to learn a few new commands.
-@code{nnsoup} is the back end for reading @sc{soup} packets. It will
-read incoming packets, unpack them, and put them in a directory where
-you can read them at leisure.
+@menu
+* Agent Basics:: How it all is supposed to work.
+* Agent Categories:: How to tell the Gnus Agent what to download.
+* Agent Commands:: New commands for all the buffers.
+* Agent Visuals:: Ways that the agent may effect your summary buffer.
+* Agent as Cache:: The Agent is a big cache too.
+* Agent Expiry:: How to make old articles go away.
+* Agent Regeneration:: How to recover from lost connections and other accidents.
+* Agent and flags:: How the Agent maintains flags.
+* Agent and IMAP:: How to use the Agent with @acronym{IMAP}.
+* Outgoing Messages:: What happens when you post/mail something?
+* Agent Variables:: Customizing is fun.
+* Example Setup:: An example @file{~/.gnus.el} file for offline people.
+* Batching Agents:: How to fetch news from a @code{cron} job.
+* Agent Caveats:: What you think it'll do and what it does.
+@end menu
-These are the variables you can use to customize its behavior:
-@table @code
+@node Agent Basics
+@subsection Agent Basics
-@item nnsoup-tmp-directory
-@vindex nnsoup-tmp-directory
-When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
-directory. (@file{/tmp/} by default.)
+First, let's get some terminology out of the way.
-@item nnsoup-directory
-@vindex nnsoup-directory
-@code{nnsoup} then moves each message and index file to this directory.
-The default is @file{~/SOUP/}.
+The Gnus Agent is said to be @dfn{unplugged} when you have severed the
+connection to the net (and notified the Agent that this is the case).
+When the connection to the net is up again (and Gnus knows this), the
+Agent is @dfn{plugged}.
-@item nnsoup-replies-directory
-@vindex nnsoup-replies-directory
-All replies will be stored in this directory before being packed into a
-reply packet. The default is @file{~/SOUP/replies/}.
+The @dfn{local} machine is the one you're running on, and which isn't
+connected to the net continuously.
-@item nnsoup-replies-format-type
-@vindex nnsoup-replies-format-type
-The @sc{soup} format of the replies packets. The default is @samp{?n}
-(rnews), and I don't think you should touch that variable. I probably
-shouldn't even have documented it. Drats! Too late!
+@dfn{Downloading} means fetching things from the net to your local
+machine. @dfn{Uploading} is doing the opposite.
-@item nnsoup-replies-index-type
-@vindex nnsoup-replies-index-type
-The index type of the replies packet. The default is @samp{?n}, which
-means ``none''. Don't fiddle with this one either!
+You know that Gnus gives you all the opportunity you'd ever want for
+shooting yourself in the foot. Some people call it flexibility. Gnus
+is also customizable to a great extent, which means that the user has a
+say on how Gnus behaves. Other newsreaders might unconditionally shoot
+you in your foot, but with Gnus, you have a choice!
-@item nnsoup-active-file
-@vindex nnsoup-active-file
-Where @code{nnsoup} stores lots of information. This is not an ``active
-file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
-this file or mess it up in any way, you're dead. The default is
-@file{~/SOUP/active}.
+Gnus is never really in plugged or unplugged state. Rather, it applies
+that state to each server individually. This means that some servers
+can be plugged while others can be unplugged. Additionally, some
+servers can be ignored by the Agent altogether (which means that
+they're kinda like plugged always).
-@item nnsoup-packer
-@vindex nnsoup-packer
-Format string command for packing a reply @sc{soup} packet. The default
-is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
+So when you unplug the Agent and then wonder why is Gnus opening a
+connection to the Net, the next step to do is to look whether all
+servers are agentized. If there is an unagentized server, you found
+the culprit.
-@item nnsoup-unpacker
-@vindex nnsoup-unpacker
-Format string command for unpacking incoming @sc{soup} packets. The
-default is @samp{gunzip -c %s | tar xvf -}.
+Another thing is the @dfn{offline} state. Sometimes, servers aren't
+reachable. When Gnus notices this, it asks you whether you want the
+server to be switched to offline state. If you say yes, then the
+server will behave somewhat as if it was unplugged, except that Gnus
+will ask you whether you want to switch it back online again.
-@item nnsoup-packet-directory
-@vindex nnsoup-packet-directory
-Where @code{nnsoup} will look for incoming packets. The default is
-@file{~/}.
+Let's take a typical Gnus session using the Agent.
-@item nnsoup-packet-regexp
-@vindex nnsoup-packet-regexp
-Regular expression matching incoming @sc{soup} packets. The default is
-@samp{Soupout}.
+@itemize @bullet
-@item nnsoup-always-save
-@vindex nnsoup-always-save
-If non-@code{nil}, save the replies buffer after each posted message.
+@item
+@findex gnus-unplugged
+You start Gnus with @code{gnus-unplugged}. This brings up the Gnus
+Agent in a disconnected state. You can read all the news that you have
+already fetched while in this mode.
-@end table
+@item
+You then decide to see whether any new news has arrived. You connect
+your machine to the net (using PPP or whatever), and then hit @kbd{J j}
+to make Gnus become @dfn{plugged} and use @kbd{g} to check for new mail
+as usual. To check for new mail in unplugged mode (@pxref{Mail
+Source Specifiers}).
+@item
+You can then read the new news immediately, or you can download the
+news onto your local machine. If you want to do the latter, you press
+@kbd{g} to check if there are any new news and then @kbd{J s} to fetch
+all the eligible articles in all the groups. (To let Gnus know which
+articles you want to download, @pxref{Agent Categories}).
-@node SOUP Replies
-@subsubsection SOUP Replies
+@item
+After fetching the articles, you press @kbd{J j} to make Gnus become
+unplugged again, and you shut down the PPP thing (or whatever). And
+then you read the news offline.
-Just using @code{nnsoup} won't mean that your postings and mailings end
-up in @sc{soup} reply packets automagically. You have to work a bit
-more for that to happen.
+@item
+And then you go to step 2.
+@end itemize
-@findex nnsoup-set-variables
-The @code{nnsoup-set-variables} command will set the appropriate
-variables to ensure that all your followups and replies end up in the
-@sc{soup} system.
+Here are some things you should do the first time (or so) that you use
+the Agent.
-In specific, this is what it does:
+@itemize @bullet
-@lisp
-(setq message-send-news-function 'nnsoup-request-post)
-(setq message-send-mail-function 'nnsoup-request-mail)
-@end lisp
+@item
+Decide which servers should be covered by the Agent. If you have a mail
+back end, it would probably be nonsensical to have it covered by the
+Agent. Go to the server buffer (@kbd{^} in the group buffer) and press
+@kbd{J a} on the server (or servers) that you wish to have covered by the
+Agent (@pxref{Server Agent Commands}), or @kbd{J r} on automatically
+added servers you do not wish to have covered by the Agent. By default,
+all @code{nntp} and @code{nnimap} servers in @code{gnus-select-method} and
+@code{gnus-secondary-select-methods} are agentized.
-And that's it, really. If you only want news to go into the @sc{soup}
-system you just use the first line. If you only want mail to be
-@sc{soup}ed you use the second.
+@item
+Decide on download policy. It's fairly simple once you decide whether
+you are going to use agent categories, topic parameters, and/or group
+parameters to implement your policy. If you're new to gnus, it
+is probably best to start with a category, @xref{Agent Categories}.
+Both topic parameters (@pxref{Topic Parameters}) and agent categories
+(@pxref{Agent Categories}) provide for setting a policy that applies
+to multiple groups. Which you use is entirely up to you. Topic
+parameters do override categories so, if you mix the two, you'll have
+to take that into account. If you have a few groups that deviate from
+your policy, you can use group parameters (@pxref{Group Parameters}) to
+configure them.
-@node Mail-To-News Gateways
-@subsection Mail-To-News Gateways
-@cindex mail-to-news gateways
-@cindex gateways
+@item
+Uhm@dots{} that's it.
+@end itemize
-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} back end provides the interface.
-Note that you can't read anything from this back end---it can only be
-used to post with.
+@node Agent Categories
+@subsection Agent Categories
-Server variables:
+One of the main reasons to integrate the news transport layer into the
+newsreader is to allow greater control over what articles to download.
+There's not much point in downloading huge amounts of articles, just to
+find out that you're not interested in reading any of them. It's better
+to be somewhat more conservative in choosing what to download, and then
+mark the articles for downloading manually if it should turn out that
+you're interested in the articles anyway.
-@table @code
-@item nngateway-address
-@vindex nngateway-address
-This is the address of the mail-to-news gateway.
+One of the more effective methods for controlling what is to be
+downloaded is to create a @dfn{category} and then assign some (or all)
+groups to this category. Groups that do not belong in any other
+category belong to the @code{default} category. Gnus has its own
+buffer for creating and managing categories.
-@item nngateway-header-transformation
-@vindex nngateway-header-transformation
-News headers 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.
+If you prefer, you can also use group parameters (@pxref{Group
+Parameters}) and topic parameters (@pxref{Topic Parameters}) for an
+alternative approach to controlling the agent. The only real
+difference is that categories are specific to the agent (so there is
+less to learn) while group and topic parameters include the kitchen
+sink.
-This default function just inserts a new @code{To} header based on the
-@code{Newsgroups} header and the gateway address.
-For instance, an article with this @code{Newsgroups} header:
+Since you can set agent parameters in several different places we have
+a rule to decide which source to believe. This rule specifies that
+the parameter sources are checked in the following order: group
+parameters, topic parameters, agent category, and finally customizable
+variables. So you can mix all of these sources to produce a wide range
+of behavior, just don't blame me if you don't remember where you put
+your settings.
-@example
-Newsgroups: alt.religion.emacs
-@end example
+@menu
+* Category Syntax:: What a category looks like.
+* Category Buffer:: A buffer for maintaining categories.
+* Category Variables:: Customize'r'Us.
+@end menu
-will get this @code{To} header inserted:
-@example
-To: alt-religion-emacs@@GATEWAY
-@end example
+@node Category Syntax
+@subsubsection Category Syntax
-The following pre-defined functions exist:
+A category consists of a name, the list of groups belonging to the
+category, and a number of optional parameters that override the
+customizable variables. The complete list of agent parameters are
+listed below.
-@findex nngateway-simple-header-transformation
+@cindex Agent Parameters
@table @code
+@item agent-groups
+The list of groups that are in this category.
-@item nngateway-simple-header-transformation
-Creates a @code{To} header that looks like
-@var{newsgroup}@@@code{nngateway-address}.
-
-@findex nngateway-mail2news-header-transformation
+@item agent-predicate
+A predicate which (generally) gives a rough outline of which articles
+are eligible for downloading; and
-@item nngateway-mail2news-header-transformation
-Creates a @code{To} header that looks like
-@code{nngateway-address}.
-@end table
+@item agent-score
+a score rule which (generally) gives you a finer granularity when
+deciding what articles to download. (Note that this @dfn{download
+score} is not necessarily related to normal scores.)
-@end table
+@item agent-enable-expiration
+a boolean indicating whether the agent should expire old articles in
+this group. Most groups should be expired to conserve disk space. In
+fact, its probably safe to say that the gnus.* hierarchy contains the
+only groups that should not be expired.
-Here's an example:
+@item agent-days-until-old
+an integer indicating the number of days that the agent should wait
+before deciding that a read article is safe to expire.
-@lisp
-(setq gnus-post-method
- '(nngateway
- "mail2news@@replay.com"
- (nngateway-header-transformation
- nngateway-mail2news-header-transformation)))
-@end lisp
+@item agent-low-score
+an integer that overrides the value of @code{gnus-agent-low-score}.
-So, to use this, simply say something like:
+@item agent-high-score
+an integer that overrides the value of @code{gnus-agent-high-score}.
-@lisp
-(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
-@end lisp
+@item agent-short-article
+an integer that overrides the value of
+@code{gnus-agent-short-article}.
+@item agent-long-article
+an integer that overrides the value of @code{gnus-agent-long-article}.
+@item agent-enable-undownloaded-faces
+a symbol indicating whether the summary buffer should display
+undownloaded articles using the @code{gnus-summary-*-undownloaded-face}
+faces. Any symbol other than @code{nil} will enable the use of
+undownloaded faces.
+@end table
-@node Combined Groups
-@section Combined Groups
+The name of a category can not be changed once the category has been
+created.
-Gnus allows combining a mixture of all the other group types into bigger
-groups.
+Each category maintains a list of groups that are exclusive members of
+that category. The exclusivity rule is automatically enforced, add a
+group to a new category and it is automatically removed from its old
+category.
-@menu
-* Virtual Groups:: Combining articles from many groups.
-* Kibozed Groups:: Looking through parts of the newsfeed for articles.
-@end menu
+A predicate in its simplest form can be a single predicate such as
+@code{true} or @code{false}. These two will download every available
+article or nothing respectively. In the case of these two special
+predicates an additional score rule is superfluous.
+Predicates of @code{high} or @code{low} download articles in respect of
+their scores in relationship to @code{gnus-agent-high-score} and
+@code{gnus-agent-low-score} as described below.
-@node Virtual Groups
-@subsection Virtual Groups
-@cindex nnvirtual
-@cindex virtual groups
-@cindex merging groups
+To gain even finer control of what is to be regarded eligible for
+download a predicate can consist of a number of predicates with logical
+operators sprinkled in between.
-An @dfn{nnvirtual group} is really nothing more than a collection of
-other groups.
+Perhaps some examples are in order.
-For instance, if you are tired of reading many small groups, you can
-put them all in one big group, and then grow tired of reading one
-big, unwieldy group. The joys of computing!
+Here's a simple predicate. (It's the default predicate, in fact, used
+for all groups that don't belong to any other category.)
-You specify @code{nnvirtual} as the method. The address should be a
-regexp to match component groups.
+@lisp
+short
+@end lisp
-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.). To create an empty virtual group, run
-@kbd{G V} (@code{gnus-group-make-empty-virtual}) in the group buffer
-and edit the method regexp with @kbd{M-e}
-(@code{gnus-group-edit-group-method})
+Quite simple, eh? This predicate is true if and only if the article is
+short (for some value of ``short'').
-Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
-newsgroups into one, big, happy newsgroup:
+Here's a more complex predicate:
@lisp
-(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
+(or high
+ (and
+ (not low)
+ (not long)))
@end lisp
-The component groups can be native or foreign; everything should work
-smoothly, but if your computer explodes, it was probably my fault.
-
-Collecting the same group from several servers might actually be a good
-idea if users have set the Distribution header to limit distribution.
-If you would like to read @samp{soc.motss} both from a server in Japan
-and a server in Norway, you could use the following as the group regexp:
+This means that an article should be downloaded if it has a high score,
+or if the score is not low and the article is not long. You get the
+drift.
-@example
-"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$"
-@end example
+The available logical operators are @code{or}, @code{and} and
+@code{not}. (If you prefer, you can use the more ``C''-ish operators
+@samp{|}, @code{&} and @code{!} instead.)
-(Remember, though, that if you're creating the group with @kbd{G m}, you
-shouldn't double the backslashes, and you should leave off the quote
-characters at the beginning and the end of the string.)
+The following predicates are pre-defined, but if none of these fit what
+you want to do, you can write your own.
-This should work kinda smoothly---all articles from both groups should
-end up in this one, and there should be no duplicates. Threading (and
-the rest) will still work as usual, but there might be problems with the
-sequence of articles. Sorting on date might be an option here
-(@pxref{Selecting a Group}).
+When evaluating each of these predicates, the named constant will be
+bound to the value determined by calling
+@code{gnus-agent-find-parameter} on the appropriate parameter. For
+example, gnus-agent-short-article will be bound to
+@code{(gnus-agent-find-parameter group 'agent-short-article)}. This
+means that you can specify a predicate in your category then tune that
+predicate to individual groups.
-One limitation, however---all groups included in a virtual
-group have to be alive (i.e., subscribed or unsubscribed). Killed or
-zombie groups can't be component groups for @code{nnvirtual} groups.
+@table @code
+@item short
+True if the article is shorter than @code{gnus-agent-short-article}
+lines; default 100.
-@vindex nnvirtual-always-rescan
-If the @code{nnvirtual-always-rescan} variable is non-@code{nil} (which
-is the default), @code{nnvirtual} will always scan groups for unread
-articles when entering a virtual group. If this variable is @code{nil}
-and you read articles in a component group after the virtual group has
-been activated, the read articles from the component group will show up
-when you enter the virtual group. You'll also see this effect if you
-have two virtual groups that have a component group in common. If
-that's the case, you should set this variable to @code{t}. Or you can
-just tap @code{M-g} on the virtual group every time before you enter
-it---it'll have much the same effect.
+@item long
+True if the article is longer than @code{gnus-agent-long-article}
+lines; default 200.
-@code{nnvirtual} can have both mail and news groups as component groups.
-When responding to articles in @code{nnvirtual} groups, @code{nnvirtual}
-has to ask the back end of the component group the article comes from
-whether it is a news or mail back end. However, when you do a @kbd{^},
-there is typically no sure way for the component back end to know this,
-and in that case @code{nnvirtual} tells Gnus that the article came from a
-not-news back end. (Just to be on the safe side.)
+@item low
+True if the article has a download score less than
+@code{gnus-agent-low-score}; default 0.
-@kbd{C-c C-n} in the message buffer will insert the @code{Newsgroups}
-line from the article you respond to in these cases.
+@item high
+True if the article has a download score greater than
+@code{gnus-agent-high-score}; default 0.
-@code{nnvirtual} groups do not inherit anything but articles and marks
-from component groups---group parameters, for instance, are not
-inherited.
+@item spam
+True if the Gnus Agent guesses that the article is spam. The
+heuristics may change over time, but at present it just computes a
+checksum and sees whether articles match.
+@item true
+Always true.
-@node Kibozed Groups
-@subsection Kibozed Groups
-@cindex nnkiboze
-@cindex kibozing
+@item false
+Always false.
+@end table
-@dfn{Kibozing} is defined by the @acronym{OED} as ``grepping through
-(parts of) the news feed''. @code{nnkiboze} is a back end that will
-do this for you. Oh joy! Now you can grind any @acronym{NNTP} server
-down to a halt with useless requests! Oh happiness!
+If you want to create your own predicate function, here's what you have
+to know: The functions are called with no parameters, but the
+@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to
+useful values.
-@kindex G k (Group)
-To create a kibozed group, use the @kbd{G k} command in the group
-buffer.
+For example, you could decide that you don't want to download articles
+that were posted more than a certain number of days ago (e.g. posted
+more than @code{gnus-agent-expire-days} ago) you might write a function
+something along the lines of the following:
-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. That's where most similarities between
-@code{nnkiboze} and @code{nnvirtual} end.
+@lisp
+(defun my-article-old-p ()
+ "Say whether an article is old."
+ (< (time-to-days (date-to-time (mail-header-date gnus-headers)))
+ (- (time-to-days (current-time)) gnus-agent-expire-days)))
+@end lisp
-In addition to this regexp detailing component groups, an
-@code{nnkiboze} group must have a score file to say what articles are
-to be included in the group (@pxref{Scoring}).
+with the predicate then defined as:
-@kindex M-x nnkiboze-generate-groups
-@findex nnkiboze-generate-groups
-You must run @kbd{M-x nnkiboze-generate-groups} after creating the
-@code{nnkiboze} groups you want to have. This command will take time.
-Lots of time. Oodles and oodles of time. Gnus has to fetch the
-headers from all the articles in all the component groups and run them
-through the scoring process to determine if there are any articles in
-the groups that are to be part of the @code{nnkiboze} groups.
+@lisp
+(not my-article-old-p)
+@end lisp
-Please limit the number of component groups by using restrictive
-regexps. Otherwise your sysadmin may become annoyed with you, and the
-@acronym{NNTP} site may throw you off and never let you back in again.
-Stranger things have happened.
+or you could append your predicate to the predefined
+@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or
+wherever.
-@code{nnkiboze} component groups do not have to be alive---they can be dead,
-and they can be foreign. No restrictions.
+@lisp
+(require 'gnus-agent)
+(setq gnus-category-predicate-alist
+ (append gnus-category-predicate-alist
+ '((old . my-article-old-p))))
+@end lisp
-@vindex nnkiboze-directory
-The generation of an @code{nnkiboze} group means writing two files in
-@code{nnkiboze-directory}, which is @file{~/News/kiboze/} by default.
-One contains the @acronym{NOV} header lines for all the articles in
-the group, and the other is an additional @file{.newsrc} file to store
-information on what groups have been searched through to find
-component articles.
+and simply specify your predicate as:
-Articles marked as read in the @code{nnkiboze} group will have
-their @acronym{NOV} lines removed from the @acronym{NOV} file.
+@lisp
+(not old)
+@end lisp
+If/when using something like the above, be aware that there are many
+misconfigured systems/mailers out there and so an article's date is not
+always a reliable indication of when it was posted. Hell, some people
+just don't give a damn.
-@node Email Based Diary
-@section Email Based Diary
-@cindex diary
-@cindex email based diary
-@cindex calendar
+The above predicates apply to @emph{all} the groups which belong to the
+category. However, if you wish to have a specific predicate for an
+individual group within a category, or you're just too lazy to set up a
+new category, you can enter a group's individual predicate in its group
+parameters like so:
-This section describes a special mail back end called @code{nndiary},
-and its companion library @code{gnus-diary}. It is ``special'' in the
-sense that it is not meant to be one of the standard alternatives for
-reading mail with Gnus. See @ref{Choosing a Mail Back End} for that.
-Instead, it is used to treat @emph{some} of your mails in a special way,
-namely, as event reminders.
+@lisp
+(agent-predicate . short)
+@end lisp
-Here is a typical scenario:
+This is the group/topic parameter equivalent of the agent category default.
+Note that when specifying a single word predicate like this, the
+@code{agent-predicate} specification must be in dotted pair notation.
-@itemize @bullet
-@item
-You've got a date with Andy Mc Dowell or Bruce Willis (select according
-to your sexual preference) in one month. You don't want to forget it.
-@item
-So you send a ``reminder'' message (actually, a diary one) to yourself.
-@item
-You forget all about it and keep on getting and reading new mail, as usual.
-@item
-From time to time, as you type `g' in the group buffer and as the date
-is getting closer, the message will pop up again to remind you of your
-appointment, just as if it were new and unread.
-@item
-Read your ``new'' messages, this one included, and start dreaming again
-of the night you're gonna have.
-@item
-Once the date is over (you actually fell asleep just after dinner), the
-message will be automatically deleted if it is marked as expirable.
-@end itemize
+The equivalent of the longer example from above would be:
-The Gnus Diary back end has the ability to handle regular appointments
-(that wouldn't ever be deleted) as well as punctual ones, operates as a
-real mail back end and is configurable in many ways. All of this is
-explained in the sections below.
+@lisp
+(agent-predicate or high (and (not low) (not long)))
+@end lisp
-@menu
-* The NNDiary Back End:: Basic setup and usage.
-* The Gnus Diary Library:: Utility toolkit on top of nndiary.
-* Sending or Not Sending:: A final note on sending diary messages.
-@end menu
+The outer parenthesis required in the category specification are not
+entered here as, not being in dotted pair notation, the value of the
+predicate is assumed to be a list.
-@node The NNDiary Back End
-@subsection The NNDiary Back End
-@cindex nndiary
-@cindex the nndiary back end
+Now, the syntax of the download score is the same as the syntax of
+normal score files, except that all elements that require actually
+seeing the article itself are verboten. This means that only the
+following headers can be scored on: @code{Subject}, @code{From},
+@code{Date}, @code{Message-ID}, @code{References}, @code{Chars},
+@code{Lines}, and @code{Xref}.
-@code{nndiary} is a back end very similar to @code{nnml} (@pxref{Mail
-Spool}). Actually, it could appear as a mix of @code{nnml} and
-@code{nndraft}. If you know @code{nnml}, you're already familiar with
-the message storing scheme of @code{nndiary}: one file per message, one
-directory per group.
+As with predicates, the specification of the @code{download score rule}
+to use in respect of a group can be in either the category definition if
+it's to be applicable to all groups in therein, or a group's parameters
+if it's to be specific to that group.
- Before anything, there is one requirement to be able to run
-@code{nndiary} properly: you @emph{must} use the group timestamp feature
-of Gnus. This adds a timestamp to each group's parameters. @ref{Group
-Timestamp} to see how it's done.
+In both of these places the @code{download score rule} can take one of
+three forms:
-@menu
-* Diary Messages:: What makes a message valid for nndiary.
-* Running NNDiary:: NNDiary has two modes of operation.
-* Customizing NNDiary:: Bells and whistles.
-@end menu
+@enumerate
+@item
+Score rule
-@node Diary Messages
-@subsubsection Diary Messages
-@cindex nndiary messages
-@cindex nndiary mails
+This has the same syntax as a normal Gnus score file except only a
+subset of scoring keywords are available as mentioned above.
-@code{nndiary} messages are just normal ones, except for the mandatory
-presence of 7 special headers. These headers are of the form
-@code{X-Diary-<something>}, @code{<something>} being one of
-@code{Minute}, @code{Hour}, @code{Dom}, @code{Month}, @code{Year},
-@code{Time-Zone} and @code{Dow}. @code{Dom} means ``Day of Month'', and
-@code{dow} means ``Day of Week''. These headers actually behave like
-crontab specifications and define the event date(s):
+example:
@itemize @bullet
@item
-For all headers except the @code{Time-Zone} one, a header value is
-either a star (meaning all possible values), or a list of fields
-(separated by a comma).
-@item
-A field is either an integer, or a range.
-@item
-A range is two integers separated by a dash.
-@item
-Possible integer values are 0--59 for @code{Minute}, 0--23 for
-@code{Hour}, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971
-for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday).
-@item
-As a special case, a star in either @code{Dom} or @code{Dow} doesn't
-mean ``all possible values'', but ``use only the other field''. Note
-that if both are star'ed, the use of either one gives the same result.
-@item
-The @code{Time-Zone} header is special in that it can only have one
-value (@code{GMT}, for instance). A star doesn't mean ``all possible
-values'' (because it makes no sense), but ``the current local time
-zone''. Most of the time, you'll be using a star here. However, for a
-list of available time zone values, see the variable
-@code{nndiary-headers}.
-@end itemize
-
-As a concrete example, here are the diary headers to add to your message
-for specifying ``Each Monday and each 1st of month, at 12:00, 20:00,
-21:00, 22:00, 23:00 and 24:00, from 1999 to 2010'' (I'll let you find
-what to do then):
+Category specification
-@example
-X-Diary-Minute: 0
-X-Diary-Hour: 12, 20-24
-X-Diary-Dom: 1
-X-Diary-Month: *
-X-Diary-Year: 1999-2010
-X-Diary-Dow: 1
-X-Diary-Time-Zone: *
-@end example
+@lisp
+(("from"
+ ("Lars Ingebrigtsen" 1000000 nil s))
+("lines"
+ (500 -100 nil <)))
+@end lisp
-@node Running NNDiary
-@subsubsection Running NNDiary
-@cindex running nndiary
-@cindex nndiary operation modes
+@item
+Group/Topic Parameter specification
-@code{nndiary} has two modes of operation: ``traditional'' (the default)
-and ``autonomous''. In traditional mode, @code{nndiary} does not get new
-mail by itself. You have to move (@kbd{B m}) or copy (@kbd{B c}) mails
-from your primary mail back end to nndiary groups in order to handle them
-as diary messages. In autonomous mode, @code{nndiary} retrieves its own
-mail and handles it independently from your primary mail back end.
+@lisp
+(agent-score ("from"
+ ("Lars Ingebrigtsen" 1000000 nil s))
+ ("lines"
+ (500 -100 nil <)))
+@end lisp
-One should note that Gnus is not inherently designed to allow several
-``master'' mail back ends at the same time. However, this does make
-sense with @code{nndiary}: you really want to send and receive diary
-messages to your diary groups directly. So, @code{nndiary} supports
-being sort of a ``second primary mail back end'' (to my knowledge, it is
-the only back end offering this feature). However, there is a limitation
-(which I hope to fix some day): respooling doesn't work in autonomous
-mode.
+Again, note the omission of the outermost parenthesis here.
+@end itemize
-In order to use @code{nndiary} in autonomous mode, you have several
-things to do:
+@item
+Agent score file
+
+These score files must @emph{only} contain the permitted scoring
+keywords stated above.
+
+example:
@itemize @bullet
@item
-Allow @code{nndiary} to retrieve new mail by itself. Put the following
-line in your @file{~/.gnus.el} file:
+Category specification
@lisp
-(setq nndiary-get-new-mail t)
+("~/News/agent.SCORE")
@end lisp
+
+or perhaps
+
+@lisp
+("~/News/agent.SCORE" "~/News/agent.group.SCORE")
+@end lisp
+
@item
-You must arrange for diary messages (those containing @code{X-Diary-*}
-headers) to be split in a private folder @emph{before} Gnus treat them.
-Again, this is needed because Gnus cannot (yet ?) properly handle
-multiple primary mail back ends. Getting those messages from a separate
-source will compensate this misfeature to some extent.
+Group Parameter specification
-As an example, here's my procmailrc entry to store diary files in
-@file{~/.nndiary} (the default @code{nndiary} mail source file):
+@lisp
+(agent-score "~/News/agent.SCORE")
+@end lisp
-@example
-:0 HD :
-* ^X-Diary
-.nndiary
-@end example
+Additional score files can be specified as above. Need I say anything
+about parenthesis?
@end itemize
-Once this is done, you might want to customize the following two options
-that affect the diary mail retrieval and splitting processes:
+@item
+Use @code{normal} score files
-@defvar nndiary-mail-sources
-This is the diary-specific replacement for the standard
-@code{mail-sources} variable. It obeys the same syntax, and defaults to
-@code{(file :path "~/.nndiary")}.
-@end defvar
+If you don't want to maintain two sets of scoring rules for a group, and
+your desired @code{downloading} criteria for a group are the same as your
+@code{reading} criteria then you can tell the agent to refer to your
+@code{normal} score files when deciding what to download.
-@defvar nndiary-split-methods
-This is the diary-specific replacement for the standard
-@code{nnmail-split-methods} variable. It obeys the same syntax.
-@end defvar
+These directives in either the category definition or a group's
+parameters will cause the agent to read in all the applicable score
+files for a group, @emph{filtering out} those sections that do not
+relate to one of the permitted subset of scoring keywords.
- Finally, you may add a permanent @code{nndiary} virtual server
-(something like @code{(nndiary "diary")} should do) to your
-@code{gnus-secondary-select-methods}.
+@itemize @bullet
+@item
+Category Specification
- Hopefully, almost everything (see the TODO section in
-@file{nndiary.el}) will work as expected when you restart Gnus: in
-autonomous mode, typing @kbd{g} and @kbd{M-g} in the group buffer, will
-also get your new diary mails and split them according to your
-diary-specific rules, @kbd{F} will find your new diary groups etc.
+@lisp
+file
+@end lisp
-@node Customizing NNDiary
-@subsubsection Customizing NNDiary
-@cindex customizing nndiary
-@cindex nndiary customization
+@item
+Group Parameter specification
-Now that @code{nndiary} is up and running, it's time to customize it.
-The custom group is called @code{nndiary} (no, really ?!). You should
-browse it to figure out which options you'd like to tweak. The following
-two variables are probably the only ones you will want to change:
+@lisp
+(agent-score . file)
+@end lisp
+@end itemize
+@end enumerate
-@defvar nndiary-reminders
-This is the list of times when you want to be reminded of your
-appointments (e.g. 3 weeks before, then 2 days before, then 1 hour
-before and that's it). Remember that ``being reminded'' means that the
-diary message will pop up as brand new and unread again when you get new
-mail.
-@end defvar
+@node Category Buffer
+@subsubsection Category Buffer
-@defvar nndiary-week-starts-on-monday
-Rather self-explanatory. Otherwise, Sunday is assumed (this is the
-default).
-@end defvar
+You'd normally do all category maintenance from the category buffer.
+When you enter it for the first time (with the @kbd{J c} command from
+the group buffer), you'll only see the @code{default} category.
+The following commands are available in this buffer:
-@node The Gnus Diary Library
-@subsection The Gnus Diary Library
-@cindex gnus-diary
-@cindex the gnus diary library
+@table @kbd
+@item q
+@kindex q (Category)
+@findex gnus-category-exit
+Return to the group buffer (@code{gnus-category-exit}).
-Using @code{nndiary} manually (I mean, writing the headers by hand and
-so on) would be rather boring. Fortunately, there is a library called
-@code{gnus-diary} written on top of @code{nndiary}, that does many
-useful things for you.
+@item e
+@kindex e (Category)
+@findex gnus-category-customize-category
+Use a customization buffer to set all of the selected category's
+parameters at one time (@code{gnus-category-customize-category}).
- In order to use it, add the following line to your @file{~/.gnus.el} file:
+@item k
+@kindex k (Category)
+@findex gnus-category-kill
+Kill the current category (@code{gnus-category-kill}).
-@lisp
-(require 'gnus-diary)
-@end lisp
+@item c
+@kindex c (Category)
+@findex gnus-category-copy
+Copy the current category (@code{gnus-category-copy}).
- Also, you shouldn't use any @code{gnus-user-format-function-[d|D]}
-(@pxref{Summary Buffer Lines}). @code{gnus-diary} provides both of these
-(sorry if you used them before).
+@item a
+@kindex a (Category)
+@findex gnus-category-add
+Add a new category (@code{gnus-category-add}).
+@item p
+@kindex p (Category)
+@findex gnus-category-edit-predicate
+Edit the predicate of the current category
+(@code{gnus-category-edit-predicate}).
-@menu
-* Diary Summary Line Format:: A nicer summary buffer line format.
-* Diary Articles Sorting:: A nicer way to sort messages.
-* Diary Headers Generation:: Not doing it manually.
-* Diary Group Parameters:: Not handling them manually.
-@end menu
+@item g
+@kindex g (Category)
+@findex gnus-category-edit-groups
+Edit the list of groups belonging to the current category
+(@code{gnus-category-edit-groups}).
-@node Diary Summary Line Format
-@subsubsection Diary Summary Line Format
-@cindex diary summary buffer line
-@cindex diary summary line format
+@item s
+@kindex s (Category)
+@findex gnus-category-edit-score
+Edit the download score rule of the current category
+(@code{gnus-category-edit-score}).
-Displaying diary messages in standard summary line format (usually
-something like @samp{From Joe: Subject}) is pretty useless. Most of
-the time, you're the one who wrote the message, and you mostly want to
-see the event's date.
+@item l
+@kindex l (Category)
+@findex gnus-category-list
+List all the categories (@code{gnus-category-list}).
+@end table
- @code{gnus-diary} provides two supplemental user formats to be used in
-summary line formats. @code{D} corresponds to a formatted time string
-for the next occurrence of the event (e.g. ``Sat, Sep 22 01, 12:00''),
-while @code{d} corresponds to an approximative remaining time until the
-next occurrence of the event (e.g. ``in 6 months, 1 week'').
- For example, here's how Joe's birthday is displayed in my
-@code{nndiary+diary:birthdays} summary buffer (note that the message is
-expirable, but will never be deleted, as it specifies a periodic event):
+@node Category Variables
+@subsubsection Category Variables
-@example
- E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week)
-@end example
+@table @code
+@item gnus-category-mode-hook
+@vindex gnus-category-mode-hook
+Hook run in category buffers.
-In order to get something like the above, you would normally add the
-following line to your diary groups'parameters:
+@item gnus-category-line-format
+@vindex gnus-category-line-format
+Format of the lines in the category buffer (@pxref{Formatting
+Variables}). Valid elements are:
-@lisp
-(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n")
-@end lisp
+@table @samp
+@item c
+The name of the category.
-However, @code{gnus-diary} does it automatically (@pxref{Diary Group
-Parameters}). You can however customize the provided summary line format
-with the following user options:
+@item g
+The number of groups in the category.
+@end table
-@defvar gnus-diary-summary-line-format
-Defines the summary line format used for diary groups (@pxref{Summary
-Buffer Lines}). @code{gnus-diary} uses it to automatically update the
-diary groups'parameters.
-@end defvar
+@item gnus-category-mode-line-format
+@vindex gnus-category-mode-line-format
+Format of the category mode line (@pxref{Mode Line Formatting}).
-@defvar gnus-diary-time-format
-Defines the format to display dates in diary summary buffers. This is
-used by the @code{D} user format. See the docstring for details.
-@end defvar
+@item gnus-agent-short-article
+@vindex gnus-agent-short-article
+Articles that have fewer lines than this are short. Default 100.
+
+@item gnus-agent-long-article
+@vindex gnus-agent-long-article
+Articles that have more lines than this are long. Default 200.
+
+@item gnus-agent-low-score
+@vindex gnus-agent-low-score
+Articles that have a score lower than this have a low score. Default
+0.
+
+@item gnus-agent-high-score
+@vindex gnus-agent-high-score
+Articles that have a score higher than this have a high score. Default
+0.
+
+@item gnus-agent-expire-days
+@vindex gnus-agent-expire-days
+The number of days that a @samp{read} article must stay in the agent's
+local disk before becoming eligible for expiration (While the name is
+the same, this doesn't mean expiring the article on the server. It
+just means deleting the local copy of the article). What is also
+important to understand is that the counter starts with the time the
+article was written to the local disk and not the time the article was
+read.
+Default 7.
+
+@item gnus-agent-enable-expiration
+@vindex gnus-agent-enable-expiration
+Determines whether articles in a group are, by default, expired or
+retained indefinitely. The default is @code{ENABLE} which means that
+you'll have to disable expiration when desired. On the other hand,
+you could set this to @code{DISABLE}. In that case, you would then
+have to enable expiration in selected groups.
-@defvar gnus-diary-delay-format-function
-Defines the format function to use for displaying delays (remaining
-times) in diary summary buffers. This is used by the @code{d} user
-format. There are currently built-in functions for English and French;
-you can also define your own. See the docstring for details.
-@end defvar
+@end table
-@node Diary Articles Sorting
-@subsubsection Diary Articles Sorting
-@cindex diary articles sorting
-@cindex diary summary lines sorting
-@findex gnus-summary-sort-by-schedule
-@findex gnus-thread-sort-by-schedule
-@findex gnus-article-sort-by-schedule
-@code{gnus-diary} provides new sorting functions (@pxref{Sorting the
-Summary Buffer} ) called @code{gnus-summary-sort-by-schedule},
-@code{gnus-thread-sort-by-schedule} and
-@code{gnus-article-sort-by-schedule}. These functions let you organize
-your diary summary buffers from the closest event to the farthest one.
+@node Agent Commands
+@subsection Agent Commands
+@findex gnus-agent-toggle-plugged
+@kindex J j (Agent)
-@code{gnus-diary} automatically installs
-@code{gnus-summary-sort-by-schedule} as a menu item in the summary
-buffer's ``sort'' menu, and the two others as the primary (hence
-default) sorting functions in the group parameters (@pxref{Diary Group
-Parameters}).
+All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j}
+(@code{gnus-agent-toggle-plugged}) command works in all modes, and
+toggles the plugged/unplugged state of the Gnus Agent.
-@node Diary Headers Generation
-@subsubsection Diary Headers Generation
-@cindex diary headers generation
-@findex gnus-diary-check-message
-@code{gnus-diary} provides a function called
-@code{gnus-diary-check-message} to help you handle the @code{X-Diary-*}
-headers. This function ensures that the current message contains all the
-required diary headers, and prompts you for values or corrections if
-needed.
+@menu
+* Group Agent Commands:: Configure groups and fetch their contents.
+* Summary Agent Commands:: Manually select then fetch specific articles.
+* Server Agent Commands:: Select the servers that are supported by the agent.
+@end menu
- This function is hooked into the @code{nndiary} back end, so that
-moving or copying an article to a diary group will trigger it
-automatically. It is also bound to @kbd{C-c C-f d} in
-@code{message-mode} and @code{article-edit-mode} in order to ease the
-process of converting a usual mail to a diary one.
- This function takes a prefix argument which will force prompting of
-all diary headers, regardless of their presence or validity. That way,
-you can very easily reschedule an already valid diary message, for
-instance.
-@node Diary Group Parameters
-@subsubsection Diary Group Parameters
-@cindex diary group parameters
-When you create a new diary group, or visit one, @code{gnus-diary}
-automatically checks your group parameters and if needed, sets the
-summary line format to the diary-specific value, installs the
-diary-specific sorting functions, and also adds the different
-@code{X-Diary-*} headers to the group's posting-style. It is then easier
-to send a diary message, because if you use @kbd{C-u a} or @kbd{C-u m}
-on a diary group to prepare a message, these headers will be inserted
-automatically (although not filled with proper values yet).
+@node Group Agent Commands
+@subsubsection Group Agent Commands
-@node Sending or Not Sending
-@subsection Sending or Not Sending
+@table @kbd
+@item J u
+@kindex J u (Agent Group)
+@findex gnus-agent-fetch-groups
+Fetch all eligible articles in the current group
+(@code{gnus-agent-fetch-groups}).
-Well, assuming you've read all of the above, here are two final notes on
-mail sending with @code{nndiary}:
+@item J c
+@kindex J c (Agent Group)
+@findex gnus-enter-category-buffer
+Enter the Agent category buffer (@code{gnus-enter-category-buffer}).
-@itemize @bullet
-@item
-@code{nndiary} is a @emph{real} mail back end. You really send real diary
-messsages for real. This means for instance that you can give
-appointments to anybody (provided they use Gnus and @code{nndiary}) by
-sending the diary message to them as well.
-@item
-However, since @code{nndiary} also has a @code{request-post} method, you
-can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the
-message won't actually be sent; just stored locally in the group. This
-comes in very handy for private appointments.
-@end itemize
+@item J s
+@kindex J s (Agent Group)
+@findex gnus-agent-fetch-session
+Fetch all eligible articles in all groups
+(@code{gnus-agent-fetch-session}).
-@node Gnus Unplugged
-@section Gnus Unplugged
-@cindex offline
-@cindex unplugged
-@cindex agent
-@cindex Gnus agent
-@cindex Gnus unplugged
+@item J S
+@kindex J S (Agent Group)
+@findex gnus-group-send-queue
+Send all sendable messages in the queue group
+(@code{gnus-group-send-queue}). @xref{Drafts}.
-In olden times (ca. February '88), people used to run their newsreaders
-on big machines with permanent connections to the net. News transport
-was dealt with by news servers, and all the newsreaders had to do was to
-read news. Believe it or not.
+@item J a
+@kindex J a (Agent Group)
+@findex gnus-agent-add-group
+Add the current group to an Agent category
+(@code{gnus-agent-add-group}). This command understands the
+process/prefix convention (@pxref{Process/Prefix}).
-Nowadays most people read news and mail at home, and use some sort of
-modem to connect to the net. To avoid running up huge phone bills, it
-would be nice to have a way to slurp down all the news and mail, hang up
-the phone, read for several hours, and then upload any responses you
-have to make. And then you repeat the procedure.
+@item J r
+@kindex J r (Agent Group)
+@findex gnus-agent-remove-group
+Remove the current group from its category, if any
+(@code{gnus-agent-remove-group}). This command understands the
+process/prefix convention (@pxref{Process/Prefix}).
-Of course, you can use news servers for doing this as well. I've used
-@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail}
-for some years, but doing that's a bore. Moving the news server
-functionality up to the newsreader makes sense if you're the only person
-reading news on a machine.
+@item J Y
+@kindex J Y (Agent Group)
+@findex gnus-agent-synchronize-flags
+Synchronize flags changed while unplugged with remote server, if any.
-Setting up Gnus as an ``offline'' newsreader is quite simple. In
-fact, you don't have to configure anything as the agent is now enabled
-by default (@pxref{Agent Variables, gnus-agent}).
-Of course, to use it as such, you have to learn a few new commands.
+@end table
-@menu
-* Agent Basics:: How it all is supposed to work.
-* Agent Categories:: How to tell the Gnus Agent what to download.
-* Agent Commands:: New commands for all the buffers.
-* Agent Visuals:: Ways that the agent may effect your summary buffer.
-* Agent as Cache:: The Agent is a big cache too.
-* Agent Expiry:: How to make old articles go away.
-* Agent Regeneration:: How to recover from lost connections and other accidents.
-* Agent and flags:: How the Agent maintains flags.
-* Agent and IMAP:: How to use the Agent with @acronym{IMAP}.
-* Outgoing Messages:: What happens when you post/mail something?
-* Agent Variables:: Customizing is fun.
-* Example Setup:: An example @file{~/.gnus.el} file for offline people.
-* Batching Agents:: How to fetch news from a @code{cron} job.
-* Agent Caveats:: What you think it'll do and what it does.
-@end menu
+@node Summary Agent Commands
+@subsubsection Summary Agent Commands
-@node Agent Basics
-@subsection Agent Basics
+@table @kbd
+@item J #
+@kindex J # (Agent Summary)
+@findex gnus-agent-mark-article
+Mark the article for downloading (@code{gnus-agent-mark-article}).
-First, let's get some terminology out of the way.
+@item J M-#
+@kindex J M-# (Agent Summary)
+@findex gnus-agent-unmark-article
+Remove the downloading mark from the article
+(@code{gnus-agent-unmark-article}).
-The Gnus Agent is said to be @dfn{unplugged} when you have severed the
-connection to the net (and notified the Agent that this is the case).
-When the connection to the net is up again (and Gnus knows this), the
-Agent is @dfn{plugged}.
+@cindex %
+@item @@
+@kindex @@ (Agent Summary)
+@findex gnus-agent-toggle-mark
+Toggle whether to download the article
+(@code{gnus-agent-toggle-mark}). The download mark is @samp{%} by
+default.
-The @dfn{local} machine is the one you're running on, and which isn't
-connected to the net continuously.
+@item J c
+@kindex J c (Agent Summary)
+@findex gnus-agent-catchup
+Mark all articles as read (@code{gnus-agent-catchup}) that are neither cached, downloaded, nor downloadable.
-@dfn{Downloading} means fetching things from the net to your local
-machine. @dfn{Uploading} is doing the opposite.
+@item J S
+@kindex J S (Agent Summary)
+@findex gnus-agent-fetch-group
+Download all eligible (@pxref{Agent Categories}) articles in this group.
+(@code{gnus-agent-fetch-group}).
-You know that Gnus gives you all the opportunity you'd ever want for
-shooting yourself in the foot. Some people call it flexibility. Gnus
-is also customizable to a great extent, which means that the user has a
-say on how Gnus behaves. Other newsreaders might unconditionally shoot
-you in your foot, but with Gnus, you have a choice!
+@item J s
+@kindex J s (Agent Summary)
+@findex gnus-agent-summary-fetch-series
+Download all processable articles in this group.
+(@code{gnus-agent-summary-fetch-series}).
-Gnus is never really in plugged or unplugged state. Rather, it applies
-that state to each server individually. This means that some servers
-can be plugged while others can be unplugged. Additionally, some
-servers can be ignored by the Agent altogether (which means that
-they're kinda like plugged always).
+@item J u
+@kindex J u (Agent Summary)
+@findex gnus-agent-summary-fetch-group
+Download all downloadable articles in the current group
+(@code{gnus-agent-summary-fetch-group}).
-So when you unplug the Agent and then wonder why is Gnus opening a
-connection to the Net, the next step to do is to look whether all
-servers are agentized. If there is an unagentized server, you found
-the culprit.
+@end table
-Another thing is the @dfn{offline} state. Sometimes, servers aren't
-reachable. When Gnus notices this, it asks you whether you want the
-server to be switched to offline state. If you say yes, then the
-server will behave somewhat as if it was unplugged, except that Gnus
-will ask you whether you want to switch it back online again.
-Let's take a typical Gnus session using the Agent.
+@node Server Agent Commands
+@subsubsection Server Agent Commands
-@itemize @bullet
+@table @kbd
+@item J a
+@kindex J a (Agent Server)
+@findex gnus-agent-add-server
+Add the current server to the list of servers covered by the Gnus Agent
+(@code{gnus-agent-add-server}).
-@item
-@findex gnus-unplugged
-You start Gnus with @code{gnus-unplugged}. This brings up the Gnus
-Agent in a disconnected state. You can read all the news that you have
-already fetched while in this mode.
+@item J r
+@kindex J r (Agent Server)
+@findex gnus-agent-remove-server
+Remove the current server from the list of servers covered by the Gnus
+Agent (@code{gnus-agent-remove-server}).
-@item
-You then decide to see whether any new news has arrived. You connect
-your machine to the net (using PPP or whatever), and then hit @kbd{J j}
-to make Gnus become @dfn{plugged} and use @kbd{g} to check for new mail
-as usual. To check for new mail in unplugged mode (@pxref{Mail
-Source Specifiers}).
+@end table
-@item
-You can then read the new news immediately, or you can download the
-news onto your local machine. If you want to do the latter, you press
-@kbd{g} to check if there are any new news and then @kbd{J s} to fetch
-all the eligible articles in all the groups. (To let Gnus know which
-articles you want to download, @pxref{Agent Categories}).
-@item
-After fetching the articles, you press @kbd{J j} to make Gnus become
-unplugged again, and you shut down the PPP thing (or whatever). And
-then you read the news offline.
+@node Agent Visuals
+@subsection Agent Visuals
-@item
-And then you go to step 2.
-@end itemize
+If you open a summary while unplugged and, Gnus knows from the group's
+active range that there are more articles than the headers currently
+stored in the Agent, you may see some articles whose subject looks
+something like @samp{[Undownloaded article #####]}. These are
+placeholders for the missing headers. Aside from setting a mark,
+there is not much that can be done with one of these placeholders.
+When Gnus finally gets a chance to fetch the group's headers, the
+placeholders will automatically be replaced by the actual headers.
+You can configure the summary buffer's maneuvering to skip over the
+placeholders if you care (See @code{gnus-auto-goto-ignores}).
-Here are some things you should do the first time (or so) that you use
-the Agent.
+While it may be obvious to all, the only headers and articles
+available while unplugged are those headers and articles that were
+fetched into the Agent while previously plugged. To put it another
+way, ``If you forget to fetch something while plugged, you might have a
+less than satisfying unplugged session''. For this reason, the Agent
+adds two visual effects to your summary buffer. These effects display
+the download status of each article so that you always know which
+articles will be available when unplugged.
-@itemize @bullet
+The first visual effect is the @samp{%O} spec. If you customize
+@code{gnus-summary-line-format} to include this specifier, you will add
+a single character field that indicates an article's download status.
+Articles that have been fetched into either the Agent or the Cache,
+will display @code{gnus-downloaded-mark} (defaults to @samp{+}). All
+other articles will display @code{gnus-undownloaded-mark} (defaults to
+@samp{-}). If you open a group that has not been agentized, a space
+(@samp{ }) will be displayed.
-@item
-Decide which servers should be covered by the Agent. If you have a mail
-back end, it would probably be nonsensical to have it covered by the
-Agent. Go to the server buffer (@kbd{^} in the group buffer) and press
-@kbd{J a} on the server (or servers) that you wish to have covered by the
-Agent (@pxref{Server Agent Commands}), or @kbd{J r} on automatically
-added servers you do not wish to have covered by the Agent. By default,
-all @code{nntp} and @code{nnimap} servers in @code{gnus-select-method} and
-@code{gnus-secondary-select-methods} are agentized.
+The second visual effect are the undownloaded faces. The faces, there
+are three indicating the article's score (low, normal, high), seem to
+result in a love/hate response from many Gnus users. The problem is
+that the face selection is controlled by a list of condition tests and
+face names (See @code{gnus-summary-highlight}). Each condition is
+tested in the order in which it appears in the list so early
+conditions have precedence over later conditions. All of this means
+that, if you tick an undownloaded article, the article will continue
+to be displayed in the undownloaded face rather than the ticked face.
-@item
-Decide on download policy. It's fairly simple once you decide whether
-you are going to use agent categories, topic parameters, and/or group
-parameters to implement your policy. If you're new to gnus, it
-is probably best to start with a category, @xref{Agent Categories}.
+If you use the Agent as a cache (to avoid downloading the same article
+each time you visit it or to minimize your connection time), the
+undownloaded face will probably seem like a good idea. The reason
+being that you do all of our work (marking, reading, deleting) with
+downloaded articles so the normal faces always appear. For those
+users using the agent to improve online performance by caching the NOV
+database (most users since 5.10.2), the undownloaded faces may appear
+to be an absolutely horrible idea. The issue being that, since none
+of their articles have been fetched into the Agent, all of the
+normal faces will be obscured by the undownloaded faces.
-Both topic parameters (@pxref{Topic Parameters}) and agent categories
-(@pxref{Agent Categories}) provide for setting a policy that applies
-to multiple groups. Which you use is entirely up to you. Topic
-parameters do override categories so, if you mix the two, you'll have
-to take that into account. If you have a few groups that deviate from
-your policy, you can use group parameters (@pxref{Group Parameters}) to
-configure them.
+If you would like to use the undownloaded faces, you must enable the
+undownloaded faces by setting the @code{agent-enable-undownloaded-faces}
+group parameter to @code{t}. This parameter, like all other agent
+parameters, may be set on an Agent Category (@pxref{Agent Categories}),
+a Group Topic (@pxref{Topic Parameters}), or an individual group
+(@pxref{Group Parameters}).
-@item
-Uhm@dots{} that's it.
-@end itemize
+The one problem common to all users using the agent is how quickly it
+can consume disk space. If you using the agent on many groups, it is
+even more difficult to effectively recover disk space. One solution
+is the @samp{%F} format available in @code{gnus-group-line-format}.
+This format will display the actual disk space used by articles
+fetched into both the agent and cache. By knowing which groups use
+the most space, users know where to focus their efforts when ``agent
+expiring'' articles.
+@node Agent as Cache
+@subsection Agent as Cache
-@node Agent Categories
-@subsection Agent Categories
+When Gnus is plugged, it is not efficient to download headers or
+articles from the server again, if they are already stored in the
+Agent. So, Gnus normally only downloads headers once, and stores them
+in the Agent. These headers are later used when generating the summary
+buffer, regardless of whether you are plugged or unplugged. Articles
+are not cached in the Agent by default though (that would potentially
+consume lots of disk space), but if you have already downloaded an
+article into the Agent, Gnus will not download the article from the
+server again but use the locally stored copy instead.
-One of the main reasons to integrate the news transport layer into the
-newsreader is to allow greater control over what articles to download.
-There's not much point in downloading huge amounts of articles, just to
-find out that you're not interested in reading any of them. It's better
-to be somewhat more conservative in choosing what to download, and then
-mark the articles for downloading manually if it should turn out that
-you're interested in the articles anyway.
+If you so desire, you can configure the agent (see @code{gnus-agent-cache}
+@pxref{Agent Variables}) to always download headers and articles while
+plugged. Gnus will almost certainly be slower, but it will be kept
+synchronized with the server. That last point probably won't make any
+sense if you are using a nntp or nnimap back end.
-One of the more effective methods for controlling what is to be
-downloaded is to create a @dfn{category} and then assign some (or all)
-groups to this category. Groups that do not belong in any other
-category belong to the @code{default} category. Gnus has its own
-buffer for creating and managing categories.
+@node Agent Expiry
+@subsection Agent Expiry
-If you prefer, you can also use group parameters (@pxref{Group
-Parameters}) and topic parameters (@pxref{Topic Parameters}) for an
-alternative approach to controlling the agent. The only real
-difference is that categories are specific to the agent (so there is
-less to learn) while group and topic parameters include the kitchen
-sink.
+@vindex gnus-agent-expire-days
+@findex gnus-agent-expire
+@kindex M-x gnus-agent-expire
+@kindex M-x gnus-agent-expire-group
+@findex gnus-agent-expire-group
+@cindex agent expiry
+@cindex Gnus agent expiry
+@cindex expiry, in Gnus agent
-Since you can set agent parameters in several different places we have
-a rule to decide which source to believe. This rule specifies that
-the parameter sources are checked in the following order: group
-parameters, topic parameters, agent category, and finally customizable
-variables. So you can mix all of these sources to produce a wide range
-of behavior, just don't blame me if you don't remember where you put
-your settings.
+The Agent back end, @code{nnagent}, doesn't handle expiry. Well, at
+least it doesn't handle it like other back ends. Instead, there are
+special @code{gnus-agent-expire} and @code{gnus-agent-expire-group}
+commands that will expire all read articles that are older than
+@code{gnus-agent-expire-days} days. They can be run whenever you feel
+that you're running out of space. Neither are particularly fast or
+efficient, and it's not a particularly good idea to interrupt them (with
+@kbd{C-g} or anything else) once you've started one of them.
-@menu
-* Category Syntax:: What a category looks like.
-* Category Buffer:: A buffer for maintaining categories.
-* Category Variables:: Customize'r'Us.
-@end menu
+Note that other functions, e.g. @code{gnus-request-expire-articles},
+might run @code{gnus-agent-expire} for you to keep the agent
+synchronized with the group.
+The agent parameter @code{agent-enable-expiration} may be used to
+prevent expiration in selected groups.
-@node Category Syntax
-@subsubsection Category Syntax
+@vindex gnus-agent-expire-all
+If @code{gnus-agent-expire-all} is non-@code{nil}, the agent
+expiration commands will expire all articles---unread, read, ticked
+and dormant. If @code{nil} (which is the default), only read articles
+are eligible for expiry, and unread, ticked and dormant articles will
+be kept indefinitely.
-A category consists of a name, the list of groups belonging to the
-category, and a number of optional parameters that override the
-customizable variables. The complete list of agent parameters are
-listed below.
+If you find that some articles eligible for expiry are never expired,
+perhaps some Gnus Agent files are corrupted. There's are special
+commands, @code{gnus-agent-regenerate} and
+@code{gnus-agent-regenerate-group}, to fix possible problems.
-@cindex Agent Parameters
-@table @code
-@item agent-groups
-The list of groups that are in this category.
+@node Agent Regeneration
+@subsection Agent Regeneration
-@item agent-predicate
-A predicate which (generally) gives a rough outline of which articles
-are eligible for downloading; and
+@cindex agent regeneration
+@cindex Gnus agent regeneration
+@cindex regeneration
-@item agent-score
-a score rule which (generally) gives you a finer granularity when
-deciding what articles to download. (Note that this @dfn{download
-score} is not necessarily related to normal scores.)
+The local data structures used by @code{nnagent} may become corrupted
+due to certain exceptional conditions. When this happens,
+@code{nnagent} functionality may degrade or even fail. The solution
+to this problem is to repair the local data structures by removing all
+internal inconsistencies.
-@item agent-enable-expiration
-a boolean indicating whether the agent should expire old articles in
-this group. Most groups should be expired to conserve disk space. In
-fact, its probably safe to say that the gnus.* hierarchy contains the
-only groups that should not be expired.
+For example, if your connection to your server is lost while
+downloaded articles into the agent, the local data structures will not
+know about articles successfully downloaded prior to the connection
+failure. Running @code{gnus-agent-regenerate} or
+@code{gnus-agent-regenerate-group} will update the data structures
+such that you don't need to download these articles a second time.
-@item agent-days-until-old
-an integer indicating the number of days that the agent should wait
-before deciding that a read article is safe to expire.
+@findex gnus-agent-regenerate
+@kindex M-x gnus-agent-regenerate
+The command @code{gnus-agent-regenerate} will perform
+@code{gnus-agent-regenerate-group} on every agentized group. While
+you can run @code{gnus-agent-regenerate} in any buffer, it is strongly
+recommended that you first close all summary buffers.
-@item agent-low-score
-an integer that overrides the value of @code{gnus-agent-low-score}.
+@findex gnus-agent-regenerate-group
+@kindex M-x gnus-agent-regenerate-group
+The command @code{gnus-agent-regenerate-group} uses the local copies
+of individual articles to repair the local @acronym{NOV}(header) database. It
+then updates the internal data structures that document which articles
+are stored locally. An optional argument will mark articles in the
+agent as unread.
+
+@node Agent and flags
+@subsection Agent and flags
+
+The Agent works with any Gnus back end including those, such as
+nnimap, that store flags (read, ticked, etc) on the server. Sadly,
+the Agent does not actually know which backends keep their flags in
+the backend server rather than in @file{.newsrc}. This means that the
+Agent, while unplugged or disconnected, will always record all changes
+to the flags in its own files.
+
+When you plug back in, Gnus will then check to see if you have any
+changed any flags and ask if you wish to synchronize these with the
+server. This behavior is customizable by @code{gnus-agent-synchronize-flags}.
-@item agent-high-score
-an integer that overrides the value of @code{gnus-agent-high-score}.
+@vindex gnus-agent-synchronize-flags
+If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will
+never automatically synchronize flags. If it is @code{ask}, which is
+the default, the Agent will check if you made any changes and if so
+ask if you wish to synchronize these when you re-connect. If it has
+any other value, all flags will be synchronized automatically.
-@item agent-short-article
-an integer that overrides the value of
-@code{gnus-agent-short-article}.
+If you do not wish to synchronize flags automatically when you
+re-connect, you can do it manually with the
+@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y}
+in the group buffer.
-@item agent-long-article
-an integer that overrides the value of @code{gnus-agent-long-article}.
+Technical note: the synchronization algorithm does not work by ``pushing''
+all local flags to the server, but rather by incrementally updated the
+server view of flags by changing only those flags that were changed by
+the user. Thus, if you set one flag on an article, quit the group then
+re-select the group and remove the flag; the flag will be set and
+removed from the server when you ``synchronize''. The queued flag
+operations can be found in the per-server @code{flags} file in the Agent
+directory. It's emptied when you synchronize flags.
-@item agent-enable-undownloaded-faces
-a symbol indicating whether the summary buffer should display
-undownloaded articles using the @code{gnus-summary-*-undownloaded-face}
-faces. Any symbol other than @code{nil} will enable the use of
-undownloaded faces.
-@end table
+@node Agent and IMAP
+@subsection Agent and IMAP
-The name of a category can not be changed once the category has been
-created.
+The Agent works with any Gnus back end, including nnimap. However,
+since there are some conceptual differences between @acronym{NNTP} and
+@acronym{IMAP}, this section (should) provide you with some information to
+make Gnus Agent work smoother as a @acronym{IMAP} Disconnected Mode client.
-Each category maintains a list of groups that are exclusive members of
-that category. The exclusivity rule is automatically enforced, add a
-group to a new category and it is automatically removed from its old
-category.
+Some things are currently not implemented in the Agent that you'd might
+expect from a disconnected @acronym{IMAP} client, including:
-A predicate in its simplest form can be a single predicate such as
-@code{true} or @code{false}. These two will download every available
-article or nothing respectively. In the case of these two special
-predicates an additional score rule is superfluous.
+@itemize @bullet
-Predicates of @code{high} or @code{low} download articles in respect of
-their scores in relationship to @code{gnus-agent-high-score} and
-@code{gnus-agent-low-score} as described below.
+@item
+Copying/moving articles into nnimap groups when unplugged.
-To gain even finer control of what is to be regarded eligible for
-download a predicate can consist of a number of predicates with logical
-operators sprinkled in between.
+@item
+Creating/deleting nnimap groups when unplugged.
-Perhaps some examples are in order.
+@end itemize
-Here's a simple predicate. (It's the default predicate, in fact, used
-for all groups that don't belong to any other category.)
+@node Outgoing Messages
+@subsection Outgoing Messages
-@lisp
-short
-@end lisp
+By default, when Gnus is unplugged, all outgoing messages (both mail
+and news) are stored in the draft group ``queue'' (@pxref{Drafts}).
+You can view them there after posting, and edit them at will.
-Quite simple, eh? This predicate is true if and only if the article is
-short (for some value of ``short'').
+You can control the circumstances under which outgoing mail is queued
+(see @code{gnus-agent-queue-mail}, @pxref{Agent Variables}). Outgoing
+news is always queued when Gnus is unplugged, and never otherwise.
-Here's a more complex predicate:
+You can send the messages either from the draft group with the special
+commands available there, or you can use the @kbd{J S} command in the
+group buffer to send all the sendable messages in the draft group.
+Posting news will only work when Gnus is plugged, but you can send
+mail at any time.
-@lisp
-(or high
- (and
- (not low)
- (not long)))
-@end lisp
+If sending mail while unplugged does not work for you and you worry
+about hitting @kbd{J S} by accident when unplugged, you can have Gnus
+ask you to confirm your action (see
+@code{gnus-agent-prompt-send-queue}, @pxref{Agent Variables}).
-This means that an article should be downloaded if it has a high score,
-or if the score is not low and the article is not long. You get the
-drift.
+@node Agent Variables
+@subsection Agent Variables
-The available logical operators are @code{or}, @code{and} and
-@code{not}. (If you prefer, you can use the more ``C''-ish operators
-@samp{|}, @code{&} and @code{!} instead.)
+@table @code
+@item gnus-agent
+@vindex gnus-agent
+Is the agent enabled? The default is @code{t}. When first enabled,
+the agent will use @code{gnus-agent-auto-agentize-methods} to
+automatically mark some back ends as agentized. You may change which
+back ends are agentized using the agent commands in the server buffer.
-The following predicates are pre-defined, but if none of these fit what
-you want to do, you can write your own.
+To enter the server buffer, use the @kbd{^}
+(@code{gnus-group-enter-server-mode}) command in the group buffer.
-When evaluating each of these predicates, the named constant will be
-bound to the value determined by calling
-@code{gnus-agent-find-parameter} on the appropriate parameter. For
-example, gnus-agent-short-article will be bound to
-@code{(gnus-agent-find-parameter group 'agent-short-article)}. This
-means that you can specify a predicate in your category then tune that
-predicate to individual groups.
-@table @code
-@item short
-True if the article is shorter than @code{gnus-agent-short-article}
-lines; default 100.
+@item gnus-agent-directory
+@vindex gnus-agent-directory
+Where the Gnus Agent will store its files. The default is
+@file{~/News/agent/}.
-@item long
-True if the article is longer than @code{gnus-agent-long-article}
-lines; default 200.
+@item gnus-agent-handle-level
+@vindex gnus-agent-handle-level
+Groups on levels (@pxref{Group Levels}) higher than this variable will
+be ignored by the Agent. The default is @code{gnus-level-subscribed},
+which means that only subscribed group will be considered by the Agent
+by default.
-@item low
-True if the article has a download score less than
-@code{gnus-agent-low-score}; default 0.
+@item gnus-agent-plugged-hook
+@vindex gnus-agent-plugged-hook
+Hook run when connecting to the network.
-@item high
-True if the article has a download score greater than
-@code{gnus-agent-high-score}; default 0.
+@item gnus-agent-unplugged-hook
+@vindex gnus-agent-unplugged-hook
+Hook run when disconnecting from the network.
-@item spam
-True if the Gnus Agent guesses that the article is spam. The
-heuristics may change over time, but at present it just computes a
-checksum and sees whether articles match.
+@item gnus-agent-fetched-hook
+@vindex gnus-agent-fetched-hook
+Hook run when finished fetching articles.
-@item true
-Always true.
+@item gnus-agent-cache
+@vindex gnus-agent-cache
+Variable to control whether use the locally stored @acronym{NOV} and
+articles when plugged, e.g. essentially using the Agent as a cache.
+The default is non-@code{nil}, which means to use the Agent as a cache.
-@item false
-Always false.
-@end table
+@item gnus-agent-go-online
+@vindex gnus-agent-go-online
+If @code{gnus-agent-go-online} is @code{nil}, the Agent will never
+automatically switch offline servers into online status. If it is
+@code{ask}, the default, the Agent will ask if you wish to switch
+offline servers into online status when you re-connect. If it has any
+other value, all offline servers will be automatically switched into
+online status.
-If you want to create your own predicate function, here's what you have
-to know: The functions are called with no parameters, but the
-@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to
-useful values.
+@item gnus-agent-mark-unread-after-downloaded
+@vindex gnus-agent-mark-unread-after-downloaded
+If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil},
+mark articles as unread after downloading. This is usually a safe
+thing to do as the newly downloaded article has obviously not been
+read. The default is @code{t}.
-For example, you could decide that you don't want to download articles
-that were posted more than a certain number of days ago (e.g. posted
-more than @code{gnus-agent-expire-days} ago) you might write a function
-something along the lines of the following:
+@item gnus-agent-synchronize-flags
+@vindex gnus-agent-synchronize-flags
+If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will
+never automatically synchronize flags. If it is @code{ask}, which is
+the default, the Agent will check if you made any changes and if so
+ask if you wish to synchronize these when you re-connect. If it has
+any other value, all flags will be synchronized automatically.
-@lisp
-(defun my-article-old-p ()
- "Say whether an article is old."
- (< (time-to-days (date-to-time (mail-header-date gnus-headers)))
- (- (time-to-days (current-time)) gnus-agent-expire-days)))
-@end lisp
+@item gnus-agent-consider-all-articles
+@vindex gnus-agent-consider-all-articles
+If @code{gnus-agent-consider-all-articles} is non-@code{nil}, the
+agent will let the agent predicate decide whether articles need to be
+downloaded or not, for all articles. When @code{nil}, the default,
+the agent will only let the predicate decide whether unread articles
+are downloaded or not. If you enable this, you may also want to look
+into the agent expiry settings (@pxref{Category Variables}), so that
+the agent doesn't download articles which the agent will later expire,
+over and over again.
-with the predicate then defined as:
+@item gnus-agent-max-fetch-size
+@vindex gnus-agent-max-fetch-size
+The agent fetches articles into a temporary buffer prior to parsing
+them into individual files. To avoid exceeding the max. buffer size,
+the agent alternates between fetching and parsing until all articles
+have been fetched. @code{gnus-agent-max-fetch-size} provides a size
+limit to control how often the cycling occurs. A large value improves
+performance. A small value minimizes the time lost should the
+connection be lost while fetching (You may need to run
+@code{gnus-agent-regenerate-group} to update the group's state.
+However, all articles parsed prior to losing the connection will be
+available while unplugged). The default is 10M so it is unusual to
+see any cycling.
-@lisp
-(not my-article-old-p)
-@end lisp
+@item gnus-server-unopen-status
+@vindex gnus-server-unopen-status
+Perhaps not an Agent variable, but closely related to the Agent, this
+variable says what will happen if Gnus cannot open a server. If the
+Agent is enabled, the default, @code{nil}, makes Gnus ask the user
+whether to deny the server or whether to unplug the agent. If the
+Agent is disabled, Gnus always simply deny the server. Other choices
+for this variable include @code{denied} and @code{offline} the latter
+is only valid if the Agent is used.
-or you could append your predicate to the predefined
-@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or
-wherever.
+@item gnus-auto-goto-ignores
+@vindex gnus-auto-goto-ignores
+Another variable that isn't an Agent variable, yet so closely related
+that most will look for it here, this variable tells the summary
+buffer how to maneuver around undownloaded (only headers stored in the
+agent) and unfetched (neither article nor headers stored) articles.
-@lisp
-(require 'gnus-agent)
-(setq gnus-category-predicate-alist
- (append gnus-category-predicate-alist
- '((old . my-article-old-p))))
-@end lisp
+The valid values are @code{nil} (maneuver to any article),
+@code{undownloaded} (maneuvering while unplugged ignores articles that
+have not been fetched), @code{always-undownloaded} (maneuvering always
+ignores articles that have not been fetched), @code{unfetched}
+(maneuvering ignores articles whose headers have not been fetched).
-and simply specify your predicate as:
+@item gnus-agent-queue-mail
+@vindex gnus-agent-queue-mail
+When @code{gnus-agent-queue-mail} is @code{always}, Gnus will always
+queue mail rather than sending it straight away. When @code{t}, Gnus
+will queue mail when unplugged only. When @code{nil}, never queue
+mail. The default is @code{t}.
-@lisp
-(not old)
-@end lisp
+@item gnus-agent-prompt-send-queue
+@vindex gnus-agent-prompt-send-queue
+When @code{gnus-agent-prompt-send-queue} is non-@code{nil} Gnus will
+prompt you to confirm that you really wish to proceed if you hit
+@kbd{J S} while unplugged. The default is @code{nil}.
-If/when using something like the above, be aware that there are many
-misconfigured systems/mailers out there and so an article's date is not
-always a reliable indication of when it was posted. Hell, some people
-just don't give a damn.
+@item gnus-agent-auto-agentize-methods
+@vindex gnus-agent-auto-agentize-methods
+If you have never used the Agent before (or more technically, if
+@file{~/News/agent/lib/servers} does not exist), Gnus will
+automatically agentize a few servers for you. This variable control
+which back ends should be auto-agentized. It is typically only useful
+to agentize remote back ends. The auto-agentizing has the same effect
+as running @kbd{J a} on the servers (@pxref{Server Agent Commands}).
+If the file exist, you must manage the servers manually by adding or
+removing them, this variable is only applicable the first time you
+start Gnus. The default is @samp{(nntp nnimap)}.
-The above predicates apply to @emph{all} the groups which belong to the
-category. However, if you wish to have a specific predicate for an
-individual group within a category, or you're just too lazy to set up a
-new category, you can enter a group's individual predicate in its group
-parameters like so:
+@end table
-@lisp
-(agent-predicate . short)
-@end lisp
-This is the group/topic parameter equivalent of the agent category default.
-Note that when specifying a single word predicate like this, the
-@code{agent-predicate} specification must be in dotted pair notation.
+@node Example Setup
+@subsection Example Setup
-The equivalent of the longer example from above would be:
+If you don't want to read this manual, and you have a fairly standard
+setup, you may be able to use something like the following as your
+@file{~/.gnus.el} file to get started.
@lisp
-(agent-predicate or high (and (not low) (not long)))
-@end lisp
-
-The outer parenthesis required in the category specification are not
-entered here as, not being in dotted pair notation, the value of the
-predicate is assumed to be a list.
-
+;; @r{Define how Gnus is to fetch news. We do this over @acronym{NNTP}}
+;; @r{from your ISP's server.}
+(setq gnus-select-method '(nntp "news.your-isp.com"))
-Now, the syntax of the download score is the same as the syntax of
-normal score files, except that all elements that require actually
-seeing the article itself are verboten. This means that only the
-following headers can be scored on: @code{Subject}, @code{From},
-@code{Date}, @code{Message-ID}, @code{References}, @code{Chars},
-@code{Lines}, and @code{Xref}.
+;; @r{Define how Gnus is to read your mail. We read mail from}
+;; @r{your ISP's @acronym{POP} server.}
+(setq mail-sources '((pop :server "pop.your-isp.com")))
-As with predicates, the specification of the @code{download score rule}
-to use in respect of a group can be in either the category definition if
-it's to be applicable to all groups in therein, or a group's parameters
-if it's to be specific to that group.
+;; @r{Say how Gnus is to store the mail. We use nnml groups.}
+(setq gnus-secondary-select-methods '((nnml "")))
-In both of these places the @code{download score rule} can take one of
-three forms:
+;; @r{Make Gnus into an offline newsreader.}
+;; (gnus-agentize) ; @r{The obsolete setting.}
+;; (setq gnus-agent t) ; @r{Now the default.}
+@end lisp
-@enumerate
-@item
-Score rule
+That should be it, basically. Put that in your @file{~/.gnus.el} file,
+edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x
+gnus}.
-This has the same syntax as a normal Gnus score file except only a
-subset of scoring keywords are available as mentioned above.
+If this is the first time you've run Gnus, you will be subscribed
+automatically to a few default newsgroups. You'll probably want to
+subscribe to more groups, and to do that, you have to query the
+@acronym{NNTP} server for a complete list of groups with the @kbd{A A}
+command. This usually takes quite a while, but you only have to do it
+once.
-example:
+After reading and parsing a while, you'll be presented with a list of
+groups. Subscribe to the ones you want to read with the @kbd{u}
+command. @kbd{l} to make all the killed groups disappear after you've
+subscribe to all the groups you want to read. (@kbd{A k} will bring
+back all the killed groups.)
-@itemize @bullet
-@item
-Category specification
+You can now read the groups at once, or you can download the articles
+with the @kbd{J s} command. And then read the rest of this manual to
+find out which of the other gazillion things you want to customize.
-@lisp
-(("from"
- ("Lars Ingebrigtsen" 1000000 nil s))
-("lines"
- (500 -100 nil <)))
-@end lisp
-@item
-Group/Topic Parameter specification
+@node Batching Agents
+@subsection Batching Agents
+@findex gnus-agent-batch
-@lisp
-(agent-score ("from"
- ("Lars Ingebrigtsen" 1000000 nil s))
- ("lines"
- (500 -100 nil <)))
-@end lisp
+Having the Gnus Agent fetch articles (and post whatever messages you've
+written) is quite easy once you've gotten things set up properly. The
+following shell script will do everything that is necessary:
-Again, note the omission of the outermost parenthesis here.
-@end itemize
+You can run a complete batch command from the command line with the
+following incantation:
-@item
-Agent score file
+@example
+#!/bin/sh
+emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1
+@end example
-These score files must @emph{only} contain the permitted scoring
-keywords stated above.
-example:
+@node Agent Caveats
+@subsection Agent Caveats
-@itemize @bullet
-@item
-Category specification
+The Gnus Agent doesn't seem to work like most other offline
+newsreaders. Here are some common questions that some imaginary people
+may ask:
-@lisp
-("~/News/agent.SCORE")
-@end lisp
+@table @dfn
+@item If I read an article while plugged, do they get entered into the Agent?
-or perhaps
+@strong{No}. If you want this behavior, add
+@code{gnus-agent-fetch-selected-article} to
+@code{gnus-select-article-hook}.
-@lisp
-("~/News/agent.SCORE" "~/News/agent.group.SCORE")
-@end lisp
+@item If I read an article while plugged, and the article already exists in
+the Agent, will it get downloaded once more?
-@item
-Group Parameter specification
+@strong{No}, unless @code{gnus-agent-cache} is @code{nil}.
-@lisp
-(agent-score "~/News/agent.SCORE")
-@end lisp
+@end table
-Additional score files can be specified as above. Need I say anything
-about parenthesis?
-@end itemize
+In short, when Gnus is unplugged, it only looks into the locally stored
+articles; when it's plugged, it talks to your ISP and may also use the
+locally stored articles.
-@item
-Use @code{normal} score files
-If you don't want to maintain two sets of scoring rules for a group, and
-your desired @code{downloading} criteria for a group are the same as your
-@code{reading} criteria then you can tell the agent to refer to your
-@code{normal} score files when deciding what to download.
+@node Scoring
+@chapter Scoring
+@cindex scoring
-These directives in either the category definition or a group's
-parameters will cause the agent to read in all the applicable score
-files for a group, @emph{filtering out} those sections that do not
-relate to one of the permitted subset of scoring keywords.
+Other people use @dfn{kill files}, but we here at Gnus Towers like
+scoring better than killing, so we'd rather switch than fight. They do
+something completely different as well, so sit up straight and pay
+attention!
-@itemize @bullet
-@item
-Category Specification
+@vindex gnus-summary-mark-below
+All articles have a default score (@code{gnus-summary-default-score}),
+which is 0 by default. This score may be raised or lowered either
+interactively or by score files. Articles that have a score lower than
+@code{gnus-summary-mark-below} are marked as read.
-@lisp
-file
-@end lisp
+Gnus will read any @dfn{score files} that apply to the current group
+before generating the summary buffer.
-@item
-Group Parameter specification
+There are several commands in the summary buffer that insert score
+entries based on the current article. You can, for instance, ask Gnus to
+lower or increase the score of all articles with a certain subject.
-@lisp
-(agent-score . file)
-@end lisp
-@end itemize
-@end enumerate
+There are two sorts of scoring entries: Permanent and temporary.
+Temporary score entries are self-expiring entries. Any entries that are
+temporary and have not been used for, say, a week, will be removed
+silently to help keep the sizes of the score files down.
-@node Category Buffer
-@subsubsection Category Buffer
+@menu
+* Summary Score Commands:: Adding score entries for the current group.
+* Group Score Commands:: General score commands.
+* Score Variables:: Customize your scoring. (My, what terminology).
+* Score File Format:: What a score file may contain.
+* Score File Editing:: You can edit score files by hand as well.
+* Adaptive Scoring:: Big Sister Gnus knows what you read.
+* Home Score File:: How to say where new score entries are to go.
+* Followups To Yourself:: Having Gnus notice when people answer you.
+* Scoring On Other Headers:: Scoring on non-standard headers.
+* 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.
+* Converting Kill Files:: Translating kill files to score files.
+* Advanced Scoring:: Using logical expressions to build score rules.
+* Score Decays:: It can be useful to let scores wither away.
+@end menu
-You'd normally do all category maintenance from the category buffer.
-When you enter it for the first time (with the @kbd{J c} command from
-the group buffer), you'll only see the @code{default} category.
-The following commands are available in this buffer:
+@node Summary Score Commands
+@section Summary Score Commands
+@cindex score commands
-@table @kbd
-@item q
-@kindex q (Category)
-@findex gnus-category-exit
-Return to the group buffer (@code{gnus-category-exit}).
+The score commands that alter score entries do not actually modify real
+score files. That would be too inefficient. Gnus maintains a cache of
+previously loaded score files, one of which is considered the
+@dfn{current score file alist}. The score commands simply insert
+entries into this list, and upon group exit, this list is saved.
-@item e
-@kindex e (Category)
-@findex gnus-category-customize-category
-Use a customization buffer to set all of the selected category's
-parameters at one time (@code{gnus-category-customize-category}).
+The current score file is by default the group's local score file, even
+if no such score file actually exists. To insert score commands into
+some other score file (e.g. @file{all.SCORE}), you must first make this
+score file the current one.
-@item k
-@kindex k (Category)
-@findex gnus-category-kill
-Kill the current category (@code{gnus-category-kill}).
+General score commands that don't actually change the score file:
-@item c
-@kindex c (Category)
-@findex gnus-category-copy
-Copy the current category (@code{gnus-category-copy}).
+@table @kbd
-@item a
-@kindex a (Category)
-@findex gnus-category-add
-Add a new category (@code{gnus-category-add}).
+@item V s
+@kindex V s (Summary)
+@findex gnus-summary-set-score
+Set the score of the current article (@code{gnus-summary-set-score}).
-@item p
-@kindex p (Category)
-@findex gnus-category-edit-predicate
-Edit the predicate of the current category
-(@code{gnus-category-edit-predicate}).
+@item V S
+@kindex V S (Summary)
+@findex gnus-summary-current-score
+Display the score of the current article
+(@code{gnus-summary-current-score}).
-@item g
-@kindex g (Category)
-@findex gnus-category-edit-groups
-Edit the list of groups belonging to the current category
-(@code{gnus-category-edit-groups}).
+@item V t
+@kindex V t (Summary)
+@findex gnus-score-find-trace
+Display all score rules that have been used on the current article
+(@code{gnus-score-find-trace}). In the @code{*Score Trace*} buffer, you
+may type @kbd{e} to edit score file corresponding to the score rule on
+current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the
+score file and edit it.
-@item s
-@kindex s (Category)
-@findex gnus-category-edit-score
-Edit the download score rule of the current category
-(@code{gnus-category-edit-score}).
+@item V w
+@kindex V w (Summary)
+@findex gnus-score-find-favourite-words
+List words used in scoring (@code{gnus-score-find-favourite-words}).
-@item l
-@kindex l (Category)
-@findex gnus-category-list
-List all the categories (@code{gnus-category-list}).
-@end table
+@item V R
+@kindex V R (Summary)
+@findex gnus-summary-rescore
+Run the current summary through the scoring process
+(@code{gnus-summary-rescore}). This might be useful if you're playing
+around with your score files behind Gnus' back and want to see the
+effect you're having.
+@item V c
+@kindex V c (Summary)
+@findex gnus-score-change-score-file
+Make a different score file the current
+(@code{gnus-score-change-score-file}).
-@node Category Variables
-@subsubsection Category Variables
+@item V e
+@kindex V e (Summary)
+@findex gnus-score-edit-current-scores
+Edit the current score file (@code{gnus-score-edit-current-scores}).
+You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
+File Editing}).
-@table @code
-@item gnus-category-mode-hook
-@vindex gnus-category-mode-hook
-Hook run in category buffers.
+@item V f
+@kindex V f (Summary)
+@findex gnus-score-edit-file
+Edit a score file and make this score file the current one
+(@code{gnus-score-edit-file}).
-@item gnus-category-line-format
-@vindex gnus-category-line-format
-Format of the lines in the category buffer (@pxref{Formatting
-Variables}). Valid elements are:
+@item V F
+@kindex V F (Summary)
+@findex gnus-score-flush-cache
+Flush the score cache (@code{gnus-score-flush-cache}). This is useful
+after editing score files.
-@table @samp
-@item c
-The name of the category.
+@item V C
+@kindex V C (Summary)
+@findex gnus-score-customize
+Customize a score file in a visually pleasing manner
+(@code{gnus-score-customize}).
-@item g
-The number of groups in the category.
@end table
-@item gnus-category-mode-line-format
-@vindex gnus-category-mode-line-format
-Format of the category mode line (@pxref{Mode Line Formatting}).
+The rest of these commands modify the local score file.
-@item gnus-agent-short-article
-@vindex gnus-agent-short-article
-Articles that have fewer lines than this are short. Default 100.
+@table @kbd
-@item gnus-agent-long-article
-@vindex gnus-agent-long-article
-Articles that have more lines than this are long. Default 200.
+@item V m
+@kindex V m (Summary)
+@findex gnus-score-set-mark-below
+Prompt for a score, and mark all articles with a score below this as
+read (@code{gnus-score-set-mark-below}).
-@item gnus-agent-low-score
-@vindex gnus-agent-low-score
-Articles that have a score lower than this have a low score. Default
-0.
+@item V x
+@kindex V x (Summary)
+@findex gnus-score-set-expunge-below
+Prompt for a score, and add a score rule to the current score file to
+expunge all articles below this score
+(@code{gnus-score-set-expunge-below}).
+@end table
-@item gnus-agent-high-score
-@vindex gnus-agent-high-score
-Articles that have a score higher than this have a high score. Default
-0.
+The keystrokes for actually making score entries follow a very regular
+pattern, so there's no need to list all the commands. (Hundreds of
+them.)
-@item gnus-agent-expire-days
-@vindex gnus-agent-expire-days
-The number of days that a @samp{read} article must stay in the agent's
-local disk before becoming eligible for expiration (While the name is
-the same, this doesn't mean expiring the article on the server. It
-just means deleting the local copy of the article). What is also
-important to understand is that the counter starts with the time the
-article was written to the local disk and not the time the article was
-read.
-Default 7.
+@findex gnus-summary-increase-score
+@findex gnus-summary-lower-score
-@item gnus-agent-enable-expiration
-@vindex gnus-agent-enable-expiration
-Determines whether articles in a group are, by default, expired or
-retained indefinitely. The default is @code{ENABLE} which means that
-you'll have to disable expiration when desired. On the other hand,
-you could set this to @code{DISABLE}. In that case, you would then
-have to enable expiration in selected groups.
+@enumerate
+@item
+The first key is either @kbd{I} (upper case i) for increasing the score
+or @kbd{L} for lowering the score.
+@item
+The second key says what header you want to score on. The following
+keys are available:
+@table @kbd
-@end table
+@item a
+Score on the author name.
+@item s
+Score on the subject line.
-@node Agent Commands
-@subsection Agent Commands
-@findex gnus-agent-toggle-plugged
-@kindex J j (Agent)
+@item x
+Score on the @code{Xref} line---i.e., the cross-posting line.
-All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j}
-(@code{gnus-agent-toggle-plugged}) command works in all modes, and
-toggles the plugged/unplugged state of the Gnus Agent.
+@item r
+Score on the @code{References} line.
+@item d
+Score on the date.
-@menu
-* Group Agent Commands:: Configure groups and fetch their contents.
-* Summary Agent Commands:: Manually select then fetch specific articles.
-* Server Agent Commands:: Select the servers that are supported by the agent.
-@end menu
+@item l
+Score on the number of lines.
+@item i
+Score on the @code{Message-ID} header.
+@item e
+Score on an ``extra'' header, that is, one of those in gnus-extra-headers,
+if your @acronym{NNTP} server tracks additional header data in overviews.
+@item f
+Score on followups---this matches the author name, and adds scores to
+the followups to this author. (Using this key leads to the creation of
+@file{ADAPT} files.)
-@node Group Agent Commands
-@subsubsection Group Agent Commands
+@item b
+Score on the body.
-@table @kbd
-@item J u
-@kindex J u (Agent Group)
-@findex gnus-agent-fetch-groups
-Fetch all eligible articles in the current group
-(@code{gnus-agent-fetch-groups}).
+@item h
+Score on the head.
-@item J c
-@kindex J c (Agent Group)
-@findex gnus-enter-category-buffer
-Enter the Agent category buffer (@code{gnus-enter-category-buffer}).
+@item t
+Score on thread. (Using this key leads to the creation of @file{ADAPT}
+files.)
-@item J s
-@kindex J s (Agent Group)
-@findex gnus-agent-fetch-session
-Fetch all eligible articles in all groups
-(@code{gnus-agent-fetch-session}).
+@end table
-@item J S
-@kindex J S (Agent Group)
-@findex gnus-group-send-queue
-Send all sendable messages in the queue group
-(@code{gnus-group-send-queue}). @xref{Drafts}.
+@item
+The third key is the match type. Which match types are valid depends on
+what headers you are scoring on.
-@item J a
-@kindex J a (Agent Group)
-@findex gnus-agent-add-group
-Add the current group to an Agent category
-(@code{gnus-agent-add-group}). This command understands the
-process/prefix convention (@pxref{Process/Prefix}).
+@table @code
-@item J r
-@kindex J r (Agent Group)
-@findex gnus-agent-remove-group
-Remove the current group from its category, if any
-(@code{gnus-agent-remove-group}). This command understands the
-process/prefix convention (@pxref{Process/Prefix}).
+@item strings
+
+@table @kbd
-@item J Y
-@kindex J Y (Agent Group)
-@findex gnus-agent-synchronize-flags
-Synchronize flags changed while unplugged with remote server, if any.
+@item e
+Exact matching.
+
+@item s
+Substring matching.
+@item f
+Fuzzy matching (@pxref{Fuzzy Matching}).
+@item r
+Regexp matching
@end table
+@item date
+@table @kbd
-@node Summary Agent Commands
-@subsubsection Summary Agent Commands
+@item b
+Before date.
+
+@item a
+After date.
+
+@item n
+This date.
+@end table
+@item number
@table @kbd
-@item J #
-@kindex J # (Agent Summary)
-@findex gnus-agent-mark-article
-Mark the article for downloading (@code{gnus-agent-mark-article}).
-@item J M-#
-@kindex J M-# (Agent Summary)
-@findex gnus-agent-unmark-article
-Remove the downloading mark from the article
-(@code{gnus-agent-unmark-article}).
+@item <
+Less than number.
-@cindex %
-@item @@
-@kindex @@ (Agent Summary)
-@findex gnus-agent-toggle-mark
-Toggle whether to download the article
-(@code{gnus-agent-toggle-mark}). The download mark is @samp{%} by
-default.
+@item =
+Equal to number.
-@item J c
-@kindex J c (Agent Summary)
-@findex gnus-agent-catchup
-Mark all articles as read (@code{gnus-agent-catchup}) that are neither cached, downloaded, nor downloadable.
+@item >
+Greater than number.
+@end table
+@end table
-@item J S
-@kindex J S (Agent Summary)
-@findex gnus-agent-fetch-group
-Download all eligible (@pxref{Agent Categories}) articles in this group.
-(@code{gnus-agent-fetch-group}).
+@item
+The fourth and usually final key says whether this is a temporary (i.e.,
+expiring) score entry, or a permanent (i.e., non-expiring) score entry,
+or whether it is to be done immediately, without adding to the score
+file.
+@table @kbd
-@item J s
-@kindex J s (Agent Summary)
-@findex gnus-agent-summary-fetch-series
-Download all processable articles in this group.
-(@code{gnus-agent-summary-fetch-series}).
+@item t
+Temporary score entry.
-@item J u
-@kindex J u (Agent Summary)
-@findex gnus-agent-summary-fetch-group
-Download all downloadable articles in the current group
-(@code{gnus-agent-summary-fetch-group}).
+@item p
+Permanent score entry.
+@item i
+Immediately scoring.
@end table
+@item
+If you are scoring on `e' (extra) headers, you will then be prompted for
+the header name on which you wish to score. This must be a header named
+in gnus-extra-headers, and @samp{TAB} completion is available.
-@node Server Agent Commands
-@subsubsection Server Agent Commands
-
-@table @kbd
-@item J a
-@kindex J a (Agent Server)
-@findex gnus-agent-add-server
-Add the current server to the list of servers covered by the Gnus Agent
-(@code{gnus-agent-add-server}).
+@end enumerate
-@item J r
-@kindex J r (Agent Server)
-@findex gnus-agent-remove-server
-Remove the current server from the list of servers covered by the Gnus
-Agent (@code{gnus-agent-remove-server}).
+So, let's say you want to increase the score on the current author with
+exact matching permanently: @kbd{I a e p}. If you want to lower the
+score based on the subject line, using substring matching, and make a
+temporary score entry: @kbd{L s s t}. Pretty easy.
-@end table
+To make things a bit more complicated, there are shortcuts. If you use
+a capital letter on either the second or third keys, Gnus will use
+defaults for the remaining one or two keystrokes. The defaults are
+``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s
+t}, and @kbd{I a R} is the same as @kbd{I a r t}.
+These functions take both the numerical prefix and the symbolic prefix
+(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower
+(or increase) the score of the article. A symbolic prefix of @code{a}
+says to use the @file{all.SCORE} file for the command instead of the
+current score file.
-@node Agent Visuals
-@subsection Agent Visuals
+@vindex gnus-score-mimic-keymap
+The @code{gnus-score-mimic-keymap} says whether these commands will
+pretend they are keymaps or not.
-If you open a summary while unplugged and, Gnus knows from the group's
-active range that there are more articles than the headers currently
-stored in the Agent, you may see some articles whose subject looks
-something like @samp{[Undownloaded article #####]}. These are
-placeholders for the missing headers. Aside from setting a mark,
-there is not much that can be done with one of these placeholders.
-When Gnus finally gets a chance to fetch the group's headers, the
-placeholders will automatically be replaced by the actual headers.
-You can configure the summary buffer's maneuvering to skip over the
-placeholders if you care (See @code{gnus-auto-goto-ignores}).
-While it may be obvious to all, the only headers and articles
-available while unplugged are those headers and articles that were
-fetched into the Agent while previously plugged. To put it another
-way, ``If you forget to fetch something while plugged, you might have a
-less than satisfying unplugged session''. For this reason, the Agent
-adds two visual effects to your summary buffer. These effects display
-the download status of each article so that you always know which
-articles will be available when unplugged.
+@node Group Score Commands
+@section Group Score Commands
+@cindex group score commands
-The first visual effect is the @samp{%O} spec. If you customize
-@code{gnus-summary-line-format} to include this specifier, you will add
-a single character field that indicates an article's download status.
-Articles that have been fetched into either the Agent or the Cache,
-will display @code{gnus-downloaded-mark} (defaults to @samp{+}). All
-other articles will display @code{gnus-undownloaded-mark} (defaults to
-@samp{-}). If you open a group that has not been agentized, a space
-(@samp{ }) will be displayed.
+There aren't many of these as yet, I'm afraid.
-The second visual effect are the undownloaded faces. The faces, there
-are three indicating the article's score (low, normal, high), seem to
-result in a love/hate response from many Gnus users. The problem is
-that the face selection is controlled by a list of condition tests and
-face names (See @code{gnus-summary-highlight}). Each condition is
-tested in the order in which it appears in the list so early
-conditions have precedence over later conditions. All of this means
-that, if you tick an undownloaded article, the article will continue
-to be displayed in the undownloaded face rather than the ticked face.
+@table @kbd
-If you use the Agent as a cache (to avoid downloading the same article
-each time you visit it or to minimize your connection time), the
-undownloaded face will probably seem like a good idea. The reason
-being that you do all of our work (marking, reading, deleting) with
-downloaded articles so the normal faces always appear. For those
-users using the agent to improve online performance by caching the NOV
-database (most users since 5.10.2), the undownloaded faces may appear
-to be an absolutely horrible idea. The issue being that, since none
-of their articles have been fetched into the Agent, all of the
-normal faces will be obscured by the undownloaded faces.
+@item W e
+@kindex W e (Group)
+@findex gnus-score-edit-all-score
+Edit the apply-to-all-groups all.SCORE file. You will be popped into
+a @code{gnus-score-mode} buffer (@pxref{Score File Editing}).
-If you would like to use the undownloaded faces, you must enable the
-undownloaded faces by setting the @code{agent-enable-undownloaded-faces}
-group parameter to @code{t}. This parameter, like all other agent
-parameters, may be set on an Agent Category (@pxref{Agent Categories}),
-a Group Topic (@pxref{Topic Parameters}), or an individual group
-(@pxref{Group Parameters}).
+@item W f
+@kindex W f (Group)
+@findex gnus-score-flush-cache
+Gnus maintains a cache of score alists to avoid having to reload them
+all the time. This command will flush the cache
+(@code{gnus-score-flush-cache}).
-The one problem common to all users using the agent is how quickly it
-can consume disk space. If you using the agent on many groups, it is
-even more difficult to effectively recover disk space. One solution
-is the @samp{%F} format available in @code{gnus-group-line-format}.
-This format will display the actual disk space used by articles
-fetched into both the agent and cache. By knowing which groups use
-the most space, users know where to focus their efforts when ``agent
-expiring'' articles.
+@end table
-@node Agent as Cache
-@subsection Agent as Cache
+You can do scoring from the command line by saying something like:
-When Gnus is plugged, it is not efficient to download headers or
-articles from the server again, if they are already stored in the
-Agent. So, Gnus normally only downloads headers once, and stores them
-in the Agent. These headers are later used when generating the summary
-buffer, regardless of whether you are plugged or unplugged. Articles
-are not cached in the Agent by default though (that would potentially
-consume lots of disk space), but if you have already downloaded an
-article into the Agent, Gnus will not download the article from the
-server again but use the locally stored copy instead.
+@findex gnus-batch-score
+@cindex batch scoring
+@example
+$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score
+@end example
-If you so desire, you can configure the agent (see @code{gnus-agent-cache}
-@pxref{Agent Variables}) to always download headers and articles while
-plugged. Gnus will almost certainly be slower, but it will be kept
-synchronized with the server. That last point probably won't make any
-sense if you are using a nntp or nnimap back end.
-@node Agent Expiry
-@subsection Agent Expiry
+@node Score Variables
+@section Score Variables
+@cindex score variables
-@vindex gnus-agent-expire-days
-@findex gnus-agent-expire
-@kindex M-x gnus-agent-expire
-@kindex M-x gnus-agent-expire-group
-@findex gnus-agent-expire-group
-@cindex agent expiry
-@cindex Gnus agent expiry
-@cindex expiry, in Gnus agent
+@table @code
-The Agent back end, @code{nnagent}, doesn't handle expiry. Well, at
-least it doesn't handle it like other back ends. Instead, there are
-special @code{gnus-agent-expire} and @code{gnus-agent-expire-group}
-commands that will expire all read articles that are older than
-@code{gnus-agent-expire-days} days. They can be run whenever you feel
-that you're running out of space. Neither are particularly fast or
-efficient, and it's not a particularly good idea to interrupt them (with
-@kbd{C-g} or anything else) once you've started one of them.
+@item gnus-use-scoring
+@vindex gnus-use-scoring
+If @code{nil}, Gnus will not check for score files, and will not, in
+general, do any score-related work. This is @code{t} by default.
-Note that other functions, e.g. @code{gnus-request-expire-articles},
-might run @code{gnus-agent-expire} for you to keep the agent
-synchronized with the group.
+@item gnus-kill-killed
+@vindex gnus-kill-killed
+If this variable is @code{nil}, Gnus will never apply score files to
+articles that have already been through the kill process. While this
+may save you lots of time, it also means that if you apply a kill file
+to a group, and then change the kill file and want to run it over you
+group again to kill more articles, it won't work. You have to set this
+variable to @code{t} to do that. (It is @code{t} by default.)
-The agent parameter @code{agent-enable-expiration} may be used to
-prevent expiration in selected groups.
+@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 @env{SAVEDIR} environment variable by default.
+This is @file{~/News/} by default.
-@vindex gnus-agent-expire-all
-If @code{gnus-agent-expire-all} is non-@code{nil}, the agent
-expiration commands will expire all articles---unread, read, ticked
-and dormant. If @code{nil} (which is the default), only read articles
-are eligible for expiry, and unread, ticked and dormant articles will
-be kept indefinitely.
+@item gnus-score-file-suffix
+@vindex gnus-score-file-suffix
+Suffix to add to the group name to arrive at the score file name
+(@file{SCORE} by default.)
-If you find that some articles eligible for expiry are never expired,
-perhaps some Gnus Agent files are corrupted. There's are special
-commands, @code{gnus-agent-regenerate} and
-@code{gnus-agent-regenerate-group}, to fix possible problems.
+@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, this might make your Emacs grow big and
+bloated, so this regexp can be used to weed out score files 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.
-@node Agent Regeneration
-@subsection Agent Regeneration
+@item gnus-save-score
+@vindex gnus-save-score
+If you have really complicated score files, and do lots of batch
+scoring, then you might set this variable to @code{t}. This will make
+Gnus save the scores into the @file{.newsrc.eld} file.
-@cindex agent regeneration
-@cindex Gnus agent regeneration
-@cindex regeneration
+If you do not set this to @code{t}, then manual scores (like those set
+with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved
+across group visits.
-The local data structures used by @code{nnagent} may become corrupted
-due to certain exceptional conditions. When this happens,
-@code{nnagent} functionality may degrade or even fail. The solution
-to this problem is to repair the local data structures by removing all
-internal inconsistencies.
+@item gnus-score-interactive-default-score
+@vindex gnus-score-interactive-default-score
+Score used by all the interactive raise/lower commands to raise/lower
+score with. Default is 1000, which may seem excessive, but this is to
+ensure that the adaptive scoring scheme gets enough room to play with.
+We don't want the small changes from the adaptive scoring to overwrite
+manually entered data.
-For example, if your connection to your server is lost while
-downloaded articles into the agent, the local data structures will not
-know about articles successfully downloaded prior to the connection
-failure. Running @code{gnus-agent-regenerate} or
-@code{gnus-agent-regenerate-group} will update the data structures
-such that you don't need to download these articles a second time.
+@item gnus-summary-default-score
+@vindex gnus-summary-default-score
+Default score of an article, which is 0 by default.
-@findex gnus-agent-regenerate
-@kindex M-x gnus-agent-regenerate
-The command @code{gnus-agent-regenerate} will perform
-@code{gnus-agent-regenerate-group} on every agentized group. While
-you can run @code{gnus-agent-regenerate} in any buffer, it is strongly
-recommended that you first close all summary buffers.
+@item gnus-summary-expunge-below
+@vindex gnus-summary-expunge-below
+Don't display the summary lines of articles that have scores lower than
+this variable. This is @code{nil} by default, which means that no
+articles will be hidden. This variable is local to the summary buffers,
+and has to be set from @code{gnus-summary-mode-hook}.
-@findex gnus-agent-regenerate-group
-@kindex M-x gnus-agent-regenerate-group
-The command @code{gnus-agent-regenerate-group} uses the local copies
-of individual articles to repair the local @acronym{NOV}(header) database. It
-then updates the internal data structures that document which articles
-are stored locally. An optional argument will mark articles in the
-agent as unread.
+@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{+}.
-@node Agent and flags
-@subsection Agent and flags
+@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{-}.
-The Agent works with any Gnus back end including those, such as
-nnimap, that store flags (read, ticked, etc) on the server. Sadly,
-the Agent does not actually know which backends keep their flags in
-the backend server rather than in @file{.newsrc}. This means that the
-Agent, while unplugged or disconnected, will always record all changes
-to the flags in its own files.
+@item gnus-score-find-score-files-function
+@vindex gnus-score-find-score-files-function
+Function used to find score files for the current group. This function
+is called with the name of the group as the argument.
-When you plug back in, Gnus will then check to see if you have any
-changed any flags and ask if you wish to synchronize these with the
-server. This behavior is customizable by @code{gnus-agent-synchronize-flags}.
+Predefined functions available are:
+@table @code
-@vindex gnus-agent-synchronize-flags
-If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will
-never automatically synchronize flags. If it is @code{ask}, which is
-the default, the Agent will check if you made any changes and if so
-ask if you wish to synchronize these when you re-connect. If it has
-any other value, all flags will be synchronized automatically.
+@item gnus-score-find-single
+@findex gnus-score-find-single
+Only apply the group's own score file.
-If you do not wish to synchronize flags automatically when you
-re-connect, you can do it manually with the
-@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y}
-in the group buffer.
+@item gnus-score-find-bnews
+@findex gnus-score-find-bnews
+Apply all score files that match, using bnews syntax. This is the
+default. If the current group is @samp{gnu.emacs.gnus}, for instance,
+@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
+@file{gnu.all.SCORE} would all apply. In short, the instances of
+@samp{all} in the score file names are translated into @samp{.*}, and
+then a regexp match is done.
-Technical note: the synchronization algorithm does not work by ``pushing''
-all local flags to the server, but rather by incrementally updated the
-server view of flags by changing only those flags that were changed by
-the user. Thus, if you set one flag on an article, quit the group then
-re-select the group and remove the flag; the flag will be set and
-removed from the server when you ``synchronize''. The queued flag
-operations can be found in the per-server @code{flags} file in the Agent
-directory. It's emptied when you synchronize flags.
+This means that if you have some score entries that you want to apply to
+all groups, then you put those entries in the @file{all.SCORE} file.
-@node Agent and IMAP
-@subsection Agent and IMAP
+The score files are applied in a semi-random order, although Gnus will
+try to apply the more general score files before the more specific score
+files. It does this by looking at the number of elements in the score
+file names---discarding the @samp{all} elements.
-The Agent works with any Gnus back end, including nnimap. However,
-since there are some conceptual differences between @acronym{NNTP} and
-@acronym{IMAP}, this section (should) provide you with some information to
-make Gnus Agent work smoother as a @acronym{IMAP} Disconnected Mode client.
+@item gnus-score-find-hierarchical
+@findex gnus-score-find-hierarchical
+Apply all score files from all the parent groups. This means that you
+can't have score files like @file{all.SCORE}, but you can have
+@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE} for each
+server.
-Some things are currently not implemented in the Agent that you'd might
-expect from a disconnected @acronym{IMAP} client, including:
+@end table
+This variable can also be a list of functions. In that case, all
+these functions will be called with the group name as argument, and
+all the returned lists of score files will be applied. These
+functions can also return lists of lists of score alists directly. In
+that case, the functions that return these non-file score alists
+should probably be placed before the ``real'' score file functions, to
+ensure that the last score file returned is the local score file.
+Phu.
-@itemize @bullet
+For example, to do hierarchical scoring but use a non-server-specific
+overall score file, you could use the value
+@example
+(list (lambda (group) ("all.SCORE"))
+ 'gnus-score-find-hierarchical)
+@end example
-@item
-Copying/moving articles into nnimap groups when unplugged.
+@item gnus-score-expiry-days
+@vindex gnus-score-expiry-days
+This variable says how many days should pass before an unused score file
+entry is expired. If this variable is @code{nil}, no score file entries
+are expired. It's 7 by default.
-@item
-Creating/deleting nnimap groups when unplugged.
+@item gnus-update-score-entry-dates
+@vindex gnus-update-score-entry-dates
+If this variable is non-@code{nil}, temporary score entries that have
+been triggered (matched) will have their dates updated. (This is how Gnus
+controls expiry---all non-matched-entries will become too old while
+matched entries will stay fresh and young.) However, if you set this
+variable to @code{nil}, even matched entries will grow old and will
+have to face that oh-so grim reaper.
-@end itemize
+@item gnus-score-after-write-file-function
+@vindex gnus-score-after-write-file-function
+Function called with the name of the score file just written.
-@node Outgoing Messages
-@subsection Outgoing Messages
+@item gnus-score-thread-simplify
+@vindex gnus-score-thread-simplify
+If this variable is non-@code{nil}, article subjects will be
+simplified for subject scoring purposes in the same manner as with
+threading---according to the current value of
+@code{gnus-simplify-subject-functions}. If the scoring entry uses
+@code{substring} or @code{exact} matching, the match will also be
+simplified in this manner.
-By default, when Gnus is unplugged, all outgoing messages (both mail
-and news) are stored in the draft group ``queue'' (@pxref{Drafts}).
-You can view them there after posting, and edit them at will.
+@end table
-You can control the circumstances under which outgoing mail is queued
-(see @code{gnus-agent-queue-mail}, @pxref{Agent Variables}). Outgoing
-news is always queued when Gnus is unplugged, and never otherwise.
-You can send the messages either from the draft group with the special
-commands available there, or you can use the @kbd{J S} command in the
-group buffer to send all the sendable messages in the draft group.
-Posting news will only work when Gnus is plugged, but you can send
-mail at any time.
+@node Score File Format
+@section Score File Format
+@cindex score file format
-If sending mail while unplugged does not work for you and you worry
-about hitting @kbd{J S} by accident when unplugged, you can have Gnus
-ask you to confirm your action (see
-@code{gnus-agent-prompt-send-queue}, @pxref{Agent Variables}).
+A score file is an @code{emacs-lisp} file that normally contains just a
+single form. Casual users are not expected to edit these files;
+everything can be changed from the summary buffer.
-@node Agent Variables
-@subsection Agent Variables
+Anyway, if you'd like to dig into it yourself, here's an example:
-@table @code
-@item gnus-agent
-@vindex gnus-agent
-Is the agent enabled? The default is @code{t}. When first enabled,
-the agent will use @code{gnus-agent-auto-agentize-methods} to
-automatically mark some back ends as agentized. You may change which
-back ends are agentized using the agent commands in the server buffer.
+@lisp
+(("from"
+ ("Lars Ingebrigtsen" -10000)
+ ("Per Abrahamsen")
+ ("larsi\\|lmi" -50000 nil R))
+ ("subject"
+ ("Ding is Badd" nil 728373))
+ ("xref"
+ ("alt.politics" -1000 728372 s))
+ ("lines"
+ (2 -100 nil <))
+ (mark 0)
+ (expunge -1000)
+ (mark-and-expunge -10)
+ (read-only nil)
+ (orphan -10)
+ (adapt t)
+ (files "/hom/larsi/News/gnu.SCORE")
+ (exclude-files "all.SCORE")
+ (local (gnus-newsgroup-auto-expire t)
+ (gnus-summary-make-false-root empty))
+ (eval (ding)))
+@end lisp
-To enter the server buffer, use the @kbd{^}
-(@code{gnus-group-enter-server-mode}) command in the group buffer.
+This example demonstrates most score file elements. @xref{Advanced
+Scoring}, for a different approach.
+Even though this looks much like Lisp code, nothing here is actually
+@code{eval}ed. The Lisp reader is used to read this form, though, so it
+has to be valid syntactically, if not semantically.
-@item gnus-agent-directory
-@vindex gnus-agent-directory
-Where the Gnus Agent will store its files. The default is
-@file{~/News/agent/}.
+Six keys are supported by this alist:
-@item gnus-agent-handle-level
-@vindex gnus-agent-handle-level
-Groups on levels (@pxref{Group Levels}) higher than this variable will
-be ignored by the Agent. The default is @code{gnus-level-subscribed},
-which means that only subscribed group will be considered by the Agent
-by default.
+@table @code
-@item gnus-agent-plugged-hook
-@vindex gnus-agent-plugged-hook
-Hook run when connecting to the network.
+@item STRING
+If the key is a string, it is the name of the header to perform the
+match on. Scoring can only be performed on these eight headers:
+@code{From}, @code{Subject}, @code{References}, @code{Message-ID},
+@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to
+these headers, there are three strings to tell Gnus to fetch the entire
+article and do the match on larger parts of the article: @code{Body}
+will perform the match on the body of the article, @code{Head} will
+perform the match on the head of the article, and @code{All} will
+perform the match on the entire article. Note that using any of these
+last three keys will slow down group entry @emph{considerably}. The
+final ``header'' you can score on is @code{Followup}. These score
+entries will result in new score entries being added for all follow-ups
+to articles that matches these score entries.
-@item gnus-agent-unplugged-hook
-@vindex gnus-agent-unplugged-hook
-Hook run when disconnecting from the network.
+Following this key is an arbitrary number of score entries, where each
+score entry has one to four elements.
+@enumerate
-@item gnus-agent-fetched-hook
-@vindex gnus-agent-fetched-hook
-Hook run when finished fetching articles.
+@item
+The first element is the @dfn{match element}. On most headers this will
+be a string, but on the Lines and Chars headers, this must be an
+integer.
-@item gnus-agent-cache
-@vindex gnus-agent-cache
-Variable to control whether use the locally stored @acronym{NOV} and
-articles when plugged, e.g. essentially using the Agent as a cache.
-The default is non-@code{nil}, which means to use the Agent as a cache.
+@item
+If the second element is present, it should be a number---the @dfn{score
+element}. This number should be an integer in the neginf to posinf
+interval. This number is added to the score of the article if the match
+is successful. If this element is not present, the
+@code{gnus-score-interactive-default-score} number will be used
+instead. This is 1000 by default.
-@item gnus-agent-go-online
-@vindex gnus-agent-go-online
-If @code{gnus-agent-go-online} is @code{nil}, the Agent will never
-automatically switch offline servers into online status. If it is
-@code{ask}, the default, the Agent will ask if you wish to switch
-offline servers into online status when you re-connect. If it has any
-other value, all offline servers will be automatically switched into
-online status.
+@item
+If the third element is present, it should be a number---the @dfn{date
+element}. This date says when the last time this score entry matched,
+which provides a mechanism for expiring the score entries. It this
+element is not present, the score entry is permanent. The date is
+represented by the number of days since December 31, 1 BCE.
-@item gnus-agent-mark-unread-after-downloaded
-@vindex gnus-agent-mark-unread-after-downloaded
-If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil},
-mark articles as unread after downloading. This is usually a safe
-thing to do as the newly downloaded article has obviously not been
-read. The default is @code{t}.
+@item
+If the fourth element is present, it should be a symbol---the @dfn{type
+element}. This element specifies what function should be used to see
+whether this score entry matches the article. What match types that can
+be used depends on what header you wish to perform the match on.
+@table @dfn
-@item gnus-agent-synchronize-flags
-@vindex gnus-agent-synchronize-flags
-If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will
-never automatically synchronize flags. If it is @code{ask}, which is
-the default, the Agent will check if you made any changes and if so
-ask if you wish to synchronize these when you re-connect. If it has
-any other value, all flags will be synchronized automatically.
+@item From, Subject, References, Xref, Message-ID
+For most header types, there are the @code{r} and @code{R} (regexp), as
+well as @code{s} and @code{S} (substring) types, and @code{e} and
+@code{E} (exact match), and @code{w} (word match) types. If this
+element is not present, Gnus will assume that substring matching should
+be used. @code{R}, @code{S}, and @code{E} differ from the others in
+that the matches will be done in a case-sensitive manner. All these
+one-letter types are really just abbreviations for the @code{regexp},
+@code{string}, @code{exact}, and @code{word} types, which you can use
+instead, if you feel like.
-@item gnus-agent-consider-all-articles
-@vindex gnus-agent-consider-all-articles
-If @code{gnus-agent-consider-all-articles} is non-@code{nil}, the
-agent will let the agent predicate decide whether articles need to be
-downloaded or not, for all articles. When @code{nil}, the default,
-the agent will only let the predicate decide whether unread articles
-are downloaded or not. If you enable this, you may also want to look
-into the agent expiry settings (@pxref{Category Variables}), so that
-the agent doesn't download articles which the agent will later expire,
-over and over again.
+@item Extra
+Just as for the standard string overview headers, if you are using
+gnus-extra-headers, you can score on these headers' values. In this
+case, there is a 5th element in the score entry, being the name of the
+header to be scored. The following entry is useful in your
+@file{all.SCORE} file in case of spam attacks from a single origin
+host, if your @acronym{NNTP} server tracks @samp{NNTP-Posting-Host} in
+overviews:
-@item gnus-agent-max-fetch-size
-@vindex gnus-agent-max-fetch-size
-The agent fetches articles into a temporary buffer prior to parsing
-them into individual files. To avoid exceeding the max. buffer size,
-the agent alternates between fetching and parsing until all articles
-have been fetched. @code{gnus-agent-max-fetch-size} provides a size
-limit to control how often the cycling occurs. A large value improves
-performance. A small value minimizes the time lost should the
-connection be lost while fetching (You may need to run
-@code{gnus-agent-regenerate-group} to update the group's state.
-However, all articles parsed prior to loosing the connection will be
-available while unplugged). The default is 10M so it is unusual to
-see any cycling.
+@lisp
+("111.222.333.444" -1000 nil s
+ "NNTP-Posting-Host")
+@end lisp
-@item gnus-server-unopen-status
-@vindex gnus-server-unopen-status
-Perhaps not an Agent variable, but closely related to the Agent, this
-variable says what will happen if Gnus cannot open a server. If the
-Agent is enabled, the default, @code{nil}, makes Gnus ask the user
-whether to deny the server or whether to unplug the agent. If the
-Agent is disabled, Gnus always simply deny the server. Other choices
-for this variable include @code{denied} and @code{offline} the latter
-is only valid if the Agent is used.
+@item Lines, Chars
+These two headers use different match types: @code{<}, @code{>},
+@code{=}, @code{>=} and @code{<=}.
-@item gnus-auto-goto-ignores
-@vindex gnus-auto-goto-ignores
-Another variable that isn't an Agent variable, yet so closely related
-that most will look for it here, this variable tells the summary
-buffer how to maneuver around undownloaded (only headers stored in the
-agent) and unfetched (neither article nor headers stored) articles.
+These predicates are true if
-The valid values are @code{nil} (maneuver to any article),
-@code{undownloaded} (maneuvering while unplugged ignores articles that
-have not been fetched), @code{always-undownloaded} (maneuvering always
-ignores articles that have not been fetched), @code{unfetched}
-(maneuvering ignores articles whose headers have not been fetched).
+@example
+(PREDICATE HEADER MATCH)
+@end example
-@item gnus-agent-queue-mail
-@vindex gnus-agent-queue-mail
-When @code{gnus-agent-queue-mail} is @code{always}, Gnus will always
-queue mail rather than sending it straight away. When @code{t}, Gnus
-will queue mail when unplugged only. When @code{nil}, never queue
-mail. The default is @code{t}.
+evaluates to non-@code{nil}. For instance, the advanced match
+@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the
+following form:
-@item gnus-agent-prompt-send-queue
-@vindex gnus-agent-prompt-send-queue
-When @code{gnus-agent-prompt-send-queue} is non-@code{nil} Gnus will
-prompt you to confirm that you really wish to proceed if you hit
-@kbd{J S} while unplugged. The default is @code{nil}.
+@lisp
+(< header-value 4)
+@end lisp
-@item gnus-agent-auto-agentize-methods
-@vindex gnus-agent-auto-agentize-methods
-If you have never used the Agent before (or more technically, if
-@file{~/News/agent/lib/servers} does not exist), Gnus will
-automatically agentize a few servers for you. This variable control
-which back ends should be auto-agentized. It is typically only useful
-to agentize remote back ends. The auto-agentizing has the same effect
-as running @kbd{J a} on the servers (@pxref{Server Agent Commands}).
-If the file exist, you must manage the servers manually by adding or
-removing them, this variable is only applicable the first time you
-start Gnus. The default is @samp{(nntp nnimap)}.
+Or to put it another way: When using @code{<} on @code{Lines} with 4 as
+the match, we get the score added if the article has less than 4 lines.
+(It's easy to get confused and think it's the other way around. But
+it's not. I think.)
-@end table
+When matching on @code{Lines}, be careful because some back ends (like
+@code{nndir}) do not generate @code{Lines} header, so every article ends
+up being marked as having 0 lines. This can lead to strange results if
+you happen to lower score of the articles with few lines.
+@item Date
+For the Date header we have three kinda silly match types:
+@code{before}, @code{at} and @code{after}. I can't really imagine this
+ever being useful, but, like, it would feel kinda silly not to provide
+this function. Just in case. You never know. Better safe than sorry.
+Once burnt, twice shy. Don't judge a book by its cover. Never not have
+sex on a first date. (I have been told that at least one person, and I
+quote, ``found this function indispensable'', however.)
-@node Example Setup
-@subsection Example Setup
+@cindex ISO8601
+@cindex date
+A more useful match type is @code{regexp}. With it, you can match the
+date string using a regular expression. The date is normalized to
+ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. 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?)
-If you don't want to read this manual, and you have a fairly standard
-setup, you may be able to use something like the following as your
-@file{~/.gnus.el} file to get started.
+@item Head, Body, All
+These three match keys use the same match types as the @code{From} (etc)
+header uses.
-@lisp
-;; @r{Define how Gnus is to fetch news. We do this over @acronym{NNTP}}
-;; @r{from your ISP's server.}
-(setq gnus-select-method '(nntp "news.your-isp.com"))
+@item Followup
+This match key is somewhat special, in that it will match the
+@code{From} header, and affect the score of not only the matching
+articles, but also all followups to the matching articles. This allows
+you e.g. increase the score of followups to your own articles, or
+decrease the score of followups to the articles of some known
+trouble-maker. Uses the same match types as the @code{From} header
+uses. (Using this match key will lead to creation of @file{ADAPT}
+files.)
-;; @r{Define how Gnus is to read your mail. We read mail from}
-;; @r{your ISP's @acronym{POP} server.}
-(setq mail-sources '((pop :server "pop.your-isp.com")))
+@item Thread
+This match key works along the same lines as the @code{Followup} match
+key. If you say that you want to score on a (sub-)thread started by an
+article with a @code{Message-ID} @var{x}, then you add a @samp{thread}
+match. This will add a new @samp{thread} match for each article that
+has @var{x} in its @code{References} header. (These new @samp{thread}
+matches will use the @code{Message-ID}s of these matching articles.)
+This will ensure that you can raise/lower the score of an entire thread,
+even though some articles in the thread may not have complete
+@code{References} headers. Note that using this may lead to
+undeterministic scores of the articles in the thread. (Using this match
+key will lead to creation of @file{ADAPT} files.)
+@end table
+@end enumerate
-;; @r{Say how Gnus is to store the mail. We use nnml groups.}
-(setq gnus-secondary-select-methods '((nnml "")))
+@cindex score file atoms
+@item mark
+The value of this entry should be a number. Any articles with a score
+lower than this number will be marked as read.
-;; @r{Make Gnus into an offline newsreader.}
-;; (gnus-agentize) ; @r{The obsolete setting.}
-;; (setq gnus-agent t) ; @r{Now the default.}
-@end lisp
+@item expunge
+The value of this entry should be a number. Any articles with a score
+lower than this number will be removed from the summary buffer.
-That should be it, basically. Put that in your @file{~/.gnus.el} file,
-edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x
-gnus}.
+@item mark-and-expunge
+The value of this entry should be a number. Any articles with a score
+lower than this number will be marked as read and removed from the
+summary buffer.
-If this is the first time you've run Gnus, you will be subscribed
-automatically to a few default newsgroups. You'll probably want to
-subscribe to more groups, and to do that, you have to query the
-@acronym{NNTP} server for a complete list of groups with the @kbd{A A}
-command. This usually takes quite a while, but you only have to do it
-once.
+@item thread-mark-and-expunge
+The value of this entry should be a number. All articles that belong to
+a thread that has a total score below this number will be marked as read
+and removed from the summary buffer. @code{gnus-thread-score-function}
+says how to compute the total score for a thread.
-After reading and parsing a while, you'll be presented with a list of
-groups. Subscribe to the ones you want to read with the @kbd{u}
-command. @kbd{l} to make all the killed groups disappear after you've
-subscribe to all the groups you want to read. (@kbd{A k} will bring
-back all the killed groups.)
+@item files
+The value of this entry should be any number of file names. These files
+are assumed to be score files as well, and will be loaded the same way
+this one was.
-You can now read the groups at once, or you can download the articles
-with the @kbd{J s} command. And then read the rest of this manual to
-find out which of the other gazillion things you want to customize.
+@item exclude-files
+The clue of this entry should be any number of files. These files will
+not be loaded, even though they would normally be so, for some reason or
+other.
+@item eval
+The value of this entry will be @code{eval}ed. This element will be
+ignored when handling global score files.
-@node Batching Agents
-@subsection Batching Agents
-@findex gnus-agent-batch
+@item read-only
+Read-only score files will not be updated or saved. Global score files
+should feature this atom (@pxref{Global Score Files}). (Note:
+@dfn{Global} here really means @dfn{global}; not your personal
+apply-to-all-groups score files.)
-Having the Gnus Agent fetch articles (and post whatever messages you've
-written) is quite easy once you've gotten things set up properly. The
-following shell script will do everything that is necessary:
+@item orphan
+The value of this entry should be a number. Articles that do not have
+parents will get this number added to their scores. Imagine you follow
+some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
+will only follow a few of the threads, also want to see any new threads.
-You can run a complete batch command from the command line with the
-following incantation:
+You can do this with the following two score file entries:
@example
-#!/bin/sh
-emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1
+ (orphan -500)
+ (mark-and-expunge -100)
@end example
+When you enter the group the first time, you will only see the new
+threads. You then raise the score of the threads that you find
+interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{c y}) the
+rest. Next time you enter the group, you will see new articles in the
+interesting threads, plus any new threads.
-@node Agent Caveats
-@subsection Agent Caveats
+I.e.---the orphan score atom is for high-volume groups where a few
+interesting threads which can't be found automatically by ordinary
+scoring rules exist.
-The Gnus Agent doesn't seem to work like most other offline
-newsreaders. Here are some common questions that some imaginary people
-may ask:
+@item adapt
+This entry controls the adaptive scoring. If it is @code{t}, the
+default adaptive scoring rules will be used. If it is @code{ignore}, no
+adaptive scoring will be performed on this group. If it is a list, this
+list will be used as the adaptive scoring rules. If it isn't present,
+or is something other than @code{t} or @code{ignore}, the default
+adaptive scoring rules will be used. If you want to use adaptive
+scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
+@code{t}, and insert an @code{(adapt ignore)} in the groups where you do
+not want adaptive scoring. If you only want adaptive scoring in a few
+groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
+insert @code{(adapt t)} in the score files of the groups where you want
+it.
-@table @dfn
-@item If I read an article while plugged, do they get entered into the Agent?
+@item adapt-file
+All adaptive score entries will go to the file named by this entry. It
+will also be applied when entering the group. This atom might be handy
+if you want to adapt on several groups at once, using the same adaptive
+file for a number of groups.
-@strong{No}. If you want this behavior, add
-@code{gnus-agent-fetch-selected-article} to
-@code{gnus-select-article-hook}.
+@item local
+@cindex local variables
+The value of this entry should be a list of @code{(@var{var}
+@var{value})} pairs. Each @var{var} will be made buffer-local to the
+current summary buffer, and set to the value specified. This is a
+convenient, if somewhat strange, way of setting variables in some
+groups if you don't like hooks much. Note that the @var{value} won't
+be evaluated.
+@end table
-@item If I read an article while plugged, and the article already exists in
-the Agent, will it get downloaded once more?
-@strong{No}, unless @code{gnus-agent-cache} is @code{nil}.
+@node Score File Editing
+@section Score File Editing
-@end table
+You normally enter all scoring commands from the summary buffer, but you
+might feel the urge to edit them by hand as well, so we've supplied you
+with a mode for that.
-In short, when Gnus is unplugged, it only looks into the locally stored
-articles; when it's plugged, it talks to your ISP and may also use the
-locally stored articles.
+It's simply a slightly customized @code{emacs-lisp} mode, with these
+additional commands:
+@table @kbd
-@node Scoring
-@chapter Scoring
-@cindex scoring
+@item C-c C-c
+@kindex C-c C-c (Score)
+@findex gnus-score-edit-exit
+Save the changes you have made and return to the summary buffer
+(@code{gnus-score-edit-exit}).
-Other people use @dfn{kill files}, but we here at Gnus Towers like
-scoring better than killing, so we'd rather switch than fight. They do
-something completely different as well, so sit up straight and pay
-attention!
+@item C-c C-d
+@kindex C-c C-d (Score)
+@findex gnus-score-edit-insert-date
+Insert the current date in numerical format
+(@code{gnus-score-edit-insert-date}). This is really the day number, if
+you were wondering.
-@vindex gnus-summary-mark-below
-All articles have a default score (@code{gnus-summary-default-score}),
-which is 0 by default. This score may be raised or lowered either
-interactively or by score files. Articles that have a score lower than
-@code{gnus-summary-mark-below} are marked as read.
+@item C-c C-p
+@kindex C-c C-p (Score)
+@findex gnus-score-pretty-print
+The adaptive score files are saved in an unformatted fashion. If you
+intend to read one of these files, you want to @dfn{pretty print} it
+first. This command (@code{gnus-score-pretty-print}) does that for
+you.
-Gnus will read any @dfn{score files} that apply to the current group
-before generating the summary buffer.
+@end table
-There are several commands in the summary buffer that insert score
-entries based on the current article. You can, for instance, ask Gnus to
-lower or increase the score of all articles with a certain subject.
+Type @kbd{M-x gnus-score-mode} to use this mode.
-There are two sorts of scoring entries: Permanent and temporary.
-Temporary score entries are self-expiring entries. Any entries that are
-temporary and have not been used for, say, a week, will be removed
-silently to help keep the sizes of the score files down.
+@vindex gnus-score-mode-hook
+@code{gnus-score-menu-hook} is run in score mode buffers.
-@menu
-* Summary Score Commands:: Adding score entries for the current group.
-* Group Score Commands:: General score commands.
-* Score Variables:: Customize your scoring. (My, what terminology).
-* Score File Format:: What a score file may contain.
-* Score File Editing:: You can edit score files by hand as well.
-* Adaptive Scoring:: Big Sister Gnus knows what you read.
-* Home Score File:: How to say where new score entries are to go.
-* Followups To Yourself:: Having Gnus notice when people answer you.
-* Scoring On Other Headers:: Scoring on non-standard headers.
-* 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.
-* Converting Kill Files:: Translating kill files to score files.
-* Advanced Scoring:: Using logical expressions to build score rules.
-* Score Decays:: It can be useful to let scores wither away.
-@end menu
+In the summary buffer you can use commands like @kbd{V f}, @kbd{V e} and
+@kbd{V t} to begin editing score files.
-@node Summary Score Commands
-@section Summary Score Commands
-@cindex score commands
+@node Adaptive Scoring
+@section Adaptive Scoring
+@cindex adaptive scoring
-The score commands that alter score entries do not actually modify real
-score files. That would be too inefficient. Gnus maintains a cache of
-previously loaded score files, one of which is considered the
-@dfn{current score file alist}. The score commands simply insert
-entries into this list, and upon group exit, this list is saved.
+If all this scoring is getting you down, Gnus has a way of making it all
+happen automatically---as if by magic. Or rather, as if by artificial
+stupidity, to be precise.
-The current score file is by default the group's local score file, even
-if no such score file actually exists. To insert score commands into
-some other score file (e.g. @file{all.SCORE}), you must first make this
-score file the current one.
+@vindex gnus-use-adaptive-scoring
+When you read an article, or mark an article as read, or kill an
+article, you leave marks behind. On exit from the group, Gnus can sniff
+these marks and add score elements depending on what marks it finds.
+You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
+@code{t} or @code{(line)}. If you want score adaptively on separate
+words appearing in the subjects, you should set this variable to
+@code{(word)}. If you want to use both adaptive methods, set this
+variable to @code{(word line)}.
-General score commands that don't actually change the score file:
+@vindex gnus-default-adaptive-score-alist
+To give you complete control over the scoring process, you can customize
+the @code{gnus-default-adaptive-score-alist} variable. For instance, it
+might look something like this:
-@table @kbd
+@lisp
+(setq gnus-default-adaptive-score-alist
+ '((gnus-unread-mark)
+ (gnus-ticked-mark (from 4))
+ (gnus-dormant-mark (from 5))
+ (gnus-del-mark (from -4) (subject -1))
+ (gnus-read-mark (from 4) (subject 2))
+ (gnus-expirable-mark (from -1) (subject -1))
+ (gnus-killed-mark (from -1) (subject -3))
+ (gnus-kill-file-mark)
+ (gnus-ancient-mark)
+ (gnus-low-score-mark)
+ (gnus-catchup-mark (from -1) (subject -1))))
+@end lisp
+
+As you see, each element in this alist has a mark as a key (either a
+variable name or a ``real'' mark---a character). Following this key is
+a arbitrary number of header/score pairs. If there are no header/score
+pairs following the key, no adaptive scoring will be done on articles
+that have that key as the article mark. For instance, articles with
+@code{gnus-unread-mark} in the example above will not get adaptive score
+entries.
-@item V s
-@kindex V s (Summary)
-@findex gnus-summary-set-score
-Set the score of the current article (@code{gnus-summary-set-score}).
+Each article can have only one mark, so just a single of these rules
+will be applied to each article.
-@item V S
-@kindex V S (Summary)
-@findex gnus-summary-current-score
-Display the score of the current article
-(@code{gnus-summary-current-score}).
+To take @code{gnus-del-mark} as an example---this alist says that all
+articles that have that mark (i.e., are marked with @samp{e}) will have a
+score entry added to lower based on the @code{From} header by -4, and
+lowered by @code{Subject} by -1. Change this to fit your prejudices.
-@item V t
-@kindex V t (Summary)
-@findex gnus-score-find-trace
-Display all score rules that have been used on the current article
-(@code{gnus-score-find-trace}). In the @code{*Score Trace*} buffer, you
-may type @kbd{e} to edit score file corresponding to the score rule on
-current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the
-score file and edit it.
+If you have marked 10 articles with the same subject with
+@code{gnus-del-mark}, the rule for that mark will be applied ten times.
+That means that that subject will get a score of ten times -1, which
+should be, unless I'm much mistaken, -10.
-@item V w
-@kindex V w (Summary)
-@findex gnus-score-find-favourite-words
-List words used in scoring (@code{gnus-score-find-favourite-words}).
+If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all
+the read articles will be marked with the @samp{E} mark. This'll
+probably make adaptive scoring slightly impossible, so auto-expiring and
+adaptive scoring doesn't really mix very well.
-@item V R
-@kindex V R (Summary)
-@findex gnus-summary-rescore
-Run the current summary through the scoring process
-(@code{gnus-summary-rescore}). This might be useful if you're playing
-around with your score files behind Gnus' back and want to see the
-effect you're having.
+The headers you can score on are @code{from}, @code{subject},
+@code{message-id}, @code{references}, @code{xref}, @code{lines},
+@code{chars} and @code{date}. In addition, you can score on
+@code{followup}, which will create an adaptive score entry that matches
+on the @code{References} header using the @code{Message-ID} of the
+current article, thereby matching the following thread.
-@item V c
-@kindex V c (Summary)
-@findex gnus-score-change-score-file
-Make a different score file the current
-(@code{gnus-score-change-score-file}).
+If you use this scheme, you should set the score file atom @code{mark}
+to something small---like -300, perhaps, to avoid having small random
+changes result in articles getting marked as read.
-@item V e
-@kindex V e (Summary)
-@findex gnus-score-edit-current-scores
-Edit the current score file (@code{gnus-score-edit-current-scores}).
-You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
-File Editing}).
+After using adaptive scoring for a week or so, Gnus should start to
+become properly trained and enhance the authors you like best, and kill
+the authors you like least, without you having to say so explicitly.
-@item V f
-@kindex V f (Summary)
-@findex gnus-score-edit-file
-Edit a score file and make this score file the current one
-(@code{gnus-score-edit-file}).
+You can control what groups the adaptive scoring is to be performed on
+by using the score files (@pxref{Score File Format}). This will also
+let you use different rules in different groups.
-@item V F
-@kindex V F (Summary)
-@findex gnus-score-flush-cache
-Flush the score cache (@code{gnus-score-flush-cache}). This is useful
-after editing score files.
+@vindex gnus-adaptive-file-suffix
+The adaptive score entries will be put into a file where the name is the
+group name with @code{gnus-adaptive-file-suffix} appended. The default
+is @file{ADAPT}.
-@item V C
-@kindex V C (Summary)
-@findex gnus-score-customize
-Customize a score file in a visually pleasing manner
-(@code{gnus-score-customize}).
+@vindex gnus-adaptive-pretty-print
+Adaptive score files can get huge and are not meant to be edited by
+human hands. If @code{gnus-adaptive-pretty-print} is @code{nil} (the
+default) those files will not be written in a human readable way.
-@end table
+@vindex gnus-score-exact-adapt-limit
+When doing adaptive scoring, substring or fuzzy matching would probably
+give you the best results in most cases. However, if the header one
+matches is short, the possibility for false positives is great, so if
+the length of the match is less than
+@code{gnus-score-exact-adapt-limit}, exact matching will be used. If
+this variable is @code{nil}, exact matching will always be used to avoid
+this problem.
-The rest of these commands modify the local score file.
+@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.
-@table @kbd
+@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
-@item V m
-@kindex V m (Summary)
-@findex gnus-score-set-mark-below
-Prompt for a score, and mark all articles with a score below this as
-read (@code{gnus-score-set-mark-below}).
+This is the default value. If you have adaption on words enabled, every
+word that appears in subjects of articles marked with
+@code{gnus-read-mark} will result in a score rule that increase the
+score with 30 points.
-@item V x
-@kindex V x (Summary)
-@findex gnus-score-set-expunge-below
-Prompt for a score, and add a score rule to the current score file to
-expunge all articles below this score
-(@code{gnus-score-set-expunge-below}).
-@end table
+@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.
-The keystrokes for actually making score entries follow a very regular
-pattern, so there's no need to list all the commands. (Hundreds of
-them.)
+@vindex gnus-adaptive-word-length-limit
+Some may feel that short words shouldn't count when doing adaptive
+scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to
+an integer. Words shorter than this number will be ignored. This
+variable defaults to @code{nil}.
-@findex gnus-summary-increase-score
-@findex gnus-summary-lower-score
+@vindex gnus-adaptive-word-syntax-table
+When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the
+syntax table in effect. It is similar to the standard syntax table, but
+it considers numbers to be non-word-constituent characters.
-@enumerate
-@item
-The first key is either @kbd{I} (upper case i) for increasing the score
-or @kbd{L} for lowering the score.
-@item
-The second key says what header you want to score on. The following
-keys are available:
-@table @kbd
+@vindex gnus-adaptive-word-minimum
+If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive
+word scoring process will never bring down the score of an article to
+below this number. The default is @code{nil}.
-@item a
-Score on the author name.
+@vindex gnus-adaptive-word-no-group-words
+If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus
+won't adaptively word score any of the words in the group name. Useful
+for groups like @samp{comp.editors.emacs}, where most of the subject
+lines contain the word @samp{emacs}.
-@item s
-Score on the subject line.
+After using this scheme for a while, it might be nice to write a
+@code{gnus-psychoanalyze-user} command to go through the rules and see
+what words you like and what words you don't like. Or perhaps not.
-@item x
-Score on the @code{Xref} line---i.e., the cross-posting line.
+Note that the adaptive word scoring thing is highly experimental and is
+likely to change in the future. Initial impressions seem to indicate
+that it's totally useless as it stands. Some more work (involving more
+rigorous statistical methods) will have to be done to make this useful.
-@item r
-Score on the @code{References} line.
-@item d
-Score on the date.
+@node Home Score File
+@section Home Score File
-@item l
-Score on the number of lines.
+The score file where new score file entries will go is called the
+@dfn{home score file}. This is normally (and by default) the score file
+for the group itself. For instance, the home score file for
+@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}.
-@item i
-Score on the @code{Message-ID} header.
+However, this may not be what you want. It is often convenient to share
+a common home score file among many groups---all @samp{emacs} groups
+could perhaps use the same home score file.
-@item e
-Score on an ``extra'' header, that is, one of those in gnus-extra-headers,
-if your @acronym{NNTP} server tracks additional header data in overviews.
+@vindex gnus-home-score-file
+The variable that controls this is @code{gnus-home-score-file}. It can
+be:
-@item f
-Score on followups---this matches the author name, and adds scores to
-the followups to this author. (Using this key leads to the creation of
-@file{ADAPT} files.)
+@enumerate
+@item
+A string. Then this file will be used as the home score file for all
+groups.
-@item b
-Score on the body.
+@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 h
-Score on the head.
+@item
+A list. The elements in this list can be:
-@item t
-Score on thread. (Using this key leads to the creation of @file{ADAPT}
-files.)
+@enumerate
+@item
+@code{(@var{regexp} @var{file-name})}. If the @var{regexp} matches the
+group name, the @var{file-name} will be used as the home score file.
-@end table
+@item
+A function. If the function returns non-@code{nil}, the result will
+be used as the home score file. The function will be called with the
+name of the group as the parameter.
@item
-The third key is the match type. Which match types are valid depends on
-what headers you are scoring on.
+A string. Use the string as the home score file.
+@end enumerate
-@table @code
+The list will be traversed from the beginning towards the end looking
+for matches.
-@item strings
+@end enumerate
-@table @kbd
+So, if you want to use just a single score file, you could say:
-@item e
-Exact matching.
+@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:
+
+@findex gnus-hierarchial-home-score-file
+@lisp
+(setq gnus-home-score-file
+ 'gnus-hierarchial-home-score-file)
+@end lisp
-@item s
-Substring matching.
+This is a ready-made function provided for your convenience.
+Other functions include
-@item f
-Fuzzy matching (@pxref{Fuzzy Matching}).
+@table @code
+@item gnus-current-home-score-file
+@findex gnus-current-home-score-file
+Return the ``current'' regular score file. This will make scoring
+commands add entry to the ``innermost'' matching score file.
-@item r
-Regexp matching
@end table
-@item date
-@table @kbd
+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:
-@item b
-Before date.
+@lisp
+(setq gnus-home-score-file
+ ;; @r{All groups that match the regexp @code{"\\.emacs"}}
+ '(("\\.emacs" "emacs.SCORE")
+ ;; @r{All the comp groups in one score file}
+ ("^comp" "comp.SCORE")))
+@end lisp
-@item a
-After date.
+@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.
-@item n
-This date.
-@end table
+In addition to using @code{gnus-home-score-file} and
+@code{gnus-home-adapt-file}, you can also use group parameters
+(@pxref{Group Parameters}) and topic parameters (@pxref{Topic
+Parameters}) to achieve much the same. Group and topic parameters take
+precedence over this variable.
-@item number
-@table @kbd
-@item <
-Less than number.
+@node Followups To Yourself
+@section Followups To Yourself
-@item =
-Equal to number.
+Gnus offers two commands for picking out the @code{Message-ID} header in
+the current buffer. Gnus will then add a score rule that scores using
+this @code{Message-ID} on the @code{References} header of other
+articles. This will, in effect, increase the score of all articles that
+respond to the article in the current buffer. Quite useful if you want
+to easily note when people answer what you've said.
-@item >
-Greater than number.
-@end table
-@end table
+@table @code
-@item
-The fourth and usually final key says whether this is a temporary (i.e.,
-expiring) score entry, or a permanent (i.e., non-expiring) score entry,
-or whether it is to be done immediately, without adding to the score
-file.
-@table @kbd
+@item gnus-score-followup-article
+@findex gnus-score-followup-article
+This will add a score to articles that directly follow up your own
+article.
-@item t
-Temporary score entry.
+@item gnus-score-followup-thread
+@findex gnus-score-followup-thread
+This will add a score to all articles that appear in a thread ``below''
+your own article.
+@end table
-@item p
-Permanent score entry.
+@vindex message-sent-hook
+These two functions are both primarily meant to be used in hooks like
+@code{message-sent-hook}, like this:
+@lisp
+(add-hook 'message-sent-hook 'gnus-score-followup-thread)
+@end lisp
-@item i
-Immediately scoring.
-@end table
-@item
-If you are scoring on `e' (extra) headers, you will then be prompted for
-the header name on which you wish to score. This must be a header named
-in gnus-extra-headers, and @samp{TAB} completion is available.
+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:
-@end enumerate
+@example
+<x6u3u47icf.fsf@@eyesore.no>
+<x6sp9o7ibw.fsf@@eyesore.no>
+@end example
-So, let's say you want to increase the score on the current author with
-exact matching permanently: @kbd{I a e p}. If you want to lower the
-score based on the subject line, using substring matching, and make a
-temporary score entry: @kbd{L s s t}. Pretty easy.
+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:
-To make things a bit more complicated, there are shortcuts. If you use
-a capital letter on either the second or third keys, Gnus will use
-defaults for the remaining one or two keystrokes. The defaults are
-``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s
-t}, and @kbd{I a R} is the same as @kbd{I a r t}.
+@lisp
+("references"
+ ("<x6[0-9a-z]+\\.fsf\\(_-_\\)?@@.*eyesore\\.no>"
+ 1000 nil r))
+@end lisp
-These functions take both the numerical prefix and the symbolic prefix
-(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower
-(or increase) the score of the article. A symbolic prefix of @code{a}
-says to use the @file{all.SCORE} file for the command instead of the
-current score file.
+Whether it's the first two or first three characters that are ``yours''
+is system-dependent.
-@vindex gnus-score-mimic-keymap
-The @code{gnus-score-mimic-keymap} says whether these commands will
-pretend they are keymaps or not.
+@node Scoring On Other Headers
+@section Scoring On Other Headers
+@cindex scoring on other headers
-@node Group Score Commands
-@section Group Score Commands
-@cindex group score commands
+Gnus is quite fast when scoring the ``traditional''
+headers---@samp{From}, @samp{Subject} and so on. However, scoring
+other headers requires writing a @code{head} scoring rule, which means
+that Gnus has to request every single article from the back end to find
+matches. This takes a long time in big groups.
-There aren't many of these as yet, I'm afraid.
+@vindex gnus-inhibit-slow-scoring
+You can inhibit this slow scoring on headers or body by setting the
+variable @code{gnus-inhibit-slow-scoring}. If
+@code{gnus-inhibit-slow-scoring} is regexp, slow scoring is inhibited if
+the group matches the regexp. If it is t, slow scoring on it is
+inhibited for all groups.
-@table @kbd
+Now, there's not much you can do about the slowness for news groups, but for
+mail groups, you have greater control. In @ref{To From Newsgroups},
+it's explained in greater detail what this mechanism does, but here's
+a cookbook example for @code{nnml} on how to allow scoring on the
+@samp{To} and @samp{Cc} headers.
-@item W e
-@kindex W e (Group)
-@findex gnus-score-edit-all-score
-Edit the apply-to-all-groups all.SCORE file. You will be popped into
-a @code{gnus-score-mode} buffer (@pxref{Score File Editing}).
+Put the following in your @file{~/.gnus.el} file.
-@item W f
-@kindex W f (Group)
-@findex gnus-score-flush-cache
-Gnus maintains a cache of score alists to avoid having to reload them
-all the time. This command will flush the cache
-(@code{gnus-score-flush-cache}).
+@lisp
+(setq gnus-extra-headers '(To Cc Newsgroups Keywords)
+ nnmail-extra-headers gnus-extra-headers)
+@end lisp
-@end table
+Restart Gnus and rebuild your @code{nnml} overview files with the
+@kbd{M-x nnml-generate-nov-databases} command. This will take a long
+time if you have much mail.
-You can do scoring from the command line by saying something like:
+Now you can score on @samp{To} and @samp{Cc} as ``extra headers'' like
+so: @kbd{I e s p To RET <your name> RET}.
-@findex gnus-batch-score
-@cindex batch scoring
-@example
-$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score
-@end example
+See? Simple.
-@node Score Variables
-@section Score Variables
-@cindex score variables
+@node Scoring Tips
+@section Scoring Tips
+@cindex scoring tips
-@table @code
+@table @dfn
-@item gnus-use-scoring
-@vindex gnus-use-scoring
-If @code{nil}, Gnus will not check for score files, and will not, in
-general, do any score-related work. This is @code{t} by default.
+@item Crossposts
+@cindex crossposts
+@cindex scoring crossposts
+If you want to lower the score of crossposts, the line to match on is
+the @code{Xref} header.
+@lisp
+("xref" (" talk.politics.misc:" -1000))
+@end lisp
-@item gnus-kill-killed
-@vindex gnus-kill-killed
-If this variable is @code{nil}, Gnus will never apply score files to
-articles that have already been through the kill process. While this
-may save you lots of time, it also means that if you apply a kill file
-to a group, and then change the kill file and want to run it over you
-group again to kill more articles, it won't work. You have to set this
-variable to @code{t} to do that. (It is @code{t} by default.)
+@item Multiple crossposts
+If you want to lower the score of articles that have been crossposted to
+more than, say, 3 groups:
+@lisp
+("xref"
+ ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+"
+ -1000 nil r))
+@end lisp
-@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 @env{SAVEDIR} environment variable by default.
-This is @file{~/News/} by default.
+@item Matching on the body
+This is generally not a very good idea---it takes a very long time.
+Gnus actually has to fetch each individual article from the server. But
+you might want to anyway, I guess. Even though there are three match
+keys (@code{Head}, @code{Body} and @code{All}), you should choose one
+and stick with it in each score file. If you use any two, each article
+will be fetched @emph{twice}. If you want to match a bit on the
+@code{Head} and a bit on the @code{Body}, just use @code{All} for all
+the matches.
-@item gnus-score-file-suffix
-@vindex gnus-score-file-suffix
-Suffix to add to the group name to arrive at the score file name
-(@file{SCORE} by default.)
+@item Marking as read
+You will probably want to mark articles that have scores below a certain
+number as read. This is most easily achieved by putting the following
+in your @file{all.SCORE} file:
+@lisp
+((mark -100))
+@end lisp
+You may also consider doing something similar with @code{expunge}.
-@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, this might make your Emacs grow big and
-bloated, so this regexp can be used to weed out score files 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 Negated character classes
+If you say stuff like @code{[^abcd]*}, you may get unexpected results.
+That will match newlines, which might lead to, well, The Unknown. Say
+@code{[^abcd\n]*} instead.
+@end table
-@item gnus-save-score
-@vindex gnus-save-score
-If you have really complicated score files, and do lots of batch
-scoring, then you might set this variable to @code{t}. This will make
-Gnus save the scores into the @file{.newsrc.eld} file.
-If you do not set this to @code{t}, then manual scores (like those set
-with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved
-across group visits.
+@node Reverse Scoring
+@section Reverse Scoring
+@cindex reverse scoring
-@item gnus-score-interactive-default-score
-@vindex gnus-score-interactive-default-score
-Score used by all the interactive raise/lower commands to raise/lower
-score with. Default is 1000, which may seem excessive, but this is to
-ensure that the adaptive scoring scheme gets enough room to play with.
-We don't want the small changes from the adaptive scoring to overwrite
-manually entered data.
+If you want to keep just articles that have @samp{Sex with Emacs} in the
+subject header, and expunge all other articles, you could put something
+like this in your score file:
-@item gnus-summary-default-score
-@vindex gnus-summary-default-score
-Default score of an article, which is 0 by default.
+@lisp
+(("subject"
+ ("Sex with Emacs" 2))
+ (mark 1)
+ (expunge 1))
+@end lisp
-@item gnus-summary-expunge-below
-@vindex gnus-summary-expunge-below
-Don't display the summary lines of articles that have scores lower than
-this variable. This is @code{nil} by default, which means that no
-articles will be hidden. This variable is local to the summary buffers,
-and has to be set from @code{gnus-summary-mode-hook}.
+So, you raise all articles that match @samp{Sex with Emacs} and mark the
+rest as read, and expunge them to boot.
-@item gnus-score-over-mark
-@vindex gnus-score-over-mark
-Mark (in the third column) used for articles with a score over the
-default. Default is @samp{+}.
-@item gnus-score-below-mark
-@vindex gnus-score-below-mark
-Mark (in the third column) used for articles with a score below the
-default. Default is @samp{-}.
+@node Global Score Files
+@section Global Score Files
+@cindex global score files
-@item gnus-score-find-score-files-function
-@vindex gnus-score-find-score-files-function
-Function used to find score files for the current group. This function
-is called with the name of the group as the argument.
+Sure, other newsreaders have ``global kill files''. These are usually
+nothing more than a single kill file that applies to all groups, stored
+in the user's home directory. Bah! Puny, weak newsreaders!
-Predefined functions available are:
-@table @code
+What I'm talking about here are Global Score Files. Score files from
+all over the world, from users everywhere, uniting all nations in one
+big, happy score file union! Ange-score! New and untested!
-@item gnus-score-find-single
-@findex gnus-score-find-single
-Only apply the group's own score file.
+@vindex gnus-global-score-files
+All you have to do to use other people's score files is to set the
+@code{gnus-global-score-files} variable. One entry for each score file,
+or each score file directory. Gnus will decide by itself what score
+files are applicable to which group.
-@item gnus-score-find-bnews
-@findex gnus-score-find-bnews
-Apply all score files that match, using bnews syntax. This is the
-default. If the current group is @samp{gnu.emacs.gnus}, for instance,
-@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
-@file{gnu.all.SCORE} would all apply. In short, the instances of
-@samp{all} in the score file names are translated into @samp{.*}, and
-then a regexp match is done.
+To use the score file
+@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and
+all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory,
+say this:
-This means that if you have some score entries that you want to apply to
-all groups, then you put those entries in the @file{all.SCORE} file.
+@lisp
+(setq gnus-global-score-files
+ '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE"
+ "/ftp@@ftp.some-where:/pub/score/"))
+@end lisp
-The score files are applied in a semi-random order, although Gnus will
-try to apply the more general score files before the more specific score
-files. It does this by looking at the number of elements in the score
-file names---discarding the @samp{all} elements.
+@findex gnus-score-search-global-directories
+@noindent
+Simple, eh? Directory names must end with a @samp{/}. These
+directories are typically scanned only once during each Gnus session.
+If you feel the need to manually re-scan the remote directories, you can
+use the @code{gnus-score-search-global-directories} command.
-@item gnus-score-find-hierarchical
-@findex gnus-score-find-hierarchical
-Apply all score files from all the parent groups. This means that you
-can't have score files like @file{all.SCORE}, but you can have
-@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE} for each
-server.
+Note that, at present, using this option will slow down group entry
+somewhat. (That is---a lot.)
-@end table
-This variable can also be a list of functions. In that case, all
-these functions will be called with the group name as argument, and
-all the returned lists of score files will be applied. These
-functions can also return lists of lists of score alists directly. In
-that case, the functions that return these non-file score alists
-should probably be placed before the ``real'' score file functions, to
-ensure that the last score file returned is the local score file.
-Phu.
+If you want to start maintaining score files for other people to use,
+just put your score file up for anonymous ftp and announce it to the
+world. Become a retro-moderator! Participate in the retro-moderator
+wars sure to ensue, where retro-moderators battle it out for the
+sympathy of the people, luring them to use their score files on false
+premises! Yay! The net is saved!
-For example, to do hierarchical scoring but use a non-server-specific
-overall score file, you could use the value
-@example
-(list (lambda (group) ("all.SCORE"))
- 'gnus-score-find-hierarchical)
-@end example
+Here are some tips for the would-be retro-moderator, off the top of my
+head:
-@item gnus-score-expiry-days
-@vindex gnus-score-expiry-days
-This variable says how many days should pass before an unused score file
-entry is expired. If this variable is @code{nil}, no score file entries
-are expired. It's 7 by default.
+@itemize @bullet
-@item gnus-update-score-entry-dates
-@vindex gnus-update-score-entry-dates
-If this variable is non-@code{nil}, temporary score entries that have
-been triggered (matched) will have their dates updated. (This is how Gnus
-controls expiry---all non-matched-entries will become too old while
-matched entries will stay fresh and young.) However, if you set this
-variable to @code{nil}, even matched entries will grow old and will
-have to face that oh-so grim reaper.
+@item
+Articles heavily crossposted are probably junk.
+@item
+To lower a single inappropriate article, lower by @code{Message-ID}.
+@item
+Particularly brilliant authors can be raised on a permanent basis.
+@item
+Authors that repeatedly post off-charter for the group can safely be
+lowered out of existence.
+@item
+Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
+articles completely.
-@item gnus-score-after-write-file-function
-@vindex gnus-score-after-write-file-function
-Function called with the name of the score file just written.
+@item
+Use expiring score entries to keep the size of the file down. You
+should probably have a long expiry period, though, as some sites keep
+old articles for a long time.
+@end itemize
-@item gnus-score-thread-simplify
-@vindex gnus-score-thread-simplify
-If this variable is non-@code{nil}, article subjects will be
-simplified for subject scoring purposes in the same manner as with
-threading---according to the current value of
-@code{gnus-simplify-subject-functions}. If the scoring entry uses
-@code{substring} or @code{exact} matching, the match will also be
-simplified in this manner.
+@dots{} I wonder whether other newsreaders will support global score files
+in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
+Wave, xrn and 1stReader are bound to implement scoring. Should we start
+holding our breath yet?
-@end table
+@node Kill Files
+@section Kill Files
+@cindex kill files
-@node Score File Format
-@section Score File Format
-@cindex score file format
+Gnus still supports those pesky old kill files. In fact, the kill file
+entries can now be expiring, which is something I wrote before Daniel
+Quinlan thought of doing score files, so I've left the code in there.
-A score file is an @code{emacs-lisp} file that normally contains just a
-single form. Casual users are not expected to edit these files;
-everything can be changed from the summary buffer.
+In short, kill processing is a lot slower (and I do mean @emph{a lot})
+than score processing, so it might be a good idea to rewrite your kill
+files into score files.
-Anyway, if you'd like to dig into it yourself, here's an example:
+Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
+forms into this file, which means that you can use kill files as some
+sort of primitive hook function to be run on group entry, even though
+that isn't a very good idea.
+
+Normal kill files look like this:
@lisp
-(("from"
- ("Lars Ingebrigtsen" -10000)
- ("Per Abrahamsen")
- ("larsi\\|lmi" -50000 nil R))
- ("subject"
- ("Ding is Badd" nil 728373))
- ("xref"
- ("alt.politics" -1000 728372 s))
- ("lines"
- (2 -100 nil <))
- (mark 0)
- (expunge -1000)
- (mark-and-expunge -10)
- (read-only nil)
- (orphan -10)
- (adapt t)
- (files "/hom/larsi/News/gnu.SCORE")
- (exclude-files "all.SCORE")
- (local (gnus-newsgroup-auto-expire t)
- (gnus-summary-make-false-root empty))
- (eval (ding)))
+(gnus-kill "From" "Lars Ingebrigtsen")
+(gnus-kill "Subject" "ding")
+(gnus-expunge "X")
@end lisp
-This example demonstrates most score file elements. @xref{Advanced
-Scoring}, for a different approach.
+This will mark every article written by me as read, and remove the
+marked articles from the summary buffer. Very useful, you'll agree.
-Even though this looks much like Lisp code, nothing here is actually
-@code{eval}ed. The Lisp reader is used to read this form, though, so it
-has to be valid syntactically, if not semantically.
+Other programs use a totally different kill file syntax. If Gnus
+encounters what looks like a @code{rn} kill file, it will take a stab at
+interpreting it.
-Six keys are supported by this alist:
+Two summary functions for editing a @sc{gnus} kill file:
+
+@table @kbd
+
+@item M-k
+@kindex M-k (Summary)
+@findex gnus-summary-edit-local-kill
+Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
+
+@item M-K
+@kindex M-K (Summary)
+@findex gnus-summary-edit-global-kill
+Edit the general kill file (@code{gnus-summary-edit-global-kill}).
+@end table
+
+Two group mode functions for editing the kill files:
+
+@table @kbd
-@table @code
+@item M-k
+@kindex M-k (Group)
+@findex gnus-group-edit-local-kill
+Edit this group's kill file (@code{gnus-group-edit-local-kill}).
-@item STRING
-If the key is a string, it is the name of the header to perform the
-match on. Scoring can only be performed on these eight headers:
-@code{From}, @code{Subject}, @code{References}, @code{Message-ID},
-@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to
-these headers, there are three strings to tell Gnus to fetch the entire
-article and do the match on larger parts of the article: @code{Body}
-will perform the match on the body of the article, @code{Head} will
-perform the match on the head of the article, and @code{All} will
-perform the match on the entire article. Note that using any of these
-last three keys will slow down group entry @emph{considerably}. The
-final ``header'' you can score on is @code{Followup}. These score
-entries will result in new score entries being added for all follow-ups
-to articles that matches these score entries.
+@item M-K
+@kindex M-K (Group)
+@findex gnus-group-edit-global-kill
+Edit the general kill file (@code{gnus-group-edit-global-kill}).
+@end table
-Following this key is an arbitrary number of score entries, where each
-score entry has one to four elements.
-@enumerate
+Kill file variables:
-@item
-The first element is the @dfn{match element}. On most headers this will
-be a string, but on the Lines and Chars headers, this must be an
-integer.
+@table @code
+@item gnus-kill-file-name
+@vindex gnus-kill-file-name
+A kill file for the group @samp{soc.motss} is normally called
+@file{soc.motss.KILL}. The suffix appended to the group name to get
+this file name is detailed by the @code{gnus-kill-file-name} variable.
+The ``global'' kill file (not in the score file sense of ``global'', of
+course) is just called @file{KILL}.
-@item
-If the second element is present, it should be a number---the @dfn{score
-element}. This number should be an integer in the neginf to posinf
-interval. This number is added to the score of the article if the match
-is successful. If this element is not present, the
-@code{gnus-score-interactive-default-score} number will be used
-instead. This is 1000 by default.
+@vindex gnus-kill-save-kill-file
+@item gnus-kill-save-kill-file
+If this variable is non-@code{nil}, Gnus will save the
+kill file after processing, which is necessary if you use expiring
+kills.
-@item
-If the third element is present, it should be a number---the @dfn{date
-element}. This date says when the last time this score entry matched,
-which provides a mechanism for expiring the score entries. It this
-element is not present, the score entry is permanent. The date is
-represented by the number of days since December 31, 1 BCE.
+@item gnus-apply-kill-hook
+@vindex gnus-apply-kill-hook
+@findex gnus-apply-kill-file-unless-scored
+@findex gnus-apply-kill-file
+A hook called to apply kill files to a group. It is
+@code{(gnus-apply-kill-file)} by default. If you want to ignore the
+kill file if you have a score file for the same group, you can set this
+hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
+kill files to be processed, you should set this variable to @code{nil}.
-@item
-If the fourth element is present, it should be a symbol---the @dfn{type
-element}. This element specifies what function should be used to see
-whether this score entry matches the article. What match types that can
-be used depends on what header you wish to perform the match on.
-@table @dfn
+@item gnus-kill-file-mode-hook
+@vindex gnus-kill-file-mode-hook
+A hook called in kill-file mode buffers.
-@item From, Subject, References, Xref, Message-ID
-For most header types, there are the @code{r} and @code{R} (regexp), as
-well as @code{s} and @code{S} (substring) types, and @code{e} and
-@code{E} (exact match), and @code{w} (word match) types. If this
-element is not present, Gnus will assume that substring matching should
-be used. @code{R}, @code{S}, and @code{E} differ from the others in
-that the matches will be done in a case-sensitive manner. All these
-one-letter types are really just abbreviations for the @code{regexp},
-@code{string}, @code{exact}, and @code{word} types, which you can use
-instead, if you feel like.
+@end table
-@item Extra
-Just as for the standard string overview headers, if you are using
-gnus-extra-headers, you can score on these headers' values. In this
-case, there is a 5th element in the score entry, being the name of the
-header to be scored. The following entry is useful in your
-@file{all.SCORE} file in case of spam attacks from a single origin
-host, if your @acronym{NNTP} server tracks @samp{NNTP-Posting-Host} in
-overviews:
-@lisp
-("111.222.333.444" -1000 nil s
- "NNTP-Posting-Host")
-@end lisp
+@node Converting Kill Files
+@section Converting Kill Files
+@cindex kill files
+@cindex converting kill files
-@item Lines, Chars
-These two headers use different match types: @code{<}, @code{>},
-@code{=}, @code{>=} and @code{<=}.
+If you have loads of old kill files, you may want to convert them into
+score files. If they are ``regular'', you can use
+the @file{gnus-kill-to-score.el} package; if not, you'll have to do it
+by hand.
-These predicates are true if
+The kill to score conversion package isn't included in Emacs by default.
+You can fetch it from the contrib directory of the Gnus distribution or
+from
+@uref{http://heim.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}.
-@example
-(PREDICATE HEADER MATCH)
-@end example
+If your old kill files are very complex---if they contain more
+non-@code{gnus-kill} forms than not, you'll have to convert them by
+hand. Or just let them be as they are. Gnus will still use them as
+before.
-evaluates to non-@code{nil}. For instance, the advanced match
-@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the
-following form:
-@lisp
-(< header-value 4)
-@end lisp
+@node Advanced Scoring
+@section Advanced Scoring
-Or to put it another way: When using @code{<} on @code{Lines} with 4 as
-the match, we get the score added if the article has less than 4 lines.
-(It's easy to get confused and think it's the other way around. But
-it's not. I think.)
+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 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?
-When matching on @code{Lines}, be careful because some back ends (like
-@code{nndir}) do not generate @code{Lines} header, so every article ends
-up being marked as having 0 lines. This can lead to strange results if
-you happen to lower score of the articles with few lines.
+By using advanced scoring rules you may create arbitrarily complex
+scoring patterns.
-@item Date
-For the Date header we have three kinda silly match types:
-@code{before}, @code{at} and @code{after}. I can't really imagine this
-ever being useful, but, like, it would feel kinda silly not to provide
-this function. Just in case. You never know. Better safe than sorry.
-Once burnt, twice shy. Don't judge a book by its cover. Never not have
-sex on a first date. (I have been told that at least one person, and I
-quote, ``found this function indispensable'', however.)
+@menu
+* Advanced Scoring Syntax:: A definition.
+* Advanced Scoring Examples:: What they look like.
+* Advanced Scoring Tips:: Getting the most out of it.
+@end menu
-@cindex ISO8601
-@cindex date
-A more useful match type is @code{regexp}. With it, you can match the
-date string using a regular expression. The date is normalized to
-ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If
-you want to match all articles that have been posted on April 1st in
-every year, you could use @samp{....0401.........} as a match string,
-for instance. (Note that the date is kept in its original time zone, so
-this will match articles that were posted when it was April 1st where
-the article was posted from. Time zones are such wholesome fun for the
-whole family, eh?)
-@item Head, Body, All
-These three match keys use the same match types as the @code{From} (etc)
-header uses.
+@node Advanced Scoring Syntax
+@subsection Advanced Scoring Syntax
-@item Followup
-This match key is somewhat special, in that it will match the
-@code{From} header, and affect the score of not only the matching
-articles, but also all followups to the matching articles. This allows
-you e.g. increase the score of followups to your own articles, or
-decrease the score of followups to the articles of some known
-trouble-maker. Uses the same match types as the @code{From} header
-uses. (Using this match key will lead to creation of @file{ADAPT}
-files.)
+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.
-@item Thread
-This match key works along the same lines as the @code{Followup} match
-key. If you say that you want to score on a (sub-)thread started by an
-article with a @code{Message-ID} @var{x}, then you add a @samp{thread}
-match. This will add a new @samp{thread} match for each article that
-has @var{x} in its @code{References} header. (These new @samp{thread}
-matches will use the @code{Message-ID}s of these matching articles.)
-This will ensure that you can raise/lower the score of an entire thread,
-even though some articles in the thread may not have complete
-@code{References} headers. Note that using this may lead to
-undeterministic scores of the articles in the thread. (Using this match
-key will lead to creation of @file{ADAPT} files.)
-@end table
-@end enumerate
+These lists may consist of three logical operators, one redirection
+operator, and various match operators.
-@cindex score file atoms
-@item mark
-The value of this entry should be a number. Any articles with a score
-lower than this number will be marked as read.
+Logical operators:
-@item expunge
-The value of this entry should be a number. Any articles with a score
-lower than this number will be removed from the summary buffer.
+@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 mark-and-expunge
-The value of this entry should be a number. Any articles with a score
-lower than this number will be marked as read and removed from the
-summary buffer.
+@item |
+@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 thread-mark-and-expunge
-The value of this entry should be a number. All articles that belong to
-a thread that has a total score below this number will be marked as read
-and removed from the summary buffer. @code{gnus-thread-score-function}
-says how to compute the total score for a thread.
+@item !
+@itemx not
+@itemx ¬
+This logical operator only takes a single argument. It returns the
+logical negation of the value of its argument.
-@item files
-The value of this entry should be any number of file names. These files
-are assumed to be score files as well, and will be loaded the same way
-this one was.
+@end table
-@item exclude-files
-The clue of this entry should be any number of files. These files will
-not be loaded, even though they would normally be so, for some reason or
-other.
+There is an @dfn{indirection operator} that will make its arguments
+apply to the ancestors of the current article being scored. For
+instance, @code{1-} will make score rules apply to the parent of the
+current article. @code{2-} will make score rules apply to the
+grandparent of the current article. Alternatively, you can write
+@code{^^}, where the number of @code{^}s (carets) says how far back into
+the ancestry you want to go.
-@item eval
-The value of this entry will be @code{eval}el. This element will be
-ignored when handling global score files.
+Finally, we have the match operators. These are the ones that do the
+real work. Match operators are header name strings followed by a match
+and a match type. A typical match operator looks like @samp{("from"
+"Lars Ingebrigtsen" s)}. The header names are the same as when using
+simple scoring, and the match types are also the same.
-@item read-only
-Read-only score files will not be updated or saved. Global score files
-should feature this atom (@pxref{Global Score Files}). (Note:
-@dfn{Global} here really means @dfn{global}; not your personal
-apply-to-all-groups score files.)
-@item orphan
-The value of this entry should be a number. Articles that do not have
-parents will get this number added to their scores. Imagine you follow
-some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
-will only follow a few of the threads, also want to see any new threads.
+@node Advanced Scoring Examples
+@subsection Advanced Scoring Examples
-You can do this with the following two score file entries:
+Please note that the following examples are score file rules. To
+make a complete score file from them, surround them with another pair
+of parentheses.
+
+Let's say you want to increase the score of articles written by Lars
+when he's talking about Gnus:
@example
- (orphan -500)
- (mark-and-expunge -100)
+@group
+((&
+ ("from" "Lars Ingebrigtsen")
+ ("subject" "Gnus"))
+ 1000)
+@end group
@end example
-When you enter the group the first time, you will only see the new
-threads. You then raise the score of the threads that you find
-interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
-rest. Next time you enter the group, you will see new articles in the
-interesting threads, plus any new threads.
+Quite simple, huh?
-I.e.---the orphan score atom is for high-volume groups where a few
-interesting threads which can't be found automatically by ordinary
-scoring rules exist.
+When he writes long articles, he sometimes has something nice to say:
-@item adapt
-This entry controls the adaptive scoring. If it is @code{t}, the
-default adaptive scoring rules will be used. If it is @code{ignore}, no
-adaptive scoring will be performed on this group. If it is a list, this
-list will be used as the adaptive scoring rules. If it isn't present,
-or is something other than @code{t} or @code{ignore}, the default
-adaptive scoring rules will be used. If you want to use adaptive
-scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
-@code{t}, and insert an @code{(adapt ignore)} in the groups where you do
-not want adaptive scoring. If you only want adaptive scoring in a few
-groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
-insert @code{(adapt t)} in the score files of the groups where you want
-it.
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ (|
+ ("subject" "Gnus")
+ ("lines" 100 >)))
+ 1000)
+@end example
-@item adapt-file
-All adaptive score entries will go to the file named by this entry. It
-will also be applied when entering the group. This atom might be handy
-if you want to adapt on several groups at once, using the same adaptive
-file for a number of groups.
+However, when he responds to things written by Reig Eigil Logge, you
+really don't want to read what he's written:
-@item local
-@cindex local variables
-The value of this entry should be a list of @code{(@var{var}
-@var{value})} pairs. Each @var{var} will be made buffer-local to the
-current summary buffer, and set to the value specified. This is a
-convenient, if somewhat strange, way of setting variables in some
-groups if you don't like hooks much. Note that the @var{value} won't
-be evaluated.
-@end table
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ (1- ("from" "Reig Eigil 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:
-@node Score File Editing
-@section Score File Editing
+@example
+((&
+ (1-
+ (&
+ ("from" "redmondo@@.*no" r)
+ ("body" "disappearing.*socks" t)))
+ (! ("from" "Lars Ingebrigtsen"))
+ ("body" "white.*socks"))
+ 1000)
+@end example
-You normally enter all scoring commands from the summary buffer, but you
-might feel the urge to edit them by hand as well, so we've supplied you
-with a mode for that.
+Suppose you're reading a high volume group and you're only interested
+in replies. The plan is to score down all articles that don't have
+subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all
+parents of articles that have subjects that begin with reply marks.
-It's simply a slightly customized @code{emacs-lisp} mode, with these
-additional commands:
+@example
+((! ("subject" "re:\\|fwd?:" r))
+ -200)
+((1- ("subject" "re:\\|fwd?:" r))
+ 200)
+@end example
-@table @kbd
+The possibilities are endless.
-@item C-c C-c
-@kindex C-c C-c (Score)
-@findex gnus-score-edit-exit
-Save the changes you have made and return to the summary buffer
-(@code{gnus-score-edit-exit}).
+@node Advanced Scoring Tips
+@subsection Advanced Scoring Tips
-@item C-c C-d
-@kindex C-c C-d (Score)
-@findex gnus-score-edit-insert-date
-Insert the current date in numerical format
-(@code{gnus-score-edit-insert-date}). This is really the day number, if
-you were wondering.
+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}, @samp{header}) last and quick matches (@samp{from},
+@samp{subject}) first.
-@item C-c C-p
-@kindex C-c C-p (Score)
-@findex gnus-score-pretty-print
-The adaptive score files are saved in an unformatted fashion. If you
-intend to read one of these files, you want to @dfn{pretty print} it
-first. This command (@code{gnus-score-pretty-print}) does that for
-you.
+The indirection arguments (@code{1-} and so on) will make their
+arguments work on previous generations of the thread. If you say
+something like:
-@end table
+@example
+...
+(1-
+ (1-
+ ("from" "lars")))
+...
+@end example
-Type @kbd{M-x gnus-score-mode} to use this mode.
+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:
-@vindex gnus-score-mode-hook
-@code{gnus-score-menu-hook} is run in score mode buffers.
+@example
+(1-
+ (&
+ ("from" "Lars")
+ ("subject" "Gnus")))
+@end example
-In the summary buffer you can use commands like @kbd{V f}, @kbd{V e} and
-@kbd{V t} to begin editing score files.
+than it is to say:
+@example
+(&
+ (1- ("from" "Lars"))
+ (1- ("subject" "Gnus")))
+@end example
-@node Adaptive Scoring
-@section Adaptive Scoring
-@cindex adaptive scoring
-If all this scoring is getting you down, Gnus has a way of making it all
-happen automatically---as if by magic. Or rather, as if by artificial
-stupidity, to be precise.
+@node Score Decays
+@section Score Decays
+@cindex score decays
+@cindex decays
-@vindex gnus-use-adaptive-scoring
-When you read an article, or mark an article as read, or kill an
-article, you leave marks behind. On exit from the group, Gnus can sniff
-these marks and add score elements depending on what marks it finds.
-You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
-@code{t} or @code{(line)}. If you want score adaptively on separate
-words appearing in the subjects, you should set this variable to
-@code{(word)}. If you want to use both adaptive methods, set this
-variable to @code{(word line)}.
+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-default-adaptive-score-alist
-To give you complete control over the scoring process, you can customize
-the @code{gnus-default-adaptive-score-alist} variable. For instance, it
-might look something like this:
+@vindex gnus-decay-scores
+@findex gnus-decay-score
+@vindex gnus-decay-score-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.
+If @code{gnus-decay-scores} is a regexp, only score files matching this
+regexp are treated. E.g. you may set it to @samp{\\.ADAPT\\'} if only
+@emph{adaptive} score files should be decayed. The decay itself if
+performed by the @code{gnus-decay-score-function} function, which is
+@code{gnus-decay-score} by default. Here's the definition of that
+function:
@lisp
-(setq gnus-default-adaptive-score-alist
- '((gnus-unread-mark)
- (gnus-ticked-mark (from 4))
- (gnus-dormant-mark (from 5))
- (gnus-del-mark (from -4) (subject -1))
- (gnus-read-mark (from 4) (subject 2))
- (gnus-expirable-mark (from -1) (subject -1))
- (gnus-killed-mark (from -1) (subject -3))
- (gnus-kill-file-mark)
- (gnus-ancient-mark)
- (gnus-low-score-mark)
- (gnus-catchup-mark (from -1) (subject -1))))
+(defun gnus-decay-score (score)
+ "Decay SCORE according to `gnus-score-decay-constant'
+and `gnus-score-decay-scale'."
+ (let ((n (- score
+ (* (if (< score 0) -1 1)
+ (min (abs score)
+ (max gnus-score-decay-constant
+ (* (abs score)
+ gnus-score-decay-scale)))))))
+ (if (and (featurep 'xemacs)
+ ;; XEmacs' floor can handle only the floating point
+ ;; number below the half of the maximum integer.
+ (> (abs n) (lsh -1 -2)))
+ (string-to-number
+ (car (split-string (number-to-string n) "\\.")))
+ (floor n))))
@end lisp
-As you see, each element in this alist has a mark as a key (either a
-variable name or a ``real'' mark---a character). Following this key is
-a arbitrary number of header/score pairs. If there are no header/score
-pairs following the key, no adaptive scoring will be done on articles
-that have that key as the article mark. For instance, articles with
-@code{gnus-unread-mark} in the example above will not get adaptive score
-entries.
+@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 magnitudes greater than 60 will be shrunk by 5% of the
+score.
+@end enumerate
+
+If you don't like this decay function, write your own. It is called
+with the score to be decayed as its only parameter, and it should return
+the new score, which should be an integer.
+
+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.
-Each article can have only one mark, so just a single of these rules
-will be applied to each article.
+@node Searching
+@chapter Searching
+@cindex searching
-To take @code{gnus-del-mark} as an example---this alist says that all
-articles that have that mark (i.e., are marked with @samp{e}) will have a
-score entry added to lower based on the @code{From} header by -4, and
-lowered by @code{Subject} by -1. Change this to fit your prejudices.
+FIXME: Add a brief overview of Gnus search capabilities. A brief
+comparison of nnir, nnmairix, contrib/gnus-namazu would be nice
+as well.
-If you have marked 10 articles with the same subject with
-@code{gnus-del-mark}, the rule for that mark will be applied ten times.
-That means that that subject will get a score of ten times -1, which
-should be, unless I'm much mistaken, -10.
+This chapter describes tools for searching groups and servers for
+articles matching a query and then retrieving those articles. Gnus
+provides a simpler mechanism for searching through articles in a summary buffer
+to find those matching a pattern. @xref{Searching for Articles}.
-If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all
-the read articles will be marked with the @samp{E} mark. This'll
-probably make adaptive scoring slightly impossible, so auto-expiring and
-adaptive scoring doesn't really mix very well.
+@menu
+* nnir:: Searching with various engines.
+* nnmairix:: Searching with Mairix.
+@end menu
-The headers you can score on are @code{from}, @code{subject},
-@code{message-id}, @code{references}, @code{xref}, @code{lines},
-@code{chars} and @code{date}. In addition, you can score on
-@code{followup}, which will create an adaptive score entry that matches
-on the @code{References} header using the @code{Message-ID} of the
-current article, thereby matching the following thread.
+@node nnir
+@section nnir
+@cindex nnir
-If you use this scheme, you should set the score file atom @code{mark}
-to something small---like -300, perhaps, to avoid having small random
-changes result in articles getting marked as read.
+This section describes how to use @code{nnir} to search for articles
+within gnus.
-After using adaptive scoring for a week or so, Gnus should start to
-become properly trained and enhance the authors you like best, and kill
-the authors you like least, without you having to say so explicitly.
+@menu
+* What is nnir?:: What does @code{nnir} do?
+* Basic Usage:: How to perform simple searches.
+* Setting up nnir:: How to set up @code{nnir}.
+@end menu
-You can control what groups the adaptive scoring is to be performed on
-by using the score files (@pxref{Score File Format}). This will also
-let you use different rules in different groups.
+@node What is nnir?
+@subsection What is nnir?
-@vindex gnus-adaptive-file-suffix
-The adaptive score entries will be put into a file where the name is the
-group name with @code{gnus-adaptive-file-suffix} appended. The default
-is @file{ADAPT}.
+@code{nnir} is a Gnus interface to a number of tools for searching
+through mail and news repositories. Different backends (like
+@code{nnimap} and @code{nntp}) work with different tools (called
+@dfn{engines} in @code{nnir} lingo), but all use the same basic search
+interface.
-@vindex gnus-adaptive-pretty-print
-Adaptive score files can get huge and are not meant to be edited by
-human hands. If @code{gnus-adaptive-pretty-print} is @code{nil} (the
-deafult) those files will not be written in a human readable way.
+The @code{nnimap} and @code{gmane} search engines should work with no
+configuration. Other engines require a local index that needs to be
+created and maintained outside of Gnus.
+
+
+@node Basic Usage
+@subsection Basic Usage
+
+In the group buffer typing @kbd{G G} will search the group on the
+current line by calling @code{gnus-group-make-nnir-group}. This prompts
+for a query string, creates an ephemeral @code{nnir} group containing
+the articles that match this query, and takes you to a summary buffer
+showing these articles. Articles may then be read, moved and deleted
+using the usual commands.
+
+The @code{nnir} group made in this way is an @code{ephemeral} group, and
+some changes are not permanent: aside from reading, moving, and
+deleting, you can't act on the original article. But there is an
+alternative: you can @emph{warp} to the original group for the article
+on the current line with @kbd{A W}, aka
+@code{gnus-warp-to-article}. Even better, the function
+@code{gnus-summary-refer-thread}, bound by default in summary buffers to
+@kbd{A T}, will first warp to the original group before it works its
+magic and includes all the articles in the thread. From here you can
+read, move and delete articles, but also copy them, alter article marks,
+whatever. Go nuts.
+
+You say you want to search more than just the group on the current line?
+No problem: just process-mark the groups you want to search. You want
+even more? Calling for an nnir search with the cursor on a topic heading
+will search all the groups under that heading.
+
+Still not enough? OK, in the server buffer
+@code{gnus-group-make-nnir-group} (now bound to @kbd{G}) will search all
+groups from the server on the current line. Too much? Want to ignore
+certain groups when searching, like spam groups? Just customize
+@code{nnir-ignored-newsgroups}.
+
+One more thing: individual search engines may have special search
+features. You can access these special features by giving a prefix-arg
+to @code{gnus-group-make-nnir-group}. If you are searching multiple
+groups with different search engines you will be prompted for the
+special search features for each engine separately.
+
+
+@node Setting up nnir
+@subsection Setting up nnir
+
+To set up nnir you may need to do some prep work. Firstly, you may need
+to configure the search engines you plan to use. Some of them, like
+@code{imap} and @code{gmane}, need no special configuration. Others,
+like @code{namazu} and @code{swish}, require configuration as described
+below. Secondly, you need to associate a search engine with a server or
+a backend.
+
+If you just want to use the @code{imap} engine to search @code{nnimap}
+servers, and the @code{gmane} engine to search @code{gmane} then you
+don't have to do anything. But you might want to read the details of the
+query language anyway.
-@vindex gnus-score-exact-adapt-limit
-When doing adaptive scoring, substring or fuzzy matching would probably
-give you the best results in most cases. However, if the header one
-matches is short, the possibility for false positives is great, so if
-the length of the match is less than
-@code{gnus-score-exact-adapt-limit}, exact matching will be used. If
-this variable is @code{nil}, exact matching will always be used to avoid
-this problem.
+@menu
+* Associating Engines:: How to associate engines.
+* The imap Engine:: Imap configuration and usage.
+* The gmane Engine:: Gmane configuration and usage.
+* The swish++ Engine:: Swish++ configuration and usage.
+* The swish-e Engine:: Swish-e configuration and usage.
+* The namazu Engine:: Namazu configuration and usage.
+* The hyrex Engine:: Hyrex configuration and usage.
+* Customizations:: User customizable settings.
+@end menu
+
+@node Associating Engines
+@subsubsection Associating Engines
-@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.
+
+When searching a group, @code{nnir} needs to know which search engine to
+use. You can configure a given server to use a particular engine by
+setting the server variable @code{nnir-search-engine} to the engine
+name. For example to use the @code{namazu} engine to search the server
+named @code{home} you can use
@lisp
-(setq gnus-default-adaptive-word-score-alist
- `((,gnus-read-mark . 30)
- (,gnus-catchup-mark . -10)
- (,gnus-killed-mark . -20)
- (,gnus-del-mark . -15)))
+(setq gnus-secondary-select-methods
+ '((nnml "home"
+ (nnimap-address "localhost")
+ (nnir-search-engine namazu))))
@end lisp
-This is the default value. If you have adaption on words enabled, every
-word that appears in subjects of articles marked with
-@code{gnus-read-mark} will result in a score rule that increase the
-score with 30 points.
+Alternatively you might want to use a particular engine for all servers
+with a given backend. For example, you might want to use the @code{imap}
+engine for all servers using the @code{nnimap} backend. In this case you
+can customize the variable @code{nnir-method-default-engines}. This is
+an alist of pairs of the form @code{(backend . engine)}. By default this
+variable is set to use the @code{imap} engine for all servers using the
+@code{nnimap} backend, and the @code{gmane} backend for @code{nntp}
+servers. (Don't worry, the @code{gmane} search engine won't actually try
+to search non-gmane @code{nntp} servers.) But if you wanted to use
+@code{namazu} for all your servers with an @code{nnimap} backend you
+could change this to
-@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.
+@lisp
+'((nnimap . namazu)
+ (nntp . gmane))
+@end lisp
-@vindex gnus-adaptive-word-length-limit
-Some may feel that short words shouldn't count when doing adaptive
-scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to
-an integer. Words shorter than this number will be ignored. This
-variable defaults to @code{nil}.
+@node The imap Engine
+@subsubsection The imap Engine
-@vindex gnus-adaptive-word-syntax-table
-When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the
-syntax table in effect. It is similar to the standard syntax table, but
-it considers numbers to be non-word-constituent characters.
+The @code{imap} engine requires no configuration.
-@vindex gnus-adaptive-word-minimum
-If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive
-word scoring process will never bring down the score of an article to
-below this number. The default is @code{nil}.
+Queries using the @code{imap} engine follow a simple query language.
+The search is always case-insensitive and supports the following
+features (inspired by the Google search input language):
-@vindex gnus-adaptive-word-no-group-words
-If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus
-won't adaptively word score any of the words in the group name. Useful
-for groups like @samp{comp.editors.emacs}, where most of the subject
-lines contain the word @samp{emacs}.
+@table @samp
-After using this scheme for a while, it might be nice to write a
-@code{gnus-psychoanalyze-user} command to go through the rules and see
-what words you like and what words you don't like. Or perhaps not.
+@item Boolean query operators
+AND, OR, and NOT are supported, and parentheses can be used to control
+operator precedence, e.g. (emacs OR xemacs) AND linux. Note that
+operators must be written with all capital letters to be
+recognised. Also preceding a term with a - sign is equivalent to NOT
+term.
-Note that the adaptive word scoring thing is highly experimental and is
-likely to change in the future. Initial impressions seem to indicate
-that it's totally useless as it stands. Some more work (involving more
-rigorous statistical methods) will have to be done to make this useful.
+@item Automatic AND queries
+If you specify multiple words then they will be treated as an AND
+expression intended to match all components.
+@item Phrase searches
+If you wrap your query in double-quotes then it will be treated as a
+literal string.
-@node Home Score File
-@section Home Score File
+@end table
-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}.
+By default the whole message will be searched. The query can be limited
+to a specific part of a message by using a prefix-arg. After inputting
+the query this will prompt (with completion) for a message part.
+Choices include ``Whole message'', ``Subject'', ``From'', and
+``To''. Any unrecognized input is interpreted as a header name. For
+example, typing @kbd{Message-ID} in response to this prompt will limit
+the query to the Message-ID header.
-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.
+Finally selecting ``Imap'' will interpret the query as a raw
+@acronym{IMAP} search query. The format of such queries can be found in
+RFC3501.
-@vindex gnus-home-score-file
-The variable that controls this is @code{gnus-home-score-file}. It can
-be:
+If you don't like the default of searching whole messages you can
+customize @code{nnir-imap-default-search-key}. For example to use
+@acronym{IMAP} queries by default
-@enumerate
-@item
-A string. Then this file will be used as the home score file for all
-groups.
+@lisp
+(setq nnir-imap-default-search-key "Imap")
+@end lisp
-@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.
+@node The gmane Engine
+@subsubsection The gmane Engine
-@item
-A list. The elements in this list can be:
+The @code{gmane} engine requires no configuration.
-@enumerate
-@item
-@code{(@var{regexp} @var{file-name})}. If the @var{regexp} matches the
-group name, the @var{file-name} will be used as the home score file.
+Gmane queries follow a simple query language:
-@item
-A function. If the function returns non-@code{nil}, the result will
-be used as the home score file. The function will be called with the
-name of the group as the parameter.
+@table @samp
+@item Boolean query operators
+AND, OR, NOT (or AND NOT), and XOR are supported, and brackets can be
+used to control operator precedence, e.g. (emacs OR xemacs) AND linux.
+Note that operators must be written with all capital letters to be
+recognised.
-@item
-A string. Use the string as the home score file.
-@end enumerate
+@item Required and excluded terms
++ and - can be used to require or exclude terms, e.g. football -american
-The list will be traversed from the beginning towards the end looking
-for matches.
+@item Unicode handling
+The search engine converts all text to utf-8, so searching should work
+in any language.
-@end enumerate
+@item Stopwords
+Common English words (like 'the' and 'a') are ignored by default. You
+can override this by prefixing such words with a + (e.g. +the) or
+enclosing the word in quotes (e.g. "the").
-So, if you want to use just a single score file, you could say:
+@end table
-@lisp
-(setq gnus-home-score-file
- "my-total-score-file.SCORE")
-@end lisp
+The query can be limited to articles by a specific author using a
+prefix-arg. After inputting the query this will prompt for an author
+name (or part of a name) to match.
-If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and
-@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say:
+@node The swish++ Engine
+@subsubsection The swish++ Engine
-@findex gnus-hierarchial-home-score-file
-@lisp
-(setq gnus-home-score-file
- 'gnus-hierarchial-home-score-file)
-@end lisp
+FIXEM: Say something more here.
-This is a ready-made function provided for your convenience.
-Other functions include
+Documentation for swish++ may be found at the swish++ sourceforge page:
+@uref{http://swishplusplus.sourceforge.net}
@table @code
-@item gnus-current-home-score-file
-@findex gnus-current-home-score-file
-Return the ``current'' regular score file. This will make scoring
-commands add entry to the ``innermost'' matching score file.
-
-@end table
-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:
+@item nnir-swish++-program
+The name of the swish++ executable. Defaults to @code{search}
-@lisp
-(setq gnus-home-score-file
- ;; @r{All groups that match the regexp @code{"\\.emacs"}}
- '(("\\.emacs" "emacs.SCORE")
- ;; @r{All the comp groups in one score file}
- ("^comp" "comp.SCORE")))
-@end lisp
+@item nnir-swish++-additional-switches
+A list of strings to be given as additional arguments to
+swish++. @code{nil} by default.
-@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.
+@item nnir-swish++-remove-prefix
+The prefix to remove from each file name returned by swish++ in order
+to get a group name. By default this is @code{$HOME/Mail}.
-In addition to using @code{gnus-home-score-file} and
-@code{gnus-home-adapt-file}, you can also use group parameters
-(@pxref{Group Parameters}) and topic parameters (@pxref{Topic
-Parameters}) to achieve much the same. Group and topic parameters take
-precedence over this variable.
+@end table
+@node The swish-e Engine
+@subsubsection The swish-e Engine
-@node Followups To Yourself
-@section Followups To Yourself
+FIXEM: Say something more here.
-Gnus offers two commands for picking out the @code{Message-ID} header in
-the current buffer. Gnus will then add a score rule that scores using
-this @code{Message-ID} on the @code{References} header of other
-articles. This will, in effect, increase the score of all articles that
-respond to the article in the current buffer. Quite useful if you want
-to easily note when people answer what you've said.
+Documentation for swish-e may be found at the swish-e homepage
+@uref{http://swish-e.org}
@table @code
-@item gnus-score-followup-article
-@findex gnus-score-followup-article
-This will add a score to articles that directly follow up your own
-article.
+@item nnir-swish-e-program
+The name of the swish-e search program. Defaults to @code{swish-e}.
+
+@item nnir-swish-e-additional-switches
+A list of strings to be given as additional arguments to
+swish-e. @code{nil} by default.
+
+@item nnir-swish-e-remove-prefix
+The prefix to remove from each file name returned by swish-e in order
+to get a group name. By default this is @code{$HOME/Mail}.
-@item gnus-score-followup-thread
-@findex gnus-score-followup-thread
-This will add a score to all articles that appear in a thread ``below''
-your own article.
@end table
-@vindex message-sent-hook
-These two functions are both primarily meant to be used in hooks like
-@code{message-sent-hook}, like this:
-@lisp
-(add-hook 'message-sent-hook 'gnus-score-followup-thread)
-@end lisp
+@node The namazu Engine
+@subsubsection The namazu Engine
+Using the namazu engine requires creating and maintaining index files.
+One directory should contain all the index files, and nnir must be told
+where to find them by setting the @code{nnir-namazu-index-directory}
+variable.
-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:
+To work correctly the @code{nnir-namazu-remove-prefix} variable must
+also be correct. This is the prefix to remove from each file name
+returned by Namazu in order to get a proper group name (albeit with `/'
+instead of `.').
+
+For example, suppose that Namazu returns file names such as
+@samp{/home/john/Mail/mail/misc/42}. For this example, use the
+following setting: @code{(setq nnir-namazu-remove-prefix
+"/home/john/Mail/")} Note the trailing slash. Removing this prefix from
+the directory gives @samp{mail/misc/42}. @code{nnir} knows to remove
+the @samp{/42} and to replace @samp{/} with @samp{.} to arrive at the
+correct group name @samp{mail.misc}.
+Extra switches may be passed to the namazu search command by setting the
+variable @code{nnir-namazu-additional-switches}. It is particularly
+important not to pass any any switches to namazu that will change the
+output format. Good switches to use include `--sort', `--ascending',
+`--early' and `--late'. Refer to the Namazu documentation for further
+information on valid switches.
+
+Mail must first be indexed with the `mknmz' program. Read the documentation
+for namazu to create a configuration file. Here is an example:
+
+@cartouche
@example
-<x6u3u47icf.fsf@@eyesore.no>
-<x6sp9o7ibw.fsf@@eyesore.no>
+ package conf; # Don't remove this line!
+
+ # Paths which will not be indexed. Don't use `^' or `$' anchors.
+ $EXCLUDE_PATH = "spam|sent";
+
+ # Header fields which should be searchable. case-insensitive
+ $REMAIN_HEADER = "from|date|message-id|subject";
+
+ # Searchable fields. case-insensitive
+ $SEARCH_FIELD = "from|date|message-id|subject";
+
+ # The max length of a word.
+ $WORD_LENG_MAX = 128;
+
+ # The max length of a field.
+ $MAX_FIELD_LENGTH = 256;
@end example
+@end cartouche
-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:
+For this example, mail is stored in the directories @samp{~/Mail/mail/},
+@samp{~/Mail/lists/} and @samp{~/Mail/archive/}, so to index them go to
+the index directory set in @code{nnir-namazu-index-directory} and issue
+the following command:
-@lisp
-("references"
- ("<x6[0-9a-z]+\\.fsf\\(_-_\\)?@@.*eyesore\\.no>"
- 1000 nil r))
-@end lisp
+@example
+mknmz --mailnews ~/Mail/archive/ ~/Mail/mail/ ~/Mail/lists/
+@end example
-Whether it's the first two or first three characters that are ``yours''
-is system-dependent.
+For maximum searching efficiency you might want to have a cron job run
+this command periodically, say every four hours.
+@node The hyrex Engine
+@subsubsection The hyrex Engine
+This engine is obsolete.
-@node Scoring On Other Headers
-@section Scoring On Other Headers
-@cindex scoring on other headers
+@node Customizations
+@subsubsection Custimozations
+
+@table @code
-Gnus is quite fast when scoring the ``traditional''
-headers---@samp{From}, @samp{Subject} and so on. However, scoring
-other headers requires writing a @code{head} scoring rule, which means
-that Gnus has to request every single article from the back end to find
-matches. This takes a long time in big groups.
+@item nnir-method-default-engines
+Alist of server backend - search engine pairs. The default associations
+are
+@example
+(nnimap . imap)
+(nntp . gmane)
+@end example
-@vindex gnus-inhibit-slow-scoring
-You can inhibit this slow scoring on headers or body by setting the
-variable @code{gnus-inhibit-slow-scoring}. If
-@code{gnus-inhibit-slow-scoring} is regexp, slow scoring is inhibited if
-the group matches the regexp. If it is t, slow scoring on it is
-inhibited for all groups.
+@item nnir-ignored-newsgroups
+A regexp to match newsgroups in the active file that should be skipped
+when searching all groups on a server.
-Now, there's not much you can do about the slowness for news groups, but for
-mail groups, you have greater control. In @ref{To From Newsgroups},
-it's explained in greater detail what this mechanism does, but here's
-a cookbook example for @code{nnml} on how to allow scoring on the
-@samp{To} and @samp{Cc} headers.
+@item nnir-summary-line-format
+The format specification to be used for lines in an nnir summary buffer.
+All the items from `gnus-summary-line-format' are available, along with
+three items unique to nnir summary buffers:
-Put the following in your @file{~/.gnus.el} file.
+@example
+%Z Search retrieval score value (integer)
+%G Article original full group name (string)
+%g Article original short group name (string)
+@end example
-@lisp
-(setq gnus-extra-headers '(To Cc Newsgroups Keywords)
- nnmail-extra-headers gnus-extra-headers)
-@end lisp
+If nil (the default) this will use @code{gnus-summary-line-format}.
-Restart Gnus and rebuild your @code{nnml} overview files with the
-@kbd{M-x nnml-generate-nov-databases} command. This will take a long
-time if you have much mail.
+@item nnir-retrieve-headers-override-function
+If non-nil, a function that retrieves article headers rather than using
+the gnus built-in function. This function takes an article list and
+group as arguments and populates the `nntp-server-buffer' with the
+retrieved headers. It should then return either 'nov or 'headers
+indicating the retrieved header format. Failure to retrieve headers
+should return @code{nil}
-Now you can score on @samp{To} and @samp{Cc} as ``extra headers'' like
-so: @kbd{I e s p To RET <your name> RET}.
+If this variable is nil, or if the provided function returns nil for a
+search result, @code{gnus-retrieve-headers} will be called instead."
-See? Simple.
+@end table
-@node Scoring Tips
-@section Scoring Tips
-@cindex scoring tips
-@table @dfn
+@node nnmairix
+@section nnmairix
-@item Crossposts
-@cindex crossposts
-@cindex scoring crossposts
-If you want to lower the score of crossposts, the line to match on is
-the @code{Xref} header.
-@lisp
-("xref" (" talk.politics.misc:" -1000))
-@end lisp
+@cindex mairix
+@cindex nnmairix
+This paragraph describes how to set up mairix and the back end
+@code{nnmairix} for indexing and searching your mail from within
+Gnus. Additionally, you can create permanent ``smart'' groups which are
+bound to mairix searches and are automatically updated.
-@item Multiple crossposts
-If you want to lower the score of articles that have been crossposted to
-more than, say, 3 groups:
-@lisp
-("xref"
- ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+"
- -1000 nil r))
-@end lisp
+@menu
+* About mairix:: About the mairix mail search engine
+* nnmairix requirements:: What you will need for using nnmairix
+* What nnmairix does:: What does nnmairix actually do?
+* Setting up mairix:: Set up your mairix installation
+* Configuring nnmairix:: Set up the nnmairix back end
+* nnmairix keyboard shortcuts:: List of available keyboard shortcuts
+* Propagating marks:: How to propagate marks from nnmairix groups
+* nnmairix tips and tricks:: Some tips, tricks and examples
+* nnmairix caveats:: Some more stuff you might want to know
+@end menu
-@item Matching on the body
-This is generally not a very good idea---it takes a very long time.
-Gnus actually has to fetch each individual article from the server. But
-you might want to anyway, I guess. Even though there are three match
-keys (@code{Head}, @code{Body} and @code{All}), you should choose one
-and stick with it in each score file. If you use any two, each article
-will be fetched @emph{twice}. If you want to match a bit on the
-@code{Head} and a bit on the @code{Body}, just use @code{All} for all
-the matches.
+@c FIXME: The markup in this section might need improvement.
+@c E.g. adding @samp, @var, @file, @command, etc.
+@c Cf. (info "(texinfo)Indicating")
-@item Marking as read
-You will probably want to mark articles that have scores below a certain
-number as read. This is most easily achieved by putting the following
-in your @file{all.SCORE} file:
-@lisp
-((mark -100))
-@end lisp
-You may also consider doing something similar with @code{expunge}.
+@node About mairix
+@subsection About mairix
-@item Negated character classes
-If you say stuff like @code{[^abcd]*}, you may get unexpected results.
-That will match newlines, which might lead to, well, The Unknown. Say
-@code{[^abcd\n]*} instead.
-@end table
+Mairix is a tool for indexing and searching words in locally stored
+mail. It was written by Richard Curnow and is licensed under the
+GPL. Mairix comes with most popular GNU/Linux distributions, but it also
+runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can
+be found at
+@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html}
+Though mairix might not be as flexible as other search tools like
+swish++ or namazu, which you can use via the @code{nnir} back end, it
+has the prime advantage of being incredibly fast. On current systems, it
+can easily search through headers and message bodies of thousands and
+thousands of mails in well under a second. Building the database
+necessary for searching might take a minute or two, but only has to be
+done once fully. Afterwards, the updates are done incrementally and
+therefore are really fast, too. Additionally, mairix is very easy to set
+up.
-@node Reverse Scoring
-@section Reverse Scoring
-@cindex reverse scoring
+For maximum speed though, mairix should be used with mails stored in
+@code{Maildir} or @code{MH} format (this includes the @code{nnml} back
+end), although it also works with mbox. Mairix presents the search
+results by populating a @emph{virtual} maildir/MH folder with symlinks
+which point to the ``real'' message files (if mbox is used, copies are
+made). Since mairix already presents search results in such a virtual
+mail folder, it is very well suited for using it as an external program
+for creating @emph{smart} mail folders, which represent certain mail
+searches.
-If you want to keep just articles that have @samp{Sex with Emacs} in the
-subject header, and expunge all other articles, you could put something
-like this in your score file:
+@node nnmairix requirements
+@subsection nnmairix requirements
-@lisp
-(("subject"
- ("Sex with Emacs" 2))
- (mark 1)
- (expunge 1))
-@end lisp
+Mairix searches local mail---that means, mairix absolutely must have
+direct access to your mail folders. If your mail resides on another
+server (e.g. an @acronym{IMAP} server) and you happen to have shell
+access, @code{nnmairix} supports running mairix remotely, e.g. via ssh.
-So, you raise all articles that match @samp{Sex with Emacs} and mark the
-rest as read, and expunge them to boot.
+Additionally, @code{nnmairix} only supports the following Gnus back
+ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use
+one of these back ends for using @code{nnmairix}. Other back ends, like
+@code{nnmbox}, @code{nnfolder} or @code{nnmh}, won't work.
+If you absolutely must use mbox and still want to use @code{nnmairix},
+you can set up a local @acronym{IMAP} server, which you then access via
+@code{nnimap}. This is a rather massive setup for accessing some mbox
+files, so just change to MH or Maildir already... However, if you're
+really, really passionate about using mbox, you might want to look into
+the package @file{mairix.el}, which comes with Emacs 23.
-@node Global Score Files
-@section Global Score Files
-@cindex global score files
+@node What nnmairix does
+@subsection What nnmairix does
-Sure, other newsreaders have ``global kill files''. These are usually
-nothing more than a single kill file that applies to all groups, stored
-in the user's home directory. Bah! Puny, weak newsreaders!
+The back end @code{nnmairix} enables you to call mairix from within Gnus,
+either to query mairix with a search term or to update the
+database. While visiting a message in the summary buffer, you can use
+several pre-defined shortcuts for calling mairix, e.g. to quickly
+search for all mails from the sender of the current message or to
+display the whole thread associated with the message, even if the
+mails are in different folders.
-What I'm talking about here are Global Score Files. Score files from
-all over the world, from users everywhere, uniting all nations in one
-big, happy score file union! Ange-score! New and untested!
+Additionally, you can create permanent @code{nnmairix} groups which are bound
+to certain mairix searches. This way, you can easily create a group
+containing mails from a certain sender, with a certain subject line or
+even for one specific thread based on the Message-ID. If you check for
+new mail in these folders (e.g. by pressing @kbd{g} or @kbd{M-g}), they
+automatically update themselves by calling mairix.
-@vindex gnus-global-score-files
-All you have to do to use other people's score files is to set the
-@code{gnus-global-score-files} variable. One entry for each score file,
-or each score file directory. Gnus will decide by itself what score
-files are applicable to which group.
+You might ask why you need @code{nnmairix} at all, since mairix already
+creates the group, populates it with links to the mails so that you can
+then access it with Gnus, right? Well, this @emph{might} work, but often
+does not---at least not without problems. Most probably you will get
+strange article counts, and sometimes you might see mails which Gnus
+claims have already been canceled and are inaccessible. This is due to
+the fact that Gnus isn't really amused when things are happening behind
+its back. Another problem can be the mail back end itself, e.g. if you
+use mairix with an @acronym{IMAP} server (I had Dovecot complaining
+about corrupt index files when mairix changed the contents of the search
+group). Using @code{nnmairix} should circumvent these problems.
+
+@code{nnmairix} is not really a mail back end---it's actually more like
+a wrapper, sitting between a ``real'' mail back end where mairix stores
+the searches and the Gnus front end. You can choose between three
+different mail back ends for the mairix folders: @code{nnml},
+@code{nnmaildir} or @code{nnimap}. @code{nnmairix} will call the mairix
+binary so that the search results are stored in folders named
+@code{zz_mairix-<NAME>-<NUMBER>} on this mail back end, but it will
+present these folders in the Gnus front end only with @code{<NAME>}.
+You can use an existing mail back end where you already store your mail,
+but if you're uncomfortable with @code{nnmairix} creating new mail
+groups alongside your other mail, you can also create e.g. a new
+@code{nnmaildir} or @code{nnml} server exclusively for mairix, but then
+make sure those servers do not accidentally receive your new mail
+(@pxref{nnmairix caveats}). A special case exists if you want to use
+mairix remotely on an IMAP server with @code{nnimap}---here the mairix
+folders and your other mail must be on the same @code{nnimap} back end.
-To use the score file
-@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and
-all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory,
-say this:
+@node Setting up mairix
+@subsection Setting up mairix
-@lisp
-(setq gnus-global-score-files
- '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE"
- "/ftp@@ftp.some-where:/pub/score/"))
-@end lisp
+First: create a backup of your mail folders (@pxref{nnmairix caveats}).
-@findex gnus-score-search-global-directories
-@noindent
-Simple, eh? Directory names must end with a @samp{/}. These
-directories are typically scanned only once during each Gnus session.
-If you feel the need to manually re-scan the remote directories, you can
-use the @code{gnus-score-search-global-directories} command.
+Setting up mairix is easy: simply create a @file{.mairixrc} file with
+(at least) the following entries:
-Note that, at present, using this option will slow down group entry
-somewhat. (That is---a lot.)
+@example
+# Your Maildir/MH base folder
+base=~/Maildir
+@end example
-If you want to start maintaining score files for other people to use,
-just put your score file up for anonymous ftp and announce it to the
-world. Become a retro-moderator! Participate in the retro-moderator
-wars sure to ensue, where retro-moderators battle it out for the
-sympathy of the people, luring them to use their score files on false
-premises! Yay! The net is saved!
+This is the base folder for your mails. All the following directories
+are relative to this base folder. If you want to use @code{nnmairix}
+with @code{nnimap}, this base directory has to point to the mail
+directory where the @acronym{IMAP} server stores the mail folders!
-Here are some tips for the would-be retro-moderator, off the top of my
-head:
+@example
+maildir= ... your maildir folders which should be indexed ...
+mh= ... your nnml/mh folders which should be indexed ...
+mbox = ... your mbox files which should be indexed ...
+@end example
-@itemize @bullet
+This specifies all your mail folders and mbox files (relative to the
+base directory!) you want to index with mairix. Note that the
+@code{nnml} back end saves mails in MH format, so you have to put those
+directories in the @code{mh} line. See the example at the end of this
+section and mairixrc's man-page for further details.
-@item
-Articles heavily crossposted are probably junk.
-@item
-To lower a single inappropriate article, lower by @code{Message-ID}.
-@item
-Particularly brilliant authors can be raised on a permanent basis.
-@item
-Authors that repeatedly post off-charter for the group can safely be
-lowered out of existence.
-@item
-Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
-articles completely.
+@example
+omit=zz_mairix-*
+@end example
-@item
-Use expiring score entries to keep the size of the file down. You
-should probably have a long expiry period, though, as some sites keep
-old articles for a long time.
-@end itemize
+@vindex nnmairix-group-prefix
+This should make sure that you don't accidentally index the mairix
+search results. You can change the prefix of these folders with the
+variable @code{nnmairix-group-prefix}.
-@dots{} I wonder whether other newsreaders will support global score files
-in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
-Wave, xrn and 1stReader are bound to implement scoring. Should we start
-holding our breath yet?
+@example
+mformat= ... 'maildir' or 'mh' ...
+database= ... location of database file ...
+@end example
+The @code{format} setting specifies the output format for the mairix
+search folder. Set this to @code{mh} if you want to access search results
+with @code{nnml}. Otherwise choose @code{maildir}.
-@node Kill Files
-@section Kill Files
-@cindex kill files
+To summarize, here is my shortened @file{.mairixrc} file as an example:
-Gnus still supports those pesky old kill files. In fact, the kill file
-entries can now be expiring, which is something I wrote before Daniel
-Quinlan thought of doing score files, so I've left the code in there.
+@example
+base=~/Maildir
+maildir=.personal:.work:.logcheck:.sent
+mh=../Mail/nnml/*...
+mbox=../mboxmail/mailarchive_year*
+mformat=maildir
+omit=zz_mairix-*
+database=~/.mairixdatabase
+@end example
-In short, kill processing is a lot slower (and I do mean @emph{a lot})
-than score processing, so it might be a good idea to rewrite your kill
-files into score files.
+In this case, the base directory is @file{~/Maildir}, where all my Maildir
+folders are stored. As you can see, the folders are separated by
+colons. If you wonder why every folder begins with a dot: this is
+because I use Dovecot as @acronym{IMAP} server, which again uses
+@code{Maildir++} folders. For testing nnmairix, I also have some
+@code{nnml} mail, which is saved in @file{~/Mail/nnml}. Since this has
+to be specified relative to the @code{base} directory, the @code{../Mail}
+notation is needed. Note that the line ends in @code{*...}, which means
+to recursively scan all files under this directory. Without the three
+dots, the wildcard @code{*} will not work recursively. I also have some
+old mbox files with archived mail lying around in @file{~/mboxmail}.
+The other lines should be obvious.
+
+See the man page for @code{mairixrc} for details and further options,
+especially regarding wildcard usage, which may be a little different
+than you are used to.
+
+Now simply call @code{mairix} to create the index for the first time.
+Note that this may take a few minutes, but every following index will do
+the updates incrementally and hence is very fast.
-Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
-forms into this file, which means that you can use kill files as some
-sort of primitive hook function to be run on group entry, even though
-that isn't a very good idea.
+@node Configuring nnmairix
+@subsection Configuring nnmairix
-Normal kill files look like this:
+In group mode, type @kbd{G b c}
+(@code{nnmairix-create-server-and-default-group}). This will ask you for all
+necessary information and create a @code{nnmairix} server as a foreign
+server. You will have to specify the following:
-@lisp
-(gnus-kill "From" "Lars Ingebrigtsen")
-(gnus-kill "Subject" "ding")
-(gnus-expunge "X")
-@end lisp
+@itemize @bullet
+
+@item
+The @strong{name} of the @code{nnmairix} server---choose whatever you
+want.
-This will mark every article written by me as read, and remove the
-marked articles from the summary buffer. Very useful, you'll agree.
+@item
+The name of the @strong{back end server} where mairix should store its
+searches. This must be a full server name, like @code{nnml:mymail}.
+Just hit @kbd{TAB} to see the available servers. Currently, servers
+which are accessed through @code{nnmaildir}, @code{nnimap} and
+@code{nnml} are supported. As explained above, for locally stored
+mails, this can be an existing server where you store your mails.
+However, you can also create e.g. a new @code{nnmaildir} or @code{nnml}
+server exclusively for @code{nnmairix} in your secondary select methods
+(@pxref{Finding the News}). If you use a secondary @code{nnml} server
+just for mairix, make sure that you explicitly set the server variable
+@code{nnml-get-new-mail} to @code{nil}, or you might lose mail
+(@pxref{nnmairix caveats}). If you want to use mairix remotely on an
+@acronym{IMAP} server, you have to choose the corresponding
+@code{nnimap} server here.
-Other programs use a totally different kill file syntax. If Gnus
-encounters what looks like a @code{rn} kill file, it will take a stab at
-interpreting it.
+@item
+@vindex nnmairix-mairix-search-options
+The @strong{command} to call the mairix binary. This will usually just
+be @code{mairix}, but you can also choose something like @code{ssh
+SERVER mairix} if you want to call mairix remotely, e.g. on your
+@acronym{IMAP} server. If you want to add some default options to
+mairix, you could do this here, but better use the variable
+@code{nnmairix-mairix-search-options} instead.
-Two summary functions for editing a @sc{gnus} kill file:
+@item
+The name of the @strong{default search group}. This will be the group
+where all temporary mairix searches are stored, i.e. all searches which
+are not bound to permanent @code{nnmairix} groups. Choose whatever you
+like.
-@table @kbd
+@item
+If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be
+asked if you work with @strong{Maildir++}, i.e. with hidden maildir
+folders (=beginning with a dot). For example, you have to answer
+@samp{yes} here if you work with the Dovecot @acronym{IMAP}
+server. Otherwise, you should answer @samp{no} here.
-@item M-k
-@kindex M-k (Summary)
-@findex gnus-summary-edit-local-kill
-Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
+@end itemize
-@item M-K
-@kindex M-K (Summary)
-@findex gnus-summary-edit-global-kill
-Edit the general kill file (@code{gnus-summary-edit-global-kill}).
-@end table
+@node nnmairix keyboard shortcuts
+@subsection nnmairix keyboard shortcuts
-Two group mode functions for editing the kill files:
+In group mode:
@table @kbd
-@item M-k
-@kindex M-k (Group)
-@findex gnus-group-edit-local-kill
-Edit this group's kill file (@code{gnus-group-edit-local-kill}).
+@item G b c
+@kindex G b c (Group)
+@findex nnmairix-create-server-and-default-group
+Creates @code{nnmairix} server and default search group for this server
+(@code{nnmairix-create-server-and-default-group}). You should have done
+this by now (@pxref{Configuring nnmairix}).
-@item M-K
-@kindex M-K (Group)
-@findex gnus-group-edit-global-kill
-Edit the general kill file (@code{gnus-group-edit-global-kill}).
-@end table
+@item G b s
+@kindex G b s (Group)
+@findex nnmairix-search
+Prompts for query which is then sent to the mairix binary. Search
+results are put into the default search group which is automatically
+displayed (@code{nnmairix-search}).
-Kill file variables:
+@item G b m
+@kindex G b m (Group)
+@findex nnmairix-widget-search
+Allows you to create a mairix search or a permanent group more
+comfortably using graphical widgets, similar to a customization
+group. Just try it to see how it works (@code{nnmairix-widget-search}).
-@table @code
-@item gnus-kill-file-name
-@vindex gnus-kill-file-name
-A kill file for the group @samp{soc.motss} is normally called
-@file{soc.motss.KILL}. The suffix appended to the group name to get
-this file name is detailed by the @code{gnus-kill-file-name} variable.
-The ``global'' kill file (not in the score file sense of ``global'', of
-course) is just called @file{KILL}.
+@item G b i
+@kindex G b i (Group)
+@findex nnmairix-search-interactive
+Another command for creating a mairix query more comfortably, but uses
+only the minibuffer (@code{nnmairix-search-interactive}).
-@vindex gnus-kill-save-kill-file
-@item gnus-kill-save-kill-file
-If this variable is non-@code{nil}, Gnus will save the
-kill file after processing, which is necessary if you use expiring
-kills.
+@item G b g
+@kindex G b g (Group)
+@findex nnmairix-create-search-group
+Creates a permanent group which is associated with a search query
+(@code{nnmairix-create-search-group}). The @code{nnmairix} back end
+automatically calls mairix when you update this group with @kbd{g} or
+@kbd{M-g}.
-@item gnus-apply-kill-hook
-@vindex gnus-apply-kill-hook
-@findex gnus-apply-kill-file-unless-scored
-@findex gnus-apply-kill-file
-A hook called to apply kill files to a group. It is
-@code{(gnus-apply-kill-file)} by default. If you want to ignore the
-kill file if you have a score file for the same group, you can set this
-hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
-kill files to be processed, you should set this variable to @code{nil}.
+@item G b q
+@kindex G b q (Group)
+@findex nnmairix-group-change-query-this-group
+Changes the search query for the @code{nnmairix} group under cursor
+(@code{nnmairix-group-change-query-this-group}).
-@item gnus-kill-file-mode-hook
-@vindex gnus-kill-file-mode-hook
-A hook called in kill-file mode buffers.
+@item G b t
+@kindex G b t (Group)
+@findex nnmairix-group-toggle-threads-this-group
+Toggles the 'threads' parameter for the @code{nnmairix} group under cursor,
+i.e. if you want see the whole threads of the found messages
+(@code{nnmairix-group-toggle-threads-this-group}).
-@end table
+@item G b u
+@kindex G b u (Group)
+@findex nnmairix-update-database
+@vindex nnmairix-mairix-update-options
+Calls mairix binary for updating the database
+(@code{nnmairix-update-database}). The default parameters are @code{-F}
+and @code{-Q} for making this as fast as possible (see variable
+@code{nnmairix-mairix-update-options} for defining these default
+options).
+@item G b r
+@kindex G b r (Group)
+@findex nnmairix-group-toggle-readmarks-this-group
+Keep articles in this @code{nnmairix} group always read or unread, or leave the
+marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}).
-@node Converting Kill Files
-@section Converting Kill Files
-@cindex kill files
-@cindex converting kill files
+@item G b d
+@kindex G b d (Group)
+@findex nnmairix-group-delete-recreate-this-group
+Recreate @code{nnmairix} group on the ``real'' mail back end
+(@code{nnmairix-group-delete-recreate-this-group}). You can do this if
+you always get wrong article counts with a @code{nnmairix} group.
-If you have loads of old kill files, you may want to convert them into
-score files. If they are ``regular'', you can use
-the @file{gnus-kill-to-score.el} package; if not, you'll have to do it
-by hand.
+@item G b a
+@kindex G b a (Group)
+@findex nnmairix-group-toggle-allowfast-this-group
+Toggles the @code{allow-fast} parameters for group under cursor
+(@code{nnmairix-group-toggle-allowfast-this-group}). The default
+behavior of @code{nnmairix} is to do a mairix search every time you
+update or enter the group. With the @code{allow-fast} parameter set,
+mairix will only be called when you explicitly update the group, but not
+upon entering. This makes entering the group faster, but it may also
+lead to dangling symlinks if something changed between updating and
+entering the group which is not yet in the mairix database.
-The kill to score conversion package isn't included in Gnus by default.
-You can fetch it from
-@uref{http://www.stud.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}.
+@item G b p
+@kindex G b p (Group)
+@findex nnmairix-group-toggle-propmarks-this-group
+Toggle marks propagation for this group
+(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating
+marks}).
-If your old kill files are very complex---if they contain more
-non-@code{gnus-kill} forms than not, you'll have to convert them by
-hand. Or just let them be as they are. Gnus will still use them as
-before.
+@item G b o
+@kindex G b o (Group)
+@findex nnmairix-propagate-marks
+Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when
+@code{nnmairix-propagate-marks-upon-close} is set to @code{nil}.
+@end table
-@node Advanced Scoring
-@section Advanced Scoring
+In summary mode:
-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 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?
+@table @kbd
-By using advanced scoring rules you may create arbitrarily complex
-scoring patterns.
+@item $ m
+@kindex $ m (Summary)
+@findex nnmairix-widget-search-from-this-article
+Allows you to create a mairix query or group based on the current
+message using graphical widgets (same as @code{nnmairix-widget-search})
+(@code{nnmairix-widget-search-from-this-article}).
-@menu
-* Advanced Scoring Syntax:: A definition.
-* Advanced Scoring Examples:: What they look like.
-* Advanced Scoring Tips:: Getting the most out of it.
-@end menu
+@item $ g
+@kindex $ g (Summary)
+@findex nnmairix-create-search-group-from-message
+Interactively creates a new search group with query based on the current
+message, but uses the minibuffer instead of graphical widgets
+(@code{nnmairix-create-search-group-from-message}).
+@item $ t
+@kindex $ t (Summary)
+@findex nnmairix-search-thread-this-article
+Searches thread for the current article
+(@code{nnmairix-search-thread-this-article}). This is effectively a
+shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the
+current article and enabled threads.
-@node Advanced Scoring Syntax
-@subsection Advanced Scoring Syntax
+@item $ f
+@kindex $ f (Summary)
+@findex nnmairix-search-from-this-article
+Searches all messages from sender of the current article
+(@code{nnmairix-search-from-this-article}). This is a shortcut for
+calling @code{nnmairix-search} with @samp{f:From}.
-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.
+@item $ o
+@kindex $ o (Summary)
+@findex nnmairix-goto-original-article
+(Only in @code{nnmairix} groups!) Tries determine the group this article
+originally came from and displays the article in this group, so that
+e.g. replying to this article the correct posting styles/group
+parameters are applied (@code{nnmairix-goto-original-article}). This
+function will use the registry if available, but can also parse the
+article file name as a fallback method.
-These lists may consist of three logical operators, one redirection
-operator, and various match operators.
+@item $ u
+@kindex $ u (Summary)
+@findex nnmairix-remove-tick-mark-original-article
+Remove possibly existing tick mark from original article
+(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix
+tips and tricks}).
-Logical operators:
+@end table
-@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}.
+@node Propagating marks
+@subsection Propagating marks
-@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}.
+First of: you really need a patched mairix binary for using the marks
+propagation feature efficiently. Otherwise, you would have to update
+the mairix database all the time. You can get the patch at
-@item !
-@itemx not
-@itemx ¬
-This logical operator only takes a single argument. It returns the
-logical negation of the value of its argument.
+@uref{http://www.randomsample.de/mairix-maildir-patch.tar}
-@end table
+You need the mairix v0.21 source code for this patch; everything else
+is explained in the accompanied readme file. If you don't want to use
+marks propagation, you don't have to apply these patches, but they also
+fix some annoyances regarding changing maildir flags, so it might still
+be useful to you.
-There is an @dfn{indirection operator} that will make its arguments
-apply to the ancestors of the current article being scored. For
-instance, @code{1-} will make score rules apply to the parent of the
-current article. @code{2-} will make score rules apply to the
-grandparent of the current article. Alternatively, you can write
-@code{^^}, where the number of @code{^}s (carets) says how far back into
-the ancestry you want to go.
+With the patched mairix binary, you can use @code{nnmairix} as an
+alternative to mail splitting (@pxref{Fancy Mail Splitting}). For
+example, instead of splitting all mails from @samp{david@@foobar.com}
+into a group, you can simply create a search group with the query
+@samp{f:david@@foobar.com}. This is actually what ``smart folders'' are
+all about: simply put everything in one mail folder and dynamically
+create searches instead of splitting. This is more flexible, since you
+can dynamically change your folders any time you want to. This also
+implies that you will usually read your mails in the @code{nnmairix}
+groups instead of your ``real'' mail groups.
-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.
+There is one problem, though: say you got a new mail from
+@samp{david@@foobar.com}; it will now show up in two groups, the
+``real'' group (your INBOX, for example) and in the @code{nnmairix}
+search group (provided you have updated the mairix database). Now you
+enter the @code{nnmairix} group and read the mail. The mail will be
+marked as read, but only in the @code{nnmairix} group---in the ``real''
+mail group it will be still shown as unread.
+You could now catch up the mail group (@pxref{Group Data}), but this is
+tedious and error prone, since you may overlook mails you don't have
+created @code{nnmairix} groups for. Of course, you could first use
+@code{nnmairix-goto-original-article} (@pxref{nnmairix keyboard
+shortcuts}) and then read the mail in the original group, but that's
+even more cumbersome.
-@node Advanced Scoring Examples
-@subsection Advanced Scoring Examples
+Clearly, the easiest way would be if marks could somehow be
+automatically set for the original article. This is exactly what
+@emph{marks propagation} is about.
-Please note that the following examples are score file rules. To
-make a complete score file from them, surround them with another pair
-of parentheses.
+Marks propagation is deactivated by default. You can activate it for a
+certain @code{nnmairix} group with
+@code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b
+p}). This function will warn you if you try to use it with your default
+search group; the reason is that the default search group is used for
+temporary searches, and it's easy to accidentally propagate marks from
+this group. However, you can ignore this warning if you really want to.
-Let's say you want to increase the score of articles written by Lars
-when he's talking about Gnus:
+With marks propagation enabled, all the marks you set in a @code{nnmairix}
+group should now be propagated to the original article. For example,
+you can now tick an article (by default with @kbd{!}) and this mark should
+magically be set for the original article, too.
-@example
-@group
-((&
- ("from" "Lars Ingebrigtsen")
- ("subject" "Gnus"))
- 1000)
-@end group
-@end example
+A few more remarks which you may or may not want to know:
-Quite simple, huh?
+@vindex nnmairix-propagate-marks-upon-close
+Marks will not be set immediately, but only upon closing a group. This
+not only makes marks propagation faster, it also avoids problems with
+dangling symlinks when dealing with maildir files (since changing flags
+will change the file name). You can also control when to propagate marks
+via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for
+details).
-When he writes long articles, he sometimes has something nice to say:
+Obviously, @code{nnmairix} will have to look up the original group for every
+article you want to set marks for. If available, @code{nnmairix} will first use
+the registry for determining the original group. The registry is very
+fast, hence you should really, really enable the registry when using
+marks propagation. If you don't have to worry about RAM and disc space,
+set @code{gnus-registry-max-entries} to a large enough value; to be on
+the safe side, choose roughly the amount of mails you index with mairix.
-@example
-((&
- ("from" "Lars Ingebrigtsen")
- (|
- ("subject" "Gnus")
- ("lines" 100 >)))
- 1000)
-@end example
+@vindex nnmairix-only-use-registry
+If you don't want to use the registry or the registry hasn't seen the
+original article yet, @code{nnmairix} will use an additional mairix
+search for determining the file name of the article. This, of course, is
+way slower than the registry---if you set hundreds or even thousands of
+marks this way, it might take some time. You can avoid this situation by
+setting @code{nnmairix-only-use-registry} to t.
-However, when he responds to things written by Reig Eigil Logge, you
-really don't want to read what he's written:
+Maybe you also want to propagate marks the other way round, i.e. if you
+tick an article in a "real" mail group, you'd like to have the same
+article in a @code{nnmairix} group ticked, too. For several good
+reasons, this can only be done efficiently if you use maildir. To
+immediately contradict myself, let me mention that it WON'T work with
+@code{nnmaildir}, since @code{nnmaildir} stores the marks externally and
+not in the file name. Therefore, propagating marks to @code{nnmairix}
+groups will usually only work if you use an IMAP server which uses
+maildir as its file format.
-@example
-((&
- ("from" "Lars Ingebrigtsen")
- (1- ("from" "Reig Eigil Logge")))
- -100000)
-@end example
+@vindex nnmairix-propagate-marks-to-nnmairix-groups
+If you work with this setup, just set
+@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t} and see what
+happens. If you don't like what you see, just set it to @code{nil} again. One
+problem might be that you get a wrong number of unread articles; this
+usually happens when you delete or expire articles in the original
+groups. When this happens, you can recreate the @code{nnmairix} group on the
+back end using @kbd{G b d}.
-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:
+@node nnmairix tips and tricks
+@subsection nnmairix tips and tricks
-@example
-((&
- (1-
- (&
- ("from" "redmondo@@.*no" r)
- ("body" "disappearing.*socks" t)))
- (! ("from" "Lars Ingebrigtsen"))
- ("body" "white.*socks"))
- 1000)
-@end example
+@itemize
+@item
+Checking Mail
-Suppose you're reading a high volume group and you're only interested
-in replies. The plan is to score down all articles that don't have
-subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all
-parents of articles that have subjects that begin with reply marks.
+@findex nnmairix-update-groups
+I put all my important mail groups at group level 1. The mairix groups
+have group level 5, so they do not get checked at start up (@pxref{Group
+Levels}).
-@example
-((! ("subject" "re:\\|fwd?:" r))
- -200)
-((1- ("subject" "re:\\|fwd?:" r))
- 200)
-@end example
+I use the following to check for mails:
-The possibilities are endless.
+@lisp
+(defun my-check-mail-mairix-update (level)
+ (interactive "P")
+ ;; if no prefix given, set level=1
+ (gnus-group-get-new-news (or level 1))
+ (nnmairix-update-groups "mairixsearch" t t)
+ (gnus-group-list-groups))
-@node Advanced Scoring Tips
-@subsection Advanced Scoring Tips
+(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update)
+@end lisp
-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}, @samp{header}) last and quick matches (@samp{from},
-@samp{subject}) first.
+Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix}
+server. See the doc string for @code{nnmairix-update-groups} for
+details.
-The indirection arguments (@code{1-} and so on) will make their
-arguments work on previous generations of the thread. If you say
-something like:
+@item
+Example: search group for ticked articles
-@example
-...
-(1-
- (1-
- ("from" "lars")))
-...
-@end example
+For example, you can create a group for all ticked articles, where the
+articles always stay unread:
-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:
+Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use
+@samp{F:f} as query and do not include threads.
-@example
-(1-
- (&
- ("from" "Lars")
- ("subject" "Gnus")))
-@end example
+Now activate marks propagation for this group by using @kbd{G b p}. Then
+activate the always-unread feature by using @kbd{G b r} twice.
-than it is to say:
+So far so good---but how do you remove the tick marks in the @code{nnmairix}
+group? There are two options: You may simply use
+@code{nnmairix-remove-tick-mark-original-article} (bound to @kbd{$ u}) to remove
+tick marks from the original article. The other possibility is to set
+@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t}, but see the above
+comments about this option. If it works for you, the tick marks should
+also exist in the @code{nnmairix} group and you can remove them as usual,
+e.g. by marking an article as read.
-@example
-(&
- (1- ("from" "Lars"))
- (1- ("subject" "Gnus")))
-@end example
+When you have removed a tick mark from the original article, this
+article should vanish from the @code{nnmairix} group after you have updated the
+mairix database and updated the group. Fortunately, there is a function
+for doing exactly that: @code{nnmairix-update-groups}. See the previous code
+snippet and the doc string for details.
+@item
+Dealing with auto-subscription of mail groups
-@node Score Decays
-@section Score Decays
-@cindex score decays
-@cindex decays
+As described before, all @code{nnmairix} groups are in fact stored on
+the mail back end in the form @samp{zz_mairix-<NAME>-<NUMBER>}. You can
+see them when you enter the back end server in the server buffer. You
+should not subscribe these groups! Unfortunately, these groups will
+usually get @emph{auto-subscribed} when you use @code{nnmaildir} or
+@code{nnml}, i.e. you will suddenly see groups of the form
+@samp{zz_mairix*} pop up in your group buffer. If this happens to you,
+simply kill these groups with C-k. For avoiding this, turn off
+auto-subscription completely by setting the variable
+@code{gnus-auto-subscribed-groups} to @code{nil} (@pxref{Filtering New
+Groups}), or if you like to keep this feature use the following kludge
+for turning it off for all groups beginning with @samp{zz_}:
-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.
+@lisp
+(setq gnus-auto-subscribed-groups
+ "^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*")
+@end lisp
-@vindex gnus-decay-scores
-@findex gnus-decay-score
-@vindex gnus-decay-score-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.
-If @code{gnus-decay-scores} is a regexp, only score files matching this
-regexp are treated. E.g. you may set it to @samp{\\.ADAPT\\'} if only
-@emph{adaptive} score files should be decayed. The decay itself if
-performed by the @code{gnus-decay-score-function} function, which is
-@code{gnus-decay-score} by default. Here's the definition of that
-function:
+@end itemize
-@lisp
-(defun gnus-decay-score (score)
- "Decay SCORE according to `gnus-score-decay-constant'
-and `gnus-score-decay-scale'."
- (let ((n (- score
- (* (if (< score 0) -1 1)
- (min (abs score)
- (max gnus-score-decay-constant
- (* (abs score)
- gnus-score-decay-scale)))))))
- (if (and (featurep 'xemacs)
- ;; XEmacs' floor can handle only the floating point
- ;; number below the half of the maximum integer.
- (> (abs n) (lsh -1 -2)))
- (string-to-number
- (car (split-string (number-to-string n) "\\.")))
- (floor n))))
+@node nnmairix caveats
+@subsection nnmairix caveats
+
+@itemize
+@item
+You can create a secondary @code{nnml} server just for nnmairix, but then
+you have to explicitly set the corresponding server variable
+@code{nnml-get-new-mail} to @code{nil}. Otherwise, new mail might get
+put into this secondary server (and would never show up again). Here's
+an example server definition:
+
+@lisp
+(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil))
@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:
+(The @code{nnmaildir} back end also has a server variabe
+@code{get-new-mail}, but its default value is @code{nil}, so you don't
+have to explicitly set it if you use a @code{nnmaildir} server just for
+mairix.)
-@enumerate
@item
-Scores between -3 and 3 will be set to 0 when this function is called.
+If you use the Gnus registry: don't use the registry with
+@code{nnmairix} groups (put them in
+@code{gnus-registry-unfollowed-groups}). Be @emph{extra careful} if
+you use @code{gnus-registry-split-fancy-with-parent}; mails which are
+split into @code{nnmairix} groups are usually gone for good as soon as
+you check the group for new mail (yes, it has happened to me...).
@item
-Scores with magnitudes between 3 and 60 will be shrunk by 3.
+Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix}
+groups (you shouldn't be able to, anyway).
@item
-Scores with magnitudes greater than 60 will be shrunk by 5% of the
-score.
-@end enumerate
+If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize
+@code{nnmairix} groups (though I have no idea what happens if you do).
-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.
+@item
+mairix does only support us-ascii characters.
-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.
+@item
+@code{nnmairix} uses a rather brute force method to force Gnus to
+completely reread the group on the mail back end after mairix was
+called---it simply deletes and re-creates the group on the mail
+back end. So far, this has worked for me without any problems, and I
+don't see how @code{nnmairix} could delete other mail groups than its
+own, but anyway: you really should have a backup of your mail
+folders.
+
+@item
+All necessary information is stored in the group parameters
+(@pxref{Group Parameters}). This has the advantage that no active file
+is needed, but also implies that when you kill a @code{nnmairix} group,
+it is gone for good.
+
+@item
+@findex nnmairix-purge-old-groups
+If you create and kill a lot of @code{nnmairix} groups, the
+``zz_mairix-*'' groups will accumulate on the mail back end server. To
+delete old groups which are no longer needed, call
+@code{nnmairix-purge-old-groups}. Note that this assumes that you don't
+save any ``real'' mail in folders of the form
+@code{zz_mairix-<NAME>-<NUMBER>}. You can change the prefix of
+@code{nnmairix} groups by changing the variable
+@code{nnmairix-group-prefix}.
+
+@item
+The following only applies if you @emph{don't} use the mentioned patch
+for mairix (@pxref{Propagating marks}):
+
+A problem can occur when using @code{nnmairix} with maildir folders and
+comes with the fact that maildir stores mail flags like @samp{Seen} or
+@samp{Replied} by appending chars @samp{S} and @samp{R} to the message
+file name, respectively. This implies that currently you would have to
+update the mairix database not only when new mail arrives, but also when
+mail flags are changing. The same applies to new mails which are indexed
+while they are still in the @samp{new} folder but then get moved to
+@samp{cur} when Gnus has seen the mail. If you don't update the database
+after this has happened, a mairix query can lead to symlinks pointing to
+non-existing files. In Gnus, these messages will usually appear with
+``(none)'' entries in the header and can't be accessed. If this happens
+to you, using @kbd{G b u} and updating the group will usually fix this.
+
+@end itemize
@iftex
@iflatex
* Compilation:: How to speed Gnus up.
* Mode Lines:: Displaying information in the mode lines.
* Highlighting and Menus:: Making buffers look all nice and cozy.
-* Buttons:: Get tendinitis in ten easy steps!
* Daemons:: Gnus can do things behind your back.
-* NoCeM:: How to avoid spam and other fatty foods.
* Undo:: Some actions can be undone.
* Predicate Specifiers:: Specifying predicates.
* Moderation:: What to do if you're a moderator.
* Fuzzy Matching:: What's the big fuzz?
* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email.
* Spam Package:: A package for filtering and processing spam.
+* The Gnus Registry:: A package for tracking messages by Message-ID.
* Other modes:: Interaction with other modes.
* Various Various:: Things that are really various.
@end menu
@item gnus-expert-user
@vindex gnus-expert-user
If this variable is non-@code{nil}, you will seldom be asked any
-questions by Gnus. It will simply assume you know what you're doing, no
-matter how strange.
+questions by Gnus. It will simply assume you know what you're doing,
+no matter how strange. For example, quitting Gnus, exiting a group
+without an update, catching up with a group, deleting expired
+articles, and replying by mail to a news message will not require
+confirmation.
@item gnus-interactive-catchup
@vindex gnus-interactive-catchup
buffer should be given. Here's an excerpt of this variable:
@lisp
-((group (vertical 1.0 (group 1.0 point)
- (if gnus-carpal (group-carpal 4))))
+((group (vertical 1.0 (group 1.0 point)))
(article (vertical 1.0 (summary 0.25 point)
(article 1.0))))
@end lisp
@lisp
(article (vertical 1.0 (group 4)
(summary 0.25 point)
- (if gnus-carpal (summary-carpal 4))
(article 1.0)))
@end lisp
If the @dfn{split} looks like something that can be @code{eval}ed (to be
precise---if the @code{car} of the split is a function or a subr), this
split will be @code{eval}ed. If the result is non-@code{nil}, it will
-be used as a split. This means that there will be three buffers if
-@code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
-is non-@code{nil}.
+be used as a split.
Not complicated enough for you? Well, try this on for size:
@lisp
(article (horizontal 1.0
(vertical 0.5
- (group 1.0)
- (gnus-carpal 4))
+ (group 1.0))
(vertical 1.0
(summary 0.25 point)
- (summary-carpal 4)
(article 1.0))))
@end lisp
@end table
-@node Buttons
-@section Buttons
-@cindex buttons
-@cindex mouse
-@cindex click
-
-Those new-fangled @dfn{mouse} contraptions is very popular with the
-young, hep kids who don't want to learn the proper way to do things
-these days. Why, I remember way back in the summer of '89, when I was
-using Emacs on a Tops 20 system. Three hundred users on one single
-machine, and every user was running Simula compilers. Bah!
-
-Right.
-
-@vindex gnus-carpal
-Well, you can make Gnus display bufferfuls of buttons you can click to
-do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
-really. Tell the chiropractor I sent you.
-
-
-@table @code
-
-@item gnus-carpal-mode-hook
-@vindex gnus-carpal-mode-hook
-Hook run in all carpal mode buffers.
-
-@item gnus-carpal-button-face
-@vindex gnus-carpal-button-face
-Face used on buttons.
-
-@item gnus-carpal-header-face
-@vindex gnus-carpal-header-face
-Face used on carpal buffer headers.
-
-@item gnus-carpal-group-buffer-buttons
-@vindex gnus-carpal-group-buffer-buttons
-Buttons in the group buffer.
-
-@item gnus-carpal-summary-buffer-buttons
-@vindex gnus-carpal-summary-buffer-buttons
-Buttons in the summary buffer.
-
-@item gnus-carpal-server-buffer-buttons
-@vindex gnus-carpal-server-buffer-buttons
-Buttons in the server buffer.
-
-@item gnus-carpal-browse-buffer-buttons
-@vindex gnus-carpal-browse-buffer-buttons
-Buttons in the browse buffer.
-@end table
-
-All the @code{buttons} variables are lists. The elements in these list
-are either cons cells where the @code{car} contains a text to be displayed and
-the @code{cdr} contains a function symbol, or a simple string.
-
-
@node Daemons
@section Daemons
@cindex demons
(gnus-demon-add-handler 'gnus-demon-close-connections 30 t)
@end lisp
-@findex gnus-demon-add-nocem
@findex gnus-demon-add-scanmail
@findex gnus-demon-add-rescan
@findex gnus-demon-add-scan-timestamps
@findex gnus-demon-add-disconnection
Some ready-made functions to do this have been created:
-@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection},
+@code{gnus-demon-add-disconnection},
@code{gnus-demon-add-nntp-close-connection},
@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and
@code{gnus-demon-add-scanmail}. Just put those functions in your
behave.
-@node NoCeM
-@section NoCeM
-@cindex nocem
-@cindex spam
-
-@dfn{Spamming} is posting the same article lots and lots of times.
-Spamming is bad. Spamming is evil.
-
-Spamming is usually canceled within a day or so by various anti-spamming
-agencies. These agencies usually also send out @dfn{NoCeM} messages.
-NoCeM is pronounced ``no see-'em'', and means what the name
-implies---these are messages that make the offending articles, like, go
-away.
-
-What use are these NoCeM messages if the articles are canceled anyway?
-Some sites do not honor cancel messages and some sites just honor cancels
-from a select few people. Then you may wish to make use of the NoCeM
-messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
-
-Gnus can read and parse the messages in this group automatically, and
-this will make spam disappear.
-
-There are some variables to customize, of course:
-
-@table @code
-@item gnus-use-nocem
-@vindex gnus-use-nocem
-Set this variable to @code{t} to set the ball rolling. It is @code{nil}
-by default.
-
-You can also set this variable to a positive number as a group level.
-In that case, Gnus scans NoCeM messages when checking new news if this
-value is not exceeding a group level that you specify as the prefix
-argument to some commands, e.g. @code{gnus},
-@code{gnus-group-get-new-news}, etc. Otherwise, Gnus does not scan
-NoCeM messages if you specify a group level to those commands. For
-example, if you use 1 or 2 on the mail groups and the levels on the news
-groups remain the default, 3 is the best choice.
-
-@item gnus-nocem-groups
-@vindex gnus-nocem-groups
-Gnus will look for NoCeM messages in the groups in this list. The
-default is
-@lisp
-("news.lists.filters" "news.admin.net-abuse.bulletins"
- "alt.nocem.misc" "news.admin.net-abuse.announce")
-@end lisp
-
-@item gnus-nocem-issuers
-@vindex gnus-nocem-issuers
-There are many people issuing NoCeM messages. This list says what
-people you want to listen to. The default is
-@lisp
-("Automoose-1" "clewis@@ferret.ocunix.on.ca"
- "cosmo.roadkill" "SpamHippo" "hweede@@snafu.de")
-@end lisp
-fine, upstanding citizens all of them.
-
-Known despammers that you can put in this list are listed at@*
-@uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}.
-
-You do not have to heed NoCeM messages from all these people---just the
-ones you want to listen to. You also don't have to accept all NoCeM
-messages from the people you like. Each NoCeM message has a @dfn{type}
-header that gives the message a (more or less, usually less) rigorous
-definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf},
-@samp{binary}, and @samp{troll}. To specify this, you have to use
-@code{(@var{issuer} @var{conditions} @dots{})} elements in the list.
-Each condition is either a string (which is a regexp that matches types
-you want to use) or a list on the form @code{(not @var{string})}, where
-@var{string} is a regexp that matches types you don't want to use.
-
-For instance, if you want all NoCeM messages from Chris Lewis except his
-@samp{troll} messages, you'd say:
-
-@lisp
-("clewis@@ferret.ocunix.on.ca" ".*" (not "troll"))
-@end lisp
-
-On the other hand, if you just want nothing but his @samp{spam} and
-@samp{spew} messages, you'd say:
-
-@lisp
-("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam")
-@end lisp
-
-The specs are applied left-to-right.
-
-
-@item gnus-nocem-verifyer
-@vindex gnus-nocem-verifyer
-@findex pgg-verify
-This should be a function for verifying that the NoCeM issuer is who she
-says she is. The default is @code{pgg-verify}, which returns
-non-@code{nil} if the verification is successful, otherwise (including
-the case the NoCeM message was not signed) returns @code{nil}. If this
-is too slow and you don't care for verification (which may be dangerous),
-you can set this variable to @code{nil}.
-
-Formerly the default was @code{mc-verify}, which is a Mailcrypt
-function. While you can still use it, you can change it into
-@code{pgg-verify} running with GnuPG if you are willing to add the
-@acronym{PGP} public keys to GnuPG's keyring.
-
-@item gnus-nocem-directory
-@vindex gnus-nocem-directory
-This is where Gnus will store its NoCeM cache files. The default is@*
-@file{~/News/NoCeM/}.
-
-@item gnus-nocem-expiry-wait
-@vindex gnus-nocem-expiry-wait
-The number of days before removing old NoCeM entries from the cache.
-The default is 15. If you make it shorter Gnus will be faster, but you
-might then see old spam.
-
-@item gnus-nocem-check-from
-@vindex gnus-nocem-check-from
-Non-@code{nil} means check for valid issuers in message bodies.
-Otherwise don't bother fetching articles unless their author matches a
-valid issuer; that is much faster if you are selective about the
-issuers.
-
-@item gnus-nocem-check-article-limit
-@vindex gnus-nocem-check-article-limit
-If non-@code{nil}, the maximum number of articles to check in any NoCeM
-group. NoCeM groups can be huge and very slow to process.
-
-@end table
-
-Using NoCeM could potentially be a memory hog. If you have many living
-(i. e., subscribed or unsubscribed groups), your Emacs process will grow
-big. If this is a problem, you should kill off all (or most) of your
-unsubscribed groups (@pxref{Subscription Commands}).
-
-
@node Undo
@section Undo
@cindex undo
* Face:: Display a funkier, teensier colored image.
* Smileys:: Show all those happy faces the way they were meant to be shown.
* Picons:: How to display pictures of what you're reading.
+* Gravatars:: Display the avatar of people you read.
* XVarious:: Other XEmacsy Gnusey variables.
@end menu
Ordered list of suffixes on picon file names to try. Defaults to
@code{("xpm" "gif" "xbm")} minus those not built-in your Emacs.
+@item gnus-picon-inhibit-top-level-domains
+@vindex gnus-picon-inhibit-top-level-domains
+If non-@code{nil} (which is the default), don't display picons for
+things like @samp{.net} and @samp{.de}, which aren't usually very
+interesting.
+
+@end table
+
+@node Gravatars
+@subsection Gravatars
+
+@iftex
+@iflatex
+\include{gravatars}
+@end iflatex
+@end iftex
+
+A gravatar is an image registered to an e-mail address.
+
+You can submit yours on-line at @uref{http://www.gravatar.com}.
+
+The following variables offer control over how things are displayed.
+
+@table @code
+
+@item gnus-gravatar-size
+@vindex gnus-gravatar-size
+The size in pixels of gravatars. Gravatars are always square, so one
+number for the size is enough.
+
+@item gnus-gravatar-properties
+@vindex gnus-gravatar-properties
+List of image properties applied to Gravatar images.
+
+@item gnus-gravatar-too-ugly
+@vindex gnus-gravatar-too-ugly
+Regexp that matches mail addresses or names of people of which avatars
+should not be displayed, or @code{nil}. It default to the value of
+@code{gnus-article-x-face-too-ugly} (@pxref{X-Face}).
+
@end table
+If you want to see them in the From field, set:
+@lisp
+(setq gnus-treat-from-gravatar 'head)
+@end lisp
+
+If you want to see them in the Cc and To fields, set:
+
+@lisp
+(setq gnus-treat-mail-gravatar 'head)
+@end lisp
+
@node XVarious
@subsection Various XEmacs Variables
Note that with the nnimap back end, message bodies will not be
downloaded by default. You need to set
@code{nnimap-split-download-body} to @code{t} to do that
-(@pxref{Splitting in IMAP}).
+(@pxref{Client-Side IMAP Splitting}).
That is about it. As some spam is likely to get through anyway, you
might want to have a nifty function to call when you happen to read
spam. And here is the nifty function:
@lisp
- (defun my-gnus-raze-spam ()
+(defun my-gnus-raze-spam ()
"Submit SPAM to Vipul's Razor, then mark it as expirable."
(interactive)
- (gnus-summary-show-raw-article)
- (gnus-summary-save-in-pipe "razor-report -f -d")
+ (gnus-summary-save-in-pipe "razor-report -f -d" t)
(gnus-summary-mark-as-expirable 1))
@end lisp
group:
@table @kbd
-@item M-d
+@item $
+@itemx M-d
@itemx M s x
@itemx S x
-@kindex M-d
-@kindex S x
-@kindex M s x
+@kindex $ (Summary)
+@kindex M-d (Summary)
+@kindex S x (Summary)
+@kindex M s x (Summary)
@findex gnus-summary-mark-as-spam
@findex gnus-summary-mark-as-spam
Mark current article as spam, showing it with the @samp{$} mark
@vindex nnimap-split-download-body
Note for IMAP users: if you use the @code{spam-check-bogofilter},
@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends,
-you should also set set the variable @code{nnimap-split-download-body}
-to @code{t}. These spam back ends are most useful when they can
-``scan'' the full message body. By default, the nnimap back end only
-retrieves the message headers; @code{nnimap-split-download-body} tells
-it to retrieve the message bodies as well. We don't set this by
-default because it will slow @acronym{IMAP} down, and that is not an
-appropriate decision to make on behalf of the user. @xref{Splitting
-in IMAP}.
+you should also set the variable @code{nnimap-split-download-body} to
+@code{t}. These spam back ends are most useful when they can ``scan''
+the full message body. By default, the nnimap back end only retrieves
+the message headers; @code{nnimap-split-download-body} tells it to
+retrieve the message bodies as well. We don't set this by default
+because it will slow @acronym{IMAP} down, and that is not an
+appropriate decision to make on behalf of the user. @xref{Client-Side
+IMAP Splitting}.
You have to specify one or more spam back ends for @code{spam-split}
to use, by setting the @code{spam-use-*} variables. @xref{Spam Back
spam-move-spam-nonspam-groups-only nil
spam-mark-only-unseen-as-spam t
spam-mark-ham-unread-before-move-from-spam-group t
- nnimap-split-rule 'nnimap-split-fancy
;; @r{understand what this does before you copy it to your own setup!}
+ ;; @r{for nnimap you'll probably want to set nnimap-split-methods, see the manual}
nnimap-split-fancy '(|
;; @r{trace references to parents and put in their group}
(: gnus-registry-split-fancy-with-parent)
@example
(setq spam-use-spamoracle t
spam-split-group "Junk"
+ ;; @r{for nnimap you'll probably want to set nnimap-split-methods, see the manual}
nnimap-split-inbox '("INBOX")
- nnimap-split-rule 'nnimap-split-fancy
nnimap-split-fancy '(| (: spam-split) "INBOX"))
@end example
Save table: (spam-stat-save)
@end smallexample
+@node The Gnus Registry
+@section The Gnus Registry
+@cindex registry
+@cindex split
+@cindex track
+
+The Gnus registry is a package that tracks messages by their
+Message-ID across all backends. This allows Gnus users to do several
+cool things, be the envy of the locals, get free haircuts, and be
+experts on world issues. Well, maybe not all of those, but the
+features are pretty cool.
+
+Although they will be explained in detail shortly, here's a quick list
+of said features in case your attention span is... never mind.
+
+@enumerate
+@item
+Split messages to their parent
+
+This keeps discussions in the same group. You can use the subject and
+the sender in addition to the Message-ID. Several strategies are
+available.
+
+@item
+Refer to messages by ID
+
+Commands like @code{gnus-summary-refer-parent-article} can take
+advantage of the registry to jump to the referred article, regardless
+of the group the message is in.
+
+@item
+Store custom flags and keywords
+
+The registry can store custom flags and keywords for a message. For
+instance, you can mark a message ``To-Do'' this way and the flag will
+persist whether the message is in the nnimap, nnml, nnmaildir,
+etc. backends.
+
+@item
+Store arbitrary data
+
+Through a simple ELisp API, the registry can remember any data for a
+message. A built-in inverse map, when activated, allows quick lookups
+of all messages matching a particular set of criteria.
+@end enumerate
+
+@menu
+* Setup::
+* Fancy splitting to parent::
+* Registry Article Refer Method::
+* Store custom flags and keywords::
+* Store arbitrary data::
+@end menu
+
+@node Setup
+@subsection Setup
+
+Fortunately, setting up the Gnus registry is pretty easy:
+
+@lisp
+(setq gnus-registry-max-entries 2500
+ gnus-registry-use-long-group-names t)
+
+(gnus-registry-initialize)
+@end lisp
+
+This adds registry saves to Gnus newsrc saves (which happen on exit
+and when you press @kbd{s} from the @code{*Group*} buffer. It also
+adds registry calls to article actions in Gnus (copy, move, etc.) so
+it's not easy to undo the initialization. See
+@code{gnus-registry-initialize} for the gory details.
+
+Here are other settings used by the author of the registry (understand
+what they do before you copy them blindly).
+
+@lisp
+(setq
+ gnus-registry-split-strategy 'majority
+ gnus-registry-ignored-groups '(("nntp" t)
+ ("nnrss" t)
+ ("spam" t)
+ ("train" t))
+ gnus-registry-max-entries 500000
+ gnus-registry-use-long-group-names t
+ gnus-registry-track-extra '(sender subject))
+@end lisp
+
+They say: keep a lot of messages around, use long group names, track
+messages by sender and subject (not just parent Message-ID), and when
+the registry splits incoming mail, use a majority rule to decide where
+messages should go if there's more than one possibility. In addition,
+the registry should ignore messages in groups that match ``nntp'',
+``nnrss'', ``spam'', or ``train.''
+
+You are doubtless impressed by all this, but you ask: ``I am a Gnus
+user, I customize to live. Give me more.'' Here you go, these are
+the general settings.
+
+@defvar gnus-registry-unfollowed-groups
+The groups that will not be followed by
+@code{gnus-registry-split-fancy-with-parent}. They will still be
+remembered by the registry. This is a list of regular expressions.
+@end defvar
+
+@defvar gnus-registry-ignored-groups
+The groups that will not be remembered by the registry. This is a
+list of regular expressions, also available through Group/Topic
+customization (so you can ignore or keep a specific group or a whole
+topic).
+@end defvar
+
+@defvar gnus-registry-use-long-group-names
+Whether the registry will use long group names. It's recommended to
+set this to @code{t}, although everything works if you don't. Future
+functionality will require it.
+@end defvar
+
+@defvar gnus-registry-max-entries
+The number (an integer or @code{nil} for unlimited) of entries the
+registry will keep.
+@end defvar
+
+@defvar gnus-registry-cache-file
+The file where the registry will be stored between Gnus sessions.
+@end defvar
+
+@node Registry Article Refer Method
+@subsection Fetching by @code{Message-ID} Using the Registry
+
+The registry knows how to map each @code{Message-ID} to the group it's
+in. This can be leveraged to enhance the ``article refer method'',
+the thing that tells Gnus how to look up an article given its
+Message-ID (@pxref{Finding the Parent}).
+
+@vindex nnregistry
+@vindex gnus-refer-article-method
+
+The @code{nnregistry} refer method does exactly that. It has the
+advantage that an article may be found regardless of the group it's
+in---provided its @code{Message-ID} is known to the registry. It can
+be enabled by augmenting the start-up file with something along these
+lines:
+
+@example
+;; Keep enough entries to have a good hit rate when referring to an
+;; article using the registry. Use long group names so that Gnus
+;; knows where the article is.
+(setq gnus-registry-max-entries 2500
+ gnus-registry-use-long-group-names t)
+
+(gnus-registry-initialize)
+
+(setq gnus-refer-article-method
+ '(current
+ (nnregistry)
+ (nnweb "gmane" (nnweb-type gmane))))
+@end example
+
+The example above instructs Gnus to first look up the article in the
+current group, or, alternatively, using the registry, and finally, if
+all else fails, using Gmane.
+
+@node Fancy splitting to parent
+@subsection Fancy splitting to parent
+
+Simply put, this lets you put followup e-mail where it belongs.
+
+Every message has a Message-ID, which is unique, and the registry
+remembers it. When the message is moved or copied, the registry will
+notice this and offer the new group as a choice to the splitting
+strategy.
+
+When a followup is made, usually it mentions the original message's
+Message-ID in the headers. The registry knows this and uses that
+mention to find the group where the original message lives. You only
+have to put a rule like this:
+
+@lisp
+(setq nnimap-my-split-fancy '(|
+
+ ;; split to parent: you need this
+ (: gnus-registry-split-fancy-with-parent)
+
+ ;; other rules, as an example
+ (: spam-split)
+ ;; default mailbox
+ "mail")
+@end lisp
+
+in your fancy split setup. In addition, you may want to customize the
+following variables.
+
+@defvar gnus-registry-track-extra
+This is a list of symbols, so it's best to change it from the
+Customize interface. By default it's @code{nil}, but you may want to
+track @code{subject} and @code{sender} as well when splitting by parent.
+It may work for you. It can be annoying if your mail flow is large and
+people don't stick to the same groups.
+@end defvar
+
+@defvar gnus-registry-split-strategy
+This is a symbol, so it's best to change it from the Customize
+interface. By default it's @code{nil}, but you may want to set it to
+@code{majority} or @code{first} to split by sender or subject based on
+the majority of matches or on the first found.
+@end defvar
+
+@node Store custom flags and keywords
+@subsection Store custom flags and keywords
+
+The registry lets you set custom flags and keywords per message. You
+can use the Gnus->Registry Marks menu or the @kbd{M M x} keyboard
+shortcuts, where @code{x} is the first letter of the mark's name.
+
+@defvar gnus-registry-marks
+The custom marks that the registry can use. You can modify the
+default list, if you like. If you do, you'll have to exit Emacs
+before they take effect (you can also unload the registry and reload
+it or evaluate the specific macros you'll need, but you probably don't
+want to bother). Use the Customize interface to modify the list.
+
+By default this list has the @code{Important}, @code{Work},
+@code{Personal}, @code{To-Do}, and @code{Later} marks. They all have
+keyboard shortcuts like @kbd{M M i} for Important, using the first
+letter.
+@end defvar
+
+@defun gnus-registry-mark-article
+Call this function to mark an article with a custom registry mark. It
+will offer the available marks for completion.
+@end defun
+
+@node Store arbitrary data
+@subsection Store arbitrary data
+
+The registry has a simple API that uses a Message-ID as the key to
+store arbitrary data (as long as it can be converted to a list for
+storage).
+
+@defun gnus-registry-store-extra-entry (id key value)
+Store @code{value} in the extra data key @code{key} for message
+@code{id}.
+@end defun
+
+@defun gnus-registry-delete-extra-entry (id key)
+Delete the extra data key @code{key} for message @code{id}.
+@end defun
+
+@defun gnus-registry-fetch-extra (id key)
+Get the extra data key @code{key} for message @code{id}.
+@end defun
+
+@defvar gnus-registry-extra-entries-precious
+If any extra entries are precious, their presence will make the
+registry keep the whole entry forever, even if there are no groups for
+the Message-ID and if the size limit of the registry is reached. By
+default this is just @code{(marks)} so the custom registry marks are
+precious.
+@end defvar
+
@node Other modes
@section Interaction with other modes
@acronym{IMAP} users might want to allow @samp{/} in group names though.
+@item gnus-safe-html-newsgroups
+@vindex gnus-safe-html-newsgroups
+Groups in which links in html articles are considered all safe. The
+value may be a regexp matching those groups, a list of group names, or
+@code{nil}. This overrides @code{mm-w3m-safe-url-regexp}. The default
+value is @code{"\\`nnrss[+:]"}. This is effective only when emacs-w3m
+renders html articles, i.e., in the case @code{mm-text-html-renderer} is
+set to @code{w3m}. @xref{Display Customization, ,Display Customization,
+emacs-mime, The Emacs MIME Manual}.
@end table
On the January 4th 2004, No Gnus was begun.
+On April 19, 2010 Gnus development was moved to Git. See
+http://git.gnus.org for details (http://www.gnus.org will be updated
+with the information when possible).
+
If you happen upon a version of Gnus that has a prefixed name --
``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'',
``Pterodactyl Gnus'', ``Oort Gnus'', ``No Gnus'' -- don't panic.
Masanobu @sc{Umeda}---the writer of the original @sc{gnus}.
@item
-Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, webmail.el,
+Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el,
nnwarchive and many, many other things connected with @acronym{MIME} and
other types of en/decoding, as well as general bug fixing, new
functionality and stuff.
You can set the process mark on both groups and articles and perform
operations on all the marked items (@pxref{Process/Prefix}).
-@item
-You can grep through a subset of groups and create a group from the
-results (@pxref{Kibozed Groups}).
-
@item
You can list subsets of groups according to, well, anything
(@pxref{Listing Groups}).
You can do lots of strange stuff with the Gnus window & frame
configuration (@pxref{Window Layout}).
-@item
-You can click on buttons instead of using the keyboard
-(@pxref{Buttons}).
-
@end itemize
else (@pxref{Document Groups}).
@item
-Gnus has a new back end (@code{nnsoup}) to create/read SOUP packets
-(@pxref{SOUP}).
+Gnus has a new back end (@code{nnsoup}) to create/read SOUP packets.
@item
The Gnus cache is much faster.
@end iflatex
@end iftex
-@item
-Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}).
-
-@lisp
-(setq gnus-use-nocem t)
-@end lisp
-
@item
Groups can be made permanently visible (@pxref{Listing Groups}).
hierarchy.
@c FIXME: `gnus-load' is mentioned in README, which is not included in
-@c CVS. We should find a better place for this item.
+@c the repository. We should find a better place for this item.
@item
@code{(require 'gnus-load)}
@acronym{TLS} wrapper shipped with Gnus
@acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and
-@acronym{NNTP} via @file{tls.el} and GNUTLS. The old
-@acronym{TLS}/@acronym{SSL} support via (external third party)
-@file{ssl.el} and OpenSSL still works.
+@acronym{NNTP} via @file{tls.el} and GNUTLS.
@item
Improved anti-spam features.
@item
@code{message-insinuate-rmail}
+@c FIXME should that not be 'message-user-agent?
Adding @code{(message-insinuate-rmail)} and @code{(setq
mail-user-agent 'gnus-user-agent)} in @file{.emacs} convinces Rmail to
compose, reply and forward messages in message-mode, where you can
@item You can now drag and drop attachments to the Message buffer.
See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}.
@xref{MIME, ,MIME, message, Message Manual}.
-@c New in 5.10.9 / 5.11 (Emacs 21.1)
+@c New in 5.10.9 / 5.11 (Emacs 22.1)
@item @code{auto-fill-mode} is enabled by default in Message mode.
See @code{message-fill-column}. @xref{Various Message Variables, ,
As the variables for the other back ends, there are
@code{nndiary-nov-is-evil}, @code{nndir-nov-is-evil},
@code{nnfolder-nov-is-evil}, @code{nnimap-nov-is-evil},
-@code{nnml-nov-is-evil}, @code{nnspool-nov-is-evil}, and
-@code{nnwarchive-nov-is-evil}. Note that a non-@code{nil} value for
-@code{gnus-nov-is-evil} overrides all those variables.@footnote{Although
-the back ends @code{nnkiboze}, @code{nnslashdot}, @code{nnultimate}, and
-@code{nnwfm} don't have their own nn*-nov-is-evil.}
+@code{nnml-nov-is-evil}, and @code{nnspool-nov-is-evil}. Note that a
+non-@code{nil} value for @code{gnus-nov-is-evil} overrides all those
+variables.
@end table
on successful article retrieval.
-@item (nnchoke-request-group GROUP &optional SERVER FAST)
+@item (nnchoke-request-group GROUP &optional SERVER FAST INFO)
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.
+If @var{info}, it allows the backend to update the group info
+structure.
+
Here's an example of some result data and a definition of the same:
@example
@lisp
;;; @r{nndir.el --- single directory newsgroup access for Gnus}
-;; @r{Copyright (C) 1995,96 Free Software Foundation, Inc.}
+;; @r{Copyright (C) 1995,1996 Free Software Foundation, Inc.}
;;; @r{Code:}
(setq gnus-read-active-file 'some)
@end lisp
-On the other hand, if the manual says ``set @code{gnus-nntp-server} to
-@samp{nntp.ifi.uio.no}'', that means:
+On the other hand, if the manual says ``set @code{gnus-nntp-server-file} to
+@samp{/etc/nntpserver}'', that means:
@lisp
-(setq gnus-nntp-server "nntp.ifi.uio.no")
+(setq gnus-nntp-server-file "/etc/nntpserver")
@end lisp
So be careful not to mix up strings (the latter) with symbols (the
@chapter Key Index
@printindex ky
-@summarycontents
-@contents
@bye
@iftex
@c mode: texinfo
@c coding: iso-8859-1
@c End:
-
-@ignore
- arch-tag: c9fa47e7-78ca-4681-bda9-9fef45d1c819
-@end ignore
projects / gnus / blobdiff