On Feb 7, 2009, at 4:52 AM, Neil Bothwick <n...@digimed.co.uk> wrote:

On Fri, 6 Feb 2009 14:25:07 +0000 (UTC), Grant Edwards wrote:

You'd expect to find a list of contents, chapters and an index
in a printed reference book, electronic documentation should
be no different.

Perhaps, but I think info is an awful implementation.  A single
large man page is much better, and a single large html page
with links in it is far, far, better.

Info is far from a perfect solution (very far)and I generally use it in Konqueror anyway, but the idea that any product, no matter how complex,
should be documented in a single, unindexed page is ridiculous.

Searching in a single page is fine, as long as the term you are looking for is fairly unique, try searching for something like avi in the mplayer man page and see how many times you need to press n before you find what
you want.

The Gentoo handbook is an excellent example of how documentation should
be arranged.


--
Neil Bothwick

Of all the people I've met you're certainly one of them

While I do like how the handbook is aranged, I'd much rather go through condensed manpages if I were looking for how to do something. The handbook is easy to read and all, and tends to provide decent reasoning for each step it suggests, but it's far too bulky for my taste.

Reply via email to