\makeindex
\begin{document}
-\newcommand{\gnusversionname}{Oort Gnus v0.07}
+\newcommand{\gnusversionname}{Oort Gnus v0.12}
\newcommand{\gnuschaptername}{}
\newcommand{\gnussectionname}{}
\thispagestyle{empty}
-Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
+Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
+2002, 2003
Free Software Foundation, Inc.
This file documents Gnus, the GNU Emacs newsreader.
-Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
+Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
+Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
+2002, 2003
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
spool or your mbox file. All at the same time, if you want to push your
luck.
-This manual corresponds to Oort Gnus v0.07.
+This manual corresponds to Oort Gnus v0.12.
@end ifinfo
* Index:: Variable, function and concept index.
* Key Index:: Key Index.
+Other related manuals
+
+* Message:(message). Composing messages.
+* Emacs-MIME:(emacs-mime). Composing messages; MIME-specific parts.
+* Sieve:(sieve). Managing Sieve scripts in Emacs.
+* PGG:(pgg). PGP/MIME with Gnus.
+
@detailmenu
--- The Detailed Node Listing ---
a @code{printf} specifications, for those of you who use (feh!) C.
@xref{Formatting Variables}.
-@samp{%M%S%5y: %(%g%)\n} is the value that produced those lines above.
+@samp{%M%S%5y:%B%(%g%)\n} is the value that produced those lines above.
There should always be a colon on the line; the cursor always moves to
the colon after performing an operation. @xref{Positioning
@item R
Number of read articles.
+@item U
+Number of unseen articles.
+
@item t
Estimated total number of articles. (This is really @var{max-number}
minus @var{min-number} plus 1.)
@item s
Select method.
+@item B
+If the summary buffer for the group is open or not.
+
@item n
Select from where.
precedence over any default @code{Gcc} rules as described later
(@pxref{Archived Messages}). CAVEAT:: It yields an error putting
@code{(gcc-self . t)} in groups of a @code{nntp} server or so, because
-a @code{nntp} server doesn't accept artciles.
+a @code{nntp} server doesn't accept articles.
@item auto-expire
@cindex auto-expire
@item posting-style
@cindex posting-style
-You can store additional posting style information for this group only
+You can store additional posting style information for this group
here (@pxref{Posting Styles}). The format is that of an entry in the
@code{gnus-posting-styles} alist, except that there's no regexp matching
the group name (of course). Style elements in this group parameter will
@example
(posting-style
(name "Funky Name")
+ ("X-My-Header" "Funky Value")
(signature "Funky Signature"))
@end example
Sort the group buffer alphabetically by back end name
(@code{gnus-group-sort-groups-by-method}).
+@item G S n
+@kindex G S n (Group)
+@findex gnus-group-sort-groups-by-real-name
+Sort the group buffer alphabetically by real (unprefixed) group name
+(@code{gnus-group-sort-groups-by-real-name}).
+
@end table
All the commands below obey the process/prefix convention
Sort the groups alphabetically by back end name
(@code{gnus-group-sort-selected-groups-by-method}).
+@item G P n
+@kindex G P n (Group)
+@findex gnus-group-sort-selected-groups-by-real-name
+Sort the groups alphabetically by real (unprefixed) group name
+(@code{gnus-group-sort-selected-groups-by-real-name}).
+
@item G P s
@kindex G P s (Group)
@findex gnus-group-sort-selected-groups
@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.
+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.
@item gnus-mark-article-hook
@vindex gnus-mark-article-hook
@subsection Setting Process Marks
@cindex setting process marks
+Process marks are displayed as @code{#} in the summary buffer, and are
+used for marking articles in such a way that other commands will
+process these articles. For instance, if you process mark four
+articles and then use the @kbd{*} command, Gnus will enter these four
+commands into the cache. For more information,
+@pxref{Process/Prefix}.
+
@table @kbd
@item M P p
@item dummy
@vindex gnus-summary-dummy-line-format
+@vindex gnus-summary-make-false-root-always
Gnus will create a dummy summary line that will pretend to be the
parent. This dummy line does not correspond to any real article, so
selecting it will just select the first real article after the dummy
article. @code{gnus-summary-dummy-line-format} is used to specify the
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.
@item empty
Gnus won't actually make any article the parent, but simply leave the
generated.
This can also be a predicate specifier (@pxref{Predicate Specifiers}).
-Avaliable predicates are @code{gnus-article-unread-p} and
+Available predicates are @code{gnus-article-unread-p} and
@code{gnus-article-unseen-p}).
Here's an example:
@findex gnus-summary-pipe-output
Save the current article in a pipe. Uhm, like, what I mean is---Pipe
the current article to a process (@code{gnus-summary-pipe-output}).
+If given a symbolic prefix (@pxref{Symbolic Prefixes}), include the
+complete headers in the piped output.
@item O P
@kindex O P (Summary)
@item W k
@kindex W k (Summary)
+@kindex W Y f (Summary)
@findex gnus-article-outlook-deuglify-article
@cindex Outlook Express
-Deuglify broken Outlook (Express) articles and redisplay
+Deuglify broken Outlook (Express) articles.
(@code{gnus-article-outlook-deuglify-article}).
+@item W Y u
+@kindex W Y u (Summary)
+@findex gnus-outlook-unwrap-lines
+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}).
+
+@item W Y a
+@kindex W Y a (Summary)
+@findex gnus-outlook-repair-attribution
+Repair a broken attribution line
+(@code{gnus-outlook-repair-attribution}).
+
+@item W Y c
+@kindex W Y c (Summary)
+@findex gnus-outlook-rearrange-citation
+Repair broken citations by rearranging the text.
+(@code{gnus-outlook-rearrange-citation}).
+
@item W w
@kindex W w (Summary)
@findex gnus-article-fill-cited-article
@vindex gnus-article-wash-function
The default is to use the function specified by
-@code{mm-inline-text-html-renderer} (@pxref{Customization, , , emacs-mime})
-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{(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:
@table @code
@item w3
@table @var
@item regexp
-All text that match this regular expression will be considered an
-external reference. Here's a typical regexp that matches embedded URLs:
-@samp{<URL:\\([^\n\r>]*\\)>}. This can also be a variable containing a
-regexp, useful variables to use include @code{gnus-button-url-regexp}.
+All text that match this regular expression (case insensitive) will be
+considered an external reference. Here's a typical regexp that matches
+embedded URLs: @samp{<URL:\\([^\n\r>]*\\)>}. This can also be a
+variable containing a regexp, useful variables to use include
+@code{gnus-button-url-regexp}.
@item button-par
Gnus has to know which parts of the matches is to be highlighted. This
@cindex x-face
@cindex smileys
-These commands add various frivolous display gimmics to the article
+These commands add various frivolous display gimmicks to the article
buffer in Emacs versions that support them.
@code{X-Face} headers are small black-and-white images supplied by the
Display an @code{X-Face} in the @code{From} header.
(@code{gnus-article-display-x-face}).
+@item W D d
+@kindex W D d (Summary)
+@findex gnus-article-display-face
+Display a @code{Face} in the @code{From} header.
+(@code{gnus-article-display-face}).
+
@item W D s
@kindex W D s (Summary)
@findex gnus-treat-smiley
'("text/x-vcard"))
@end lisp
+@item gnus-article-loose-mime
+@vindex gnus-article-loose-mime
+If non-@code{nil}, Gnus won't required the @samp{MIME-Version} header
+before interpreting the message as a @sc{mime} message. This helps
+when reading messages from certain broken mail user agents. The
+default is @code{nil}.
+
+@item gnus-article-emulate-mime
+@vindex gnus-article-emulate-mime
+There are other, non-@sc{mime} encoding methods used. The most common
+is @samp{uuencode}, but yEncode is also getting to be popular. If
+This variable is non-@code{nil}, Gnus will look in message bodies to
+see if it finds these encodings, and if so, it'll run them through the
+Gnus @sc{mime} machinery. The default is @code{t}.
+
@item gnus-unbuttonized-mime-types
@vindex gnus-unbuttonized-mime-types
This is a list of regexps. @sc{mime} types that match a regexp from
this list won't have @sc{mime} buttons inserted unless they aren't
-displayed or this variable is overriden by
+displayed or this variable is overridden by
@code{gnus-buttonized-mime-types}. The default value is
-@code{(".*/.*")}.
+@code{(".*/.*")}. This variable is only used when
+@code{gnus-inhibit-mime-unbuttonizing} is nil.
@item gnus-buttonized-mime-types
@vindex gnus-buttonized-mime-types
this list will have @sc{mime} buttons inserted unless they aren't
displayed. This variable overrides
@code{gnus-unbuttonized-mime-types}. The default value is @code{nil}.
+This variable is only used when @code{gnus-inhibit-mime-unbuttonizing}
+is nil.
To see e.g. security buttons but no other buttons, you could set this
variable to @code{("multipart/signed")} and leave
@end lisp
@noindent
-to your @file{.gnus} file.
+to your @file{.gnus.el} file.
@end table
@lisp
(setq gnus-refer-article-method
'(current
- (nnweb "refer" (nnweb-type google))))
+ (nnweb "google" (nnweb-type google))))
@end lisp
Most of the mail back ends support fetching by @code{Message-ID}, but
@kindex B t (Summary)
@findex gnus-summary-respool-trace
Similarly, this command will display all fancy splitting patterns used
-when repooling, if any (@code{gnus-summary-respool-trace}).
+when respooling, if any (@code{gnus-summary-respool-trace}).
@item B p
@kindex B p (Summary)
Pull all cached articles (for the current group) into the summary buffer
(@code{gnus-summary-insert-cached-articles}).
+@item Y d
+@kindex Y d (Summary)
+@findex gnus-summary-insert-dormant-articles
+Pull all dormant articles (for the current group) into the summary buffer
+(@code{gnus-summary-insert-dormant-articles}).
+
@end table
@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)
@xref{Article Washing}.
@item gnus-confirm-mail-reply-to-news
@vindex gnus-confirm-mail-reply-to-news
-If non-@code{nil}, Gnus requests confirmation when replying to news.
+This can also be a function receiving the group name as the only
+parameter which should return non-@code{nil} if a confirmation is
+needed, or a regular expression matching group names, where
+confirmation is should be asked for.
+
If you find yourself never wanting to reply to mail, but occasionally
press R anyway, this variable might be for you.
+@item gnus-confirm-treat-mail-like-news
+@vindex gnus-confirm-treat-mail-like-news
+If non-@code{nil}, Gnus also requests confirmation according to
+@code{gnus-confirm-mail-reply-to-news} when replying to mail. This is
+useful for treating mailing lists like newsgroups.
+
@end table
It is useful if your ISP requires the POP-before-SMTP authentication.
See the documentation for the function @code{mail-source-touch-pop}.
-Other possible choises for @code{message-send-mail-function} includes
+Other possible choices for @code{message-send-mail-function} includes
@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail},
and @code{feedmail-send-it}.
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} file:
+mail" back end), you could put the following in your @file{.gnus.el} file:
@lisp
(setq gnus-secondary-select-methods '((nnml "")))
@code{nnmail-split-fancy} manually. You can do it by running
@code{gnus-group-split-update}. If you'd rather have it updated
automatically, just tell @code{gnus-group-split-setup} to do it for
-you. For example, add to your @file{.gnus}:
+you. For example, add to your @file{.gnus.el}:
@lisp
(gnus-group-split-setup AUTO-UPDATE CATCH-ALL)
articles you read as expirable, no matter if they were read or unread
before. To avoid having articles marked as read marked as expirable
automatically, you can put something like the following in your
-@file{.gnus} file:
+@file{.gnus.el} file:
@vindex gnus-mark-article-hook
@lisp
Gnus provides a plethora of functions for washing articles while
displaying them, but it might be nicer to do the filtering before
-storing the mail to disc. For that purpose, we have three hooks and
+storing the mail to disk. For that purpose, we have three hooks and
various functions that can be put in these hooks.
@table @code
course, and is still maintained by Stallman.
Both of the above forms leave your mail in a single file on your
-filesystem, and they must parse that entire file each time you take a
+file system, and they must parse that entire file each time you take a
look at your mail.
@item nnml
provided by the active file and overviews.
@code{nnml} costs @dfn{inodes} in a big way; that is, it soaks up the
-resource which defines available places in the filesystem to put new
+resource which defines available places in the file system to put new
files. Sysadmins take a dim view of heavy inode occupation within
-tight, shared filesystems. But if you live on a personal machine where
-the filesystem is your own and space is not at a premium, @code{nnml}
+tight, shared file systems. But if you live on a personal machine where
+the file system is your own and space is not at a premium, @code{nnml}
wins big.
It is also problematic using this back end if you are living in a
@code{df -i} to see how plentiful your inode supply is.) If this slows
you down or takes up very much space, consider switching to ReiserFS
(@uref{http://www.namesys.com/}) or another non-block-structured
-filesystem.
+file system.
Since maildirs don't require locking for delivery, the maildirs you use
as groups can also be the maildirs your mail is directly delivered to.
(It keeps in memory some of the things that @code{nnml} stores in files
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 somthing small (0 would probably not work, but 1 probably
+parameter to something small (0 would probably not work, but 1 probably
would) to make it use less memory.
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 filesystem.
+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.
similar. You restore the data by restoring the directory tree, and
adding a server definition pointing to that directory in Gnus. The
@ref{Article Backlog}, @ref{Asynchronous Fetching} and other things
-might interfer with overwriting data, so you may want to shut down Gnus
+might interfere with overwriting data, so you may want to shut down Gnus
before you restore the data.
It is also possible to archive individual @code{nnml},
has to retrieve absolutely all comments in a group upon entry. If a
threaded display is not required, @code{nnslashdot} will only retrieve
the comments that are actually wanted by the user. Threading is nicer,
-but much, much slower than untreaded.
+but much, much slower than unthreaded.
@item nnslashdot-login-name
@vindex nnslashdot-login-name
@vindex imap-ssl-program
For SSL connections, the OpenSSL program is available from
@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay,
-and nnimap support it too - altough the most recent versions of
+and nnimap support it too - although the most recent versions of
SSLeay, 0.9.x, are known to have serious bugs making it
useless. Earlier versions, especially 0.8.x, of SSLeay are known to
work. The variable @code{imap-ssl-program} contain parameters to pass
@item
@dfn{login:} Plain-text username/password via LOGIN.
@item
-@dfn{anonymous:} Login as `anonymous', supplying your emailadress as password.
+@dfn{anonymous:} Login as `anonymous', supplying your email address as password.
@end itemize
@item nnimap-expunge-on-close
* Server Agent Commands::
@end menu
-You can run a complete batch command from the command line with the
-following incantation:
-
-@cindex gnus-agent-batch
-@example
-$ emacs -batch -l ~/.gnus.el -f gnus-agent-batch
-@end example
written) is quite easy once you've gotten things set up properly. The
following shell script will do everything that is necessary:
+You can run a complete batch command from the command line with the
+following incantation:
+
@example
#!/bin/sh
-emacs -batch -l ~/.emacs -f gnus-agent-batch >/dev/null
+emacs -batch -l ~/.emacs -f -l ~/.gnus.el gnus-agent-batch >/dev/null 2>&1
@end example
@table @dfn
@item If I read an article while plugged, do they get entered into the Agent?
-@strong{No}.
+@strong{No}. If you want this behaviour, add
+@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?
Some may feel that short words shouldn't count when doing adaptive
scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to
an integer. Words shorter than this number will be ignored. This
-variable defaults til @code{nil}.
+variable defaults to @code{nil}.
@vindex gnus-adaptive-word-syntax-table
When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the
function is called @code{gnus-goto-colon}.
But perhaps the most convenient way to deal with this, if you don't want
-to have a colon in your line, is to use the @samp{%C} specifier. If you
-put a @samp{%C} somewhere in your format line definition, Gnus will
+to have a colon in your line, is to use the @samp{%*} specifier. If you
+put a @samp{%*} somewhere in your format line definition, Gnus will
place point there.
The problem is that when formatting, Gnus assumes that if a string is 10
characters wide, it'll be 10 Latin characters wide on the screen. In
-these coutries, that's not true.
+these countries, that's not true.
@vindex gnus-use-correct-string-widths
To help fix this, you can set @code{gnus-use-correct-string-widths} to
@code{t}. This makes buffer generation slower, but the results will be
-prettieer. The default value under XEmacs is @code{t} but @code{nil}
+prettier. The default value under XEmacs is @code{t} but @code{nil}
for Emacs.
all the timings in the handlers will be affected.)
So, if you want to add a handler, you could put something like this in
-your @file{.gnus} file:
+your @file{.gnus.el} file:
@findex gnus-demon-add-handler
@lisp
@code{gnus-demon-add-nntp-close-connection},
@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and
@code{gnus-demon-add-scanmail}. Just put those functions in your
-@file{.gnus} if you want those abilities.
+@file{.gnus.el} if you want those abilities.
@findex gnus-demon-init
@findex gnus-demon-cancel
@code{gnus-convert-image-to-x-face-command} shell command.
Here's how you would typically use the former function. Put something
-like the folllowing in your @file{.gnus.el} file:
+like the following in your @file{.gnus.el} file:
@lisp
(setq message-required-news-headers
A novel technique to fight spam is to require senders to do something
costly for each message they send. This has the obvious drawback that
you cannot rely on that everyone in the world uses this technique,
-since it is not part of the internet standards, but it may be useful
+since it is not part of the Internet standards, but it may be useful
in smaller communities.
While the tools in the previous section work well in practice, they
The idea behind @code{spam.el} is to have a control center for spam detection
and filtering in Gnus. To that end, @code{spam.el} does two things: it
-filters incoming mail, and it analyzes mail known to be spam.
+filters incoming mail, and it analyzes mail known to be spam or ham.
+@emph{Ham} is the name used throughout @code{spam.el} to indicate
+non-spam messages.
So, what happens when you load @code{spam.el}? First of all, you get
the following keyboard commands:
@kindex S x
@kindex M s x
@findex gnus-summary-mark-as-spam
-(@code{gnus-summary-mark-as-spam})
+@code{gnus-summary-mark-as-spam}.
Mark current article as spam, showing it with the @samp{H} mark.
Whenever you see a spam article, make sure to mark its summary line
-with @kbd{M-d} before leaving the group.
+with @kbd{M-d} before leaving the group. This is done automatically
+for unread articles in @emph{spam} groups.
@item M s t
@itemx S t
@kindex M s t
@kindex S t
@findex spam-bogofilter-score
-(@code{spam-bogofilter-score}
+@code{spam-bogofilter-score}.
You must have bogofilter processing enabled for that command to work
properly.
@end table
-Gnus can learn from the spam you get. All you have to do is collect
-your spam in one or more spam groups, and set the variable
-@code{spam-junk-mailgroups} as appropriate. In these groups, all messages
-are considered to be spam by default: they get the @samp{H} mark. You must
-review these messages from time to time and remove the @samp{H} mark for
-every message that is not spam after all. When you leave a spam
-group, all messages that continue with the @samp{H} mark, are passed on to
-the spam-detection engine (bogofilter, ifile, and others). To remove
-the @samp{H} 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 @samp{H}
-marked articles, saved or unsaved, are sent to Bogofilter or ifile
-(depending on @code{spam-use-bogofilter} and @code{spam-use-ifile}), which will study
-them as spam samples.
+Also, when you load @code{spam.el}, you will be able to customize its
+variables. Try @code{customize-group} on the @samp{spam} variable
+group.
+
+The concepts of ham processors and spam processors are very important.
+Ham processors and spam processors for a group can be set with the
+@code{spam-process} group parameter, or the
+@code{gnus-spam-process-newsgroups} variable. Ham processors take
+mail known to be non-spam (@emph{ham}) and process it in some way so
+that later similar mail will also be considered non-spam. Spam
+processors take mail known to be spam and process it so similar spam
+will be detected later.
+
+Gnus learns from the spam you get. You have to collect your spam in
+one or more spam groups, and set or customize the variable
+@code{spam-junk-mailgroups} as appropriate. You can also declare
+groups to contain spam by setting their group parameter
+@code{spam-contents} to @code{gnus-group-spam-classification-spam}, or
+by customizing the corresponding variable
+@code{gnus-spam-newsgroup-contents}. The @code{spam-contents} group
+parameter and the @code{gnus-spam-newsgroup-contents} variable can
+also be used to declare groups as @emph{ham} groups if you set their
+classification to @code{gnus-group-spam-classification-ham}. If
+groups are not classified by means of @code{spam-junk-mailgroups},
+@code{spam-contents}, or @code{gnus-spam-newsgroup-contents}, they are
+considered @emph{unclassified}. All groups are unclassified by
+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
+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
+will study them as spam samples.
Messages may also be deleted in various other ways, and unless
-@code{spam-ham-marks-form} gets overridden below, marks @samp{R} and @samp{r} for
-default read or explicit delete, marks @samp{X} and @samp{K} for automatic or
-explicit kills, as well as mark @samp{Y} for low scores, are all considered
-to be associated with articles which are not spam. This assumption
-might be false, in particular if you use kill files or score files as
-means for detecting genuine spam, you should then adjust
-@code{spam-ham-marks-form}. When you leave a group, all _unsaved_ articles
-bearing any the above marks are sent to Bogofilter or ifile, which
-will study these as not-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}, and nothing else.
-
-All other marks do not contribute to Bogofilter or ifile
-pre-conditioning. In particular, ticked, dormant or souped articles
-are likely to contribute later, when they will get deleted for real,
-so there is no need to use them prematurely. Explicitly expired
-articles do not contribute, command @kbd{E} is a way to get rid of an
-article without Bogofilter or ifile ever seeing it.
-
-@strong{TODO: @code{spam-use-ifile} does not process spam articles on group exit.
-I'm waiting for info from the author of @code{ifile-gnus.el}, because I think
-that functionality should go in @code{ifile-gnus.el} rather than @code{spam.el}.}
+@code{spam-ham-marks} gets overridden below, marks @samp{R} and
+@samp{r} for default read or explicit delete, marks @samp{X} and
+@samp{K} for automatic or explicit kills, as well as mark @samp{Y} for
+low scores, are all considered to be associated with articles which
+are not spam. This assumption might be false, in particular if you
+use kill files or score files as means for detecting genuine spam, you
+should then adjust the @code{spam-ham-marks} variable.
+
+@defvar spam-ham-marks
+You can customize this variable to be the list of marks you want to
+consider ham. By default, the list contains the deleted, read,
+killed, kill-filed, and low-score marks.
+@end defvar
+
+@defvar spam-spam-marks
+You can customize this variable to be the list of marks you want to
+consider spam. By default, the list contains only the spam mark.
+@end defvar
+
+When you leave @emph{any} group, regardless of its
+@code{spam-contents} classification, all spam-marked articles are sent
+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},
+and nothing else.
+
+When you leave a @emph{spam} group, all spam-marked articles are
+marked as expired after processing with the spam processor. This is
+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
+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} group, all ham-marked articles are sent to
+a ham processor, which will study these as non-spam samples.
+
+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.
To use the @code{spam.el} facilities for incoming mail filtering, you
must add the following to your fancy split list
@code{nnimap-split-fancy}, depending on whether you use the nnmail or
nnimap back ends to retrieve your mail.
-The @code{spam-split} function will process incoming mail and send the mail
-considered to be spam into the group name given by the variable
-@code{spam-split-group}. Usually that group name is @samp{spam}.
+The @code{spam-split} function will process incoming mail and send the
+mail considered to be spam into the group name given by the variable
+@code{spam-split-group}. By default that group name is @samp{spam},
+but you can customize it.
+
+@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.}
+
+@emph{TODO: spam.el needs to provide a uniform way of training all the
+statistical databases. Some have that functionality built-in, others
+don't.}
The following are the methods you can use to control the behavior of
-@code{spam-split}:
+@code{spam-split} and their corresponding spam and ham processors:
@menu
* Blacklists and Whitelists::
* BBDB Whitelists::
* Blackholes::
* Bogofilter::
-* Ifile spam filtering::
+* ifile spam filtering::
+* spam-stat spam filtering::
* Extending spam.el::
@end menu
@cindex spam.el
@defvar spam-use-blacklist
-Set this variables to t (the default) if you want to use blacklists.
+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.
@end defvar
@defvar spam-use-whitelist
-Set this variables to t if you want to use whitelists.
+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.
+@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
+added to a group's @code{spam-process} parameter, the senders of
+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
consider to be spam senders. For instance, to block mail from any
sender at @samp{vmadmin.com}, you can put @samp{vmadmin.com} in your
-blacklist. Since you start out with an empty blacklist, no harm is
-done by having the @code{spam-use-blacklist} variable set, so it is
-set by default. Blacklist entries use the Emacs regular expression
-syntax.
+blacklist. You start out with an empty blacklist. Blacklist entries
+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. Also see @ref{BBDB Whitelists}.
-Whitelist entries use the Emacs regular expression syntax.
+whitelists is very comprehensive or permissive. Also see @ref{BBDB
+Whitelists}. Whitelist entries use the Emacs regular expression
+syntax.
-The Blacklist and whitelist location can be customized with the
-@code{spam-directory} variable (@file{~/News/spam} by default). The whitelist
-and blacklist files will be in that directory, named @file{whitelist} and
+The blacklist and whitelist file locations can be customized with the
+@code{spam-directory} variable (@file{~/News/spam} by default), or
+the @code{spam-whitelist} and @code{spam-blacklist} variables
+directly. The whitelist and blacklist files will by default be in the
+@code{spam-directory} directory, named @file{whitelist} and
@file{blacklist} respectively.
@node BBDB Whitelists
@cindex BBDB, spam filtering
@cindex spam.el
-@defvar spam-use-bbdb
+@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
+@code{spam-use-BBDB} to work properly. Only addresses in the BBDB
will be allowed through; all others will be classified as spam.
@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
+added to a group's @code{spam-process} parameter, the senders of
+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
@subsubsection Blackholes
@cindex spam filtering
@defvar spam-use-blackholes
-You can let Gnus consult the blackhole-type distributed spam
-processing systems (DCC, for instance) when you set this option. The
-variable @code{spam-blackhole-servers} holds the list of blackhole servers
-Gnus will consult.
+This option is disabled by default. You can let Gnus consult the
+blackhole-type distributed spam processing systems (DCC, for instance)
+when you set this option. The variable @code{spam-blackhole-servers}
+holds the list of blackhole servers Gnus will consult. The current
+list is fairly comprehensive, but make sure to let us know if it
+contains outdated servers.
+
+The blackhole check uses the @code{dig.el} package, but you can tell
+@code{spam.el} to use @code{dns.el} instead for better performance if
+you set @code{spam-use-dig} to nil. It is not recommended at this
+time to set @code{spam-use-dig} to nil despite the possible
+performance improvements, because some users may be unable to use it,
+but you can try it and see if it works for you.
+
+@end defvar
+
+@defvar spam-blackhole-servers
+
+The list of servers to consult for blackhole checks.
-This variable is disabled by default. It is not recommended at this
-time because of bugs in the @code{dns.el} code.
+@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.
@end defvar
+Blackhole checks are done only on incoming mail. There is no spam or
+ham processor for blackholes.
+
@node Bogofilter
@subsubsection Bogofilter
@cindex spam filtering
@defvar spam-use-bogofilter
-Set this variable if you want 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}.
+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}.
With a minimum of care for associating the @samp{H} mark for spam
articles only, Bogofilter training all gets fairly automatic. You
score of the current article (between 0.0 and 1.0), together with the
article words which most significantly contribute to the score.
+If the @code{bogofilter} executable is not in your path, Bogofilter
+processing will be turned off.
+
+@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.}
@end defvar
-@node Ifile spam filtering
-@subsubsection Ifile spam filtering
+@node ifile spam filtering
+@subsubsection ifile spam filtering
@cindex spam filtering
@cindex ifile, spam filtering
@cindex spam.el
@defvar spam-use-ifile
-Enable this variable if you want to use Ifile, a statistical analyzer
-similar to Bogofilter. Currently you must have @code{ifile-gnus.el}
-loaded. The integration of Ifile with @code{spam.el} is not finished
-yet, but you can use @code{ifile-gnus.el} on its own if you like.
+Enable this variable if you want @code{spam-split} to use ifile, a
+statistical analyzer similar to Bogofilter.
+
+@end defvar
+
+@defvar spam-ifile-all-categories
+
+Enable this variable if you want @code{spam-use-ifile} to give you all
+the ifile categories, not just spam/non-spam. If you use this, make
+sure you train ifile as described in its documentation.
+
+@end defvar
+
+@defvar spam-ifile-spam-category
+This is the category of spam messages as far as ifile is concerned.
+The actual string used is irrelevant, but you probably want to leave
+the default value of @samp{spam}.
@end defvar
+@defvar spam-ifile-database-path
+
+This is the filename for the ifile database. It is not specified by
+default, so ifile will use its own default database name.
+
+@end defvar
+
+The ifile mail classifier is similar to Bogofilter in intent and
+purpose. A ham and a spam processor are provided, plus the
+@code{spam-use-ifile} variable to indicate to spam-split that ifile
+should be used. The 1.2.1 version of ifile was used to test this
+functionality.
+
+@node spam-stat spam filtering
+@subsubsection spam-stat spam filtering
+@cindex spam filtering
+@cindex spam-stat, spam filtering
+@cindex spam-stat.el
+@cindex spam.el
+
+@xref{Filtering Spam Using Statistics (spam-stat.el)}.
+
+@defvar spam-use-stat
+
+Enable this variable if you want @code{spam-split} to use
+spam-stat.el, an Emacs Lisp statistical analyzer.
+
+@end defvar
+
+@defvar gnus-group-spam-exit-processor-stat
+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 spam-marked
+articles will be added to the spam-stat database of spam messages.
+@end defvar
+
+@defvar gnus-group-ham-exit-processor-stat
+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 spam-stat database
+of non-spam messages. Note that this ham processor has no effect in
+@emph{spam} or @emph{unclassified} groups.
+@end defvar
+
+This enables spam.el to cooperate with spam-stat.el. spam-stat.el
+provides an internal (Lisp-only) spam database, which unlike ifile or
+Bogofilter does not require external programs. A spam and a ham
+processor, and the @code{spam-use-stat} variable for @code{spam-split}
+are provided.
+
@node Extending spam.el
@subsubsection Extending spam.el
@cindex spam filtering
@cindex spam.el, extending
@cindex extending spam.el
-Say you want to add a new back end called blackbox. Provide the following:
+Say you want to add a new back end called blackbox. For filtering
+incoming mail, provide the following:
@enumerate
-@item
-documentation
@item
code
@code{spam-check-*} functions for examples of what you can do.
@end enumerate
+For processing spam and ham messages, provide the following:
+
+@enumerate
+
+@item
+code
+
+Note you don't have to provide a spam or a ham processor. Only
+provide them if Blackbox supports spam or ham processing.
+
+@example
+(defvar gnus-group-spam-exit-processor-blackbox "blackbox"
+ "The Blackbox summary exit spam processor.
+Only applicable to spam groups.")
+
+(defvar gnus-group-ham-exit-processor-blackbox "blackbox"
+ "The whitelist summary exit ham processor.
+Only applicable to non-spam (unclassified and ham) groups.")
+
+@end example
+
+@item
+functionality
+
+@example
+(defun spam-blackbox-register-spam-routine ()
+ (spam-generic-register-routine
+ ;; the spam function
+ (lambda (article)
+ (let ((from (spam-fetch-field-from-fast article)))
+ (when (stringp from)
+ (blackbox-do-something-with-this-spammer from))))
+ ;; the ham function
+ nil))
+
+(defun spam-blackbox-register-ham-routine ()
+ (spam-generic-register-routine
+ ;; the spam function
+ nil
+ ;; the ham function
+ (lambda (article)
+ (let ((from (spam-fetch-field-from-fast article)))
+ (when (stringp from)
+ (blackbox-do-something-with-this-ham-sender from))))))
+@end example
+
+Write the @code{blackbox-do-something-with-this-ham-sender} and
+@code{blackbox-do-something-with-this-spammer} functions. You can add
+more complex code than fetching the message sender, but keep in mind
+that retrieving the whole message takes significantly longer than the
+sender through @code{spam-fetch-field-from-fast}, because the message
+senders are kept in memory by Gnus.
+
+@end enumerate
+
+
@node Filtering Spam Using Statistics (spam-stat.el)
@subsection Filtering Spam Using Statistics (spam-stat.el)
@cindex Paul Graham
@file{~/Mail/mail/misc} (this usually corresponds the the group
@samp{nnml:mail.misc}).
+When you are using IMAP, you won't have the mails available locally,
+so that will not work. One solution is to use the Gnus Agent to cache
+the articles. Then you can use directories such as
+@file{"~/News/agent/nnimap/mail.yourisp.com/personal_spam"} for
+@code{spam-stat-process-spam-directory}. @xref{Agent as Cache}.
+
@defvar spam-stat
This variable holds the hash-table with all the statistics -- the
dictionary we have been talking about. For every word in either
collection, this hash-table stores a vector describing how often the
word appeared in spam and often it appeared in non-spam mails.
+@end defvar
If you want to regenerate the statistics from scratch, you need to
reset the dictionary.
-@end defvar
-
@defun spam-stat-reset
Reset the @code{spam-stat} hash-table, deleting all the statistics.
+@end defun
When you are done, you must save the dictionary. The dictionary may
be rather large. If you will not update the dictionary incrementally
can reduce the size of the dictionary by deleting all words that did
not appear often enough or that do not clearly belong to only spam or
only non-spam mails.
-@end defun
@defun spam-stat-reduce-size
Reduce the size of the dictionary. Use this only if you do not want
created.
Next, you need to adapt your fancy splitting rules: You need to
-determine how to use @code{spam-stat}. In the simplest case, you only have
-two groups, @samp{mail.misc} and @samp{mail.spam}. The following expression says
-that mail is either spam or it should go into @samp{mail.misc}. If it is
-spam, then @code{spam-stat-split-fancy} will return @samp{mail.spam}.
+determine how to use @code{spam-stat}. The following examples are for
+the nnml back end. Using the nnimap back end works just as well. Just
+use @code{nnimap-split-fancy} instead of @code{nnmail-split-fancy}.
+
+In the simplest case, you only have two groups, @samp{mail.misc} and
+@samp{mail.spam}. The following expression says that mail is either
+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
(setq nnmail-split-fancy
@end defvar
If you also filter mail with specific subjects into other groups, use
-the following expression. It only the mails not matching the regular
+the following expression. Only mails not matching the regular
expression are considered potential spam.
@example
The main interface to using @code{spam-stat}, are the following functions:
@defun spam-stat-buffer-is-spam
-called in a buffer, that buffer is considered to be a new spam mail;
-use this for new mail that has not been processed before
-
+Called in a buffer, that buffer is considered to be a new spam mail.
+Use this for new mail that has not been processed before.
@end defun
@defun spam-stat-buffer-is-no-spam
-called in a buffer, that buffer is considered to be a new non-spam
-mail; use this for new mail that has not been processed before
-
+Called in a buffer, that buffer is considered to be a new non-spam
+mail. Use this for new mail that has not been processed before.
@end defun
@defun spam-stat-buffer-change-to-spam
-called in a buffer, that buffer is no longer considered to be normal
-mail but spam; use this to change the status of a mail that has
-already been processed as non-spam
-
+Called in a buffer, that buffer is no longer considered to be normal
+mail but spam. Use this to change the status of a mail that has
+already been processed as non-spam.
@end defun
@defun spam-stat-buffer-change-to-non-spam
-called in a buffer, that buffer is no longer considered to be spam but
-normal mail; use this to change the status of a mail that has already
-been processed as spam
-
+Called in a buffer, that buffer is no longer considered to be spam but
+normal mail. Use this to change the status of a mail that has already
+been processed as spam.
@end defun
@defun spam-stat-save
-save the hash table to the file; the filename used is stored in the
-variable @code{spam-stat-file}
-
+Save the hash table to the file. The filename used is stored in the
+variable @code{spam-stat-file}.
@end defun
@defun spam-stat-load
-load the hash table from a file; the filename used is stored in the
-variable @code{spam-stat-file}
-
+Load the hash table from a file. The filename used is stored in the
+variable @code{spam-stat-file}.
@end defun
@defun spam-stat-score-word
-return the spam score for a word
-
+Return the spam score for a word.
@end defun
@defun spam-stat-score-buffer
-return the spam score for a buffer
-
+Return the spam score for a buffer.
@end defun
@defun spam-stat-split-fancy
-for fancy mail splitting; add the rule @samp{(: spam-stat-split-fancy)} to
-@code{nnmail-split-fancy}
+Use this function for fancy mail splitting. Add the rule @samp{(:
+spam-stat-split-fancy)} to @code{nnmail-split-fancy}
+@end defun
-This requires the following in your @file{~/.gnus} file:
+Make sure you load the dictionary before using it. This requires the
+following in your @file{~/.gnus} file:
@example
(require 'spam-stat)
(spam-stat-load)
@end example
-@end defun
-
Typical test will involve calls to the following functions:
@example
whatever packages the Gnus XEmacs package requires. The current
requirements are @samp{gnus}, @samp{w3}, @samp{mh-e},
@samp{mailcrypt}, @samp{rmail}, @samp{eterm}, @samp{mail-lib},
-@samp{xemacs-base}, and @samp{fsf-compat}. The @samp{misc-games}
-package is required for Morse decoding.
+@samp{xemacs-base}, @samp{sh-script} and @samp{fsf-compat}. The
+@samp{misc-games} package is required for Morse decoding.
@node History
decoding (verification and decryption).
@item PGP/MIME - RFC 2015/3156
-RFC 2015 (superceded by 3156 which references RFC 2440 instead of RFC
+RFC 2015 (superseded by 3156 which references RFC 2440 instead of RFC
1991) describes the @sc{mime}-wrapping around the RF 1991/2440 format.
Gnus supports both encoding and decoding.
read if your machine should go down (@pxref{Auto Save}).
@item
-Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
+Gnus now has its own startup file (@file{.gnus.el}) to avoid cluttering up
the @file{.emacs} file.
@item
@kbd{C-h v}, abort execution with @kbd{q}, and resume execution with
@kbd{c} or @kbd{g}.
+@cindex elp
+@cindex profile
+@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
+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
+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
+slowest function in the profiler output, you probably profiled the
+wrong part of Gnus. To reset profiling statistics, use @kbd{M-x
+elp-reset-all}. @kbd{M-x elp-restore-all} is supposed to remove
+profiling, but given the complexities and dynamic code generation in
+Gnus, it might not always work perfectly.
+
If you just need help, you are better off asking on
@samp{gnu.emacs.gnus}. I'm not very helpful.
alterations. This comes in handy if the back end really carries all the
information (as is the case with virtual and imap groups). This
function should destructively alter the info to suit its needs, and
-should return the (altered) group info.
+should return a non-nil value.
There should be no result data from this function.
The function should return a cons where the @code{car} is the group name and
the @code{cdr} is the article number that the article was entered as.
+The group should exist before the backend is asked to accept the
+article for that group.
+
There should be no data returned.
projects / gnus / blobdiff