Re: svn commit: rev 35694 - spamassassin/trunk

["Malte S. Stretz" <ms...@gmx.net>]

On Wednesday 04 August 2004 21:37 CET Justin Mason wrote:
> Hold on -- I'm -1 on this change (the "sa-learn" part that is).

Doh, not again.

> in my opinion, it's more important that the documentation be usable, than
> that the "normal" ordering of the sections be preserved.
>
> I'm happy to have the first three be "NAME, SYNOPSIS, DESCRIPTION", but
> requiring that the very verbose and bulky "OPTIONS" section appear before
> the human-readable explanation sections in "sa-learn", is not a good
> thing.

Actually, when I look at a man page I don't care too much about the theory 
behind what the tool does but the options to call it with.  Agreed, the 
SYNOPSIS (needed by Pod::Usage) is already pretty verbose (I hope to find a 
way to cut this down one day), but I still have to scroll over three 
screens of Bayes theory before I come to the actual OPTIONS description. 
Very odd in my eyes.

Can we solve this on the list or shall I open a bug? ;-)

Cheers,
Malte

-- 
[SGT] Simon G. Tatham: "How to Report Bugs Effectively"
      <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>
[ESR] Eric S. Raymond: "How To Ask Questions The Smart Way"
      <http://www.catb.org/~esr/faqs/smart-questions.html>