Re: Texinfo vs man (was: Re: Debian GNU/Linux Reference Card under construction)

[Jan Nieuwenhuizen <janneke@gnu.org>]

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.
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.

> 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.

>>     In general, a GNU manual should serve both as tutorial and
>>     reference.

> Yeah, well, that's braindead.

Why do you think that?  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.

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.  They
read as a book, but have a great separation into concepts and a good
index, which makes for an excellent reference.

> If it's not possible to create one text that can be used for both
> purposes;

I hope to think this assumption is wrong.  It's the easy route to
take, as a documentation writer, but you can do better, imho.

Jan.

-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien       | http://www.lilypond.org