Some more bogofilter information

Some more bogofilter information

[Russ Allbery]

I haven't had time to turn this into a patch to the manual, and I'm not
sure if I will have time, but I just finished setting up bogofilter and
wrote up some of the things that I found confusing as well as some random
notes on the process.

(One of the things that I found confusing was that the documentation
really did not explain how to set the relevant variables by hand if one
didn't want to use group properties or customize.  I appreciate that lots
of people like the newfangled customize way, but being a programmer, I
really like a programmatic API that I can write in Lisp.)

Anyway, here are the notes:

    <http://journals.eyrie.org/eagle/archives/000052.html>

I'll be happy to answer any questions about what I mean.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>

spam.el configurations needed (also: Some more bogofilter information)

[Ted Zlatanov]

On Tue, 10 Jun 2003, rra@stanford.edu wrote:
> I haven't had time to turn this into a patch to the manual, and I'm
> not sure if I will have time, but I just finished setting up
> bogofilter and wrote up some of the things that I found confusing as
> well as some random notes on the process.

I would certainly appreciate your patch to the manual.  I don't have
too much free time either, unfortunately.

If anyone feels like it, a reorganization of the spam.el docs in the
manual would be very useful.  I wrote it in an organic fashion,
without a plan, and as a programmer I'm not a good documentation
writer for my own code :)

> (One of the things that I found confusing was that the documentation
> really did not explain how to set the relevant variables by hand if
> one didn't want to use group properties or customize.  I appreciate
> that lots of people like the newfangled customize way, but being a
> programmer, I really like a programmatic API that I can write in
> Lisp.)

So you don't like that the *structure* of those variables is not
explained, or that *examples* of actual settings are not given?

For the first part, it's a lot of duplicate effort IMHO to explain
what is clearly available through the customize interface.  The
defcustom declarations describe the variable structure completely.
Also, comments in the examples would be better than a dry recounting
of internal variable structure, IMHO again.

For the second one, I agree that examples of settings would be very
useful.  

So please, spam.el users, send me your configurations and I'll try to
include them in the manual.  This seems to be the biggest stumbling
block for new users - starting a new configuration is pretty hard.

Russ, furthermore on your web page:
http://journals.eyrie.org/eagle/archives/000052.html

RA: "gnus-spam-process-newsgroups takes a list of pairs of similar
regexes matched to lists of processing functions, which is different
than what the documentation says. "

In the manual I just have:

@vindex gnus-spam-process-newsgroups
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.

I'm not sure where the documentation gives wrong info as you say, can
you please clarify?

RA: "Another point that's very unclear from the documentation that I
found out through a lot of fiddling is that you need to add both the
spam and ham bogofilter processors to the list of processors for each
of your ham groups. Otherwise, the spam that you mark never actually
gets registered with bogofilter."

The manual says:

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{$},
and nothing else.

I thought that was clear, but being the programmer and familiar with
the software, I'm not a good documentation writer.  I assume everyone
knows what I mean :)  Can you suggest a rewording?

Also I think the bit about avoiding auto-expire for newsgroups is very
useful, can you suggest a spot in the docs it should go?

Thanks
Ted