On 2009-02-08, Graham Murray <gra...@gmurray.org.uk> wrote: > Neil Bothwick <n...@digimed.co.uk> writes: > >> Everyone's more or less agreeing here, that the info format is >> useful but the standard info reader sucks. Once you start >> reading info pages in a decent reader, like Konqueror, they >> are useful for more complex documents. Although I'd still >> prefer HTML, mainly because of the wide choice of readers >> available. > > Yet much (I would even suggest most) HTML documentation does > not take much advantage of the HTML format. It is rare for it > to contain many hyperlinks within the text. Often it is > formatted more like a book with each page just having > previous, next, up and contents links at top and/or bottom > with few, if any, hyperlinks in the text.
And that format completely sucks for much the same reason that info sucks. I hate it when a large HTML document is broken up into chunks 1-2 paragraphs long with prev/next buttons. Such documents are impossible to search either by eye or using a browser's search feature. Unfortunately, when HTML is generated from info or docbook formats, the default seems to be to generated a completely factured, disconnected heap if small HTML pages. The Python documentation is like that. The Gentoo docs are a pretty decent example of how to do HTML documentation right. -- Grant
