\makeindex
\begin{document}
-\newcommand{\gnusversionname}{Oort Gnus v0.07}
+\newcommand{\gnusversionname}{Oort Gnus v0.13}
\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.13.
@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 ---
* 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
* Anti-Spam Basics:: Simple steps to reduce the amount of spam.
* SpamAssassin:: How to use external anti-spam tools.
* Hashcash:: Reduce spam by burning CPU time.
-* Filtering Spam Using spam.el::
-* Filtering Spam Using Statistics (spam-stat.el)::
+* Filtering Spam Using The Spam ELisp Package::
+* Filtering Spam Using Statistics with spam-stat::
Appendices
@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
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
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.
@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
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
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:
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
@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}
@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).
@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 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
@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
@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
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
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)
@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
like @code{\222} or @code{\264} where you're expecting some kind of
apostrophe or quotation mark, then try this wash.
-@item W k
-@kindex W k (Summary)
+@item W Y f
+@kindex W Y f (Summary)
@findex gnus-article-outlook-deuglify-article
@cindex Outlook Express
-Deuglify broken Outlook (Express) articles and redisplay
+Full deuglify of broken Outlook (Express) articles: Treat dumbquotes,
+unwrap lines, repair attribution and rearrange citation.
(@code{gnus-article-outlook-deuglify-article}).
+@item W Y u
+@kindex W Y u (Summary)
+@findex gnus-article-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-article-outlook-repair-attribution
+Repair a broken attribution line.
+(@code{gnus-article-outlook-repair-attribution}).
+
+@item W Y c
+@kindex W Y c (Summary)
+@findex gnus-article-outlook-rearrange-citation
+Repair broken citations by rearranging the text.
+(@code{gnus-article-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
@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)
@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.
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
@enumerate
@item
-To handle PGP messages, you have to install mailcrypt or gpg.el as
-well as a OpenPGP implementation (such as GnuPG).
+To handle PGP and PGP/MIME messages, you have to install an OpenPGP
+implementation such as GnuPG. The lisp interface to GnuPG included
+with Gnus is called PGG (@pxref{Top, ,PGG, pgg, PGG Manual}), but
+Mailcrypt and gpg.el are also supported.
@item
To handle @sc{s/mime} message, you need to install OpenSSL. OpenSSL 0.9.6
@code{always}, always decrypt; @code{known}, only decrypt known
protocols. Otherwise, ask user.
+@item mml1991-use
+@vindex mml1991-use
+Symbol indicating elisp interface to OpenPGP implementation for PGP
+messages. The default is @code{pgg}, but @code{mailcrypt} and
+@code{gpg} are also supported although deprecated.
+
+@item mml2015-use
+@vindex mml2015-use
+Symbol indicating elisp interface to OpenPGP implementation for
+PGP/MIME messages. The default is @code{pgg}, but @code{mailcrypt}
+and @code{gpg} are also supported although deprecated.
+
@end table
@node Mailing List
@item c (Article)
@kindex c (Article)
Copy the @sc{mime} object to a fresh buffer and display this buffer
-(@code{gnus-mime-copy-part}).
+(@code{gnus-mime-copy-part}). Compressed files like @file{.gz} and
+@file{.bz2} are automatically decompressed if
+@code{auto-compression-mode} is enabled (@pxref{Compressed Files,,
+Accessing Compressed Files, emacs, The Emacs Editor}).
@findex gnus-mime-print-part
@item p (Article)
@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)
@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}.
see the @code{mm-verify-option} and @code{mm-decrypt-option} options
(@pxref{Security}).
-For PGP, Gnus supports two external libraries, @sc{gpg.el} and
-@sc{Mailcrypt}, you need to install at least one of them. The
-@sc{s/mime} support in Gnus requires the external program OpenSSL.
-
+@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
@end table
-Also @xref{Security, ,Security, message, Message Manual}.
+@xref{Security, ,Security, message, Message Manual}, for more information.
@node Select Methods
@chapter Select Methods
@item nnspool-active-file
@vindex nnspool-active-file
-The path to the active file.
+The name of the active file.
@item nnspool-newsgroups-file
@vindex nnspool-newsgroups-file
-The path to the group descriptions file.
+The name of the group descriptions file.
@item nnspool-history-file
@vindex nnspool-history-file
-The path to the news history file.
+The name of the news history file.
@item nnspool-active-times-file
@vindex nnspool-active-times-file
-The path to the active date file.
+The name of the active date file.
@item nnspool-nov-is-evil
@vindex nnspool-nov-is-evil
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 "")))
@table @code
@item :path
-The path of the file. Defaults to the value of the @code{MAIL}
+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}).
@end table
(file :path "/usr/spool/mail/user-name")
@end lisp
-Or using the default path:
+Or using the default file name:
@lisp
(file)
@table @code
@item :path
-The path of the directory where the files are. There is no default
+The name of the directory where the files are. There is no default
value.
@item :suffix
@table @code
@item :path
-The path of the directory where the mails are stored. The default is
+The name of the directory where the mails are stored. The default is
taken from the @code{MAILDIR} environment variable or
@samp{~/Maildir/}.
@item :subdirs
@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)
Go to the group buffer.
@item
-Type `G f' and give the path to the mbox file when prompted to create an
+Type @kbd{G f} and give the file name to the mbox file when prompted to create an
@code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
@item
-Type `SPACE' to enter the newly created group.
+Type @kbd{SPACE} to enter the newly created group.
@item
-Type `M P b' to process-mark all articles in this group's buffer
+Type @kbd{M P b} to process-mark all articles in this group's buffer
(@pxref{Setting Process Marks}).
@item
-Type `B r' to respool all the process-marked articles, and answer
+Type @kbd{B r} to respool all the process-marked articles, and answer
@samp{nnml} when prompted (@pxref{Mail Group Commands}).
@end enumerate
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
(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:
@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
Nnmail equivalent: @code{nnmail-split-fancy}.
+@item nnimap-split-download-body
+@findex nnimap-split-download-body
+@vindex nnimap-split-download-body
+
+Set to non-nil to download entire articles during splitting. This is
+generally not required, and will slow things down considerably. You
+may need it if you want to use an advanced splitting function that
+analyses the body to split the article.
+
@end table
@node Expiring in IMAP
@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-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).
* 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.
@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
-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
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)
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.
+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.
+
@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.
@end lisp
If you use the list form, the last element must always be the default
-method---it must always match all groups.
+method---it must always match all groups. Also, for a regexp to match,
+it must match from the beginning of the group's name.
@vindex gnus-agent-expire-all
If @code{gnus-agent-expire-all} is non-@code{nil}, this command will
(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.
+@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 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.
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. 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).
+
@item gnus-server-unopen-status
@vindex gnus-server-unopen-status
Perhaps not a Agent variable, but closely related to the Agent, this
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?
@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.
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.
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.
(vertical 0.24
(if (buffer-live-p gnus-summary-buffer)
'(summary 0.5))
- (group 1.0)))))
+ (group 1.0))))
@end lisp
One common desire for a multiple frame split is to have a separate frame
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
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
* 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.
-
-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.
+subdirectories. Defaults to @code{("/usr/lib/picon"
+"/usr/local/faces")}.
-@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
easier insertion of X-Face headers in outgoing messages.
@findex gnus-random-x-face
-@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
+@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
@code{gnus-convert-pbm-to-x-face-command} shell command. The
-@samp{pbm} files should be 48x48 pixels big.
+@samp{pbm} files should be 48x48 pixels big. It returns the X-Face
+header data as a string.
+
+@findex gnus-insert-random-x-face-header
+@code{gnus-insert-random-x-face-header} calls
+@code{gnus-random-x-face} and inserts a @samp{X-Face} header with the
+randomly generated data.
+@findex gnus-x-face-from-file
@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.
-Here's how you would typically use the former function. Put something
-like the folllowing in your @file{.gnus.el} file:
+Here's how you would typically use the first function. Put something
+like the following in your @file{.gnus.el} file:
@lisp
(setq message-required-news-headers
(list '(X-Face . gnus-random-x-face))))
@end lisp
-Using the latter function would be something like this:
+Using the last function would be something like this:
@lisp
(setq message-required-news-headers
@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
* Anti-Spam Basics:: Simple steps to reduce the amount of spam.
* SpamAssassin:: How to use external anti-spam tools.
* Hashcash:: Reduce spam by burning CPU time.
-* Filtering Spam Using spam.el::
-* Filtering Spam Using Statistics (spam-stat.el)::
+* Filtering Spam Using The Spam ELisp Package::
+* Filtering Spam Using Statistics with spam-stat::
@end menu
@node The problem of spam
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
customized mail filtering scripts. Improvements in this area would be
a useful contribution, however.
-@node Filtering Spam Using spam.el
-@subsection Filtering Spam Using spam.el
+@node Filtering Spam Using The Spam ELisp Package
+@subsection Filtering Spam Using The Spam ELisp Package
@cindex spam filtering
-@cindex spam.el
+@cindex spam
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:
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
@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}.
@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 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} 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 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{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{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.}
+
+@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::
+* Regular Expressions Header Matching::
* Bogofilter::
-* Ifile spam filtering::
-* Extending spam.el::
+* ifile spam filtering::
+* spam-stat spam filtering::
+* Extending the spam elisp package::
@end menu
@node Blacklists and Whitelists
@cindex spam filtering
@cindex whitelists, spam filtering
@cindex blacklists, spam filtering
-@cindex spam.el
+@cindex spam
@defvar spam-use-blacklist
-Set this variables to t (the default) if you want to use blacklists.
+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 variables to t if you want to use whitelists.
+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 @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 spam filtering
@cindex BBDB whitelists, spam filtering
@cindex BBDB, spam filtering
-@cindex spam.el
+@cindex spam
-@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
@cindex blackholes, spam filtering
-@cindex spam.el
+@cindex spam
@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. The current list is fairly comprehensive.
+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.
+
+@end defvar
+
+@defvar spam-use-dig
-This variable is enabled by default. It uses the @code{dig.el}
-package to look up hosts in the blackhole list, but you can tell
-@code{spam.el} to use @code{dns.el} instead if you set
-@code{spam-use-dig} to nil. It is not recommended at this time to set
-@code{spam-use-dig} to nil because of some issues with the
-@code{dns.el} code, but you can try it and see if it works for you.
+Use the @code{dig.el} package instead of the @code{dns.el} package.
+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, repectively.
+
+@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
@cindex bogofilter, spam filtering
-@cindex spam.el
+@cindex spam
@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.
With a minimum of care for associating the @samp{H} 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
-@node Ifile spam filtering
-@subsubsection Ifile spam filtering
+@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.
+@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
@cindex ifile, spam filtering
-@cindex spam.el
+@cindex spam
@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
-@node Extending spam.el
-@subsubsection Extending spam.el
+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.el, extending
-@cindex extending spam.el
+@cindex spam-stat, spam filtering
+@cindex spam-stat
+@cindex spam
+
+@xref{Filtering Spam Using Statistics with spam-stat}.
-Say you want to add a new back end called blackbox. Provide the following:
+@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 the spam elisp package
+@subsubsection Extending the spam elisp package
+@cindex spam filtering
+@cindex spam elisp package, extending
+@cindex extending the spam elisp package
+
+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
-@node Filtering Spam Using Statistics (spam-stat.el)
-@subsection Filtering Spam Using Statistics (spam-stat.el)
+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 with spam-stat
+@subsection Filtering Spam Using Statistics with spam-stat
@cindex Paul Graham
@cindex Graham, Paul
@cindex naive Bayesian spam filtering
@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
@table @code
@item gnus-home-directory
-All Gnus path variables will be initialized from this variable, which
-defaults to @file{~/}.
+All Gnus file and directory variables will be initialized from this
+variable, which defaults to @file{~/}.
@item gnus-directory
@vindex gnus-directory
-Most Gnus storage path variables will be initialized from this variable,
-which defaults to the @samp{SAVEDIR} environment variable, or
-@file{~/News/} if that variable isn't set.
+Most Gnus storage file and directory variables will be initialized from
+this variable, which defaults to the @samp{SAVEDIR} environment
+variable, or @file{~/News/} if that variable isn't set.
Note that Gnus is mostly loaded when the @file{.gnus.el} file is read.
This means that other directory variables that are initialized from this
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.
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.
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
projects / gnus / blobdiff