From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.emacs.gnus.general/56890 Path: main.gmane.org!not-for-mail From: Jonas Steverud Newsgroups: gmane.emacs.gnus.general Subject: Re: Regarding spam.el Date: Sat, 03 Apr 2004 11:58:48 +0200 Organization: The Deciples of Albericht Nibelungen Sender: ding-owner@lists.math.uh.edu Message-ID: References: <4nwu53pamd.fsf@lifelogs.com> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1080986448 22434 80.91.224.253 (3 Apr 2004 10:00:48 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 3 Apr 2004 10:00:48 +0000 (UTC) Original-X-From: ding-owner+M5429@lists.math.uh.edu Sat Apr 03 12:00:40 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 1B9hx9-0006Pj-00 for ; Sat, 03 Apr 2004 12:00:39 +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 1B9hvR-0002mA-00; Sat, 03 Apr 2004 03:58:53 -0600 Original-Received: from util2.math.uh.edu ([129.7.128.23]) by malifon.math.uh.edu with esmtp (Exim 3.20 #1) id 1B9hvI-0002m2-00 for ding@lists.math.uh.edu; Sat, 03 Apr 2004 03:58:44 -0600 Original-Received: from justine.libertine.org ([66.139.78.221] ident=postfix) by util2.math.uh.edu with esmtp (Exim 4.30) id 1B9hvH-000232-PI for ding@lists.math.uh.edu; Sat, 03 Apr 2004 03:58:43 -0600 Original-Received: from mxfep01.bredband.com (mxfep01.bredband.com [195.54.107.70]) by justine.libertine.org (Postfix) with ESMTP id 618583A020A for ; Sat, 3 Apr 2004 03:58:40 -0600 (CST) Original-Received: from c-a85372d5.036-4-67626721.cust.bredbandsbolaget.se.bredband.net ([213.114.83.177] [213.114.83.177]) by mxfep01.bredband.com with ESMTP id <20040403095839.TWQX12989.mxfep01.bredband.com@c-a85372d5.036-4-67626721.cust.bredbandsbolaget.se.bredband.net> for ; Sat, 3 Apr 2004 11:58:39 +0200 Original-To: ding@gnus.org Mail-Copies-To: never In-Reply-To: <4nwu53pamd.fsf@lifelogs.com> (Ted Zlatanov's message of "Mon, 29 Mar 2004 17:11:06 -0500") User-Agent: Gnus/5.110001 (No Gnus v0.1) Emacs/21.3 (darwin) X-Spam-Score: -4.8 (----) Precedence: bulk Xref: main.gmane.org gmane.emacs.gnus.general:56890 X-Report-Spam: http://spam.gmane.org/gmane.emacs.gnus.general:56890 Ted Zlatanov writes: (I only saw your mails recently due to an accident with gnus-split-with-parent, which is ridiculous since I was keeping an eye out for them. :-/) > 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. Individually IMHO. Maybe something like this: - Variabel: gnus-group-spam-exit-processor-bogofilter (obsolete) That way the user can skip the entire description and not find out afterwards that it is obsolete. When I read it I know some variables are obsolete and since I don't remember which I have to scan downward each time I reach a variable to see if it is obsolete or not. It definitely reduces the reading speed and adds a bit of confusion. > I think that's explained clearly. Feel free to suggest alternate wording. See below. >> 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. Yes, and I think that is part of the problem - the information is very dense. Writing documentation is not a contest in writing with as few words as possible (not in any way claiming that you participate in such a contest ;-) ), it is actually a contest in writing more words then you think is necessary. There are extremes off course as any university student can testify about, some authors are payed by the page number. I've written quite a few documents in my time (does ISO 9000 and ISO 9001 ring a bell?) and in my experience, there are numerous occasions when one think that "this is enough" - and that is exactly not the case. One should always write ten per cent more then one think is necessary. What the documentation really needs is more words. E.g. the sequence of events needs a list of the stages at the beginning, i.e. 1) Stage A, 2) Stage B etc., and then each stage is describes in a sub topic of its own if they become lengthy or at least under a headline. OTOH the nodes in a info file are very short so it shouldn't be a problem to have a node for each stage. >> 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. Yes, and that is very good! Maybe include a pointer to that section? In general, the examples in "this is my setup" are usually quite complex (which is good!) but to understand the concept they need to be very simple. I.e. include a very simple example where you describe the variable/concept: "To do Foo, set the bar variable to X, i.e. add the following line of code to the group parameter: (BAR . X)" where Foo is a very simple thing. Have a look at the examples for e.g. splitting mail, they are usually very simple but very descriptive. Sorry, but I have no specific suggestions. >> 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. What I tried to say is that in some places a number of parameters and variables is introduced ("blah X blah Y blah Z blah") but it is not clear if X is a parameter or a variable. If X is a parameter, is then Y and Z it as well or can it be so that X and Z are parameters and Y is a variable? If X is a parameter, what is then the corresponding global variable (because it is mentioned that for each parameter, there is a variable, but no hint of naming scheme)? E.g. from the sequence of events: ------ If a spam is found in any group (this can be changed to only non-spam groups with `spam-move-spam-nonspam-groups-only'), it is processed by the active `spam-processors' (*note Spam ELisp Package Global Variables::) when the group is exited. Furthermore, the spam is moved ------ Is spam-move-spam-nonspam-groups-only a parameter or a variable? I have to look at the example to know. spam-move-spam-nonspam-groups-only is only mentioned twice, above and in the example. I will not be able to read the docs with C-h v unless I load the spam.el package. Which I probably won't do before I understood that I have to do that and how I will be able to do it. I will not load it before I've understood what will happen when I do. If you catch my drift (or however the expression goes). > Have you tried the customize interface [...] Nope, I prefer the old fashioned way of typing Lisp one-liners on a neural interface... ;-) Besides, my aim with this is to "debug" the manual, to try to find the parts which confuses me. Using the customize interface is not exactly cheating, but isn't exactly right either. (And I only used the customize interface once before for JDEE and I can't say that I know how to handle it.) > A lot of readers jump to the section of interest. Yes, I am like that myself. But when one reads something for the first time it is a good idea to start on the first page and read then in sequence. You have to know that something is of interest before you can jump there, so to speak. ;-) > Reread the explanations of gnus-{spam,ham}-process-destinations and > see if they make more sense after my fixes. Which are in CVS I expect. I've decided that I will use the released versions of No Gnus, so I will see the new text when 0.02 is released. >> 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. See my comment above about distinguishing between parameters and variables. > 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. That is way I send these emails. I want to help with that, to point out the places that needs to be fleshed out. I might not be able with the text to write yet since I need to understand more of it before, but I hope my questions and points helps you understand how others read the documentation. (I better add a disclaimer at once: If I ever sounds like I'm ranting, that is not my intention. :-) ) Enjoy. /Jonas -- ( http://hem.bredband.net/steverud/ ! Wei Wu Wei ) ( Meaning of U2 Lyrics, Roleplaying ! To Do Without Do )