Ken Marsh <kmarsh(_at_)charm(_dot_)net> writes:
On Wed, 5 Feb 1997, Philip Guenther wrote:
Well, scoring isn't mentioned on the main manpages to avoid confusing
new users. However, at the top of the procmailsc(5) manpage it says:
[*] w^x condition
If you think in terms of BNF grammers, then you would say:
As a sometime parser writer, as a matter of fact, I do think in BNF. :)
condition_line ::= * condition
condition ::= w^x condition
| ! condition
| $ condition
| var ?? condition
| ? command
| regexp
| > number
| < number
But if you think in BNF grammers, wouldn't the above seem obvious?
No. First of all, the BNF you just gave isn't in there. Second, if
it was, it is still missing:
condition ::= command
*Where* did this BNF rule come from??? Stop, think about the grammer
you've now created by adding this rule. You say you've written
parsers. Then you understand what it means for a grammer to be
ambigious. The reason the BNF I gave doesn't include the rule you add
is that it would make it ambigious. procmail would have no way to tell
the differance between a regexp and a command. Okay, so the author of
procmail had to change the grammer to eliminate this ambiguity. He did
so by requiring a command to be preceded by a '?'. Then he documented
this on the manpage.
If you want to negate the return code of a command as a condition, you
must say:
* ! ? commmand
The BNF isn't in the manpage because a) 90% of the people reading the
manpage don't understand BNF, and would be confused/scared by it; and
b) those that do understand BNF (or even know what it stands for) are
likely to guess that you can use multiple special flags on a condition
line, try it, and find it works. And there's always the source code
for really strange questions.
Each line is a condition: everything follows from that.
Everything that's implied or given in examples, but not defined? I
know I'm going on, but honestly, it's just not in the man pages.
Is there some other reference I should be looking at?
Well, let's see, the procmailrc(5) manpage says:
Recipes
A line starting with ':' marks the beginning of a recipe.
It has the following format:
:0 [flags] [ : [locallockfile] ]
<zero or more conditions (one per line)>
<exactly one action line>
No offense, but what does "one per line" mean to you?
If you're frustrated with the manpages, fix them. Come up with a
description/structure that is a) correct; b) clear to a newbie; c)
complete; d) useful for the intermediate user; and e) will server as a
reference for the experienced. Submit it to Stephen and see what he
says. Keep in mind that Stephen believes that (a) and (b) are the most
important.
Before you heckle someone's documentation, try writing a replacement.
There have been a couple times I've found passages in the manpages
slightly confusing or misleading on technical points, but when I've
tried to rephrase them in a clearer fashion, they've come out more
technically correct, but they've also obscured the main point, such
that the big picture would be lost in the details. In a manpage
destined for beginning users, the Big Picture is much more important
than any detail, and I think Stephen has done a very good job of
presenting the big picture without losing the details for those how
look and *think*.
Maybe you should just submit some examples for the procmailex(5)
manpage that demonstrates some more condition possibilities...
Philip Guenther