Re: [TUHS] man-page style

[Norman Wilson <norman@oclsc.org>]

WIlliam Cheswick <ches@cheswick.com> wrote:

> As for the configuration: when Norman Wilson moved to Toronto, he
> implemented some form of little language for configuring sendmail,
> treating it somewhat as an assembly language.

Bill's half right.  I didn't invent a language; I used what was there.

I decided that the best way to deal with Sendmail's own configuration
language was to treat it as I would the assembly language for a
specialized, irregularly-designed microprocessor:

1.  Understand as well as possible what the instructions actually do;
2.  Write the simplest possible program that will get the job done;
3.  Avoid extra layers of macros and so on that hide the details, because
that also hides the irregularities and makes it harder to understand
and debug;
4.  By the same reason, don't just copy someone else's program that
does something complicated; write your own and do things simply.

Sendmail has plenty of design flaws (not just in the language), as
I'm sure Eric will acknowledge; but I think the biggest problem
people have had with it that most people copied the rather-complicated
sample configuration files shipped with the source rather than just
reading the manual, doing a few experiments to understand the behaviour,
and writing something simple.

On the other hand, I've never quite understood why so many people
treat device drivers as scary and untouchable, copying an existing
one and hacking it until it seems to work rather than understanding
what the device actually does and writing a simple program to control
it.  So perhaps my brain just doesn't work normally.

Norman Wilson
Toronto ON