[ On Wednesday, July 4, 2001 at 23:22:11 (-0400), Dave C. wrote: ]
> Subject: Re: [Exim] Why no man pages for Exim on FreeBSD?
>
> I must again speak up for the simple - I find the the plain ASCII text
> version of the specification the easiest to use.
Well, on the side of simple, there's one thing to be said for both
'info' and 'man' pages: you don't have to know where they are
installed, or be logged in as any special user, to read them.
The problem with 'info' documents is that though they are usually
presented with a fairly powerful hyper-text browser (with full-text
search capabilities), the layout of a full manual doesn't lend itself
very well to being used as a quick-reference. Manual pages help focus
the search domain down to just the most relevant information.
I do agree that every unix program should have a simple manual page to
describe its command-line syntax (if any), give a basic description,
perhaps give a basic example, explain common errors one might see,
mention any well known bugs or design flaws/limitations, and of course
provide reference to more detailed documentation (as well as provide all
the really basic information about the program, such as who wrote it and
when, what standards it might conform to). The same rules should apply
for every configuration file too!
Manual pages are a concise (some might even say terse) reference to the
most essential bits of information necessary for understanding a command
or configuration file. Manual pages should not be the sole source of
detailed documentation or how-to's for something big and complex, and
they certainly shouldn't run on and on forever (the most infamous
example being the tome for rn, and other examples being almost anything
else ever written by Larry Wall! ;-)
In a closely related example I'd say the manual pages for Smail are a
bit too much verbiage, though they do try to stick just to the reference
material, leaving detailed exmaples, theory of operation, etc., more to
the (now drastically out-of-date) administrator's manual. They're also
focused on specific domains too (eg. commands or config files).
Now of course in this particular case it might be more appropriate for
the *BSD folks to write and maintain such manual pages for Exim.... :-)
--
Greg A. Woods
+1 416 218-0098 VE3TCP <gwoods@???> <woods@???>
Planix, Inc. <woods@???>; Secrets of the Weird <woods@???>
