Show
Ignore:
Timestamp:
05/03/06 18:37:43 (3 years ago)
Author:
miyoshi
Message:

Sync up with Emacs CVS HEAD.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk

    • Property svn:ignore changed from
      bin
       to
      bin
      site-lisp

  • trunk/man/gnus.texi

    r4058 r4073  
    800800* Image Enhancements::          Modern versions of Emacs/XEmacs can display images. 
    801801* Fuzzy Matching::              What's the big fuzz? 
    802 * Thwarting Email Spam::        A how-to on avoiding unsolicited commercial email. 
     802* Thwarting Email Spam::        Simple ways to avoid unsolicited commercial email. 
     803* Spam Package::                A package for filtering and processing spam. 
    803804* Other modes::                 Interaction with other modes. 
    804805* Various Various::             Things that are really various. 
    …… 
    819820* X-Face::                      Display a funky, teensy black-and-white image. 
    820821* Face::                        Display a funkier, teensier colored image. 
    821 * Smileys::                     Show all those happy faces the way they were meant to be shown. 
     822* Smileys::                     Show all those happy faces the way they were 
     823                                  meant to be shown. 
    822824* Picons::                      How to display pictures of what you're reading. 
    823825* XVarious::                    Other XEmacsy Gnusey variables. 
    …… 
    829831* SpamAssassin::                How to use external anti-spam tools. 
    830832* Hashcash::                    Reduce spam by burning CPU time. 
    831 * Filtering Spam Using The Spam ELisp Package:: 
    832 * Filtering Spam Using Statistics with spam-stat:: 
    833  
    834 Filtering Spam Using The Spam ELisp Package 
    835  
    836 * Spam ELisp Package Sequence of Events:: 
    837 * Spam ELisp Package Filtering of Incoming Mail:: 
    838 * Spam ELisp Package Global Variables:: 
    839 * Spam ELisp Package Configuration Examples:: 
    840 * Blacklists and Whitelists:: 
    841 * BBDB Whitelists:: 
    842 * Gmane Spam Reporting:: 
    843 * Anti-spam Hashcash Payments:: 
    844 * Blackholes:: 
    845 * Regular Expressions Header Matching:: 
    846 * Bogofilter:: 
    847 * ifile spam filtering:: 
    848 * spam-stat spam filtering:: 
    849 * SpamOracle:: 
    850 * Extending the Spam ELisp package:: 
    851  
    852 Filtering Spam Using Statistics with spam-stat 
     833 
     834Spam Package 
     835 
     836* Spam Package Introduction:: 
     837* Filtering Incoming Mail:: 
     838* Detecting Spam in Groups:: 
     839* Spam and Ham Processors:: 
     840* Spam Package Configuration Examples:: 
     841* Spam Back Ends:: 
     842* Extending the Spam package:: 
     843* Spam Statistics Package:: 
     844 
     845Spam Statistics Package 
    853846 
    854847* Creating a spam-stat dictionary:: 
    …… 
    2079820791* Image Enhancements::          Modern versions of Emacs/XEmacs can display images. 
    2079920792* Fuzzy Matching::              What's the big fuzz? 
    20800 * Thwarting Email Spam::        A how-to on avoiding unsolicited commercial email. 
     20793* Thwarting Email Spam::        Simple ways to avoid unsolicited commercial email. 
     20794* Spam Package::                A package for filtering and processing spam. 
    2080120795* Other modes::                 Interaction with other modes. 
    2080220796* Various Various::             Things that are really various. 
    …… 
    2248022474* SpamAssassin::                How to use external anti-spam tools. 
    2248122475* Hashcash::                    Reduce spam by burning CPU time. 
    22482 * Filtering Spam Using The Spam ELisp Package:: 
    22483 * Filtering Spam Using Statistics with spam-stat:: 
    2248422476@end menu 
    2248522477 
    …… 
    2279722789a useful contribution, however. 
    2279822790 
    22799 @node Filtering Spam Using The Spam ELisp Package 
    22800 @subsection Filtering Spam Using The Spam ELisp Package 
     22791@node Spam Package 
     22792@section Spam Package 
    2280122793@cindex spam filtering 
    2280222794@cindex spam 
    2280322795 
    22804 The idea behind @file{spam.el} is to have a control center for spam detection 
    22805 and filtering in Gnus.  To that end, @file{spam.el} does two things: it 
    22806 filters new mail, and it analyzes mail known to be spam or ham. 
    22807 @dfn{Ham} is the name used throughout @file{spam.el} to indicate 
    22808 non-spam messages. 
     22796The Spam package provides Gnus with a centralized mechanism for 
     22797detecting and filtering spam.  It filters new mail, and processes 
     22798messages according to whether they are spam or ham.  (@dfn{Ham} is the 
     22799name used throughout this manual to indicate non-spam messages.) 
     22800 
     22801@menu 
     22802* Spam Package Introduction:: 
     22803* Filtering Incoming Mail:: 
     22804* Detecting Spam in Groups:: 
     22805* Spam and Ham Processors:: 
     22806* Spam Package Configuration Examples:: 
     22807* Spam Back Ends:: 
     22808* Extending the Spam package:: 
     22809* Spam Statistics Package:: 
     22810@end menu 
     22811 
     22812@node Spam Package Introduction 
     22813@subsection Spam Package Introduction 
     22814@cindex spam filtering 
     22815@cindex spam filtering sequence of events 
     22816@cindex spam 
     22817 
     22818You must read this section to understand how the Spam package works. 
     22819Do not skip, speed-read, or glance through this section. 
    2280922820 
    2281022821@cindex spam-initialize 
    22811 First of all, you @strong{must} run the function 
    22812 @code{spam-initialize} to autoload @code{spam.el} and to install the 
    22813 @code{spam.el} hooks.  There is one exception: if you use the 
    22814 @code{spam-use-stat} (@pxref{spam-stat spam filtering}) setting, you 
    22815 should turn it on before @code{spam-initialize}: 
     22822@vindex spam-use-stat 
     22823To use the Spam package, you @strong{must} first run the function 
     22824@code{spam-initialize}: 
    2281622825 
    2281722826@example 
    22818 (setq spam-use-stat t) ;; if needed 
    2281922827(spam-initialize) 
    2282022828@end example 
    2282122829 
    22822 So, what happens when you load @file{spam.el}? 
    22823  
    22824 First, some hooks will get installed by @code{spam-initialize}.  There 
    22825 are some hooks for @code{spam-stat} so it can save its databases, and 
    22826 there are hooks so interesting things will happen when you enter and 
    22827 leave a group.  More on the sequence of events later (@pxref{Spam 
    22828 ELisp Package Sequence of Events}). 
    22829  
    22830 You get the following keyboard commands: 
     22830This autoloads @code{spam.el} and installs the various hooks necessary 
     22831to let the Spam package do its job.  In order to make use of the Spam 
     22832package, you have to set up certain group parameters and variables, 
     22833which we will describe below.  All of the variables controlling the 
     22834Spam package can be found in the @samp{spam} customization group. 
     22835 
     22836There are two ``contact points'' between the Spam package and the rest 
     22837of Gnus: checking new mail for spam, and leaving a group. 
     22838 
     22839Checking new mail for spam is done in one of two ways: while splitting 
     22840incoming mail, or when you enter a group. 
     22841 
     22842The first way, checking for spam while splitting incoming mail, is 
     22843suited to mail back ends such as @code{nnml} or @code{nnimap}, where 
     22844new mail appears in a single spool file.  The Spam package processes 
     22845incoming mail, and sends mail considered to be spam to a designated 
     22846``spam'' group.  @xref{Filtering Incoming Mail}. 
     22847 
     22848The second way is suited to back ends such as @code{nntp}, which have 
     22849no incoming mail spool, or back ends where the server is in charge of 
     22850splitting incoming mail.  In this case, when you enter a Gnus group, 
     22851the unseen or unread messages in that group are checked for spam. 
     22852Detected spam messages are marked as spam.  @xref{Detecting Spam in 
     22853Groups}. 
     22854 
     22855@cindex spam back ends 
     22856In either case, you have to tell the Spam package what method to use 
     22857to detect spam messages.  There are several methods, or @dfn{spam back 
     22858ends} (not to be confused with Gnus back ends!) to choose from: spam 
     22859``blacklists'' and ``whitelists'', dictionary-based filters, and so 
     22860forth.  @xref{Spam Back Ends}. 
     22861 
     22862In the Gnus summary buffer, messages that have been identified as spam 
     22863always appear with a @samp{$} symbol. 
     22864 
     22865The Spam package divides Gnus groups into three categories: ham 
     22866groups, spam groups, and unclassified groups.  You should mark each of 
     22867the groups you subscribe to as either a ham group or a spam group, 
     22868using the @code{spam-contents} group parameter (@pxref{Group 
     22869Parameters}).  Spam groups have a special property: when you enter a 
     22870spam group, all unseen articles are marked as spam.  Thus, mail split 
     22871into a spam group is automatically marked as spam. 
     22872 
     22873Identifying spam messages is only half of the Spam package's job.  The 
     22874second half comes into play whenever you exit a group buffer.  At this 
     22875point, the Spam package does several things: 
     22876 
     22877First, it calls @dfn{spam and ham processors} to process the articles 
     22878according to whether they are spam or ham.  There is a pair of spam 
     22879and ham processors associated with each spam back end, and what the 
     22880processors do depends on the back end.  At present, the main role of 
     22881spam and ham processors is for dictionary-based spam filters: they add 
     22882the contents of the messages in the group to the filter's dictionary, 
     22883to improve its ability to detect future spam.  The @code{spam-process} 
     22884group parameter specifies what spam processors to use.  @xref{Spam and 
     22885Ham Processors}. 
     22886 
     22887If the spam filter failed to mark a spam message, you can mark it 
     22888yourself, so that the message is processed as spam when you exit the 
     22889group: 
    2283122890 
    2283222891@table @kbd 
    22833  
    2283422892@item M-d 
    2283522893@itemx M s x 
    …… 
    2283922897@kindex M s x 
    2284022898@findex gnus-summary-mark-as-spam 
    22841 @code{gnus-summary-mark-as-spam}. 
    22842  
    22843 Mark current article as spam, showing it with the @samp{$} mark. 
    22844 Whenever you see a spam article, make sure to mark its summary line 
    22845 with @kbd{M-d} before leaving the group.  This is done automatically 
    22846 for unread articles in @emph{spam} groups. 
    22847  
    22848 @item M s t 
    22849 @itemx S t 
    22850 @kindex M s t 
    22851 @kindex S t 
    22852 @findex spam-bogofilter-score 
    22853 @code{spam-bogofilter-score}. 
    22854  
    22855 You must have Bogofilter installed for that command to work properly. 
    22856  
    22857 @xref{Bogofilter}. 
    22858  
     22899@findex gnus-summary-mark-as-spam 
     22900Mark current article as spam, showing it with the @samp{$} mark 
     22901(@code{gnus-summary-mark-as-spam}). 
    2285922902@end table 
    2286022903 
    22861 Also, when you load @file{spam.el}, you will be able to customize its 
    22862 variables.  Try @code{customize-group} on the @samp{spam} variable 
    22863 group. 
    22864  
    22865 @menu 
    22866 * Spam ELisp Package Sequence of Events:: 
    22867 * Spam ELisp Package Filtering of Incoming Mail:: 
    22868 * Spam ELisp Package Global Variables:: 
    22869 * Spam ELisp Package Configuration Examples:: 
    22870 * Blacklists and Whitelists:: 
    22871 * BBDB Whitelists:: 
    22872 * Gmane Spam Reporting:: 
    22873 * Anti-spam Hashcash Payments:: 
    22874 * Blackholes:: 
    22875 * Regular Expressions Header Matching:: 
    22876 * Bogofilter:: 
    22877 * ifile spam filtering:: 
    22878 * spam-stat spam filtering:: 
    22879 * SpamOracle:: 
    22880 * Extending the Spam ELisp package:: 
    22881 @end menu 
    22882  
    22883 @node Spam ELisp Package Sequence of Events 
    22884 @subsubsection Spam ELisp Package Sequence of Events 
    22885 @cindex spam filtering 
    22886 @cindex spam filtering sequence of events 
    22887 @cindex spam 
    22888  
    22889 You must read this section to understand how @code{spam.el} works. 
    22890 Do not skip, speed-read, or glance through this section. 
    22891  
    22892 There are two @emph{contact points}, if you will, between 
    22893 @code{spam.el} and the rest of Gnus: checking new mail for spam, and 
    22894 leaving a group. 
    22895  
    22896 Getting new mail is done in one of two ways.  You can either split 
    22897 your incoming mail or you can classify new articles as ham or spam 
    22898 when you enter the group. 
    22899  
    22900 Splitting incoming mail is better suited to mail backends such as 
    22901 @code{nnml} or @code{nnimap} where new mail appears in a single file 
    22902 called a @dfn{Spool File}.  See @xref{Spam ELisp Package Filtering of 
    22903 Incoming Mail}. 
    22904  
    22905 For backends such as @code{nntp} there is no incoming mail spool, so 
    22906 an alternate mechanism must be used.  This may also happen for 
    22907 backends where the server is in charge of splitting incoming mail, and 
    22908 Gnus does not do further splitting.  The @code{spam-autodetect} and 
    22909 @code{spam-autodetect-methods} group parameters (accessible with 
    22910 @kbd{G c} and @kbd{G p} as usual), and the corresponding variables 
    22911 @code{gnus-spam-autodetect-methods} and 
    22912 @code{gnus-spam-autodetect-methods} (accessible with @kbd{M-x 
    22913 customize-variable} as usual). 
    22914  
    22915 When @code{spam-autodetect} is used, it hooks into the process of 
    22916 entering a group.  Thus, entering a group with unseen or unread 
    22917 articles becomes the substitute for checking incoming mail.  Whether 
    22918 only unseen articles or all unread articles will be processed is 
    22919 determined by the @code{spam-autodetect-recheck-messages}.  When set 
    22920 to @code{t}, unread messages will be rechecked. 
    22921  
    22922 @code{spam-autodetect} grants the user at once more and less control 
    22923 of spam filtering.  The user will have more control over each group's 
    22924 spam methods, so for instance the @samp{ding} group may have 
    22925 @code{spam-use-BBDB} as the autodetection method, while the 
    22926 @samp{suspect} group may have the @code{spam-use-blacklist} and 
    22927 @code{spam-use-bogofilter} methods enabled.  Every article detected to 
    22928 be spam will be marked with the spam mark @samp{$} and processed on 
    22929 exit from the group as normal spam.  The user has less control over 
    22930 the @emph{sequence} of checks, as he might with @code{spam-split}. 
    22931  
    22932 When the newly split mail goes into groups, or messages are 
    22933 autodetected to be ham or spam, those groups must be exited (after 
    22934 entering, if needed) for further spam processing to happen.  It 
    22935 matters whether the group is considered a ham group, a spam group, or 
    22936 is unclassified, based on its @code{spam-content} parameter 
    22937 (@pxref{Spam ELisp Package Global Variables}).  Spam groups have the 
    22938 additional characteristic that, when entered, any unseen or unread 
    22939 articles (depending on the @code{spam-mark-only-unseen-as-spam} 
    22940 variable) will be marked as spam.  Thus, mail split into a spam group 
    22941 gets automatically marked as spam when you enter the group. 
    22942  
    22943 So, when you exit a group, the @code{spam-processors} are applied, if 
    22944 any are set, and the processed mail is moved to the 
    22945 @code{ham-process-destination} or the @code{spam-process-destination} 
    22946 depending on the article's classification.  If the 
    22947 @code{ham-process-destination} or the @code{spam-process-destination}, 
    22948 whichever is appropriate, are @code{nil}, the article is left in the 
    22949 current group. 
    22950  
    22951 If a spam is found in any group (this can be changed to only non-spam 
    22952 groups with @code{spam-move-spam-nonspam-groups-only}), it is 
    22953 processed by the active @code{spam-processors} (@pxref{Spam ELisp 
    22954 Package Global Variables}) when the group is exited.  Furthermore, the 
    22955 spam is moved to the @code{spam-process-destination} (@pxref{Spam 
    22956 ELisp Package Global Variables}) for further training or deletion. 
    22957 You have to load the @code{gnus-registry.el} package and enable the 
    22958 @code{spam-log-to-registry} variable if you want spam to be processed 
    22959 no more than once.  Thus, spam is detected and processed everywhere, 
    22960 which is what most people want.  If the 
    22961 @code{spam-process-destination} is @code{nil}, the spam is marked as 
     22904@noindent 
     22905Similarly, you can unmark an article if it has been erroneously marked 
     22906as spam.  @xref{Setting Marks}. 
     22907 
     22908Normally, a ham message found in a non-ham group is not processed as 
     22909ham---the rationale is that it should be moved into a ham group for 
     22910further processing (see below).  However, you can force these articles 
     22911to be processed as ham by setting 
     22912@code{spam-process-ham-in-spam-groups} and 
     22913@code{spam-process-ham-in-nonham-groups}. 
     22914 
     22915@vindex gnus-ham-process-destinations 
     22916@vindex gnus-spam-process-destinations 
     22917The second thing that the Spam package does when you exit a group is 
     22918to move ham articles out of spam groups, and spam articles out of ham 
     22919groups.  Ham in a spam group is moved to the group specified by the 
     22920variable @code{gnus-ham-process-destinations}, or the group parameter 
     22921@code{ham-process-destination}.  Spam in a ham group is moved to the 
     22922group specified by the variable @code{gnus-spam-process-destinations}, 
     22923or the group parameter @code{spam-process-destination}.  If these 
     22924variables are not set, the articles are left in their current group. 
     22925If an article cannot not be moved (e.g., with a read-only backend such 
     22926as @acronym{NNTP}), it is copied. 
     22927 
     22928If an article is moved to another group, it is processed again when 
     22929you visit the new group.  Normally, this is not a problem, but if you 
     22930want each article to be processed only once, load the 
     22931@code{gnus-registry.el} package and set the variable 
     22932@code{spam-log-to-registry} to @code{t}.  @xref{Spam Package 
     22933Configuration Examples}. 
     22934 
     22935Normally, spam groups ignore @code{gnus-spam-process-destinations}. 
     22936However, if you set @code{spam-move-spam-nonspam-groups-only} to 
     22937@code{nil}, spam will also be moved out of spam groups, depending on 
     22938the @code{spam-process-destination} parameter. 
     22939 
     22940The final thing the Spam package does is to mark spam articles as 
    2296222941expired, which is usually the right thing to do. 
    22963  
    22964 If spam can not be moved---because of a read-only backend such as 
    22965 @acronym{NNTP}, for example, it will be copied. 
    22966  
    22967 If a ham mail is found in a ham group, as determined by the 
    22968 @code{ham-marks} parameter, it is processed as ham by the active ham 
    22969 @code{spam-processor} when the group is exited.  With the variables 
    22970 @code{spam-process-ham-in-spam-groups} and 
    22971 @code{spam-process-ham-in-nonham-groups} the behavior can be further 
    22972 altered so ham found anywhere can be processed.  You have to load the 
    22973 @code{gnus-registry.el} package and enable the 
    22974 @code{spam-log-to-registry} variable if you want ham to be processed 
    22975 no more than once.  Thus, ham is detected and processed only when 
    22976 necessary, which is what most people want.  More on this in 
    22977 @xref{Spam ELisp Package Configuration Examples}. 
    22978  
    22979 If ham can not be moved---because of a read-only backend such as 
    22980 @acronym{NNTP}, for example, it will be copied. 
    2298122942 
    2298222943If all this seems confusing, don't worry.  Soon it will be as natural 
    …… 
    229842294550 years in the future yet.  Just trust us, it's not so bad. 
    2298522946 
    22986 @node Spam ELisp Package Filtering of Incoming Mail 
    22987 @subsubsection Spam ELisp Package Filtering of Incoming Mail 
     22947@node Filtering Incoming Mail 
     22948@subsection Filtering Incoming Mail 
    2298822949@cindex spam filtering 
    2298922950@cindex spam filtering incoming mail 
    2299022951@cindex spam 
    2299122952 
    22992 To use the @file{spam.el} facilities for incoming mail filtering, you 
    22993 must add the following to your fancy split list 
    22994 @code{nnmail-split-fancy} or @code{nnimap-split-fancy}: 
     22953To use the Spam package to filter incoming mail, you must first set up 
     22954fancy mail splitting.  @xref{Fancy Mail Splitting}.  The Spam package 
     22955defines a special splitting function that you can add to your fancy 
     22956split variable (either @code{nnmail-split-fancy} or 
     22957@code{nnimap-split-fancy}, depending on your mail back end): 
    2299522958 
    2299622959@example 
    …… 
    2299822961@end example 
    2299922962 
    23000 Note that the fancy split may be called @code{nnmail-split-fancy} or 
    23001 @code{nnimap-split-fancy}, depending on whether you use the nnmail or 
    23002 nnimap back ends to retrieve your mail. 
    23003  
    23004 Also, @code{spam-split} will not modify incoming mail in any way. 
    23005  
    23006 The @code{spam-split} function will process incoming mail and send the 
    23007 mail considered to be spam into the group name given by the variable 
    23008 @code{spam-split-group}.  By default that group name is @samp{spam}, 
    23009 but you can customize @code{spam-split-group}.  Make sure the contents 
    23010 of @code{spam-split-group} are an @emph{unqualified} group name, for 
    23011 instance in an @code{nnimap} server @samp{your-server} the value 
    23012 @samp{spam} will turn out to be @samp{nnimap+your-server:spam}.  The 
    23013 value @samp{nnimap+server:spam}, therefore, is wrong and will 
    23014 actually give you the group 
    23015 @samp{nnimap+your-server:nnimap+server:spam} which may or may not 
    23016 work depending on your server's tolerance for strange group names. 
    23017  
    23018 You can also give @code{spam-split} a parameter, 
    23019 e.g. @code{spam-use-regex-headers} or @code{"maybe-spam"}.  Why is 
    23020 this useful? 
    23021  
    23022 Take these split rules (with @code{spam-use-regex-headers} and 
    23023 @code{spam-use-blackholes} set): 
     22963@vindex spam-split-group 
     22964@noindent 
     22965The @code{spam-split} function scans incoming mail according to your 
     22966chosen spam back end(s), and sends messages identified as spam to a 
     22967spam group.  By default, the spam group is a group named @samp{spam}, 
     22968but you can change this by customizing @code{spam-split-group}.  Make 
     22969sure the contents of @code{spam-split-group} are an unqualified group 
     22970name.  For instance, in an @code{nnimap} server @samp{your-server}, 
     22971the value @samp{spam} means @samp{nnimap+your-server:spam}.  The value 
     22972@samp{nnimap+server:spam} is therefore wrong---it gives the group 
     22973@samp{nnimap+your-server:nnimap+server:spam}. 
     22974 
     22975@code{spam-split} does not modify the contents of messages in any way. 
     22976 
     22977@vindex nnimap-split-download-body 
     22978Note for IMAP users: if you use the @code{spam-check-bogofilter}, 
     22979@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends, 
     22980you should also set set the variable @code{nnimap-split-download-body} 
     22981to @code{t}.  These spam back ends are most useful when they can 
     22982``scan'' the full message body.  By default, the nnimap back end only 
     22983retrieves the message headers; @code{nnimap-split-download-body} tells 
     22984it to retrieve the message bodies as well.  We don't set this by 
     22985default because it will slow @acronym{IMAP} down, and that is not an 
     22986appropriate decision to make on behalf of the user.  @xref{Splitting 
     22987in IMAP}. 
     22988 
     22989You have to specify one or more spam back ends for @code{spam-split} 
     22990to use, by setting the @code{spam-use-*} variables.  @xref{Spam Back 
     22991Ends}.  Normally, @code{spam-split} simply uses all the spam back ends 
     22992you enabled in this way.  However, you can tell @code{spam-split} to 
     22993use only some of them.  Why this is useful?  Suppose you are using the 
     22994@code{spam-use-regex-headers} and @code{spam-use-blackholes} spam back 
     22995ends, and the following split rule: 
    2302422996 
    2302522997@example 
    …… 
    2303123003@end example 
    2303223004 
    23033 Now, the problem is that you want all ding messages to make it to the 
    23034 ding folder.  But that will let obvious spam (for example, spam 
    23035 detected by SpamAssassin, and @code{spam-use-regex-headers}) through, 
    23036 when it's sent to the ding list.  On the other hand, some messages to 
    23037 the ding list are from a mail server in the blackhole list, so the 
    23038 invocation of @code{spam-split} can't be before the ding rule. 
    23039  
    23040 You can let SpamAssassin headers supersede ding rules, but all other 
    23041 @code{spam-split} rules (including a second invocation of the 
    23042 regex-headers check) will be after the ding rule: 
     23005@noindent 
     23006The problem is that you want all ding messages to make it to the ding 
     23007folder.  But that will let obvious spam (for example, spam detected by 
     23008SpamAssassin, and @code{spam-use-regex-headers}) through, when it's 
     23009sent to the ding list.  On the other hand, some messages to the ding 
     23010list are from a mail server in the blackhole list, so the invocation 
     23011of @code{spam-split} can't be before the ding rule. 
     23012 
     23013The solution is to let SpamAssassin headers supersede ding rules, and 
     23014perform the other @code{spam-split} rules (including a second 
     23015invocation of the regex-headers check) after the ding rule.  This is 
     23016done by passing a parameter to @code{spam-split}: 
    2304323017 
    2304423018@example 
    2304523019nnimap-split-fancy 
    2304623020      '(| 
    23047         ;; @r{all spam detected by @code{spam-use-regex-headers} goes to @samp{regex-spam}} 
     23021        ;; @r{spam detected by @code{spam-use-regex-headers} goes to @samp{regex-spam}} 
    2304823022        (: spam-split "regex-spam" 'spam-use-regex-headers) 
    2304923023        (any "ding" "ding") 
    …… 
    2305423028@end example 
    2305523029 
     23030@noindent 
    2305623031This lets you invoke specific @code{spam-split} checks depending on 
    23057 your particular needs, and to target the results of those checks to a 
     23032your particular needs, and target the results of those checks to a 
    2305823033particular spam group.  You don't have to throw all mail into all the 
    2305923034spam tests.  Another reason why this is nice is that messages to 
    …… 
    2306223037spam checks for your nnmail split vs. your nnimap split.  Go crazy. 
    2306323038 
    23064 You should still have specific checks such as 
    23065 @code{spam-use-regex-headers} set to @code{t}, even if you 
    23066 specifically invoke @code{spam-split} with the check.  The reason is 
    23067 that when loading @file{spam.el}, some conditional loading is done 
    23068 depending on what @code{spam-use-xyz} variables you have set.  This 
    23069 is usually not critical, though. 
    23070  
    23071 @emph{Note for IMAP users} 
    23072  
    23073 The boolean variable @code{nnimap-split-download-body} needs to be 
    23074 set, if you want to split based on the whole message instead of just 
    23075 the headers.  By default, the nnimap back end will only retrieve the 
    23076 message headers.  If you use @code{spam-check-bogofilter}, 
    23077 @code{spam-check-ifile}, or @code{spam-check-stat} (the splitters that 
    23078 can benefit from the full message body), you should set this variable. 
    23079 It is not set by default because it will slow @acronym{IMAP} down, and 
    23080 that is not an appropriate decision to make on behalf of the user. 
    23081  
    23082 @xref{Splitting in IMAP}. 
    23083  
    23084 @emph{TODO: spam.el needs to provide a uniform way of training all the 
    23085 statistical databases.  Some have that functionality built-in, others 
    23086 don't.} 
    23087  
    23088 @node Spam ELisp Package Global Variables 
    23089 @subsubsection Spam ELisp Package Global Variables 
     23039You should set the @code{spam-use-*} variables for whatever spam back 
     23040ends you intend to use.  The reason is that when loading 
     23041@file{spam.el}, some conditional loading is done depending on what 
     23042@code{spam-use-xyz} variables you have set.  @xref{Spam Back Ends}. 
     23043 
     23044@c @emph{TODO: spam.el needs to provide a uniform way of training all the 
     23045@c statistical databases.  Some have that functionality built-in, others 
     23046@c don't.} 
     23047 
     23048@node Detecting Spam in Groups 
     23049@subsection Detecting Spam in Groups 
     23050 
     23051To detect spam when visiting a group, set the group's 
     23052@code{spam-autodetect} and @code{spam-autodetect-methods} group 
     23053parameters.  These are accessible with @kbd{G c} or @kbd{G p}, as 
     23054usual (@pxref{Group Parameters}). 
     23055 
     23056You should set the @code{spam-use-*} variables for whatever spam back 
     23057ends you intend to use.  The reason is that when loading 
     23058@file{spam.el}, some conditional loading is done depending on what 
     23059@code{spam-use-xyz} variables you have set. 
     23060 
     23061By default, only unseen articles are processed for spam.  You can 
     23062force Gnus to recheck all messages in the group by setting the 
     23063variable @code{spam-autodetect-recheck-messages} to @code{t}. 
     23064 
     23065If you use the @code{spam-autodetect} method of checking for spam, you 
     23066can specify different spam detection methods for different groups. 
     23067For instance, the @samp{ding} group may have @code{spam-use-BBDB} as 
     23068the autodetection method, while the @samp{suspect} group may have the 
     23069@code{spam-use-blacklist} and @code{spam-use-bogofilter} methods 
     23070enabled.  Unlike with @code{spam-split}, you don't have any control 
     23071over the @emph{sequence} of checks, but this is probably unimportant. 
     23072 
     23073@node Spam and Ham Processors 
     23074@subsection Spam and Ham Processors 
    2309023075@cindex spam filtering 
    2309123076@cindex spam filtering variables 
    …… 
    2309423079 
    2309523080@vindex gnus-spam-process-newsgroups 
    23096 The concepts of ham processors and spam processors are very important. 
    23097 Ham processors and spam processors for a group can be set with the 
    23098 @code{spam-process} group parameter, or the 
    23099 @code{gnus-spam-process-newsgroups} variable.  Ham processors take 
    23100 mail known to be non-spam (@emph{ham}) and process it in some way so 
    23101 that later similar mail will also be considered non-spam.  Spam 
    23102 processors take mail known to be spam and process it so similar spam 
    23103 will be detected later. 
    23104  
    23105 The format of the spam or ham processor entry used to be a symbol, 
    23106 but now it is a @sc{cons} cell.  See the individual spam processor entries 
    23107 for more information. 
     23081Spam and ham processors specify special actions to take when you exit 
     23082a group buffer.  Spam processors act on spam messages, and ham 
     23083processors on ham messages.  At present, the main role of these 
     23084processors is to update the dictionaries of dictionary-based spam back 
     23085ends such as Bogofilter (@pxref{Bogofilter}) and the Spam Statistics 
     23086package (@pxref{Spam Statistics Filtering}). 
     23087 
     23088The spam and ham processors that apply to each group are determined by 
     23089the group's@code{spam-process} group parameter.  If this group 
     23090parameter is not defined, they are determined by the variable 
     23091@code{gnus-spam-process-newsgroups}. 
    2310823092 
    2310923093@vindex gnus-spam-newsgroup-contents 
    …… 
    2325923243spam.  It is recommended that you leave it off. 
    2326023244 
    23261 @node Spam ELisp Package Configuration Examples 
    23262 @subsubsection Spam ELisp Package Configuration Examples 
     23245@node Spam Package Configuration Examples 
     23246@subsection Spam Package Configuration Examples 
    2326323247@cindex spam filtering 
    2326423248@cindex spam filtering configuration examples 
    …… 
    2338523369Because of the @code{gnus-group-spam-classification-spam} entry, all 
    2338623370messages are marked as spam (with @code{$}).  When I find a false 
    23387 positive, I mark the message with some other ham mark (@code{ham-marks}, 
    23388 @ref{Spam ELisp Package Global Variables}).  On group exit, those 
    23389 messages are copied to both groups, @samp{INBOX} (where I want to have 
    23390 the article) and @samp{training.ham} (for training bogofilter) and 
    23391 deleted from the @samp{spam.detected} folder. 
     23371positive, I mark the message with some other ham mark 
     23372(@code{ham-marks}, @ref{Spam and Ham Processors}).  On group exit, 
     23373those messages are copied to both groups, @samp{INBOX} (where I want 
     23374to have the article) and @samp{training.ham} (for training bogofilter) 
     23375and deleted from the @samp{spam.detected} folder. 
    2339223376 
    2339323377The @code{gnus-article-sort-by-chars} entry simplifies detection of 
    …… 
    2342423408not the same as on news.gmane.org, thus @code{spam-report.el} has to check 
    2342523409the @code{X-Report-Spam} header to find the correct number. 
     23410 
     23411@node Spam Back Ends 
     23412@subsection Spam Back Ends 
     23413@cindex spam back ends 
     23414 
     23415The spam package offers a variety of back ends for detecting spam. 
     23416Each back end defines a set of methods for detecting spam 
     23417(@pxref{Filtering Incoming Mail}, @pxref{Detecting Spam in Groups}), 
     23418and a pair of spam and ham processors (@pxref{Spam and Ham 
     23419Processors}). 
     23420 
     23421@menu 
     23422* Blacklists and Whitelists:: 
     23423* BBDB Whitelists:: 
     23424* Gmane Spam Reporting:: 
     23425* Anti-spam Hashcash Payments:: 
     23426* Blackholes:: 
     23427* Regular Expressions Header Matching:: 
     23428* Bogofilter:: 
     23429* ifile spam filtering:: 
     23430* Spam Statistics Filtering:: 
     23431* SpamOracle:: 
     23432@end menu 
    2342623433 
    2342723434@node Blacklists and Whitelists 
    …… 
    2372923736@end defvar 
    2373023737 
     23738@table @kbd 
     23739@item M s t 
     23740@itemx S t 
     23741@kindex M s t 
     23742@kindex S t 
     23743@findex spam-bogofilter-score 
     23744Get the Bogofilter spamicity score (@code{spam-bogofilter-score}). 
     23745@end table 
     23746 
    2373123747@defvar spam-use-bogofilter-headers 
    2373223748 
    …… 
    2383023846functionality. 
    2383123847 
    23832 @node spam-stat spam filtering 
    23833 @subsubsection spam-stat spam filtering 
     23848@node Spam Statistics Filtering 
     23849@subsubsection Spam Statistics Filtering 
    2383423850@cindex spam filtering 
    2383523851@cindex spam-stat, spam filtering 
    …… 
    2383723853@cindex spam 
    2383823854 
    23839 @xref{Filtering Spam Using Statistics with spam-stat}. 
     23855This back end uses the Spam Statistics Emacs Lisp package to perform 
     23856statistics-based filtering (@pxref{Spam Statistics Package}).  Before 
     23857using this, you may want to perform some additional steps to 
     23858initialize your Spam Statistics dictionary.  @xref{Creating a 
     23859spam-stat dictionary}. 
    2384023860 
    2384123861@defvar spam-use-stat 
    23842  
    23843 Enable this variable if you want @code{spam-split} to use 
    23844 spam-stat.el, an Emacs Lisp statistical analyzer. 
    2384523862 
    2384623863@end defvar 
    …… 
    2390323920the advantage that the user can see the @emph{X-Spam} headers. 
    2390423921 
    23905 The easiest method is to make @file{spam.el} (@pxref{Filtering Spam 
    23906 Using The Spam ELisp Package}) call SpamOracle. 
     23922The easiest method is to make @file{spam.el} (@pxref{Spam Package}) 
     23923call SpamOracle. 
    2390723924 
    2390823925@vindex spam-use-spamoracle 
    2390923926To enable SpamOracle usage by @file{spam.el}, set the variable 
    2391023927@code{spam-use-spamoracle} to @code{t} and configure the 
    23911 @code{nnmail-split-fancy} or @code{nnimap-split-fancy} as described in 
    23912 the section @xref{Filtering Spam Using The Spam ELisp Package}.  In 
    23913 this example the @samp{INBOX} of an nnimap server is filtered using 
    23914 SpamOracle.  Mails recognized as spam mails will be moved to 
    23915 @code{spam-split-group}, @samp{Junk} in this case.  Ham messages stay 
    23916 in @samp{INBOX}: 
     23928@code{nnmail-split-fancy} or @code{nnimap-split-fancy}.  @xref{Spam 
     23929Package}.  In this example the @samp{INBOX} of an nnimap server is 
     23930filtered using SpamOracle.  Mails recognized as spam mails will be 
     23931moved to @code{spam-split-group}, @samp{Junk} in this case.  Ham 
     23932messages stay in @samp{INBOX}: 
    2391723933 
    2391823934@example 
    …… 
    2394623962SpamOracle employs a statistical algorithm to determine whether a 
    2394723963message is spam or ham.  In order to get good results, meaning few 
    23948 false hits or misses, SpamOracle needs training.  SpamOracle learns the 
    23949 characteristics of your spam mails.  Using the @emph{add} mode 
     23964false hits or misses, SpamOracle needs training.  SpamOracle learns 
     23965the characteristics of your spam mails.  Using the @emph{add} mode 
    2395023966(training mode) one has to feed good (ham) and spam mails to 
    23951 SpamOracle.  This can be done by pressing @kbd{|} in the Summary buffer 
    23952 and pipe the mail to a SpamOracle process or using @file{spam.el}'s 
    23953 spam- and ham-processors, which is much more convenient.  For a 
    23954 detailed description of spam- and ham-processors, @xref{Filtering Spam 
    23955 Using The Spam ELisp Package}. 
     23967SpamOracle.  This can be done by pressing @kbd{|} in the Summary 
     23968buffer and pipe the mail to a SpamOracle process or using 
     23969@file{spam.el}'s spam- and ham-processors, which is much more 
     23970convenient.  For a detailed description of spam- and ham-processors, 
     23971@xref{Spam Package}. 
    2395623972 
    2395723973@defvar gnus-group-spam-exit-processor-spamoracle 
    …… 
    2400224018SpamOracle as new samples for spam. 
    2400324019 
    24004 @node Extending the Spam ELisp package 
    24005 @subsubsection Extending the Spam ELisp package 
     24020@node Extending the Spam package 
     24021@subsection Extending the Spam package 
    2400624022@cindex spam filtering 
    2400724023@cindex spam elisp package, extending 
    …… 
    2411024126@end enumerate 
    2411124127 
    24112  
    24113 @node Filtering Spam Using Statistics with spam-stat 
    24114 @subsection Filtering Spam Using Statistics with spam-stat 
     24128@node Spam Statistics Package 
     24129@subsection Spam Statistics Package 
    2411524130@cindex Paul Graham 
    2411624131@cindex Graham, Paul 
    …… 
    2413924154than a certain threshold, the mail is considered to be spam. 
    2414024155 
    24141 Gnus supports this kind of filtering.  But it needs some setting up. 
     24156The Spam Statistics package adds support to Gnus for this kind of 
     24157filtering.  It can be used as one of the back ends of the Spam package 
     24158(@pxref{Spam Package}), or by itself. 
     24159 
     24160Before using the Spam Statistics package, you need to set it up. 
    2414224161First, you need two collections of your mail, one with spam, one with 
    2414324162non-spam.  Then you need to create a dictionary using these two 
    …… 
    2422524244@subsubsection Splitting mail using spam-stat 
    2422624245 
    24227 In order to use @code{spam-stat} to split your mail, you need to add the 
    24228 following to your @file{~/.gnus.el} file: 
     24246This section describes how to use the Spam statistics 
     24247@emph{independently} of the @xref{Spam Package}. 
     24248 
     24249First, add the following to your @file{~/.gnus.el} file: 
    2422924250 
    2423024251@lisp 
    …… 
    2487124892 
    2487224893@item 
    24873 Emacs 20.7 and up. 
    24874  
    24875 @item 
    24876 XEmacs 21.1 and up. 
     24894Emacs 21.1 and up. 
     24895 
     24896@item 
     24897XEmacs 21.4 and up. 
    2487724898 
    2487824899@end itemize 
    …… 
    2488024901This Gnus version will absolutely not work on any Emacsen older than 
    2488124902that.  Not reliably, at least.  Older versions of Gnus may work on older 
    24882 Emacs versions. 
     24903Emacs versions.  Particularly, Gnus 5.10.8 should also work on Emacs 
     2490420.7 and XEmacs 21.1. 
    2488324905 
    2488424906There are some vague differences between Gnus on the various