Documentation Don'ts

[swestrup]

Okay, look, I understand how the introduction of info pages rather than the fixing of man was a really bad idea, and why folks would want to push back. BUT, you know, the average user needs documentation.

So, Debian, having a man page that says that there is no man page, and to use info instead, and then to automatically generate an info-page from the man page is like a WAY stupid idea!

So now there's three or four major system tools that I've discovered have no real documentation, because its all in 'info' pages which have been replaced by stub man pages...

Comments

[hendrikboom.livejournal.com]

The info pages were Richard Stallman's idea, and have their own navigation tool with keyboard commands that no one I know remembers. You need the weird commands just to find your way around the help pages that explain the commands. But it's his baby, and he's adamant about it. Meanwhile, the man pages from upstream are going completely u=out-of-date, and the info pages don't seem to have any idea how to organize something for easy reference or navigation.

I hate it too.

Have a look at xman. I think that's a set of documentations obtained from I don't know where, but navigable with a mouse.

-- hendrik

[sps.livejournal.com]

I find info to be much nicer from within emacs, and far superior for book-style documentation (the emacs and gnu make manuals come to mind). That said, the divergence of the two formats is completely unacceptable.

(I thought xman was just a man front end for X. Perhaps it's a new thing with an old name?)

[(Anonymous)]

Konqueror, the KDE file manager/web browser, can open "info:topic" with the same interface it uses for HTML. (It can also do "man:topic", which just gets you nicer looking formatting than the command line since there are no links.) Trying to test it just now, I find that I don't actually have any info pages on my system, which surprised but pleases me.

[swestrup]

Well, that's my complaint too. "man chmod" says "see info chmod" and "info chmod" doesn't exist. I've tried to see if there is some info package with all of the missing documentation somewhere, but to no avail.

[sfllaw.livejournal.com]

info 'coreutils(chmod)'

[swestrup]

Well, what-do-you-know. 'info coreutils' actually works! Of course, this is not what the man pages say to look up...

[hendrikboom.livejournal.com]

Another thing: Often the documentation is in a separate package from the software. Sometimes that's because it's bulky and you might want to save disk space; sometimes it's because of copyright politics, and the documentation is in NONFREE. Apparently Debian considers the GNU Documentation License to be nonfree because of the invariant sections.