Rubenerd

This post by ncm is simply wonderful, and I’m unashamedly quoting the entire thing.

I remember the first time I encountered GNU Info. A man page said nothing useful, and referred me to GNU Info.

This. FreeBSD and NetBSD have beautiful manpages. It was a genuine shock to read the terse, incomplete GNU ones by comparison.

The first problem was that the key bindings were stupid and counterintuitive. (Still are. Every time I run it I have to figure them out all over again.) A bigger problem was that the files were badly organized, so that the information I needed was dispersed to lots of different places. Worst, having scoured the whole subtree, what I needed to know usually was not there.

I could see what had happened. All this handy organizational apparatus had to be used, so everything is broken into little sub-pages. Since it’s essentially hierarchical, every detail gets separated from other related details and stuck under a nice sub-sub-heading. The really useful information doesn’t really fit under any nice hierarchical category. Since there’s no good place to put it, it doesn’t get written down at all.

GNU Info sucks harder than a CFM56 at full throttle. And those are versatile sucking mechanisms, they’re not even mounted in circular nacelles on the next generation Boeing 737s.

Contrast this with the experience of man pages. On my system, man automatically pipes to less, so I can scroll around freely to see the whole thing. There are headers, but no intrusive hierarchy. For anything useful the author thinks of, there was someplace good to put it, generally next to something related. In better-written pages, there’s a flow, with later paragraphs building on earlier foundations. At the end, there’s a “see also” that tells me what other man pages might be interesting. Usually there are examples.

And here’s the kicker.

The only useful info pages I’ve seen were converted from man pages.

Back in “the day”, something as big as the make manual was considered too big to put in a man page, but that seems not to be a problem any more; certainly the bash man page is huge yet useful and entirely usable.