Re: [exim] Referring people to the docs vs. an example

On Tue, 2007-07-17 at 07:19 -0700, Marc Perkel wrote:
> Although pointing t the docs is helpful and Exim docs are better than
> most open source projects, the Exim scripting is not very intuitive and
> has a lot of quirks and is light on examples. So even if you go to the
> docs for someone who is new to Exim they will still spend an hour trying
> to do something simple.

To be pedantic about it, the config file isn't a scripting language -
it's a config file. Yes, it has logic in it, but it isn't a scripting
language.

> In this example, the user asked about how to do something based on load
> levels. Yes, Exim has a $load_average command

...variable. That's a variable.

The original answer to the OP's question stated:

"More specifically: smtp_load_reserve"

Which, if you read the link that accompanied it, states:

"If the system load average ever gets higher than this, incoming SMTP
calls are accepted only from those hosts that match an entry in
smtp_reserve_hosts."

That's as absolutely clear a statement of a config option as it's
possible to have. It applies before any ACLs are run, as it's a global
option.

> No other language that I know of builds conditionals that look like
> this. So if you are a new user then you also have to research how to
> build a conditional comparison. And you also have to understand the
> whole ACL thing. But if you just actually answer the question then the
> person can paste the code into the ACL without having to spend hours
> looking up several things that some of us just know. Most people don't
> dedicate their lives to Exim.

Anyone who wants to use any piece of software is going to struggle if
they only ever use examples. Knowing the underlying meaning of logic,
conditionals, tests and statements is an essential part of that
understanding.

Most people don't dedicate their lives to driving cars, either, but an
essential part of learning how to drive is understanding how the car
functions (at a basic level). In my experience no driving instructor
worth the title teaches mechanistically in the way you suggest by (for
example) showing a video of someone driving a car (the contextual
equivalent of a config cut'n'paste); they teach by both example and
explanation.
In the UK at least the method for learning road laws and good practice
is to make people learn the Highway Code, almost by rote. This is the
documentation method alone - it doesn't teach you how to drive, but it
teaches you about road laws.
Putting the two together - documentation and examples - you have the
best method of teaching almost *any* subject.

Anyway, that's enough digression.

> So - pointing to the docs might be barely good enough but pasting a bit
> of code example is generally better.

I respectfully disagree (and I'm not about to argue about it, either).
Pasting a bit of code *together with* a link to docs and/or a comment
about what the code does, how and why is far more helpful than simply
cut'n'paste. Sometimes the how and why, or the explanation, are very
short or unnecessary - and if the person asking the question still
doesn't get it, then they can come back and say so.

The fact remains that you obviously misread (or didn't read at all) the
answer to the original question, which stated the answer clearly and in
a more accurately detailed way than your config snippet did.

With regards to your comments about syntax, please use the Wiki and add
things to the Exim5 pages. Even better, provide the code to make Exim do
what *you* want it to do.

Graeme