Re: Regarding spam.el

[Ted Zlatanov <tzz@lifelogs.com>]

On Tue, 09 Mar 2004, tvrud@bredband.net wrote:

> 1. Is gnus-group-*-exit-processor-bogofilter obsolete? If so, it
>    should be better marked as such in the info file. Same for all
>    similar obsolete variables.

Those variables are obsolete, but I'm keeping them until the next
major release of Gnus.  The ({spam|ham} spam-use-BACKEND) format will
replace the processor variables.  How should these deprecations be
marked, in bulk (a single note) or individually?  I'll add them.

> 2. In "Spam ELisp Package Sequence of Events": Second half of fifth
>        paragraph: The `spam-autodetect' and
>        `spam-autodetect-methods'... Yes, what about them? 

That's a good catch.  The sentence ran on for so long, I forgot it
was supposed to say something :)  Fixed.

> First half of the paragrapg is clear, then a bunch of parameters and
> varaibles comes out of the blue. 

Well yes, I have to introduce them at some point :)

> What are they used for? 

I think that's explained clearly.  Feel free to suggest alternate wording.

> What can they be set to?

That's what the customize interface is for.  I don't want to explain
every possible option - as you noticed, the information is very dense
already.

> The reader only gets confused. Either a reference to a info node or
> explaination text is needed.  The paragraph after explains it but
> not very clear. An example woul be very nice.

My setup in "Spam ELisp Package Configuration Examples" uses
spam-autodetect.  I welcome any other fixes to the docs - pointers,
more examples, rewordings.

> 
> 3. There are several group parameters and variables mentioned in the
>    info file and it is not always obvious which is which. A separate
>    page/node or at the end of one of the nodes with a list of all
>    variables and the corresponding parameters with examples would be
>    a good idea.

I'm not sure at all what you mean here.

> 4. How do I tell Gnus that nnfolder:Spam is my spam group and that
>    all other groups are ham? There a number of references to a
>    spam-contents variable/parameter but I got all confused trying to
>    figure out what to set it to. And where. Several parts of the
>    info nodes only lists what parameters and variables there are but
>    not what I set them to, what values that are valid.

Have you tried the customize interface to the
gnus-spam-newsgroup-contents variable?  You just need to set
nnfolder:Spam as 'spam, and AFTERWARDS in the list you need to set .*
as 'ham.

Using `G c' on a group/topic will show you all the spam-related
parameters.  Each one has a corresponding global variable, as defined
in gnus.el (but I don't know of a way to link the variable
customization to the parameter customization).

> 5. The following paragraph from "Spam ELisp Package Global
>    Variables" is typical for the entire documentation:
> 
>    "When you leave a _spam_ group, all spam-marked articles are
>    marked as expired after processing with the spam processor.  This
>    is not done for _unclassified_ or _ham_ groups.  Also, any *ham*
>    articles in a spam group will be moved to a location determined
>    by either the `ham-process-destination' group parameter or a
>    match in the `gnus-ham-process-destinations' variable, which is a
>    list of regular expressions matched with group names (it's
>    easiest to customize this variable with `customize-variable
>    gnus-ham-process-destinations').  Each newsgroup specification
>    has the format (REGEXP PROCESSOR) in a standard Lisp list, if you
>    prefer to customize the variable manually.  The ultimate location
>    is a group name or names.  If the `ham-process-destination'
>    parameter is not set, ham articles are left in place.  If the
>    `spam-mark-ham-unread-before-move-from-spam-group' parameter is
>    set, the ham articles are marked as unread before being moved."
> 
>    a. The author gets sidetracked by his own willingness to explain
>       and help the reader, e.g. the "(it's easiest to customize...)"
>       part. It is not uncommon that when the author explains what
>       something is, he then tells the reader how to set the
>       variable/parameter ("use M-x customize-..." or "...G c or G p
>       as usual"). These lengthy side notes cuts up the flow of the
>       text and starts to annoy the reader when he reads it for the
>       umpteenth time. Better to state in the beginning of the Spam
>       nodes that these fascillities can be used and when a reminder
>       is needed, add a short reminder that doesn't side track the
>       reader.

A lot of readers jump to the section of interest.  I think it's fair
to expect that, and to provide help there.  If you would like to
suggest an alternate way to accomodate both careful and
jump-to-point-of-interest readers, I'm all ears.

>    b. The explaination of (gnus-)ham-process-destinations is not
>       complete and even confusing. It is a list of regexp matched
>       with group names. In the next sentance it is declared as a
>       (REGEXP PROCESSOR). That is not a list of regexps, it is a
>       list of lists that contains a regexp and a PROCESSOR. What
>       this PROCESSOR is not explained.

I added a fix for this error, thank you.

>    c. The given information is not consistent with information given
>       a bit further down the page:
> 
>    "When you leave a _ham_ or _unclassified_ group, all *spam*
>    articles are moved to a location determined by either the
>    `spam-process-destination' group parameter or a match in the
>    `gnus-spam-process-destinations' variable, which is a list of
>    regular expressions matched with group names (it's easiest to
>    customize this variable with `customize-variable
>    gnus-spam-process-destinations').  Each newsgroup specification
>    has the repeated format (REGEXP GROUP) and they are all in a
>    standard Lisp list, if you prefer to customize the variable
>    manually.  The ultimate location is a group name or names.  If
>    the `spam-process-destination' parameter is not set, the spam
>    articles are only expired.  The group name is fully qualified,
>    meaning that if you see `nntp:servername' before the group name
>    in the group buffer then you need it here as well."
> 
>       Here the parameter is a list of (REGEXP GROUP). What is the
>       REGEXP matched on?

Reread the explanations of gnus-{spam,ham}-process-destinations and
see if they make more sense after my fixes.

>    d. In the example section gives the following example:
>       ((spam-process-destination .
>       "nnimap+mail.lifelogs.com:train")) When did a string become a
>       (REGEXP PROCESSOR) or (REGEXP GROUP)?  Same goes for
>       (ham-process-destination "nnimap+mail.lifelogs.com:mail"
>       "nnimap+mail.lifelogs.com:trainham")

That's the group/topic parameter, whereas the paragraphs above were
talking about the gnus-{spam,ham}-process-destinations variables.
With the group/topic parameters, the regexp is implied and we only
need the group name(s).

> Summary:
>  The entire documentation needs to be fleshed out with examples and
>  a better flow of text. At some places it is more or less just a
>  long list of variable and parameter names which is as penetrable as
>  a brick wall.

I agree.  spam.el is very complex, and I would love to a) improve the
documentation, and b) write a new user customization interface to it.

> I'm willing to help with this, but I need to understand how it works
> before I can do anything about it.

Thanks for the offer.

There is one reason why I'm not good at documenting spam.el: I know it
too well.  Where someone else might say, "wait, why is this variable
mentioned here" or "what does that parameter mean?" I can miss those
spots.  So it's not intentional that the documentation is confusing,
and I want to make it better.

If you are interested in helping, I'll be glad to incorporate your
changes into the manual.

Thanks
Ted