HOWTO for setting up a new or changing an existing KMail antispam wizard

configuration entry. This should clear up things for people you want to
"mess" with that file ;-). Back-ported from KDE 4 trunk (rev 685323).

svn path=/branches/KDE/3.5/kdepim/; revision=685331

kmail.antispamrc-HOWTO

@@ -0,0 +1,154 @@
+
+HOWTO for setting up a KMail antispam wizard configuration entry
+================================================================
+
+This is a HOWTO for setting up a KMail antispam wizard configuration
+entry. Since this possibly is more developer related, I put this as
+text file into the source SVN. Possibly some of this should go to the
+user documentation.
+
+I gathered the information from several mails and comments by Andreas
+Gungl, the original developer of the antispam wizard for KMail, and
+Ingo Kloecker.
+
+When you have questions do not hesitate to ask me, Martin Steigerwald, 
+Andreas or Ingo.
+
+
+Basics
+------
+
+The configuration file for the KMail antispam wizard "kmail.antispamrc"
+consists of one entry for each spamfilter that the antispam wizard
+shall support.
+
+At the beginning of the file in the section "General" the option "tools" 
+specifies the count of configured spam filters. Increase that by one 
+when you add a new entry:
+
+[General]
+tools=11
+
+
+A spam filter configuration entry starts with a header like this:
+
+[Spamtool #11]
+
+
+After this you place all the options for the spam filter. Please use
+an ordering that is similar to the other entries in the configuration
+file so that things are unified a bit.
+
+
+General options
+---------------
+
+- Ident: Specifies the internal identifier for the entry
+
+- Version: Specifies the version of the entry (FIXME what is this for?)
+
+- Priority: Specifies the priority of the filter. This value is used to
+  place faster filters before the slower ones in the selection list. If the
+  user chooses the top item, he gets the fastest filter. Provider sided
+  "filters" (which produce headers tough) like the GMX filter have a prio
+  at about 70, they are very fast as they don't consume time on the client
+  side. Since CRM114 is almost as fast it gets 65 ;-).
+
+- VisibleName: This is the name that is presented to the user
+
+Or:
+
+- HeadersOnly=yes: This is used for entries where KMail should just parse
+  the mail headers for the spam score display (see Razor filter and below
+  for spam score display details).
+
+
+Spam filter options
+-------------------
+
+These specify details about the spamfilter.
+
+- Executable: Specifies a test whether the executable of the spamfilter
+  can be started. You should provide something which can be run on the
+  command line and returns [ $? -eq 0 ], i.e. it doesn't wait for any input 
+  etc. It usually make sense to assume the program in the $PATH, so you
+  should better avoid /usr/bin. Set executable to "echo" for provider based 
+  filters.
+  Example: Executable=crm -v | grep "CRM114"
+
+- URL: URL to the homepage of the filter
+
+- PipeFilterName: Name of the pipe-through filter used to send mails to the
+  spamfilter and get them back with added spam filter headers.
+
+- PipeCmdDetect: Command used to pipe the mail into.
+
+- ExecCmdSpam: Command used to mark a mail as spam.
+
+- ExecCmdHam: Command used to mark a mail as ham.
+
+- SupportsBayes: Set to 1 if you have a spam filter that can learn. Only
+  in this case KMail uses ExecCmdSpam and ExecCmdHam to let the user mark
+  mail as ham or spam.
+
+
+Spam detection options
+----------------------
+
+These specify how KMail shall detect whether a mail is spam, unsure or good.
+
+- DetectionHeader: The name of the header where the spam filter puts the spam
+  status of a mail into.
+
+- DetectionPattern: The pattern the spam filter uses for marking a mail as
+  spam.
+
+- DetectionPattern2: The pattern the spam filter uses for marking a mail as
+  unsure. Set "SupportsUnsure=1" when you use this.
+
+- DetectionOnly: Don't pipe mails through the spam filter, but just use headers
+  from outside, e.g. a provider based spam filter (See GMX).
+
+- UseRegExp: Set to 1 if you need to use regular expressions in the detection
+  patterns. KMail can operate faster when they are not required.
+
+- SupportsUnsure: Set to 1 if you have a spam filter that supports
+  classying mails as unsure to tell the user to train those.
+
+
+Spam score display
+------------------
+
+Those regular expressions are used to extract the actual "spamicity" 
+score and the threshold (i.e. the upper bound for non-spam) from 
+SpamAssassin's ScoreHeader. The score and the threshold are then used 
+for showing the spam status in the message header, i.e. the small 
+colorbar.
+
+You need to specify the following values:
+
+- ScoreName: The name that will be shown in the message header.
+
+- ScoreHeader: The message header containing the score value.
+
+- ScoreType: The type of the score, cf. below.
+
+- ScoreValueRegexp: A regular expression for extracting the score from 
+  the ScoreHeader.
+
+- ScoreThresholdRegexp: A regular expression for extracting the threshold 
+  from the ScoreHeader; only needed for Adjusted type. Please set to 
+  nothing (ScoreThresholdRegexp=) if not needed.
+
+
+KMail supports the following ScoreType values:
+
+- Bool: Simple Yes or No (Razor)
+
+- Decimal: For probability between 0.0 and 1.0 (BogoFilter)
+
+- Percentage: For straight percentages between 0.0 and 100.0
+
+- Adjusted: Use this when we need to compare against a threshold
+  (SpamAssasssin)
+