From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.emacs.gnus.general/56847 Path: main.gmane.org!not-for-mail From: Ted Zlatanov Newsgroups: gmane.emacs.gnus.general Subject: Re: Regarding spam.el Date: Mon, 29 Mar 2004 17:11:06 -0500 Organization: =?koi8-r?q?=F4=C5=CF=C4=CF=D2=20=FA=CC=C1=D4=C1=CE=CF=D7?= @ Cienfuegos Sender: ding-owner@lists.math.uh.edu Message-ID: <4nwu53pamd.fsf@lifelogs.com> References: NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1080599150 19305 80.91.224.253 (29 Mar 2004 22:25:50 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 29 Mar 2004 22:25:50 +0000 (UTC) Original-X-From: ding-owner+M5386@lists.math.uh.edu Tue Mar 30 00:25:41 2004 Return-path: Original-Received: from malifon.math.uh.edu ([129.7.128.13]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1B85CO-0004p7-00 for ; Tue, 30 Mar 2004 00:25:40 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.math.uh.edu) by malifon.math.uh.edu with smtp (Exim 3.20 #1) id 1B85Bq-0000ZL-00; Mon, 29 Mar 2004 16:25:06 -0600 Original-Received: from util2.math.uh.edu ([129.7.128.23]) by malifon.math.uh.edu with esmtp (Exim 3.20 #1) id 1B85Bl-0000ZG-00 for ding@lists.math.uh.edu; Mon, 29 Mar 2004 16:25:01 -0600 Original-Received: from justine.libertine.org ([66.139.78.221] ident=postfix) by util2.math.uh.edu with esmtp (Exim 4.30) id 1B85Bi-0003Fu-GZ for ding@lists.math.uh.edu; Mon, 29 Mar 2004 16:24:58 -0600 Original-Received: from clifford.bwh.harvard.edu (clifford.bwh.harvard.edu [134.174.9.41]) by justine.libertine.org (Postfix) with ESMTP id 444073A0042 for ; Mon, 29 Mar 2004 16:24:57 -0600 (CST) Original-Received: from asimov (asimov [134.174.9.63]) by clifford.bwh.harvard.edu (8.10.2+Sun/8.11.0) with ESMTP id i2TMN2P15713 for ; Mon, 29 Mar 2004 17:23:02 -0500 (EST) Original-To: ding@gnus.org X-Face: bd.DQ~'29fIs`T_%O%C\g%6jW)yi[zuz6;d4V0`@y-~$#3P_Ng{@m+e4o<4P'#(_GJQ%TT= D}[Ep*b!\e,fBZ'j_+#"Ps?s2!4H2-Y"sx" Mail-Followup-To: ding@gnus.org In-Reply-To: (Jonas Steverud's message of "Tue, 09 Mar 2004 14:49:22 +0100") User-Agent: Gnus/5.110002 (No Gnus v0.2) Emacs/21.3.50 (gnu/linux) X-Spam-Score: -4.9 (----) Precedence: bulk Xref: main.gmane.org gmane.emacs.gnus.general:56847 X-Report-Spam: http://spam.gmane.org/gmane.emacs.gnus.general:56847 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