\makeindex
\begin{document}
-\newcommand{\gnusversionname}{Oort Gnus v0.12}
+\newcommand{\gnusversionname}{Oort Gnus v0.16}
\newcommand{\gnuschaptername}{}
\newcommand{\gnussectionname}{}
\newcommand{\gnusversion}[1]{{\small\textit{#1}}}
\newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
\newcommand{\gnusresult}[1]{\gnustt{=> #1}}
+\newcommand{\gnusacronym}[1]{\textit{#1}}
+\newcommand{\gnusemail}[1]{\textit{#1}}
\newcommand{\gnusbullet}{{${\bullet}$}}
\newcommand{\gnusdollar}{\$}
spool or your mbox file. All at the same time, if you want to push your
luck.
-This manual corresponds to Oort Gnus v0.12.
+This manual corresponds to Oort Gnus v0.16.
@end ifinfo
* Loose Threads:: How Gnus gathers loose threads into bigger threads.
* Filling In Threads:: Making the threads displayed look fuller.
* More Threading:: Even more variables for fiddling with threads.
-* Low-Level Threading:: You thought it was over... but you were wrong!
+* Low-Level Threading:: You thought it was over@dots{} but you were wrong!
Decoding Articles
* Rmail Babyl:: Emacs programs use the rmail babyl format.
* Mail Spool:: Store your mail in a private spool?
* MH Spool:: An mhspool-like back end.
+* Maildir:: Another one-file-per-message format.
* Mail Folders:: Having one file for each group.
* Comparing Mail Back Ends:: An in-depth looks at pros and cons.
* 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.
+* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
* A note on namespaces:: How to (not) use IMAP namespace in Gnus.
Other Sources
* Agent Commands:: New commands for all the buffers.
* 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 IMAP:: How to use the Agent with IMAP.
* Outgoing Messages:: What happens when you post/mail something?
* Agent Variables:: Customizing is fun.
Agent Commands
-* Group Agent Commands::
-* Summary Agent Commands::
-* Server Agent Commands::
+* 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.
Scoring
* Picons:: How to display pictures of what you're reading.
* Smileys:: Show all those happy faces the way they were meant to be shown.
* X-Face:: Display a funky, teensy black-and-white image.
-* Toolbar:: Click'n'drool.
* XVarious:: Other XEmacsy Gnusey variables.
-Picons
-
-* Picon Basics:: What are picons and How do I get them.
-* Picon Requirements:: Don't go further if you aren't using XEmacs.
-* Easy Picons:: Displaying Picons---the easy way.
-* Hard Picons:: The way you should do it. You'll learn something.
-* Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with.
-
Thwarting Email Spam
* The problem of spam:: Some background, and some solutions
that is no problem whatsoever. You just do it.
The problem appears when you want to run two Gnusae that use the same
-@code{.newsrc} file.
+@file{.newsrc} file.
To work around that problem some, we here at the Think-Tank at the Gnus
Towers have come up with a new concept: @dfn{Masters} and
me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
Applications}) will be much more expensive, of course.)
+@findex gnus-slave
Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or
however you do it). Each subsequent slave Gnusae should be started with
@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
they were created, so the latest changes will have precedence.)
Information from the slave files has, of course, precedence over the
-information in the normal (i.e., master) @code{.newsrc} file.
+information in the normal (i.e., master) @file{.newsrc} file.
-If the @code{.newsrc*} files have not been saved in the master when the
+If the @file{.newsrc*} files have not been saved in the master when the
slave starts, you may be prompted as to whether to read an auto-save
-file. If you answer "yes", the unsaved changes to the master will be
-incorporated into the slave. If you answer "no", the slave may see some
+file. If you answer ``yes'', the unsaved changes to the master will be
+incorporated into the slave. If you answer ``no'', the slave may see some
messages as unread that have been read in the master.
@node Fetching a Group
several servers where not all servers support @code{ask-server}.
@vindex gnus-startup-file
+@vindex gnus-backup-startup-file
+@vindex version-control
The @code{gnus-startup-file} variable says where the startup files are.
The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
file being whatever that one is, with a @samp{.eld} appended.
+If you want version control for this file, set
+@code{gnus-backup-startup-file}. It respects the same values as the
+@code{version-control} variable.
@vindex gnus-save-newsrc-hook
@vindex gnus-save-quick-newsrc-hook
@end lisp
@vindex gnus-init-file
+@vindex gnus-site-init-file
When Gnus starts, it will read the @code{gnus-site-init-file}
(@file{.../site-lisp/gnus} by default) and @code{gnus-init-file}
(@file{~/.gnus} by default) files. These are normal Emacs Lisp files
this variable is @code{nil}, which it is by default, Gnus will dribble
into the directory where the @file{.newsrc} file is located. (This is
normally the user's home directory.) The dribble file will get the same
-file permissions as the @code{.newsrc} file.
+file permissions as the @file{.newsrc} file.
@vindex gnus-always-read-dribble-file
If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will
If non-@code{nil}, the startup message won't be displayed. That way,
your boss might not notice as easily that you are reading news instead
of doing your job. Note that this variable is used before
-@file{.gnus.el} is loaded, so it should be set in @code{.emacs} instead.
+@file{.gnus.el} is loaded, so it should be set in @file{.emacs} instead.
@item gnus-no-groups-message
@vindex gnus-no-groups-message
@item ticked
The number of ticked articles in the group.
@item total
-The total number of articles in the group. Or rather, MAX-NUMBER minus
-MIN-NUMBER plus one.
+The total number of articles in the group. Or rather,
+@var{max-number} minus @var{min-number} plus one.
@item topic
When using the topic minor mode, this variable is bound to the current
topic being inserted.
first unread article (@code{gnus-group-read-group}). If there are no
unread articles in the group, or if you give a non-numerical prefix to
this command, Gnus will offer to fetch all the old articles in this
-group from the server. If you give a numerical prefix @var{N}, @var{N}
-determines the number of articles Gnus will fetch. If @var{N} is
-positive, Gnus fetches the @var{N} newest articles, if @var{N} is
-negative, Gnus fetches the @code{abs(@var{N})} oldest articles.
+group from the server. If you give a numerical prefix @var{n}, @var{n}
+determines the number of articles Gnus will fetch. If @var{n} is
+positive, Gnus fetches the @var{n} newest articles, if @var{n} is
+negative, Gnus fetches the @code{abs(@var{n})} oldest articles.
Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old
articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u
@vindex gnus-select-group-hook
@vindex gnus-auto-select-first
+@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
(auto-expire . t))
@end example
-We see that each element consists of a "dotted pair"---the thing before
+We see that each element consists of a ``dotted pair''---the thing before
the dot is the key, while the thing after the dot is the value. All the
parameters have this form @emph{except} local variable specs, which are
not dotted pairs, but proper lists.
to-address and to-list parameters for this group as addresses of
mailing lists you are subscribed to. Giving Gnus this information is
(only) a first step in getting it to generate correct Mail-Followup-To
-headers for your posts to these lists. Look here @pxref{(message)Mailing
-Lists} for a complete treatment of available MFT support.
+headers for your posts to these lists. Look here @pxref{Mailing
+Lists, , Mailing Lists, message, The Message Manual} for a complete
+treatment of available MFT support.
See also @code{gnus-find-subscribed-addresses}, the function that
directly uses this group parameter.
Display all articles, both read and unread.
@item an integer
-Display the last INTEGER articles in the group. This is the same as
-entering the group with C-u INTEGER.
+Display the last @var{integer} articles in the group. This is the same as
+entering the group with C-u @var{integer}.
@item default
Display the default visible articles, which normally includes unread and
silly Lisp errors.) You might also be interested in reading about topic
parameters (@pxref{Topic Parameters}).
+@vindex gnus-parameters
Group parameters can be set via the @code{gnus-parameters} variable too.
But some variables, such as @code{visible}, have no effect. For
example:
-@example
+@lisp
(setq gnus-parameters
'(("mail\\..*"
(gnus-show-threads nil)
("list\\..*"
(total-expire . t)
(broken-reply-to . t))))
-@end example
+@end lisp
String value of parameters will be subjected to regexp substitution, as
the @code{to-group} example shows.
@vindex gnus-exit-gnus-hook
@vindex gnus-suspend-gnus-hook
+@vindex gnus-after-exiting-gnus-hook
@code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
@code{gnus-exit-gnus-hook} is called when you quit Gnus, while
@code{gnus-after-exiting-gnus-hook} is called as the final item when
is a toggling command.)
Go ahead, just try it. I'll still be here when you get back. La de
-dum... Nice tune, that... la la la... What, you're back? Yes, and
-now press @kbd{l}. There. All your groups are now listed under
-@samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
-bothered?
+dum@dots{} Nice tune, that@dots{} la la la@dots{} What, you're back?
+Yes, and now press @kbd{l}. There. All your groups are now listed
+under @samp{misc}. Doesn't that make you feel all warm and fuzzy?
+Hot and bothered?
If you want this permanently enabled, you should add that minor mode to
the hook for the group mode. Put the following line in your
@kindex T # (Topic)
@findex gnus-topic-mark-topic
Mark all groups in the current topic with the process mark
-(@code{gnus-topic-mark-topic}).
+(@code{gnus-topic-mark-topic}). This command works recursively on
+sub-topics unless given a prefix.
@item T M-#
@kindex T M-# (Topic)
@findex gnus-topic-unmark-topic
Remove the process mark from all groups in the current topic
-(@code{gnus-topic-unmark-topic}).
+(@code{gnus-topic-unmark-topic}). This command works recursively on
+sub-topics unless given a prefix.
@item C-c C-x
@kindex C-c C-x (Topic)
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
+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.
@vindex gnus-group-name-charset-group-alist
An alist of regexp of group name and the charset for group names. It
is used to show non-ASCII group names. @code{((".*" utf-8))} is the
-default value if UTF-8 is supported, otherwise the default is nil.
+default value if UTF-8 is supported, otherwise the default is
+@code{nil}.
For example:
@lisp
@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-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.
+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{(emacs)Compressed Files}).
+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
@vindex gnus-sieve-crosspost
The variable @code{gnus-sieve-crosspost} controls how the Sieve script
-is generated. If it is non-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"
+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 nil. (When
-@code{gnus-sieve-crosspost} is non-nil, it looks the same except that
-the line containing the call to @code{stop} is removed.)
+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" @{
Indentation based on thread level (@pxref{Customizing Threading}).
@item B
A complex trn-style thread tree, showing response-connecting trace
-lines.
+lines. A thread could be drawn like this:
+
+@example
+>
++->
+| +->
+| | \->
+| | \->
+| \->
++->
+\->
+@end example
+
+You can customize the appearance with the following options. Note
+that it is possible to make the thread display look really neat by
+replacing the default ASCII characters with graphic line-drawing
+glyphs.
+@table @code
+@item gnus-sum-thread-tree-root
+@vindex gnus-sum-thread-tree-root
+Used for the root of a thread. If @code{nil}, use subject
+instead. The default is @samp{> }.
+
+@item gnus-sum-thread-tree-single-indent
+@vindex gnus-sum-thread-tree-single-indent
+Used for a thread with just one message. If @code{nil}, use subject
+instead. The default is @samp{}.
+
+@item gnus-sum-thread-tree-vertical
+@vindex gnus-sum-thread-tree-vertical
+Used for drawing a vertical line. The default is @samp{| }.
+
+@item gnus-sum-thread-tree-indent
+@vindex gnus-sum-thread-tree-indent
+Used for indenting. The default is @samp{ }.
+
+@item gnus-sum-thread-tree-leaf-with-other
+@vindex gnus-sum-thread-tree-leaf-with-other
+Used for a leaf with brothers. The default is @samp{+-> }.
+
+@item gnus-sum-thread-tree-single-leaf
+@vindex gnus-sum-thread-tree-single-leaf
+Used for a leaf without brothers. The default is @samp{\-> }
+
+@end table
+
@item T
Nothing if the article is a root and lots of spaces if it isn't (it
pushes everything after it off the screen).
@vindex nnmail-extra-headers
A related variable is @code{nnmail-extra-headers}, which controls when
-to include extra headers when generating overview (@sc{nov}) files. If
-you have old overview files, you should regenerate them after changing
-this variable, by entering the server buffer using `^', and then `g' on
-the appropriate mail server (e.g. nnml) to cause regeneration.
+to include extra headers when generating overview (@sc{nov}) files.
+If you have old overview files, you should regenerate them after
+changing this variable, by entering the server buffer using @kbd{^},
+and then @kbd{g} on the appropriate mail server (e.g. nnml) to cause
+regeneration.
@vindex gnus-summary-line-format
You also have to instruct Gnus to display the data by changing the
Select the current article, or, if that one's read already, the next
unread article (@code{gnus-summary-next-page}).
+If you have an article window open already and you press @kbd{SPACE}
+again, the article will be scrolled. This lets you conveniently
+@kbd{SPACE} through an entire newsgroup. @pxref{Paging the Article}.
+
@item G n
@itemx n
@kindex n (Summary)
@item gnus-select-article-hook
@vindex gnus-select-article-hook
This hook is called whenever an article is selected. By default it
-exposes any threads hidden under the selected article. If you wish
-that the Agent saves all articles you read, putting
-@code{gnus-agent-fetch-selected-article} on this hook should do it.
+exposes any threads hidden under the selected article. If you would
+like each article to be saved in the Agent as you read it, putting
+@code{gnus-agent-fetch-selected-article} on this hook will do so.
@item gnus-mark-article-hook
@vindex gnus-mark-article-hook
or, if you have come to the end of the current article, will choose the
next article (@code{gnus-summary-next-page}).
+@vindex gnus-article-boring-faces
+@vindex gnus-article-skip-boring
+If @code{gnus-article-skip-boring} is non-@code{nil} and the rest of
+the article consists only of citations and signature, then it will be
+skipped; the next article will be shown instead. You can customize
+what is considered uninteresting with
+@code{gnus-article-boring-faces}. You can manually view the article's
+pages, no matter how boring, using @kbd{C-M-v}.
+
@item DEL
@kindex DEL (Summary)
@findex gnus-summary-prev-page
prefix is 1, prompt for a group to post to.
This function actually prepares a news even when using mail groups.
-This is useful for "posting" messages to mail groups without actually
+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.
@code{X-Gnus-Delayed} header and puts the message in the
@code{nndraft:delayed} group.
+@findex gnus-delay-send-queue
And whenever you get new news, Gnus looks through the group for articles
which are due and sends them. It uses the @code{gnus-delay-send-queue}
function for this. By default, this function is added to the hook
@findex gnus-delay-initialize
By default, this function installs @code{gnus-delay-send-queue} in
@code{gnus-get-new-news-hook}. But it accepts the optional second
-argument @code{no-check}. If it is non-nil,
+argument @code{no-check}. If it is non-@code{nil},
@code{gnus-get-new-news-hook} is not changed. The optional first
argument is ignored.
with a @samp{.} in the second column (@code{gnus-unseen-mark}).
Compare with @code{gnus-recent-mark}.
+@item
+@vindex gnus-downloaded-mark
+When using the Gnus agent @pxref{Agent Basics}, articles may be
+downloaded for unplugged (offline) viewing. If you are using the
+@samp{%O} spec, these articles get the @samp{+} mark in that spec.
+(The variable @code{gnus-downloaded-mark} controls which character to
+use.)
+
@item
@vindex gnus-undownloaded-mark
-When using the Gnus agent @pxref{Agent Basics}, some articles might not
-have been downloaded. Such articles cannot be viewed while you are
-offline (unplugged). These articles get the @samp{@@} mark in the
-first column. (The variable @code{gnus-undownloaded-mark} controls
-which character to use.)
+When using the Gnus agent @pxref{Agent Basics}, some articles might
+not have been downloaded. Such articles cannot be viewed while you
+are unplugged (offline). If you are using the @samp{%O} spec, these
+articles get the @samp{-} mark in that spec. (The variable
+@code{gnus-undownloaded-mark} controls which character to use.)
@item
@vindex gnus-downloadable-mark
* Loose Threads:: How Gnus gathers loose threads into bigger threads.
* Filling In Threads:: Making the threads displayed look fuller.
* More Threading:: Even more variables for fiddling with threads.
-* Low-Level Threading:: You thought it was over... but you were wrong!
+* Low-Level Threading:: You thought it was over@dots{} but you were wrong!
@end menu
format of the dummy roots. It accepts only one format spec: @samp{S},
which is the subject of the article. @xref{Formatting Variables}.
If you want all threads to have a dummy root, even the non-gathered
-ones, set @code{gnus-summary-make-false-root-always} to t.
+ones, set @code{gnus-summary-make-false-root-always} to @code{t}.
@item empty
Gnus won't actually make any article the parent, but simply leave the
@vindex gnus-thread-operation-ignore-subject
If you ignore subject while threading, you'll naturally end up with
threads that have several different subjects in them. If you then issue
-a command like `T k' (@code{gnus-summary-kill-thread}) you might not
+a command like @kbd{T k} (@code{gnus-summary-kill-thread}) you might not
wish to kill the entire thread, but just those parts of the thread that
have the same subject as the current article. If you like this idea,
you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it
also become more loaded---both with the extra article requests, and the
extra connection.
-Ok, so now you know that you shouldn't really use this thing... unless
+Ok, so now you know that you shouldn't really use this thing@dots{} unless
you really want to.
@vindex gnus-asynchronous
@vindex gnus-async-prefetch-article-p
@findex gnus-async-read-p
There are probably some articles that you don't want to pre-fetch---read
-articles, for instance. The @code{gnus-async-prefetch-article-p} variable controls whether an article is to be pre-fetched. This function should
-return non-@code{nil} when the article in question is to be
-pre-fetched. The default is @code{gnus-async-read-p}, which returns
-@code{nil} on read articles. The function is called with an article
-data structure as the only parameter.
+articles, for instance. The @code{gnus-async-prefetch-article-p}
+variable controls whether an article is to be pre-fetched. This
+function should return non-@code{nil} when the article in question is
+to be pre-fetched. The default is @code{gnus-async-read-p}, which
+returns @code{nil} on read articles. The function is called with an
+article data structure as the only parameter.
-If, for instance, you wish to pre-fetch only unread articles shorter than 100 lines, you could say something like:
+If, for instance, you wish to pre-fetch only unread articles shorter
+than 100 lines, you could say something like:
@lisp
(defun my-async-short-unread-p (data)
bound before exploding and taking your machine down with you. I put
that in there just to keep y'all on your toes.
-This variable is @code{nil} by default.
+The default value is 20.
@node Saving Articles
You can have Gnus suggest where to save articles by plonking a regexp into
the @code{gnus-split-methods} alist. For instance, if you would like to
save articles related to Gnus in the file @file{gnus-stuff}, and articles
-related to VM in @code{vm-stuff}, you could set this variable to something
+related to VM in @file{vm-stuff}, you could set this variable to something
like:
@lisp
@vindex gnus-uu-user-view-rules
@cindex sox
This variable is consulted first when viewing files. If you wish to use,
-for instance, @code{sox} to convert an @samp{.au} sound file, you could
+for instance, @code{sox} to convert an @file{.au} sound file, you could
say something like:
@lisp
(setq gnus-uu-user-view-rules
thread. This may not be smart, as no other decoder I have seen is able
to follow threads when collecting uuencoded articles. (Well, I have
seen one package that does that---@code{gnus-uu}, but somehow, I don't
-think that counts...) Default is @code{nil}.
+think that counts@dots{}) Default is @code{nil}.
@item gnus-uu-post-separate-description
@vindex gnus-uu-post-separate-description
@end table
-@item W W p
-@kindex W W p (Summary)
-@findex gnus-article-hide-pgp
-@vindex gnus-article-hide-pgp-hook
-Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}). The
-@code{gnus-article-hide-pgp-hook} hook will be run after a @sc{pgp}
-signature has been hidden. For example, to automatically verify
-articles that have signatures in them do:
-@lisp
-;;; Hide pgp cruft if any.
-
-(setq gnus-treat-strip-pgp t)
-
-;;; After hiding pgp, verify the message;
-;;; only happens if pgp signature is found.
-
-(add-hook 'gnus-article-hide-pgp-hook
- (lambda ()
- (save-excursion
- (set-buffer gnus-original-article-buffer)
- (mc-verify))))
-@end lisp
-
@item W W P
@kindex W W P (Summary)
@findex gnus-article-hide-pem
@item gnus-article-address-banner-alist
@vindex gnus-article-address-banner-alist
Alist of mail addresses and banners. Each element has the form
-@code{(ADDRESS . BANNER)}, where ADDRESS is a regexp matching a mail
-address in the From header, BANNER is one of a symbol @code{signature},
-an item in @code{gnus-article-banner-alist}, a regexp and @code{nil}.
-If ADDRESS matches author's mail address, it will remove things like
-advertisements. For example, if a sender has the mail address
-@samp{hail@@yoo-hoo.co.jp} and there is a banner something like
-@samp{Do You Yoo-hoo!?} in all articles he sends, you can use the
-following element to remove them:
+@code{(@var{address} . @var{banner})}, where @var{address} is a regexp
+matching a mail address in the From header, @var{banner} is one of a
+symbol @code{signature}, an item in @code{gnus-article-banner-alist},
+a regexp and @code{nil}. If @var{address} matches author's mail
+address, it will remove things like advertisements. For example, if a
+sender has the mail address @samp{hail@@yoo-hoo.co.jp} and there is a
+banner something like @samp{Do You Yoo-hoo!?} in all articles he
+sends, you can use the following element to remove them:
@lisp
("@@yoo-hoo\\.co\\.jp\\'" . "\n_+\nDo You Yoo-hoo!\\?\n.*\n.*\n")
you type this, you see the article exactly as it exists on disk or on
the server.
+@item g
+Force redisplaying of the current article
+(@code{gnus-summary-show-article}). This is also not really washing.
+If you type this, you see the article without any previously applied
+interactive Washing functions but with all default treatments
+(@pxref{Customizing Articles}).
+
@item W l
@kindex W l (Summary)
@findex gnus-summary-stop-page-breaking
@item W m
@kindex W m (Summary)
@findex gnus-summary-morse-message
-@c @icon{gnus-summary-morse-message}
Morse decode the article buffer (@code{gnus-summary-morse-message}).
@item W t
@item W Y u
@kindex W Y u (Summary)
@findex gnus-article-outlook-unwrap-lines
+@vindex gnus-outlook-deuglify-unwrap-min
+@vindex gnus-outlook-deuglify-unwrap-max
Unwrap lines that appear to be wrapped citation lines. You can control
what lines will be unwrapped by frobbing
@code{gnus-outlook-deuglify-unwrap-min} and
@code{gnus-outlook-deuglify-unwrap-max}, indicating the miminum and
maximum length of an unwrapped citation line.
-(@code{gnus-outlook-deuglify-article}).
+(@code{gnus-article-outlook-unwrap-lines}).
@item W Y a
@kindex W Y a (Summary)
@vindex gnus-article-wash-function
The default is to use the function specified by
-@code{mm-text-html-renderer} (@pxref{(emacs-mime)Display
-Customization}) to convert the @sc{html}, but this is controlled by
-the @code{gnus-article-wash-function} variable. Pre-defined functions
-you can use include:
+@code{mm-text-html-renderer} (@pxref{Display Customization, ,Display
+Customization, emacs-mime, The Emacs MIME Manual}) to convert the
+@sc{html}, but this is controlled by the
+@code{gnus-article-wash-function} variable. Pre-defined functions you
+can use include:
@table @code
@item w3
X-Sent: 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.
variable, which is an alist of regexps (use the first item to match full
group names) and default charsets to be used when reading these groups.
+@vindex gnus-newsgroup-ignored-charsets
In addition, some people do use soi-disant @sc{mime}-aware agents that
aren't. These blithely mark messages as being in @code{iso-8859-1}
even if they really are in @code{koi-8}. To help here, the
@item B r
@kindex B r (Summary)
@findex gnus-summary-respool-article
+@vindex gnus-summary-respool-default-method
Respool the mail article (@code{gnus-summary-respool-article}).
@code{gnus-summary-respool-default-method} will be used as the default
select method when respooling. This variable is @code{nil} by default,
@item B p
@kindex B p (Summary)
@findex gnus-summary-article-posted-p
-Some people have a tendency to send you "courtesy" copies when they
+Some people have a tendency to send you ``courtesy'' copies when they
follow up to articles you have posted. These usually have a
@code{Newsgroups} header in them, but not always. This command
(@code{gnus-summary-article-posted-p}) will try to fetch the current
@end menu
@table @code
+@vindex gnus-summary-display-while-building
+@item gnus-summary-display-while-building
+If non-@code{nil}, show and update the summary buffer as it's being
+built. If @code{t}, update the buffer after every line is inserted.
+If the value is an integer, @var{n}, update the display every @var{n}
+lines. The default is @code{nil}.
+
@vindex gnus-summary-mode-hook
@item gnus-summary-mode-hook
This hook is called when creating a summary mode buffer.
@findex gnus-summary-exit
@vindex gnus-summary-exit-hook
@vindex gnus-summary-prepare-exit-hook
+@vindex gnus-group-no-more-groups-hook
@c @icon{gnus-summary-exit}
Exit the current group and update all information on the group
(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
@kindex A M (summary)
@findex gnus-mailing-list-insinuate
Gnus understands some mailing list fields of RFC 2369. To enable it,
-either add a `to-list' group parameter (@pxref{Group Parameters}),
+add a @code{to-list} group parameter (@pxref{Group Parameters}),
possibly using @kbd{A M} (@code{gnus-mailing-list-insinuate}) in the
-summary buffer, or say:
-
-@lisp
-(add-hook 'gnus-summary-mode-hook 'turn-on-gnus-mailing-list-mode)
-@end lisp
+summary buffer.
That enables the following commands to the summary buffer:
@item to-address
Remove the @code{To} header if it only contains the address identical to
the current groups's @code{to-address} parameter.
+@item to-list
+Remove the @code{To} header if it only contains the address identical to
+the current groups's @code{to-list} parameter.
+@item cc-list
+Remove the @code{CC} header if it only contains the address identical to
+the current groups's @code{to-list} parameter.
@item date
Remove the @code{Date} header if the article is less than three days
old.
Prompt for a file name, then save the @sc{mime} object and strip it from
the article. Then proceed to article editing, where a reasonable
suggestion is being made on how the altered article should look
-like. The stripped @sc{mime} object will be referred via the
+like. The stripped @sc{mime} object will be referred via the
message/external-body @sc{mime} type.
(@code{gnus-mime-save-part-and-strip}).
+@findex gnus-mime-delete-part
+@item d (Article)
+@kindex d (Article)
+Delete the @sc{mime} object from the article and replace it with some
+information about the removed @sc{mime} object
+(@code{gnus-mime-delete-part}).
+
@findex gnus-mime-copy-part
@item c (Article)
@kindex c (Article)
@cindex article customization
A slew of functions for customizing how the articles are to look like
-exist. You can call these functions interactively, or you can have them
+exist. You can call these functions interactively
+(@pxref{Article Washing}), or you can have them
called automatically when you select the articles.
To have them called automatically, you should set the corresponding
@item gnus-treat-strip-leading-blank-lines (t, integer)
@item gnus-treat-strip-multiple-blank-lines (t, integer)
@item gnus-treat-strip-pem (t, last, integer)
-@item gnus-treat-strip-pgp (t, last, integer)
@item gnus-treat-strip-trailing-blank-lines (t, last, integer)
@item gnus-treat-unsplit-urls (t, integer)
@item gnus-treat-wash-html (t, integer)
@item gnus-treat-hide-citation-maybe (t, integer)
@item gnus-treat-hide-headers (head)
@item gnus-treat-hide-signature (t, last)
+@item gnus-treat-strip-banner (t, last)
+@item gnus-treat-strip-list-identifiers (head)
@xref{Article Hiding}.
@kindex SPACE (Article)
@findex gnus-article-next-page
Scroll forwards one page (@code{gnus-article-next-page}).
+This is exactly the same as @kbd{h SPACE h}.
@item DEL
@kindex DEL (Article)
@findex gnus-article-prev-page
Scroll backwards one page (@code{gnus-article-prev-page}).
+This is exactly the same as @kbd{h DEL h}.
@item C-c ^
@kindex C-c ^ (Article)
@vindex gnus-page-delimiter
This is the delimiter mentioned above. By default, it is @samp{^L}
(formfeed).
+
+@cindex IDNA
+@cindex internationalized domain names
+@vindex gnus-use-idna
+@item gnus-use-idna
+This variable controls whether Gnus performs IDNA decoding of
+internationalized domain names inside @sc{From:}, @sc{To:} and
+@sc{Cc:} headers. This requires GNU Libidn
+(@url{http://www.gnu.org/software/libidn/}, and this variable is only
+enabled if you have installed it.
+
@end table
lists will work most of the time. Posting to these groups (@kbd{a}) is
still a pain, though.
+@item gnus-user-agent
+@vindex gnus-user-agent
+@cindex User-Agent
+
+This variable controls which information should be exposed in the
+User-Agent header. It can be one of the symbols @code{gnus} (show only
+Gnus version), @code{emacs-gnus} (show only Emacs and Gnus versions),
+@code{emacs-gnus-config} (same as @code{emacs-gnus} plus system
+configuration), @code{emacs-gnus-type} (same as @code{emacs-gnus} plus
+system type) or a custom string. If you set it to a string, be sure to
+use a valid format, see RFC 2616."
+
@end table
You may want to do spell-checking on messages that you send out. Or, if
The first element in each style is called the @code{match}. If it's a
string, then Gnus will try to regexp match it against the group name.
-If it is the form @code{(header MATCH REGEXP)}, then Gnus will look in
-the original article for a header whose name is MATCH and compare that
-REGEXP. MATCH and REGEXP are strings. (There original article is the
-one you are replying or following up to. If you are not composing a
-reply or a followup, then there is nothing to match against.) If the
-@code{match} is a function symbol, that function will be called with no
-arguments. If it's a variable symbol, then the variable will be
+If it is the form @code{(header @var{match} @var{regexp})}, then Gnus
+will look in the original article for a header whose name is
+@var{match} and compare that @var{regexp}. @var{match} and
+@var{regexp} are strings. (There original article is the one you are
+replying or following up to. If you are not composing a reply or a
+followup, then there is nothing to match against.) If the
+@code{match} is a function symbol, that function will be called with
+no arguments. If it's a variable symbol, then the variable will be
referenced. If it's a list, then that list will be @code{eval}ed. In
-any case, if this returns a non-@code{nil} value, then the style is said
-to @dfn{match}.
+any case, if this returns a non-@code{nil} value, then the style is
+said to @dfn{match}.
Each style may contain an arbitrary amount of @dfn{attributes}. Each
attribute consists of a @code{(@var{name} @var{value})} pair. The
If the group doesn't exist, it will be created and you'll be subscribed
to it. The only way to make it disappear from the Group buffer is to
-unsubscribe it.
+unsubscribe it. The special properties of the draft group comes from
+a group property (@pxref{Group Parameters}), and if lost the group
+behaves like any other group. This means the commands below will not
+be available. To restore the special properties of the group, the
+simplest way is to kill the group, using @kbd{C-k}, and restart
+Gnus. The group is automatically created again with the
+correct parameters. The content of the group is not lost.
@c @findex gnus-dissociate-buffer-from-draft
@c @kindex C-c M-d (Mail)
Articles}).
@findex gnus-draft-send-all-messages
+@kindex D s (Draft)
@findex gnus-draft-send-message
+@kindex D S (Draft)
If you have lots of rejected messages you want to post (or mail) without
doing further editing, you can use the @kbd{D s} command
(@code{gnus-draft-send-message}). This command understands the
command (@code{gnus-draft-send-all-messages}) will ship off all messages
in the buffer.
+@findex gnus-draft-toggle-sending
+@kindex D t (Draft)
If you have some messages that you wish not to send, you can use the
@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message
as unsendable. This is a toggling command.
see the @code{mm-verify-option} and @code{mm-decrypt-option} options
(@pxref{Security}).
+@vindex gnus-message-replysign
+@vindex gnus-message-replyencrypt
+@vindex gnus-message-replysignencrypted
Often, you would like to sign replies to people who send you signed
messages. Even more often, you might want to encrypt messages which
are in reply to encrypted messages. Gnus offers
One sticky point when defining variables (both on back ends and in Emacs
in general) is that some variables are typically initialized from other
variables when the definition of the variables is being loaded. If you
-change the "base" variable after the variables have been loaded, you
-won't change the "derived" variables.
+change the ``base'' variable after the variables have been loaded, you
+won't change the ``derived'' variables.
This typically affects directory and file variables. For instance,
@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml}
Note that not all servers support the recommended ID. This works for
INN versions 2.3.0 and later, for instance.
+
+@item nntp-read-timeout
+@vindex nntp-read-timeout
+How long nntp should wait between checking for the end of output.
+Shorter values mean quicker response, but is more CPU intensive. The
+default is 0.1 seconds. If you have a slow line to the server (and
+don't like to see Emacs eat your available CPU power), you might set
+this to, say, 1.
+
@end table
@menu
This is the default, and simply connects to some port or other on the
remote system.
+@findex nntp-open-tls-stream
+@item nntp-open-tls-stream
+Opens a connection to a server over a @dfn{secure} channel. To use
+this you must have GNUTLS installed (see
+@uref{http://www.gnu.org/software/gnutls/}). You then define a server
+as follows:
+
+@lisp
+;; "nntps" is port 563 and is predefined in our /etc/services
+;; however, gnutls-cli -p doesn't like named ports.
+;;
+(nntp "snews.bar.com"
+ (nntp-open-connection-function nntp-open-tls-stream)
+ (nntp-port-number )
+ (nntp-address "snews.bar.com"))
+@end lisp
+
@findex nntp-open-ssl-stream
@item nntp-open-ssl-stream
-Opens a connection to a server over a @dfn{secure} channel. To use
-this you must have OpenSSL (@uref{http://www.openssl.org}) or SSLeay
-installed (@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL}, and you also
-need @file{ssl.el} (from the W3 distribution, for instance). You then
+Opens a connection to a server over a @dfn{secure} channel. To use this
+you must have OpenSSL (@uref{http://www.openssl.org}) or SSLeay
+installed (@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL}. You then
define a server as follows:
@lisp
-;; Type `C-c C-c' after you've finished editing.
-;;
;; "snews" is port 563 and is predefined in our /etc/services
-;; however, openssl s_client -port doesn't like named ports
+;; however, openssl s_client -port doesn't like named ports.
;;
(nntp "snews.bar.com"
(nntp-open-connection-function nntp-open-ssl-stream)
These functions are called indirect because they connect to an
intermediate host before actually connecting to the @sc{nntp} server.
All of these functions and related variables are also said to belong to
-the "via" family of connection: they're all prefixed with "via" to make
+the ``via'' family of connection: they're all prefixed with ``via'' to make
things cleaner. The behavior of these functions is also affected by
commonly understood variables (@pxref{Common Variables}).
@vindex nntp-via-rlogin-command-switches
List of strings to be used as the switches to
@code{nntp-via-rlogin-command}. The default is @code{nil}. If you use
-@samp{ssh} for `nntp-via-rlogin-command', you may set this to
+@samp{ssh} for @code{nntp-via-rlogin-command}, you may set this to
@samp{("-C")} in order to compress all data connections, otherwise set
this to @samp{("-t")} or @samp{("-C" "-t")} if the telnet command
requires a pseudo-tty allocation on an intermediate host.
@item nntp-pre-command
@vindex nntp-pre-command
-A command wrapper to use when connecting through a non native connection
-function (all except @code{nntp-open-network-stream} and
-@code{nntp-open-ssl-stream}. This is where you would put a @samp{SOCKS}
-wrapper for instance.
+A command wrapper to use when connecting through a non native
+connection function (all except @code{nntp-open-network-stream},
+@code{nntp-open-tls-stream}, and @code{nntp-open-ssl-stream}. This is
+where you would put a @samp{SOCKS} wrapper for instance.
@item nntp-address
@vindex nntp-address
@item nntp-port-number
@vindex nntp-port-number
-Port number to connect to the @sc{nntp} server. The default is @samp{nntp}.
-If you use @sc{nntp} over @sc{ssl}, you may want to use integer ports rather
-than named ports (i.e, use @samp{563} instead of @samp{snews}), because
-external SSL tools may not work with named ports.
+Port number to connect to the @sc{nntp} server. The default is
+@samp{nntp}. If you use @sc{nntp} over @sc{tls}/@sc{ssl}, you may
+want to use integer ports rather than named ports (i.e, use @samp{563}
+instead of @samp{snews} or @samp{nntps}), because external TLS/SSL
+tools may not work with named ports.
@item nntp-end-of-line
@vindex nntp-end-of-line
mail back end of your choice into @code{gnus-secondary-select-methods},
and things will happen automatically.
-For instance, if you want to use @code{nnml} (which is a "one file per
-mail" back end), you could put the following in your @file{.gnus.el} file:
+For instance, if you want to use @code{nnml} (which is a ``one file per
+mail'' back end), you could put the following in your @file{.gnus.el} file:
@lisp
(setq gnus-secondary-select-methods '((nnml "")))
Now, the next time you start Gnus, this back end will be queried for new
articles, and it will move all the messages in your spool file to its
-directory, which is @code{~/Mail/} by default. The new group that will
+directory, which is @file{~/Mail/} by default. The new group that will
be created (@samp{mail.misc}) will be subscribed, and you can read it
like any other group.
mail belongs in that group.
The last of these groups should always be a general one, and the regular
-expression should @emph{always} be @samp{} so that it matches any mails
+expression should @emph{always} be @samp{*} so that it matches any mails
that haven't been matched by any of the other regexps. (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".)
+rule to make a match will ``win'', unless you have crossposting enabled.
+In that case, all matching rules will ``win''.)
If you like to tinker with this yourself, you can set this variable to a
function of your choice. This function will be called without any
The mail back ends all support cross-posting. If several regexps match,
the mail will be ``cross-posted'' to all those groups.
@code{nnmail-crosspost} says whether to use this mechanism or not. Note
-that no articles are crossposted to the general (@samp{}) group.
+that no articles are crossposted to the general (@samp{*}) group.
@vindex nnmail-crosspost-link-function
@cindex crosspost
@vindex nnmail-mail-splitting-charset
@vindex nnmail-mail-splitting-decodes
-By default the splitting codes MIME decodes headers so you can match
+By default the splitting codes @sc{mime} decodes headers so you can match
on non-ASCII strings. The @code{nnmail-mail-splitting-charset}
variable specifies the default charset for decoding. The behaviour
can be turned off completely by binding
The file name. Defaults to the value of the @code{MAIL}
environment variable or the value of @code{rmail-spool-directory}
(usually something like @file{/usr/mail/spool/user-name}).
+
+@item :prescript
+@itemx :postscript
+Script run before/after fetching mail.
@end table
An example file mail source:
@item :path
The name of the directory where the mails are stored. The default is
taken from the @code{MAILDIR} environment variable or
-@samp{~/Maildir/}.
+@file{~/Maildir/}.
@item :subdirs
The subdirectories of the Maildir. The default is
@samp{("new" "cur")}.
and fetches articles from a given @sc{imap} mailbox. @xref{IMAP}, for
more information.
-Note that for the Kerberos, GSSAPI, SSL/TLS and STARTTLS support you
+Note that for the Kerberos, GSSAPI, TLS/SSL and STARTTLS support you
may need external programs and libraries, @xref{IMAP}.
Keywords:
@item :port
The port number of the @sc{imap} server. The default is @samp{143}, or
-@samp{993} for SSL/TLS connections.
+@samp{993} for TLS/SSL connections.
@item :user
The user name to give to the @sc{imap} server. The default is the login
@item :stream
What stream to use for connecting to the server, this is one of the
symbols in @code{imap-stream-alist}. Right now, this means
-@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{ssl},
-@samp{shell} or the default @samp{network}.
+@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{tls},
+@samp{ssl}, @samp{shell} or the default @samp{network}.
@item :authentication
Which authenticator to use for authenticating to the server, this is
@item :program
When using the `shell' :stream, the contents of this variable is
-mapped into the `imap-shell-program' variable. This should be a
+mapped into the @code{imap-shell-program} variable. This should be a
@code{format}-like string (or list of strings). Here's an example:
@example
The name of the server.
@item l
-User name from `imap-default-user'.
+User name from @code{imap-default-user}.
@item p
The port number of the server.
@item mail-source-delete-incoming
@vindex mail-source-delete-incoming
-If non-@code{nil}, delete incoming files after handling them.
+If non-@code{nil}, delete incoming files after handling them. If
+@code{t}, delete the files immediately, if @code{nil}, never delete any
+files. If a positive number, delete files older than number of days
+(This will only happen, when reveiving 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.
+
+@item mail-source-delete-old-incoming-confirm
+@vindex mail-source-delete-old-incoming-confirm
+If @code{non-nil}, ask for for confirmation before deleting old incoming
+files. This variable only applies when
+@code{mail-source-delete-incoming} is a positive number.
+
+@item mail-source-ignore-errors
+@vindex mail-source-ignore-errors
+If non-@code{nil}, ignore errors when reading mail from a mail source.
@item mail-source-directory
@vindex mail-source-directory
@vindex nnmail-split-hook
@item nnmail-split-hook
-@findex article-decode-encoded-words
+@findex gnus-article-decode-encoded-words
@findex RFC 1522 decoding
@findex RFC 2047 decoding
Hook run in the buffer where the mail headers of each message is kept
when the @code{:} function is run.
@item
-@code{(! @var{func} @var{split})}: If the split is a list, and the first
-element is @code{!}, then SPLIT will be processed, and FUNC will be
-called as a function with the result of SPLIT as argument. FUNC should
-return a split.
+@code{(! @var{func} @var{split})}: If the split is a list, and the
+first element is @code{!}, then @var{split} will be processed, and
+@var{func} will be called as a function with the result of @var{split}
+as argument. @var{func} should return a split.
@item
@code{nil}: If the split is @code{nil}, it is ignored.
There are six different mail back ends in the standard Gnus, and more
back ends are available separately. The mail back end most people use
(because it is possibly the fastest) is @code{nnml} (@pxref{Mail
-Spool}). You might notice that only five back ends are listed below;
-@code{nnmaildir}'s documentation has not yet been completely
-incorporated into this manual. Until it is, you can find it at
-@uref{http://multivac.cwru.edu./nnmaildir/}.
+Spool}).
@menu
* Unix Mail Box:: Using the (quite) standard Un*x mbox.
* Rmail Babyl:: Emacs programs use the rmail babyl format.
* Mail Spool:: Store your mail in a private spool?
* MH Spool:: An mhspool-like back end.
+* Maildir:: Another one-file-per-message format.
* Mail Folders:: Having one file for each group.
* Comparing Mail Back Ends:: An in-depth looks at pros and cons.
@end menu
@table @code
@item nnml-directory
@vindex nnml-directory
-All @code{nnml} directories will be placed under this directory.
-The default is the value of `message-directory' (whose default value is
-@file{~/Mail}).
+All @code{nnml} directories will be placed under this directory. The
+default is the value of @code{message-directory} (whose default value
+is @file{~/Mail}).
@item nnml-active-file
@vindex nnml-active-file
The active file for the @code{nnml} server. The default is
-@file{~/Mail/active"}.
+@file{~/Mail/active}.
@item nnml-newsgroups-file
@vindex nnml-newsgroups-file
The @code{nnml} group descriptions file. @xref{Newsgroups File
-Format}. The default is @file{~/Mail/newsgroups"}.
+Format}. The default is @file{~/Mail/newsgroups}.
@item nnml-get-new-mail
@vindex nnml-get-new-mail
@end table
+@node Maildir
+@subsubsection Maildir
+@cindex nnmaildir
+@cindex maildir
+
+@code{nnmaildir} stores mail in the maildir format, with each maildir
+corresponding to a group in Gnus. This format is documented here:
+@uref{http://cr.yp.to/proto/maildir.html} and here:
+@uref{http://www.qmail.org/man/man5/maildir.html}. nnmaildir also
+stores extra information in the @file{.nnmaildir/} directory within a
+maildir.
+
+Maildir format was designed to allow concurrent deliveries and
+reading, without needing locks. With other backends, you would have
+your mail delivered to a spool of some kind, and then you would
+configure Gnus to split mail from that spool into your groups. You
+can still do that with nnmaildir, but the more common configuration is
+to have your mail delivered directly to the maildirs that appear as
+group in Gnus.
+
+nnmaildir is designed to be perfectly reliable: @kbd{C-g} will never
+corrupt its data in memory, and @code{SIGKILL} will never corrupt its
+data in the filesystem.
+
+nnmaildir stores article marks and NOV data in each maildir. So you
+can copy a whole maildir from one Gnus setup to another, and you will
+keep your marks.
+
+Virtual server settings:
+
+@table @code
+@item directory
+For each of your nnmaildir servers (it's very unlikely that you'd need
+more than one), you need to create a directory and populate it with
+maildirs or symlinks to maildirs (and nothing else; do not choose a
+directory already used for other purposes). Each maildir will be
+represented in Gnus as a newsgroup on that server; the filename of the
+symlink will be the name of the group. Any filenames in the directory
+starting with `.' are ignored. The directory is scanned when you
+first start Gnus, and each time you type @kbd{g} in the group buffer;
+if any maildirs have been removed or added, nnmaildir notices at these
+times.
+
+The value of the @code{directory} parameter should be a Lisp form
+which is processed by @code{eval} and @code{expand-file-name} to get
+the path of the directory for this server. The form is @code{eval}ed
+only when the server is opened; the resulting string is used until the
+server is closed. (If you don't know about forms and @code{eval},
+don't worry - a simple string will work.) This parameter is not
+optional; you must specify it. I don't recommend using
+@code{"~/Mail"} or a subdirectory of it; several other parts of Gnus
+use that directory by default for various things, and may get confused
+if nnmaildir uses it too. @code{"~/.nnmaildir"} is a typical value.
+
+@item target-prefix
+This should be a Lisp form which is processed by @code{eval} and
+@code{expand-file-name}. The form is @code{eval}ed only when the
+server is opened; the resulting string is used until the server is
+closed.
+
+When you create a group on an nnmaildir server, the maildir is created
+with @code{target-prefix} prepended to its name, and a symlink
+pointing to that maildir is created, named with the plain group name.
+So if @code{directory} is @code{"~/.nnmaildir"} and
+@code{target-prefix} is @code{"../maildirs/"}, then when you create
+the group @code{foo}, nnmaildir will create
+@file{~/.nnmaildir/../maildirs/foo} as a maildir, and will create
+@file{~/.nnmaildir/foo} as a symlink pointing to
+@file{../maildirs/foo}.
+
+You can set @code{target-prefix} to a string without any slashes to
+create both maildirs and symlinks in the same @code{directory}; in
+this case, any maildirs found in @code{directory} whose names start
+with @code{target-prefix} will not be listed as groups (but the
+symlinks pointing to them will be).
+
+As a special case, if @code{target-prefix} is @code{""} (the default),
+then when you create a group, the maildir will be created in
+@code{directory} without a corresponding symlink. Beware that you
+cannot use @code{gnus-group-delete-group} on such groups without the
+@code{force} argument.
+
+@item directory-files
+This should be a function with the same interface as
+@code{directory-files} (such as @code{directory-files} itself). It is
+used to scan the server's @code{directory} for maildirs. This
+parameter is optional; the default is
+@code{nnheader-directory-files-safe} if
+@code{nnheader-directory-files-is-safe} is @code{nil}, and
+@code{directory-files} otherwise.
+(@code{nnheader-directory-files-is-safe} is checked only once when the
+server is opened; if you want to check it each time the directory is
+scanned, you'll have to provide your own function that does that.)
+
+@item get-new-mail
+If non-@code{nil}, then after scanning for new mail in the group
+maildirs themselves as usual, this server will also incorporate mail
+the conventional Gnus way, from @code{mail-sources} according to
+@code{nnmail-split-methods} or @code{nnmail-split-fancy}. The default
+value is @code{nil}.
+
+Do @emph{not} use the same maildir both in @code{mail-sources} and as
+an nnmaildir group. The results might happen to be useful, but that
+would be by chance, not by design, and the results might be different
+in the future. If your split rules create new groups, remember to
+supply a @code{create-directory} server parameter.
+@end table
+
+@subsubsection Group parameters
+
+nnmaildir uses several group parameters. It's safe to ignore all
+this; the default behavior for nnmaildir is the same as the default
+behavior for other mail backends: articles are deleted after one week,
+etc. Except for the expiry parameters, all this functionality is
+unique to nnmaildir, so you can ignore it if you're just trying to
+duplicate the behavior you already have with another backend.
+
+If the value of any of these parameters is a vector, the first element
+is evaluated as a Lisp form and the result is used, rather than the
+original value. If the value is not a vector, the value itself is
+evaluated as a Lisp form. (This is why these parameters use names
+different from those of other, similar parameters supported by other
+backends: they have different, though similar, meanings.) (For
+numbers, strings, @code{nil}, and @code{t}, you can ignore the
+@code{eval} business again; for other values, remember to use an extra
+quote and wrap the value in a vector when appropriate.)
+
+@table @code
+@item expire-age
+An integer specifying the minimum age, in seconds, of an article before
+it will be expired, or the symbol @code{never} to specify that
+articles should never be expired. If this parameter is not set,
+nnmaildir falls back to the usual
+@code{nnmail-expiry-wait}(@code{-function}) variables (overridable by
+the @code{expiry-wait}(@code{-function}) group parameters. If you
+wanted a value of 3 days, you could use something like @code{[(* 3 24
+60 60)]}; nnmaildir will evaluate the form and use the result. An
+article's age is measured starting from the article file's
+modification time. Normally, this is the same as the article's
+delivery time, but editing an article makes it younger. Moving an
+article (other than via expiry) may also make an article younger.
+
+@item expire-group
+If this is set to a string (a full Gnus group name, like
+@code{"backend+server.address.string:group.name"}), and if it is not
+the name of the same group that the parameter belongs to, then
+articles will be moved to the specified group during expiry before
+being deleted. @emph{If this is set to an nnmaildir group, the
+article will be just as old in the destination group as it was in the
+source group.} So be careful with @code{expire-age} in the destination
+group. If this is set to the name of the same group that the
+parameter belongs to, then the article is not expired at all. If you
+use the vector form, the first element is evaluated once for each
+article. So that form can refer to
+@code{nnmaildir-article-file-name}, etc., to decide where to put the
+article.
+
+@item read-only
+If this is set to @code{t}, nnmaildir will treat the articles in this
+maildir as read-only. This means: articles are not renamed from
+@file{new/} into @file{cur/}; articles are only found in @file{new/},
+not @file{cur/}; articles are never deleted; articles cannot be
+edited. @file{new/} is expected to be a symlink to the @file{new/}
+directory of another maildir - e.g., a system-wide mailbox containing
+a mailing list of common interest. Everything in the maildir outside
+@file{new/} is @emph{not} treated as read-only, so for a shared
+mailbox, you do still need to set up your own maildir (or have write
+permission to the shared mailbox); your maildir just won't contain
+extra copies of the articles.
+
+@item directory-files
+A function with the same interface as @code{directory-files}. It is
+used to scan the directories in the maildir corresponding to this
+group to find articles. The default is the function specified by the
+server's @code{directory-files} parameter.
+
+@item distrust-Lines:
+If non-@code{nil}, nnmaildir will always count the lines of an
+article, rather than use the @code{Lines:} header field. If
+@code{nil}, the header field will be used if present.
+
+@item always-marks
+A list of mark symbols, such as
+@code{['(read expire)]}. Whenever Gnus asks nnmaildir for
+article marks, nnmaildir will say that all articles have these
+marks, regardless of whether the marks stored in the filesystem
+say so. This is a proof-of-concept feature that will probably be
+removed eventually; it ought to be done in Gnus proper, or
+abandoned if it's not worthwhile.
+
+@item never-marks
+A list of mark symbols, such as @code{['(tick expire)]}. Whenever
+Gnus asks nnmaildir for article marks, nnmaildir will say that no
+articles have these marks, regardless of whether the marks stored in
+the filesystem say so. @code{never-marks} overrides
+@code{always-marks}. This is a proof-of-concept feature that will
+probably be removed eventually; it ought to be done in Gnus proper, or
+abandoned if it's not worthwhile.
+
+@item nov-cache-size
+An integer specifying the size of the NOV memory cache. To speed
+things up, nnmaildir keeps NOV data in memory for a limited number of
+articles in each group. (This is probably not worthwhile, and will
+probably be removed in the future.) This parameter's value is noticed
+only the first time a group is seen after the server is opened - i.e.,
+when you first start Gnus, typically. The NOV cache is never resized
+until the server is closed and reopened. The default is an estimate
+of the number of articles that would be displayed in the summary
+buffer: a count of articles that are either marked with @code{tick} or
+not marked with @code{read}, plus a little extra.
+@end table
+
+@subsubsection Article identification
+Articles are stored in the @file{cur/} subdirectory of each maildir.
+Each article file is named like @code{uniq:info}, where @code{uniq}
+contains no colons. nnmaildir ignores, but preserves, the
+@code{:info} part. (Other maildir readers typically use this part of
+the filename to store marks.) The @code{uniq} part uniquely
+identifies the article, and is used in various places in the
+@file{.nnmaildir/} subdirectory of the maildir to store information
+about the corresponding article. The full pathname of an article is
+available in the variable @code{nnmaildir-article-file-name} after you
+request the article in the summary buffer.
+
+@subsubsection NOV data
+An article identified by @code{uniq} has its NOV data (used to
+generate lines in the summary buffer) stored in
+@code{.nnmaildir/nov/uniq}. There is no
+@code{nnmaildir-generate-nov-databases} function. (There isn't much
+need for it - an article's NOV data is updated automatically when the
+article or @code{nnmail-extra-headers} has changed.) You can force
+nnmaildir to regenerate the NOV data for a single article simply by
+deleting the corresponding NOV file, but @emph{beware}: this will also
+cause nnmaildir to assign a new article number for this article, which
+may cause trouble with @code{seen} marks, the Agent, and the cache.
+
+@subsubsection Article marks
+An article identified by @code{uniq} is considered to have the mark
+@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists.
+When Gnus asks nnmaildir for a group's marks, nnmaildir looks for such
+files and reports the set of marks it finds. When Gnus asks nnmaildir
+to store a new set of marks, nnmaildir creates and deletes the
+corresponding files as needed. (Actually, rather than create a new
+file for each mark, it just creates hard links to
+@file{.nnmaildir/markfile}, to save inodes.)
+
+You can invent new marks by creating a new directory in
+@file{.nnmaildir/marks/}. You can tar up a maildir and remove it from
+your server, untar it later, and keep your marks. You can add and
+remove marks yourself by creating and deleting mark files. If you do
+this while Gnus is running and your nnmaildir server is open, it's
+best to exit all summary buffers for nnmaildir groups and type @kbd{s}
+in the group buffer first, and to type @kbd{g} or @kbd{M-g} in the
+group buffer afterwards. Otherwise, Gnus might not pick up the
+changes, and might undo them.
+
+
@node Mail Folders
@subsubsection Mail Folders
@cindex nnfolder
@item nnfolder-newsgroups-file
@vindex nnfolder-newsgroups-file
The name of the group descriptions file. @xref{Newsgroups File
-Format}. The default is @file{~/Mail/newsgroups"}
+Format}. The default is @file{~/Mail/newsgroups}
@item nnfolder-get-new-mail
@vindex nnfolder-get-new-mail
Basically the effect of @code{nnfolder} is @code{nnmbox} (the first
method described above) on a per-group basis. That is, @code{nnmbox}
-itself puts *all* one's mail in one file; @code{nnfolder} provides a
+itself puts @emph{all} one's mail in one file; @code{nnfolder} provides a
little bit of optimization to this so that each of one's mail groups has
a Unix mail box file. It's faster than @code{nnmbox} because each group
can be parsed separately, and still provides the simple Unix mail box
thus damaging message bodies), and another set to be used as groups (in
whatever format you like). A maildir has a built-in spool, in the
@code{new/} subdirectory. Beware that currently, mail moved from
-@code{new/} to @code{cur/} instead of via mail splitting will undergo
-treatment such as duplicate checking.
-
-An article will not necessarily keep the same number across Gnus
-sessions; articles are renumbered starting from 1 for each Gnus session
-(more precisely, each time you open the @code{nnmaildir} server). This
-way, you don't get gaps in your article number ranges, and when entering
-large groups, Gnus is likely to give a more accurate article count. The
-price is that @code{nnmaildir} doesn't work with the cache or agent.
-This will probably be changed in the future.
+@code{new/} to @code{cur/} instead of via mail splitting will not
+undergo treatment such as duplicate checking.
@code{nnmaildir} stores article marks for a given group in the
corresponding maildir, in a way designed so that it's easy to manipulate
and that @code{nnmh} repeatedly parses out of message files.) If this
is a problem for you, you can set the @code{nov-cache-size} group
parameter to something small (0 would probably not work, but 1 probably
-would) to make it use less memory.
+would) to make it use less memory. This caching will probably be
+removed in the future.
-Startup and shutdown are likely to be slower with @code{nnmaildir} than
-with other back ends. Everything in between is likely to be faster,
-depending in part on your file system.
+Startup is likely to be slower with @code{nnmaildir} than with other
+back ends. Everything in between is likely to be faster, depending in
+part on your file system.
@code{nnmaildir} does not use @code{nnoo}, so you cannot use @code{nnoo}
to write an @code{nnmaildir}-derived back end.
@item nnslashdot-directory
@vindex nnslashdot-directory
Where @code{nnslashdot} will store its files. The default is
-@samp{~/News/slashdot/}.
+@file{~/News/slashdot/}.
@item nnslashdot-active-url
@vindex nnslashdot-active-url
@item nnultimate-directory
@vindex nnultimate-directory
The directory where @code{nnultimate} stores its files. The default is
-@samp{~/News/ultimate/}.
+@file{~/News/ultimate/}.
@end table
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 an_egroup RET egroups RET
@item nnwarchive-directory
@vindex nnwarchive-directory
The directory where @code{nnwarchive} stores its files. The default is
-@samp{~/News/warchive/}.
+@file{~/News/warchive/}.
@item nnwarchive-login
@vindex nnwarchive-login
@item nnrss-directory
@vindex nnrss-directory
The directory where @code{nnrss} stores its files. The default is
-@samp{~/News/rss/}.
+@file{~/News/rss/}.
@end table
@cindex nnimap
@cindex @sc{imap}
-@sc{imap} is a network protocol for reading mail (or news, or ...),
+@sc{imap} is a network protocol for reading mail (or news, or @dots{}),
think of it as a modernized @sc{nntp}. Connecting to a @sc{imap}
server is much similar to connecting to a news server, you just
specify the network address of the server.
manipulate mails stored on the @sc{imap} server. This is the kind of
usage explained in this section.
-A server configuration in @code{~/.gnus} with a few @sc{imap} servers
-might look something like the following. (Note that for SSL/TLS, you
+A server configuration in @file{~/.gnus} with a few @sc{imap} servers
+might look something like the following. (Note that for TLS/SSL, you
need external programs and libraries, see below.)
@lisp
(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:
@item nnimap-server-port
@vindex nnimap-server-port
-Port on server to contact. Defaults to port 143, or 993 for SSL.
+Port on server to contact. Defaults to port 143, or 993 for TLS/SSL.
Note that this should be an integer, example server specification:
@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 SSL/TLS. (@sc{imap} over SSL/TLS is being replaced by STARTTLS, which
+of TLS/SSL. (@sc{imap} over TLS/SSL is being replaced by STARTTLS, which
can be automatically detected, but it's not widely deployed yet.)
Example server specification:
@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program.
@item
@dfn{starttls:} Connect via the STARTTLS extension (similar to
-SSL). Requires the external library @samp{starttls.el} and program
+TLS/SSL). Requires the external library @samp{starttls.el} and program
@samp{starttls}.
@item
+@dfn{tls:} Connect through TLS. Requires GNUTLS (the program
+@samp{gnutls-cli}).
+@item
@dfn{ssl:} Connect through SSL. Requires OpenSSL (the program
-@samp{openssl}) or SSLeay (@samp{s_client}) as well as the external
-library @samp{ssl.el}.
+@samp{openssl}) or SSLeay (@samp{s_client}).
@item
@dfn{shell:} Use a shell command to start @sc{imap} connection.
@item
@code{imap-kerberos4-program} contain parameters to pass to the imtest
program.
+For TLS connection, the @code{gnutls-cli} program from GNUTLS is
+needed. It is available from
+@uref{http://www.gnu.org/software/gnutls/}.
+
@vindex imap-ssl-program
For SSL connections, the OpenSSL program is available from
@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay,
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. You also need @samp{ssl.el} (from the W3
-distribution, for instance).
+to OpenSSL/SSLeay.
@vindex imap-shell-program
@vindex imap-shell-host
@table @code
@item always
-The default behavior, delete all articles marked as "Deleted" when
+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
* 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.
+* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
* A note on namespaces:: How to (not) use IMAP namespace in Gnus.
@end menu
them every time you fetch new mail.)
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".
+end. The first rule to make a match will ``win'', unless you have
+crossposting enabled. In that case, all matching rules will ``win''.
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
@subsection Expiring in IMAP
@cindex expiring imap mail
-Even though @sc{nnimap} is not a proper @sc{nnmail} derived back end,
-it supports most features in regular expiring (@pxref{Expiring Mail}).
-Unlike splitting in IMAP (@pxref{Splitting in IMAP}) it do not clone
-the @sc{nnmail} variables (i.e., creating @var{nnimap-expiry-wait})
-but reuse the @sc{nnmail} variables. What follows below are the
-variables used by the @sc{nnimap} expiry process.
+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 IMAP (@pxref{Splitting in IMAP}) it do
+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.
A note on how the expire mark is stored on the @sc{imap} server is
appropriate here as well. The expire mark is translated into a
-@sc{imap} client specific mark, @code{gnus-expire}, and stored on the
+@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
@item nnmail-expiry-wait-function
These variables are fully supported. The expire value can be a
-number, the symbol @var{immediate} or @var{never}.
+number, the symbol @code{immediate} or @code{never}.
@item nnmail-expiry-target
This variable is supported, and internally implemented by calling the
-@sc{nnmail} functions that handle this. It contains an optimization
+@code{nnmail} functions that handle this. It contains an optimization
that if the destination is a IMAP group on the same server, the
article is copied instead of appended (that is, uploaded again).
@itemize @bullet
@item
-Giving "anyone" the "lrs" rights (lookup, read, keep seen/unseen flags)
+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,
+``anyone'' posting ("p") capabilities to have ``plussing'' work (that is,
mail sent to user+mailbox@@domain ending up in the @sc{imap} mailbox
INBOX.mailbox).
@end itemize
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
+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.
run through @code{nndoc-unquote-dashes} before being delivered.
To hook your own document definition into @code{nndoc}, use the
-@code{nndoc-add-type} function. It takes two parameters---the first is
-the definition itself and the second (optional) parameter says where in
-the document type definition alist to put this definition. The alist is
-traversed sequentially, and @code{nndoc-TYPE-type-p} is called for a given type @code{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{nndoc-add-type} function. It takes two parameters---the first
+is the definition itself and the second (optional) parameter says
+where in the document type definition alist to put this definition.
+The alist is traversed sequentially, and @code{nndoc-TYPE-type-p} is
+called for a given type @code{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.
@node SOUP
@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/"}.
+reply packet. The default is @file{~/SOUP/replies/}.
@item nnsoup-replies-format-type
@vindex nnsoup-replies-format-type
* Agent Commands:: New commands for all the buffers.
* 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 IMAP:: How to use the Agent with IMAP.
* Outgoing Messages:: What happens when you post/mail something?
* Agent Variables:: Customizing is fun.
@itemize @bullet
@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.
@code{gnus-secondary-select-methods} are agentized.
@item
-Decide on download policy. @xref{Agent Categories}.
+
+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 grou parameters (@pxref{Group Parameters}) to
+configure them.
@item
-Uhm... that's it.
+Uhm@dots{} that's it.
@end itemize
mark the articles for downloading manually if it should turn out that
you're interested in the articles anyway.
-The main way to control 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.
+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.
+
+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.
+
+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.
@menu
* Category Syntax:: What a category looks like.
@node Category Syntax
@subsubsection Category Syntax
-A category consists of two things.
+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.
-@enumerate
-@item
+@table @code
+@item gnus-agent-cat-name
+The name of the category.
+
+@item gnus-agent-cat-groups
+The list of groups that are in this category.
+
+@item gnus-agent-cat-predicate
A predicate which (generally) gives a rough outline of which articles
are eligible for downloading; and
-@item
+@item gnus-agent-cat-score-file
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 enumerate
+
+@item gnus-agent-cat-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.
+
+@item gnus-agent-cat-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.
+
+@item gnus-agent-cat-low-score
+an integer that overrides the value of @code{gnus-agent-low-score}.
+
+@item gnus-agent-cat-high-score
+an integer that overrides the value of @code{gnus-agent-high-score}.
+
+@item gnus-agent-cat-length-when-short
+an integer that overrides the value of
+@code{gnus-agent-short-article}.
+
+@item gnus-agent-cat-length-when-long
+an integer that overrides the value of @code{gnus-agent-long-article}.
+@end table
+
+The name of a category can not be changed once the category has been
+created.
+
+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.
A predicate in its simplest form can be a single predicate such as
@code{true} or @code{false}. These two will download every available
The following predicates are pre-defined, but if none of these fit what
you want to do, you can write your own.
+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 iff the article is shorter than @code{gnus-agent-short-article}
always a reliable indication of when it was posted. Hell, some people
just don't give a damn.
-The above predicates apply to *all* the groups which belong to the
+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 it's group
(agent-predicate . short)
@end lisp
-This is the group parameter equivalent of the agent category default.
+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.
@end lisp
@item
-Group Parameter specification
+Group/Topic Parameter specification
@lisp
(agent-score ("from"
@item
Agent score file
-These score files must *only* contain the permitted scoring keywords
-stated above.
+These score files must @emph{only} contain the permitted scoring
+keywords stated above.
example:
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, *filtering out* those sections that do not
+files for a group, @emph{filtering out} those sections that do not
relate to one of the permitted subset of scoring keywords.
@itemize @bullet
@findex gnus-category-exit
Return to the group buffer (@code{gnus-category-exit}).
+@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}).
+
@item k
@kindex k (Category)
@findex gnus-category-kill
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.
+
@end table
@node Agent Commands
@subsection Agent Commands
+@findex gnus-agent-toggle-plugged
+@kindex J j (Agent)
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
@menu
-* Group Agent Commands::
-* Summary Agent Commands::
-* Server Agent Commands::
+* 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
Remove the downloading mark from the article
(@code{gnus-agent-unmark-article}).
+@cindex %
@item @@
@kindex @@ (Agent Summary)
@findex gnus-agent-toggle-mark
-Toggle whether to download the article (@code{gnus-agent-toggle-mark}).
+Toggle whether to download the article
+(@code{gnus-agent-toggle-mark}). The dowload mark is @samp{%} by
+default.
@item J c
@kindex J c (Agent Summary)
@findex gnus-agent-catchup
-Mark all undownloaded articles as read (@code{gnus-agent-catchup}).
+Mark all articles as read (@code{gnus-agent-catchup}) that are neither cached, downloaded, nor downloadable.
+
+@item J S
+@kindex J S (Agent Summary)
+@findex gnus-agent-fetch-group
+Download all eligible (See @pxref{Agent Categories}) articles in this group.
+(@code{gnus-agent-fetch-group}).
+
+@item J s
+@kindex J s (Agent Summary)
+@findex gnus-agent-fetch-series
+Download all processable articles in this group.
+(@code{gnus-agent-fetch-series}).
@item J u
@kindex J u (Agent Summary)
article into the Agent, Gnus will not download the article from the
server again but use the locally stored copy instead.
-This behaviour can be controlled by @code{gnus-agent-cache}
-(@pxref{Agent Variables}).
+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 backend.
@node Agent Expiry
@subsection Agent Expiry
@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
-@code{nnagent} doesn't handle expiry. Instead, there's a special
-@code{gnus-agent-expire} command that will expire all read articles that
-are older than @code{gnus-agent-expire-days} days. It can be run
-whenever you feel that you're running out of space. It's not
-particularly fast or efficient, and it's not a particularly good idea to
-interrupt it (with @kbd{C-g} or anything else) once you've started it.
-
-@code{gnus-agent-expire-days} can also be a list of regexp/day pairs.
-The regexps will be matched against group names to allow differing
-expiry in different groups.
+The Agent backend, @code{nnagent}, doesn't handle expiry. Well, at
+least it doesn't handle it like other backends. 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.
-@lisp
-(setq gnus-agent-expire-days
- '(("alt\\." 7)
- (".*binary" 1)
- ("." 21)))
-@end lisp
+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.
-If you use the list form, the last element must always be the default
-method---it must always match all groups.
+The agent parameter @code{agent-enable-expiration} may be used to
+prevent expiration in selected groups.
@vindex gnus-agent-expire-all
-If @code{gnus-agent-expire-all} is non-@code{nil}, this command 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.
+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.
-@findex gnus-agent-regenerate
If you find that some articles eligible for expiry are never expired,
-perhaps some Gnus Agent files are corrupted. There's a special
-@code{gnus-agent-regenerate} command to fix possible problems.
+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.
+
+@node Agent Regeneration
+@subsection Agent Regeneration
+
+@cindex Agent Regeneration
+@cindex Gnus Agent Regeneration
+@cindex regeneration
+
+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.
+
+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.
+
+@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.
+
+@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 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 IMAP
@subsection Agent and IMAP
-The Agent work with any Gnus back end, including nnimap. However,
+The Agent works with any Gnus back end, including nnimap. However,
since there are some conceptual differences between @sc{nntp} and
@sc{imap}, this section (should) provide you with some information to
make Gnus Agent work smoother as a @sc{imap} Disconnected Mode client.
The first thing to keep in mind is that all flags (read, ticked, etc)
-are kept on the @sc{imap} server, rather than in @code{.newsrc} as is the
+are kept on the @sc{imap} server, rather than in @file{.newsrc} as is the
case for nntp. Thus Gnus need to remember flag changes when
disconnected, and synchronize these flags when you plug back in.
@end itemize
-Technical note: the synchronization algorithm does not work by "pushing"
+Technical note: the synchronization algorithm does not work by ``pushing''
all local flags to the server, but rather incrementally update the
server view of flags by changing only those flags that were changed by
the user. Thus, if you set one flag on a article, quit the group and
re-select the group and remove the flag; the flag will be set and
-removed from the server when you "synchronize". The queued flag
+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 gnus-agent-fetched-hook
@vindex gnus-agent-fetched-hook
-Hook run when after finishing fetching articles.
+Hook run when finished fetching articles.
@item gnus-agent-cache
@vindex gnus-agent-cache
other value, all offline servers will be automatically switched into
online status.
+@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 t.
+
+@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 fetch all missing headers. When @code{nil}, the agent will
+fetch only new headers. The default is @code{nil}.
+
+@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.
+
@item gnus-server-unopen-status
@vindex gnus-server-unopen-status
Perhaps not a Agent variable, but closely related to the Agent, this
for this variable include @code{denied} and @code{offline} the latter
is only valid if the Agent is used.
+@item gnus-auto-goto-ignores
+@vindex gnus-auto-goto-ignores
+Another variable that isn't a 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.
+
+The legal 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).
+
@end table
@node Batching Agents
@subsection Batching Agents
+@findex gnus-agent-batch
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
@code{gnus-agent-fetch-selected-article} to
@code{gnus-select-article-hook}.
-@item If I read an article while plugged, and the article already exists in the Agent, will it get downloaded once more?
+@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 `nil'.
+@strong{No}, unless @code{gnus-agent-cache} is @code{nil}.
@end table
In short, when Gnus is unplugged, it only looks into the locally stored
-articles; when it's plugged, it only talks to your ISP and also uses the
+articles; when it's plugged, it talks to your ISP and may also use the
locally stored articles.
Score on the @code{Message-ID} header.
@item e
-Score on an "extra" header, that is, one of those in gnus-extra-headers,
+Score on an ``extra'' header, that is, one of those in gnus-extra-headers,
if your @sc{nntp} server tracks additional header data in overviews.
@item f
@item gnus-score-file-suffix
@vindex gnus-score-file-suffix
Suffix to add to the group name to arrive at the score file name
-(@samp{SCORE} by default.)
+(@file{SCORE} by default.)
@item gnus-score-uncacheable-files
@vindex gnus-score-uncacheable-files
@cindex score cache
All score files are normally cached to avoid excessive re-loading of
score files. However, if this might make 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
+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
@item local
@cindex local variables
-The value of this entry should be a list of @code{(VAR VALUE)} pairs.
-Each @var{var} will be made buffer-local to the current summary buffer,
-and set to the value specified. This is a convenient, if somewhat
-strange, way of setting variables in some groups if you don't like hooks
-much. Note that the @var{value} won't be evaluated.
+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
on the @code{References} header using the @code{Message-ID} of the
current article, thereby matching the following thread.
-You can also score on @code{thread}, which will try to score all
-articles that appear in a thread. @code{thread} matches uses a
-@code{Message-ID} to match on the @code{References} header of the
-article. If the match is made, the @code{Message-ID} of the article is
-added to the @code{thread} rule. (Think about it. I'd recommend two
-aspirins afterwards.)
-
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.
@vindex gnus-adaptive-file-suffix
The adaptive score entries will be put into a file where the name is the
group name with @code{gnus-adaptive-file-suffix} appended. The default
-is @samp{ADAPT}.
+is @file{ADAPT}.
@vindex gnus-score-exact-adapt-limit
When doing adaptive scoring, substring or fuzzy matching would probably
old articles for a long time.
@end itemize
-... I wonder whether other newsreaders will support global score files
+@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?
In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
Where 1 means something like this article is a waste of bandwidth and 5
means that the article was really good. The basic question to ask
-yourself is, "on a scale from 1 to 5 would I like to see more articles
-like this one?"
+yourself is, ``on a scale from 1 to 5 would I like to see more articles
+like this one?''
There are four ways to enter a rating for an article in GroupLens.
that do explicitly say so in this manual. To apply the process/prefix
convention to commands that do not use it, you can use the @kbd{M-&}
command. For instance, to mark all the articles in the group as
-expirable, you could say `M P b M-& E'.
+expirable, you could say @kbd{M P b M-& E}.
@node Interactive
@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
Text inside the @samp{%<<} and @samp{%>>} specifiers will get the
-special @code{balloon-help} property set to @code{gnus-balloon-face-0}.
-If you say @samp{%1<<}, you'll get @code{gnus-balloon-face-1} and so on.
-The @code{gnus-balloon-face-*} variables should be either strings or
-symbols naming functions that return a string. When the mouse passes
-over text with this property set, a balloon window will appear and
-display the string. Please refer to @ref{(emacs)Help Echo} (in GNU
-Emacs) or the doc string of @code{balloon-help-mode} (in XEmacs) for
-more information on this. (For technical reasons, the guillemets have
-been approximated as @samp{<<} and @samp{>>} in this paragraph.)
+special @code{balloon-help} property set to
+@code{gnus-balloon-face-0}. If you say @samp{%1<<}, you'll get
+@code{gnus-balloon-face-1} and so on. The @code{gnus-balloon-face-*}
+variables should be either strings or symbols naming functions that
+return a string. When the mouse passes over text with this property
+set, a balloon window will appear and display the string. Please
+refer to @ref{Tooltips, ,Tooltips, emacs, The Emacs Manual},
+(in GNU Emacs) or the doc string of @code{balloon-help-mode} (in
+XEmacs) for more information on this. (For technical reasons, the
+guillemets have been approximated as @samp{<<} and @samp{>>} in this
+paragraph.)
Here's an alternative recipe for the group buffer:
you'll get top speed again. Gnus will save these compiled specs in the
@file{.newsrc.eld} file. (User-defined functions aren't compiled by
this function, though---you should compile them yourself by sticking
-them into the @code{.gnus.el} file and byte-compiling that file.)
+them into the @file{.gnus.el} file and byte-compiling that file.)
@node Mode Lines
* Picons:: How to display pictures of what you're reading.
* Smileys:: Show all those happy faces the way they were meant to be shown.
* X-Face:: Display a funky, teensy black-and-white image.
-* Toolbar:: Click'n'drool.
* XVarious:: Other XEmacsy Gnusey variables.
@end menu
good way to do so. Its also a great way to impress people staring
over your shoulder as you read news.
-@menu
-* Picon Basics:: What are picons and How do I get them.
-* Picon Requirements:: Don't go further if you aren't using XEmacs.
-* Easy Picons:: Displaying Picons---the easy way.
-* Hard Picons:: The way you should do it. You'll learn something.
-* Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with.
-@end menu
-
-
-@node Picon Basics
-@subsubsection Picon Basics
-
What are Picons? To quote directly from the Picons Web site:
@iftex
@code{GIF} formats.
@end quotation
-@vindex gnus-picons-piconsearch-url
-If you have a permanent connection to the Internet you can use Steve
-Kinzler's Picons Search engine by setting
-@code{gnus-picons-piconsearch-url} to the string @*
-@uref{http://www.cs.indiana.edu/picons/search.html}.
-
-@vindex gnus-picons-database
-Otherwise you need a local copy of his database. For instructions on
-obtaining and installing the picons databases, point your Web browser at @*
-@uref{http://www.cs.indiana.edu/picons/ftp/index.html}. Gnus expects
-picons to be installed into a location pointed to by
-@code{gnus-picons-database}.
+@vindex gnus-picon-databases
+For instructions on obtaining and installing the picons databases,
+point your Web browser at
+@uref{http://www.cs.indiana.edu/picons/ftp/index.html}.
If you are using Debian GNU/Linux, saying @samp{apt-get install
picons.*} will install the picons where Gnus can find them.
+To enable displaying picons, simply make sure that
+@code{gnus-picon-databases} points to the directory containing the
+Picons databases.
-@node Picon Requirements
-@subsubsection Picon Requirements
-
-To have Gnus display Picons for you, you must have @code{x} support
-compiled into XEmacs. To display color picons which are much nicer
-than the black & white one, you also need one of @code{xpm} or
-@code{gif} compiled into XEmacs.
-
-@vindex gnus-picons-convert-x-face
-If you want to display faces from @code{X-Face} headers, you should have
-the @code{xface} support compiled into XEmacs. Otherwise you must have
-the @code{netpbm} utilities installed, or munge the
-@code{gnus-picons-convert-x-face} variable to use something else.
-(NOTE: @code{x-face} is used in the variable name, not @code{xface})
-
-@node Easy Picons
-@subsubsection Easy Picons
-
-To enable displaying picons, simply put the following line in your
-@file{~/.gnus} file and start Gnus.
-
-@lisp
-(setq gnus-use-picons t)
-(setq gnus-treat-display-picons t)
-@end lisp
-
-and make sure @code{gnus-picons-database} points to the directory
-containing the Picons databases.
-
-Alternatively if you want to use the web piconsearch engine add this:
-
-@lisp
-(setq gnus-picons-piconsearch-url
- "http://www.cs.indiana.edu:800/piconsearch")
-@end lisp
-
-
-@node Hard Picons
-@subsubsection Hard Picons
-
-@iftex
-@iflatex
-\margindex{}
-@end iflatex
-@end iftex
-
-Gnus can display picons for you as you enter and leave groups and
-articles. It knows how to interact with three sections of the picons
-database. Namely, it can display the picons newsgroup pictures,
-author's face picture(s), and the authors domain. To enable this
-feature, you need to select where to get the picons from, and where to
-display them.
+The following variables offer control over where things are located.
@table @code
-@item gnus-picons-database
-@vindex gnus-picons-database
-The location of the picons database. Should point to a directory
+@item gnus-picon-databases
+@vindex gnus-picon-databases
+The location of the picons database. This is a list of directories
containing the @file{news}, @file{domains}, @file{users} (and so on)
-subdirectories. This is only useful if
-@code{gnus-picons-piconsearch-url} is @code{nil}. Defaults to
-@file{/usr/local/faces/}.
-
-@item gnus-picons-piconsearch-url
-@vindex gnus-picons-piconsearch-url
-The URL for the web picons search engine. The only currently known
-engine is @uref{http://www.cs.indiana.edu:800/piconsearch}. To
-workaround network delays, icons will be fetched in the background. If
-this is @code{nil} 'the default), then picons are fetched from local
-database indicated by @code{gnus-picons-database}.
-
-@item gnus-picons-display-where
-@vindex gnus-picons-display-where
-Where the picon images should be displayed. It is @code{picons} by
-default (which by default maps to the buffer @samp{*Picons*}). Other
-valid places could be @code{article}, @code{summary}, or
-@samp{*scratch*} for all I care. Just make sure that you've made the
-buffer visible using the standard Gnus window configuration
-routines---@pxref{Window Layout}.
-
-@item gnus-picons-group-excluded-groups
-@vindex gnus-picons-group-excluded-groups
-Groups that are matched by this regexp won't have their group icons
-displayed.
-
-@end table
-
-Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
-window configuration for you to include the @code{picons} buffer.
+subdirectories. Defaults to @code{("/usr/lib/picon"
+"/usr/local/faces")}.
-Now that you've made those decision, you need to add the following
-functions to the appropriate hooks so these pictures will get displayed
-at the right time.
-
-@vindex gnus-picons-display-where
-@table @code
-@item gnus-article-display-picons
-@findex gnus-article-display-picons
-Looks up and displays the picons for the author and the author's domain
-in the @code{gnus-picons-display-where} buffer.
-
-@item gnus-picons-article-display-x-face
-@findex gnus-picons-article-display-x-face
-Decodes and displays the X-Face header if present.
-(NOTE: @code{x-face} is used in the function name, not @code{xface})
-
-@end table
-
-
-
-@node Picon Useless Configuration
-@subsubsection Picon Useless Configuration
-
-@iftex
-@iflatex
-\margindex{}
-@end iflatex
-@end iftex
-
-The following variables offer further control over how things are
-done, where things are located, and other useless stuff you really
-don't need to worry about.
-
-@table @code
-
-@item gnus-picons-news-directories
-@vindex gnus-picons-news-directories
-List of subdirectories to search in @code{gnus-picons-database} for
+@item gnus-picon-news-directories
+@vindex gnus-picon-news-directories
+List of subdirectories to search in @code{gnus-picon-databases} for
newsgroups faces. @code{("news")} is the default.
-@item gnus-picons-user-directories
-@vindex gnus-picons-user-directories
-List of subdirectories to search in @code{gnus-picons-database} for user
-faces. @code{("local" "users" "usenix" "misc")} is the default.
+@item gnus-picon-user-directories
+@vindex gnus-picon-user-directories
+List of subdirectories to search in @code{gnus-picon-databases} for user
+faces. @code{("users" "usenix" "local" "misc")} is the default.
-@item gnus-picons-domain-directories
-@vindex gnus-picons-domain-directories
-List of subdirectories to search in @code{gnus-picons-database} for
+@item gnus-picon-domain-directories
+@vindex gnus-picon-domain-directories
+List of subdirectories to search in @code{gnus-picon-databases} for
domain name faces. Defaults to @code{("domains")}. Some people may
want to add @samp{"unknown"} to this list.
-@item gnus-picons-convert-x-face
-@vindex gnus-picons-convert-x-face
-If you don't have @code{xface} support builtin XEmacs, this is the
-command to use to convert the @code{X-Face} header to an X bitmap
-(@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
-Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
-gnus-picons-x-face-file-name)}
-(NOTE: @code{x-face} is used in the variable name, not @code{xface})
-
-@item gnus-picons-x-face-file-name
-@vindex gnus-picons-x-face-file-name
-Names a temporary file to store the @code{X-Face} bitmap in. Defaults
-to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
-(NOTE: @code{x-face} is used in the variable name, not @code{xface})
-
-@item gnus-picons-has-modeline-p
-@vindex gnus-picons-has-modeline-p
-If you have set @code{gnus-picons-display-where} to @code{picons}, your
-XEmacs frame will become really cluttered. To alleviate this a bit you
-can set @code{gnus-picons-has-modeline-p} to @code{nil}; this will
-remove the mode line from the Picons buffer. This is only useful if
-@code{gnus-picons-display-where} is @code{picons}.
-
-@item gnus-picons-refresh-before-display
-@vindex gnus-picons-refresh-before-display
-If non-nil, display the article buffer before computing the picons.
-Defaults to @code{nil}.
-
-@item gnus-picons-display-as-address
-@vindex gnus-picons-display-as-address
-If @code{t} display textual email addresses along with pictures.
-Defaults to @code{t}.
-
-@item gnus-picons-file-suffixes
-@vindex gnus-picons-file-suffixes
+@item gnus-picon-file-types
+@vindex gnus-picon-file-types
Ordered list of suffixes on picon file names to try. Defaults to
-@code{("xpm" "gif" "xbm")} minus those not builtin your XEmacs.
-
-@item gnus-picons-setup-hook
-@vindex gnus-picons-setup-hook
-Hook run in the picon buffer, if that is displayed.
-
-@item gnus-picons-display-article-move-p
-@vindex gnus-picons-display-article-move-p
-Whether to move point to first empty line when displaying picons. This
-has only an effect if `gnus-picons-display-where' has value `article'.
-
-If @code{nil}, display the picons in the @code{From} and
-@code{Newsgroups} lines. This is the default.
-
-@item gnus-picons-clear-cache-on-shutdown
-@vindex gnus-picons-clear-cache-on-shutdown
-Whether to clear the picons cache when exiting gnus. Gnus caches every
-picons it finds while it is running. This saves some time in the search
-process but eats some memory. If this variable is set to @code{nil},
-Gnus will never clear the cache itself; you will have to manually call
-@code{gnus-picons-clear-cache} to clear it. Otherwise the cache will be
-cleared every time you exit Gnus. Defaults to @code{t}.
-
-@iftex
-@iflatex
-\margindex{}
-@end iflatex
-@end iftex
+@code{("xpm" "gif" "xbm")} minus those not builtin your Emacs.
@end table
(setq gnus-treat-display-smileys t)
@end lisp
-Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and
+Smiley maps text smiley faces---@samp{:-)}, @samp{8-)}, @samp{:-(} and
the like---to pictures and displays those instead of the text smiley
faces. The conversion is controlled by a list of regexps that matches
text and maps that to file names.
-@vindex smiley-nosey-regexp-alist
-@vindex smiley-deformed-regexp-alist
-Smiley supplies two example conversion alists by default:
-@code{smiley-deformed-regexp-alist} (which matches @samp{:)}, @samp{:(}
-and so on), and @code{smiley-nosey-regexp-alist} (which matches
-@samp{:-)}, @samp{:-(} and so on).
-
-The alist used is specified by the @code{smiley-regexp-alist} variable,
-which defaults to the value of @code{smiley-deformed-regexp-alist}.
-
-The first item in each element is the regexp to be matched; the second
-element is the regexp match group that is to be replaced by the picture;
-and the third element is the name of the file to be displayed.
+@vindex smiley-regexp-alist
+The alist used is specified by the @code{smiley-regexp-alist}
+variable. The first item in each element is the regexp to be matched;
+the second element is the regexp match group that is to be replaced by
+the picture; and the third element is the name of the file to be
+displayed.
The following variables customize where Smiley will look for these
-files, as well as the color to be used and stuff:
+files:
@table @code
@vindex smiley-data-directory
Where Smiley will look for smiley faces files.
-@item smiley-flesh-color
-@vindex smiley-flesh-color
-Skin color. The default is @samp{yellow}, which is really racist.
-
-@item smiley-features-color
-@vindex smiley-features-color
-Color of the features of the face. The default is @samp{black}.
-
-@item smiley-tongue-color
-@vindex smiley-tongue-color
-Color of the tongue. The default is @samp{red}.
-
-@item smiley-circle-color
-@vindex smiley-circle-color
-Color of the circle around the face. The default is @samp{black}.
-
-@item smiley-mouse-face
-@vindex smiley-mouse-face
-Face used for mouse highlighting over the smiley face.
+@item gnus-smiley-file-types
+@vindex gnus-smiley-file-types
+List of suffixes on smiley file names to try.
@end table
friends.@footnote{On a GNU/Linux system look for packages with names
like @code{netpbm}, @code{libgr-progs} and @code{compface}.})
-(NOTE: @code{x-face} is used in the variable/function names, not
+(Note: @code{x-face} is used in the variable/function names, not
@code{xface}).
Gnus provides a few convenience functions and variables to allow
easier insertion of X-Face headers in outgoing messages.
@findex gnus-random-x-face
+@vindex gnus-convert-pbm-to-x-face-command
+@vindex gnus-x-face-directory
@code{gnus-random-x-face} goes through all the @samp{pbm} files in
@code{gnus-x-face-directory} and picks one at random, and then
converts it to the X-Face format by using the
randomly generated data.
@findex gnus-x-face-from-file
+@vindex gnus-convert-image-to-x-face-command
@code{gnus-x-face-from-file} takes a GIF file as the parameter, and then
converts the file to X-Face format by using the
@code{gnus-convert-image-to-x-face-command} shell command.
@end lisp
-@node Toolbar
-@subsection Toolbar
-
-@table @code
-
-@iftex
-@iflatex
-\margindex{}
-@end iflatex
-@end iftex
-
-@item gnus-use-toolbar
-@vindex gnus-use-toolbar
-If @code{nil}, don't display toolbars. If non-@code{nil}, it should be
-one of @code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar},
-@code{right-toolbar}, or @code{left-toolbar}.
-
-@item gnus-group-toolbar
-@vindex gnus-group-toolbar
-The toolbar in the group buffer.
-
-@item gnus-summary-toolbar
-@vindex gnus-summary-toolbar
-The toolbar in the summary buffer.
-
-@item gnus-summary-mail-toolbar
-@vindex gnus-summary-mail-toolbar
-The toolbar in the summary buffer of mail groups.
-
-@end table
-
-
@node XVarious
@subsection Various XEmacs Variables
A glyph displayed in all Gnus mode lines. It is a tiny gnu head by
default.
+@end table
+
+@subsubsection Toolbar
+
+@table @code
+
+@item gnus-use-toolbar
+@vindex gnus-use-toolbar
+If @code{nil}, don't display toolbars. If non-@code{nil}, it should be
+one of @code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar},
+@code{right-toolbar}, or @code{left-toolbar}.
+
+@item gnus-group-toolbar
+@vindex gnus-group-toolbar
+The toolbar in the group buffer.
+
+@item gnus-summary-toolbar
+@vindex gnus-summary-toolbar
+The toolbar in the summary buffer.
+
+@item gnus-summary-mail-toolbar
+@vindex gnus-summary-mail-toolbar
+The toolbar in the summary buffer of mail groups.
+
+@end table
+
@iftex
@iflatex
\margindex{}
@end iflatex
@end iftex
-@end table
-
-
-
@node Fuzzy Matching
@section Fuzzy Matching
and processing.
The simplest approach to filtering spam is filtering. If you get 200
-spam messages per day from @email{random-address@@vmadmin.com}, you
+spam messages per day from @samp{random-address@@vmadmin.com}, you
block @samp{vmadmin.com}. If you get 200 messages about
@samp{VIAGRA}, you discard all messages with @samp{VIAGRA} in the
message. This, unfortunately, is a great way to discard legitimate
@item hashcash-payment-alist
@vindex hashcash-payment-alist
Some receivers may require you to spend burn more CPU time than the
-default. This variable contains a list of @samp{(ADDR AMOUNT)} cells,
-where ADDR is the receiver (email address or newsgroup) and AMOUNT is
-the number of bits in the collision that is needed. It can also
-contain @samp{(ADDR STRING AMOUNT)} cells, where the STRING is the
-string to use (normally the email address or newsgroup name is used).
+default. This variable contains a list of @samp{(@var{addr}
+@var{amount})} cells, where @var{addr} is the receiver (email address
+or newsgroup) and @var{amount} is the number of bits in the collision
+that is needed. It can also contain @samp{(@var{addr} @var{string}
+@var{amount})} cells, where the @var{string} is the string to use
+(normally the email address or newsgroup name is used).
@item hashcash
@vindex hashcash
@findex gnus-summary-mark-as-spam
@code{gnus-summary-mark-as-spam}.
-Mark current article as spam, showing it with the @samp{H} mark.
+Mark current article as spam, showing it with the @samp{$} mark.
Whenever you see a spam article, make sure to mark its summary line
with @kbd{M-d} before leaving the group. This is done automatically
for unread articles in @emph{spam} groups.
@findex spam-bogofilter-score
@code{spam-bogofilter-score}.
-You must have bogofilter processing enabled for that command to work
-properly.
+You must have Bogofilter installed for that command to work properly.
@xref{Bogofilter}.
default.
In spam groups, all messages are considered to be spam by default:
-they get the @samp{H} mark when you enter the group. You must review
-these messages from time to time and remove the @samp{H} mark for
-every message that is not spam after all. To remove the @samp{H}
-mark, you can use @kbd{M-u} to "unread" the article, or @kbd{d} for
+they get the @samp{$} mark when you enter the group. You must review
+these messages from time to time and remove the @samp{$} mark for
+every message that is not spam after all. To remove the @samp{$}
+mark, you can use @kbd{M-u} to ``unread'' the article, or @kbd{d} for
declaring it read the non-spam way. When you leave a group, all
-spam-marked (@samp{H}) articles are sent to a spam processor which
+spam-marked (@samp{$}) articles are sent to a spam processor which
will study them as spam samples.
Messages may also be deleted in various other ways, and unless
to a spam processor, which will study these as spam samples. If you
explicit kill a lot, you might sometimes end up with articles marked
@samp{K} which you never saw, and which might accidentally contain
-spam. Best is to make sure that real spam is marked with @samp{H},
+spam. Best is to make sure that real spam is marked with @samp{$},
and nothing else.
When you leave a @emph{spam} group, all spam-marked articles are
not done for @emph{unclassified} or @emph{ham} groups. Also, any
@strong{ham} articles in a spam group will be moved to a location
determined by either the @code{ham-process-destination} group
-parameter or the @code{gnus-ham-process-destinations} variable. The
+parameter or a match in the @code{gnus-ham-process-destinations}
+variable, which is a list of regular expressions matched with group
+names (it's easiest to customize this variable with
+@code{customize-variable gnus-ham-process-destinations}). The ultimate
location is a group name. If the @code{ham-process-destination}
parameter is not set, spam articles are only expired.
When you leave a @emph{ham} or @emph{unclassified} group, all
@strong{spam} articles are moved to a location determined by either
-the @code{spam-process-destination} group parameter or the
-@code{gnus-spam-process-destinations} variable. The location is a
-group name. If the @code{spam-process-destination} parameter is not
-set, the spam articles are only expired.
+the @code{spam-process-destination} group parameter or a match in the
+@code{gnus-spam-process-destinations} variable, which is a list of
+regular expressions matched with group names (it's easiest to
+customize this variable with @code{customize-variable
+gnus-spam-process-destinations}). The ultimate location is a group
+name. If the @code{spam-process-destination} parameter is not set,
+the spam articles are only expired.
To use the @code{spam.el} facilities for incoming mail filtering, you
must add the following to your fancy split list
@code{spam-split-group}. By default that group name is @samp{spam},
but you can customize it.
+@emph{Note for IMAP users}
+
+The boolean variable @code{nnimap-split-download-body} needs to be
+set, if you want to split based on the whole message instead of just
+the headers. By default, the nnimap backend will only retrieve the
+message headers. If you use spam-check-bogofilter, spam-check-ifile,
+or spam-check-stat (the splitters that can benefit from the full
+message body), you should set this variable. It is not set by default
+because it will slow IMAP down.
+
+@xref{Splitting in IMAP}.
+
@emph{TODO: Currently, spam.el only supports insertion of articles
into a backend. There is no way to tell spam.el that an article is no
longer spam or ham.}
* Blacklists and Whitelists::
* BBDB Whitelists::
* Blackholes::
+* Regular Expressions Header Matching::
* Bogofilter::
* ifile spam filtering::
* spam-stat spam filtering::
-* Extending the spam elist package::
+* Extending the spam elisp package::
@end menu
@node Blacklists and Whitelists
@cindex spam
@defvar spam-use-blacklist
-Set this variable to t if you want to use blacklists when splitting
-incoming mail. Messages whose senders are in the blacklist will be
-sent to the @code{spam-split-group}. This is an explicit filter,
-meaning that it acts only on mail senders @emph{declared} to be
-spammers.
+
+Set this variable to @code{t} if you want to use blacklists when
+splitting incoming mail. Messages whose senders are in the blacklist
+will be sent to the @code{spam-split-group}. This is an explicit
+filter, meaning that it acts only on mail senders @emph{declared} to
+be spammers.
+
@end defvar
@defvar spam-use-whitelist
-Set this variable to t if you want to use whitelists when splitting
-incoming mail. Messages whose senders are not in the whitelist will
-be sent to the @code{spam-split-group}. This is an implicit filter,
-meaning it believes everyone to be a spammer unless told otherwise.
-Use with care.
+
+Set this variable to @code{t} if you want to use whitelists when
+splitting incoming mail. Messages whose senders are not in the
+whitelist will be sent to the next spam-split rule. This is an
+explicit filter, meaning that unless someone is in the whitelist, their
+messages are not assumed to be spam or ham.
+
+@end defvar
+
+@defvar spam-use-whitelist-exclusive
+
+Set this variable to @code{t} if you want to use whitelists as an
+implicit filter, meaning that every message will be considered spam
+unless the sender is in the whitelist. Use with care.
+
@end defvar
@defvar gnus-group-spam-exit-processor-blacklist
+
Add this symbol to a group's @code{spam-process} parameter by
customizing the group parameters or the
@code{gnus-spam-process-newsgroups} variable. When this symbol is
added to a group's @code{spam-process} parameter, the senders of
spam-marked articles will be added to the blacklist.
+
@end defvar
@defvar gnus-group-ham-exit-processor-whitelist
+
Add this symbol to a group's @code{spam-process} parameter by
customizing the group parameters or the
@code{gnus-spam-process-newsgroups} variable. When this symbol is
ham-marked articles in @emph{ham} groups will be added to the
whitelist. Note that this ham processor has no effect in @emph{spam}
or @emph{unclassified} groups.
+
@end defvar
Blacklists are lists of regular expressions matching addresses you
use the Emacs regular expression syntax.
Conversely, whitelists tell Gnus what addresses are considered
-legitimate. All non-whitelisted addresses are considered spammers.
-This option is probably not useful for most Gnus users unless the
-whitelists is very comprehensive or permissive. Also see @ref{BBDB
-Whitelists}. Whitelist entries use the Emacs regular expression
-syntax.
+legitimate. All messages from whitelisted addresses are considered
+non-spam. Also see @ref{BBDB Whitelists}. Whitelist entries use the
+Emacs regular expression syntax.
The blacklist and whitelist file locations can be customized with the
@code{spam-directory} variable (@file{~/News/spam} by default), or
@defvar spam-use-BBDB
Analogous to @code{spam-use-whitelist} (@pxref{Blacklists and
-Whitelists}), but uses the BBDB as the source of whitelisted addresses,
-without regular expressions. You must have the BBDB loaded for
-@code{spam-use-BBDB} to work properly. Only addresses in the BBDB
-will be allowed through; all others will be classified as spam.
+Whitelists}), but uses the BBDB as the source of whitelisted
+addresses, without regular expressions. You must have the BBDB loaded
+for @code{spam-use-BBDB} to work properly. Messages whose senders are
+not in the BBDB will be sent to the next spam-split rule. This is an
+explicit filter, meaning that unless someone is in the BBDB, their
+messages are not assumed to be spam or ham.
+
+@end defvar
+
+@defvar spam-use-BBDB-exclusive
+
+Set this variable to @code{t} if you want to use the BBDB as an
+implicit filter, meaning that every message will be considered spam
+unless the sender is in the BBDB. Use with care. Only sender
+addresses in the BBDB will be allowed through; all others will be
+classified as spammers.
@end defvar
@defvar gnus-group-ham-exit-processor-BBDB
+
Add this symbol to a group's @code{spam-process} parameter by
customizing the group parameters or the
@code{gnus-spam-process-newsgroups} variable. When this symbol is
ham-marked articles in @emph{ham} groups will be added to the
BBDB. Note that this ham processor has no effect in @emph{spam}
or @emph{unclassified} groups.
+
@end defvar
@node Blackholes
@end defvar
+@defvar spam-blackhole-good-server-regex
+
+A regular expression for IPs that should not be checked against the
+blackhole server list. When set to nil, it has no effect.
+
+@end defvar
+
@defvar spam-use-dig
Use the @code{dig.el} package instead of the @code{dns.el} package.
-The default setting of t is recommended.
+The default setting of @code{t} is recommended.
@end defvar
Blackhole checks are done only on incoming mail. There is no spam or
ham processor for blackholes.
+@node Regular Expressions Header Matching
+@subsubsection Regular Expressions Header Matching
+@cindex spam filtering
+@cindex regular expressions header matching, spam filtering
+@cindex spam
+
+@defvar spam-use-regex-headers
+
+This option is disabled by default. You can let Gnus check the
+message headers against lists of regular expressions when you set this
+option. The variables @code{spam-regex-headers-spam} and
+@code{spam-regex-headers-ham} hold the list of regular expressions.
+Gnus will check against the message headers to determine if the
+message is spam or ham, respectively.
+
+@end defvar
+
+@defvar spam-regex-headers-spam
+
+The list of regular expressions that, when matched in the headers of
+the message, positively identify it as spam.
+
+@end defvar
+
+@defvar spam-regex-headers-ham
+
+The list of regular expressions that, when matched in the headers of
+the message, positively identify it as ham.
+
+@end defvar
+
+Regular expression header checks are done only on incoming mail.
+There is no specific spam or ham processor for regular expressions.
+
@node Bogofilter
@subsubsection Bogofilter
@cindex spam filtering
@defvar spam-use-bogofilter
Set this variable if you want @code{spam-split} to use Eric Raymond's
-speedy Bogofilter. This has been tested with a locally patched copy
-of version 0.4. Make sure to read the installation comments in
-@code{spam.el}.
+speedy Bogofilter.
-With a minimum of care for associating the @samp{H} mark for spam
+With a minimum of care for associating the @samp{$} mark for spam
articles only, Bogofilter training all gets fairly automatic. You
should do this until you get a few hundreds of articles in each
-category, spam or not. The shell command @command{head -1
-~/.bogofilter/*} shows both article counts. The command @kbd{S t} in
-summary mode, either for debugging or for curiosity, triggers
-Bogofilter into displaying in another buffer the @emph{spamicity}
-score of the current article (between 0.0 and 1.0), together with the
-article words which most significantly contribute to the score.
+category, spam or not. The command @kbd{S t} in summary mode, either
+for debugging or for curiosity, shows the @emph{spamicity} score of
+the current article (between 0.0 and 1.0).
+
+Bogofilter determines if a message is spam based on an internal
+threshold, set at compilation time. That threshold can't be
+customized.
If the @code{bogofilter} executable is not in your path, Bogofilter
processing will be turned off.
+You should not enable this if you use @code{spam-use-bogofilter-headers}.
+
@end defvar
+@defvar spam-use-bogofilter-headers
+
+Set this variable if you want @code{spam-split} to use Eric Raymond's
+speedy Bogofilter, looking only at the message headers. It works
+similarly to @code{spam-use-bogofilter}, but the @code{X-Bogosity} header
+must be in the message already. Normally you would do this with a
+procmail recipe or something similar; consult the Bogofilter
+installation documents for details.
+
+You should not enable this if you use @code{spam-use-bogofilter}.
+
+@end defvar
@defvar gnus-group-spam-exit-processor-bogofilter
Add this symbol to a group's @code{spam-process} parameter by
customizing the group parameters or the
@code{gnus-spam-process-newsgroups} variable. When this symbol is
added to a group's @code{spam-process} parameter, spam-marked articles
-will be added to the bogofilter spam database, and ham-marked articles
-will be added to the bogofilter ham database. @strong{Note that the
-Bogofilter spam processor is the only spam processor to also do ham
-processing.}
+will be added to the Bogofilter spam database.
+@end defvar
+
+@defvar gnus-group-ham-exit-processor-bogofilter
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, the ham-marked
+articles in @emph{ham} groups will be added to the Bogofilter database
+of non-spam messages. Note that this ham processor has no effect in
+@emph{spam} or @emph{unclassified} groups.
@end defvar
+@defvar spam-bogofilter-database-directory
+
+This is the directory where Bogofilter will store its databases. It
+is not specified by default, so Bogofilter will use its own default
+database directory.
+
+@end defvar
+
+The Bogofilter mail classifier is similar to ifile in intent and
+purpose. A ham and a spam processor are provided, plus the
+@code{spam-use-bogofilter} and @code{spam-use-bogofilter-headers}
+variables to indicate to spam-split that Bogofilter should either be
+used, or has already been used on the article. The 0.9.2.1 version of
+Bogofilter was used to test this functionality.
+
@node ifile spam filtering
@subsubsection ifile spam filtering
@cindex spam filtering
processor, and the @code{spam-use-stat} variable for @code{spam-split}
are provided.
-@node Extending the spam elist package
+@node Extending the spam elisp package
@subsubsection Extending the spam elisp package
@cindex spam filtering
@cindex spam elisp package, extending
@item
code
-@example
+@lisp
(defvar spam-use-blackbox nil
"True if blackbox should be used.")
-@end example
+@end lisp
Add
@example
Write the @code{spam-check-blackbox} function. It should return
@samp{nil} or @code{spam-split-group}. See the existing
@code{spam-check-*} functions for examples of what you can do.
+
+Make sure to add @code{spam-use-blackbox} to
+@code{spam-list-of-statistical-checks} if Blackbox is a statistical
+mail analyzer that needs the full message body to operate.
+
@end enumerate
For processing spam and ham messages, provide the following:
Note you don't have to provide a spam or a ham processor. Only
provide them if Blackbox supports spam or ham processing.
-@example
+@lisp
(defvar gnus-group-spam-exit-processor-blackbox "blackbox"
"The Blackbox summary exit spam processor.
Only applicable to spam groups.")
"The whitelist summary exit ham processor.
Only applicable to non-spam (unclassified and ham) groups.")
-@end example
+@end lisp
@item
functionality
-@example
+@lisp
(defun spam-blackbox-register-spam-routine ()
(spam-generic-register-routine
;; the spam function
(let ((from (spam-fetch-field-from-fast article)))
(when (stringp from)
(blackbox-do-something-with-this-ham-sender from))))))
-@end example
+@end lisp
Write the @code{blackbox-do-something-with-this-ham-sender} and
@code{blackbox-do-something-with-this-spammer} functions. You can add
In order to use @code{spam-stat} to split your mail, you need to add the
following to your @file{~/.gnus} file:
-@example
+@lisp
(require 'spam-stat)
(spam-stat-load)
-@end example
+@end lisp
This will load the necessary Gnus code, and the dictionary you
created.
spam or it should go into @samp{mail.misc}. If it is spam, then
@code{spam-stat-split-fancy} will return @samp{mail.spam}.
-@example
+@lisp
(setq nnmail-split-fancy
`(| (: spam-stat-split-fancy)
"mail.misc"))
-@end example
+@end lisp
@defvar spam-stat-split-fancy-spam-group
The group to use for spam. Default is @samp{mail.spam}.
the following expression. Only mails not matching the regular
expression are considered potential spam.
-@example
+@lisp
(setq nnmail-split-fancy
`(| ("Subject" "\\bspam-stat\\b" "mail.emacs")
(: spam-stat-split-fancy)
"mail.misc"))
-@end example
+@end lisp
If you want to filter for spam first, then you must be careful when
creating the dictionary. Note that @code{spam-stat-split-fancy} must
non-spam, therefore both should be in your collection of non-spam
mails, when creating the dictionary!
-@example
+@lisp
(setq nnmail-split-fancy
`(| (: spam-stat-split-fancy)
("Subject" "\\bspam-stat\\b" "mail.emacs")
"mail.misc"))
-@end example
+@end lisp
You can combine this with traditional filtering. Here, we move all
HTML-only mails into the @samp{mail.spam.filtered} group. Note that since
nor in your collection of non-spam mails, when creating the
dictionary!
-@example
+@lisp
(setq nnmail-split-fancy
`(| ("Content-Type" "text/html" "mail.spam.filtered")
(: spam-stat-split-fancy)
("Subject" "\\bspam-stat\\b" "mail.emacs")
"mail.misc"))
-@end example
+@end lisp
@node Low-level interface to the spam-stat dictionary
Make sure you load the dictionary before using it. This requires the
following in your @file{~/.gnus} file:
-@example
+@lisp
(require 'spam-stat)
(spam-stat-load)
-@end example
+@end lisp
Typical test will involve calls to the following functions:
@table @code
@item gnus-home-directory
+@vindex gnus-home-directory
All Gnus file and directory variables will be initialized from this
variable, which defaults to @file{~/}.
Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
``worser''? ``much worser''? ``worsest''?)
-I would like to take this opportunity to thank the Academy for... oops,
+I would like to take this opportunity to thank the Academy for@dots{} oops,
wrong show.
@itemize @bullet
New element in @code{gnus-boring-article-headers}---@code{long-to}.
@item
- @kbd{M-i} symbolic prefix command. See the section "Symbolic
-Prefixes" in the Gnus manual for details.
+ @kbd{M-i} symbolic prefix command. See the section ``Symbolic
+Prefixes'' in the Gnus manual for details.
@item
@kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix
-@kbd{a} to add the score rule to the "all.SCORE" file.
+@kbd{a} to add the score rule to the @file{all.SCORE} file.
@item
@code{gnus-simplify-subject-functions} variable to allow greater
@code{gnus-adaptive-word-minimum} variable.
@item
- The "lapsed date" article header can be kept continually
+ The ``lapsed date'' article header can be kept continually
updated by the @code{gnus-start-date-timer} command.
@item
@cindex slow
Sometimes, a problem do not directly generate a elisp error but
manifests itself by causing Gnus to be very slow. In these cases, you
-can use @kbd{M-x toggle-debug-on-quit} and press C-j when things are
+can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are
slow, and then try to analyze the backtrace (repeating the procedure
helps isolating the real problem areas). A fancier approach is to use
the elisp profiler, ELP. The profiler is (or should be) fully
documented elsewhere, but to get you started there are a few steps
that need to be followed. First, instrument the part of Gnus you are
interested in for profiling, e.g. @kbd{M-x elp-instrument-package RET
-gnus} or @kbd{M-x elp-instrument-packagre RET message}. Then perform
+gnus} or @kbd{M-x elp-instrument-package RET message}. Then perform
the operation that is slow and press @kbd{M-x elp-results}. You will
then see which operations that takes time, and can debug them further.
If the entire operation takes much longer than the time spent in the
@cindex gnu.emacs.gnus
@cindex ding mailing list
-You can also ask on the ding mailing list---@samp{ding@@gnus.org}.
-Write to @samp{ding-request@@gnus.org} to subscribe.
+You can also ask on the ding mailing list---@email{ding@@gnus.org}.
+Write to @email{ding-request@@gnus.org} to subscribe.
@page
This might later be expanded to @code{various}, which will be a mixture
of HEADs and @sc{nov} lines, but this is currently not supported by Gnus.
-If @var{fetch-old} is non-@code{nil} it says to try fetching "extra
-headers", in some meaning of the word. This is generally done by
+If @var{fetch-old} is non-@code{nil} it says to try fetching ``extra
+headers'', in some meaning of the word. This is generally done by
fetching (at most) @var{fetch-old} extra headers less than the smallest
article number in @code{articles}, and filling the gaps as well. The
presence of this parameter can be ignored if the back end finds it
header = <text> eol
@end example
+@cindex BNF
+(The version of BNF used here is the one used in RFC822.)
+
If the return value is @code{nov}, the data buffer should contain
@dfn{network overview database} lines. These are basically fields
separated by tabs.
@example
nov-buffer = *nov-line
-nov-line = 8*9 [ field <TAB> ] eol
+nov-line = field 7*8[ <TAB> field ] eol
field = <text except TAB>
@end example
Set/remove/add marks on articles. Normally Gnus handles the article
marks (such as read, ticked, expired etc) internally, and store them in
-@code{~/.newsrc.eld}. Some back ends (such as @sc{imap}) however carry
+@file{~/.newsrc.eld}. Some back ends (such as @sc{imap}) however carry
all information about the articles on the server, so Gnus need to
propagate the mark information to the server.
-ACTION is a list of mark setting requests, having this format:
+@var{action} is a list of mark setting requests, having this format:
@example
(RANGE ACTION MARK)
@end example
-RANGE is a range of articles you wish to update marks on. ACTION is
-@code{add} or @code{del}, used to add marks or remove marks
-(preserving all marks not mentioned). MARK is a list of marks; where
-each mark is a symbol. Currently used marks are @code{read},
-@code{tick}, @code{reply}, @code{expire}, @code{killed},
+@var{range} is a range of articles you wish to update marks on.
+@var{action} is @code{add} or @code{del}, used to add marks or remove
+marks (preserving all marks not mentioned). @var{mark} is a list of
+marks; where each mark is a symbol. Currently used marks are
+@code{read}, @code{tick}, @code{reply}, @code{expire}, @code{killed},
@code{dormant}, @code{save}, @code{download}, @code{unsend},
@code{forward} and @code{recent}, but your back end should, if
possible, not limit itself to these.
There should be no result data returned.
-@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
-&optional LAST)
+@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST)
This function should move @var{article} (which is a number) from
@var{group} by calling @var{accept-form}.
This macro defines some common functions that almost all back ends should
have.
-@example
+@lisp
(nnoo-define-basics nndir)
-@end example
+@end lisp
@item deffoo
This macro is just like @code{defun} and takes the same parameters. In
This macro allows mapping of functions from the current back end to
functions from the parent back ends.
-@example
+@lisp
(nnoo-map-functions nndir
(nnml-retrieve-headers 0 nndir-current-group 0 0)
(nnmh-request-article 0 nndir-current-group 0 0))
-@end example
+@end lisp
This means that when @code{nndir-retrieve-headers} is called, the first,
third, and fourth parameters will be passed on to
last thing in the source file, since it will only define functions that
haven't already been defined.
-@example
+@lisp
(nnoo-import nndir
(nnmh
nnmh-request-list
nnmh-request-newgroups)
(nnml))
-@end example
+@end lisp
This means that calls to @code{nndir-request-list} should just be passed
on to @code{nnmh-request-list}, while all public functions from
This function (really ``special form'') @code{setq} is the one that can
set a variable to some value. This is really all you need to know. Now
-you can go and fill your @code{.emacs} file with lots of these to change
+you can go and fill your @file{.emacs} file with lots of these to change
how Gnus works.
-If you have put that thing in your @code{.emacs} file, it will be read
+If you have put that thing in your @file{.emacs} file, it will be read
and @code{eval}ed (which is lisp-ese for ``run'') the next time you
start Emacs. If you want to change the variable right away, simply say
@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the