Bug#368328: closed by Andreas Metzler <ametzler@debian.org> (Re: Bug#368328: which options are the most important?)

[Frederik Eaton]

On Sun, May 21, 2006 at 08:49:03PM +0200, Andreas Metzler wrote:
> On 2006-05-21 Frederik Eaton <frederik at a5.repetae.net> wrote:
> >>> The exim4 man page doesn't say which command-line options are the most
> >>> important.
> 
> >>> The options are listed in alphabetical order, so I don't know in which
> >>> order to read them to start learning about exim.
> 
> >> You should not read the manpage to "start learning about exim", the
> >> manpage is just a short reference, not a manual. Read
> >> /usr/share/doc/exim4-base/spec.txt.gz or
> >> /usr/share/doc/exim4-doc-html/html/index.html if you want to learn
> >> about exim.
> 
> > Yes, it looks like spec.txt.gz is a good way to learn about exim... if
> > I want to learn about the whole thing, in every excruciating detail,
> > from start to finish.
> 
> You'd start with chapter 3, probably "3.13 Delivery in detail", then
> read "7. The default configuration file". After that you'd have a
> basic understanding.

3.5 seems useful too. I think the three options mentioned there (-bm,
-bs, -bS) should be up at the top of the man page, maybe with the same
explanatory text.

> > I also notice that the command-line options are alphabetized in that
> > document as well.
> 
> > I don't think you're honestly considering the merits of my suggestion. 
> 
> I really, honestly cannot see how anybody could start learning by
> consulting the list of command-line options. The key things to know
> are
> 
> 1. What routers and transports do.
> 2. How ACLs work (If you can talk SMTP by telnet you are set).
> 3. Basic string expansion and lookups (lsearch), aka
> the-lots-of-curly-braces-thing.
> 4. Where to find further documentation.

Obviously for an MTA there is a lot more to understand than the
command line interface. But if I (1) know that I want to run the exim
command, for instance I have a message that I want to send with it,
but (2) I don't know the exact options to use; then the man page seems
like a reasonable place to look. In exim's case, it is practically
useless - the few options which comprise 99% of all uses are buried
deep within the man page.

> [...]
> >>    I am quite familiar with exim but given two options I really cannot
> >>    tell which one is more important (Is -d or -qqf more important?), I
> >>    could probably order them into "used often", "internal" and
> >>    "everything else", but thats not useful.
> 
> > That would be very useful indeed. Could you do that?
> 
> It is not useful. Usually the only options you'll need are:
> 
> - invoke with -oi -oem for piping (possible -t)
> - start daemon with -bd -q15m
> - Force queue-run with -qff
> - -b* to test stuff
> - Debug with -d

It would be good to have this information somewhere in the man page.

> For everything else you'll usually just end up refering to the
> option 
> a) because some other piece of documentation refered to it. (In which
> case alphabetical order is the most usable one.)
> b) you are searching for an option that does X. In that case you'll
> need to search for X using less, google, whatever.
> 
> The alphabetic order also groups similar options together, as for
> example all testiong options start with -b, so is not just a mess.

Sure, you get *some* order by listing things alphabetically; so I
don't understand your aversion to having *more* order. Is order good,
or what? Maybe having order is good when it's useful for defending
your position, but not mine?

Frederik

-- 
http://ofb.net/~frederik/