On Mon, May 03, 2004 at 10:18:14AM +0200, Jan Nieuwenhuizen wrote:
> Wouter Verhelst writes:
>
> > Are you suggesting that "foo --help" should contain everything,
>
> No, I must have been unclear. foo --help is OK. Only for the
> simplest of programs, foo --help can and should display more than a
> fraction of the program's funtionality or documentation.
>
> If you know beforehand that you need to learn more than the name of
> the command line switches or where the output goes, it would be good
> if there was one source of documentation, not a whole path to follow.
We disagree then, for reasons you conveniently snipped out.
> Man is fine for simple things, info is just the next step; it's fine
> for both simple and more fleshy documentation. With man, more
> information easily gets in the way, that's why man pages are usually
> terse, and terse man pages are often considered to be better. Info
> solves the need for being terse. More information is not a problem
> like it is with man.
IMO, it does not. Many info pages do indeed have an index section, but
many others do not. In some cases, the index section is hard to find. In
many cases, it is incomplete so that when one searches an index section,
it does not yield a result, meaning, you've spent a good few minutes to
find something which will need a full-text search after all anyway.
Also, I don't like doing work which a computer can do more easily for
me. Searching a large index section takes more time than hitting
"/<search term><enter>" and waiting for the result; therefore, it's
silly to do that with on-line documentation.
> > What I meant to say is that, IME, info pages tend to lean towards
> > over-documentation, so that one does not easily find the documentation
> > one needs anymore
>
> Info has indexes, menus (and also the poor man's string search and
> regex searches). If you cannot find the information you are looking
> for very easily in an info document, I consider that to be a bug that
> should be reported and fixed.
Well, then in my experience, most -- if not all -- info pages are buggy
by your definition.
> >> In general, a GNU manual should serve both as tutorial and
> >> reference.
>
> > Yeah, well, that's braindead.
>
> Why do you think that?
Uh, I explained that in the part you snipped out.
> I think it is a very difficult thing to write, but the best type of
> documentation for a user if you do get it right.
I've never seen an example where it was "done right".
> The best way to understand why I think it can be done, would be to
> read the TeX book, and or the metafont manual by Donald Knuth.
That could be true; but I've never seen those. Do you have a reference,
so that I an have a look? (I did find
http://www.ctan.org/tex-archive/systems/knuth/tex/texbook.tex by
googling, but that is hardly readable and has been broken on purpose so
that it cannot be converted into something more useful)
> They read as a book, but have a great separation into concepts and a
> good index, which makes for an excellent reference.
Again, this sounds like there are distinct "reference" and "tutorial"
sections. Do correct me if I'm wrong; but if I'm not, I fail to see how
they would be different.
> > If it's not possible to create one text that can be used for both
> > purposes;
>
> I hope to think this assumption is wrong.
I have yet to see an example which proves you're right.
> It's the easy route to take, as a documentation writer, but you can do
> better, imho.
Given the fact that most developers do not like to write documentation,
taking the easy route is not necessarily a bad idea. It can mean the
difference between "minimal, but sufficient" documentation, and no
documentation at all.
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
Attachment:
signature.asc
Description: Digital signature