exit codes in docs

[Boris 'pi' Piwinger]

Matthias Andree wrote:

> What is way more important than scalability is having stable
> interfaces. That's what people build on, if they must change their whole
> integration stuff with every point release of bogofilter

That is important, I agree. But at some point we need to do
something. Exit code for unsure has been forgotten at some
point, it was added now. You argue that exit codes must not
change, others say, it is more logical the way it is done
now. Both are valid arguments.

> It's not the addition of an exit code for "unsure" that bothers me, but
> the change of an interface. We absolutely need a stable interface before
> we release bogofilter-1.0.

I strongly agree here. We are still at some more or less
early stage of development. Fixing everything too early
creates problems. Changes create problems. So as someone
else said: If we do need to make changes, let's do it now.

> If we want an extensible interface, then the
> exit code interface doesn't look too attractive.

I might not get your point, but exit codes are for sure very
useful and the easiest way to just get the simple answer to
the question "Is it spam?"

> I'll reiterate my procmail example criticism again:
> 
> many of the procmail examples, namely of the
> 
>        :0HB:
>        * ? bogofilter
>        Mail/spam
> 
> kind, mix all possible results, error, unsure, nospam, into one
> set. This is wrong.

In theory: Yes. In practice: It does work for many people.
It is *the* standard way of doing it. I know you don't like
procmail, but many people use it.

> It's not robust, it's not support-friendly and not
> the right thing to do. We shouldn't encourage such false use.

Suggest a better recipe.

> We should remove that example; unless there is protest within 24 hours,
> I'll remove it.

Count my protest.

> Then, we should define a machine-readable, extensible interface that
> prints a single line per mail on stdout and that a user cannot
> redefine. Casting bogofilter -tv with built-in defaults into concrete
> comes to mind.

ACK. I don't really understand why -t instead of -tv doesn't
do it, but never mind.

> We can offer a configurable interface with a separate
> option,

No -t should be good enough, don't you think?

> but I want to have a "canonical interface" that is configuration
> invariant and that people use in problem reporting and that should be
> the preferred way of using bogofilter results in a script.

NACK, this is a good way if you need detailled information,
but for the simple question of ham/spam/unsure, this is a
step too complicated.

pi