A Rant. Linux Man pages vs Info pages

27 08 2005

This one just bit me on the ass tonight.
Why is it that the Gnu Linux heads can’t understand that a single documentation format, one that has been in place since time immemorial, should be replaced by one that is inferior, annoying, and requires a whole new set of skills, JUST TO LOOK UP SOME TEXT?
I bring you the idiocy that is ‘info’. It is the grossest example of ’emacsification’ that is all too common place in the Linux world.
Here’s a real life example of this ridiculousness.
Today I needed to write a ‘sed’ script to do some line processing. No problem, I just need to look in the man page to see how to do a few things. But lo! The man page for ‘sed’ on my machine (Debian Sarge Linux) doesn’t have any useful information. In fact, it has almost nothing at all. It does, however, helpfully say, about line 30:

This is just a brief synopsis of sed commands to serve as a reminder to those who already know sed; other documentation (such as the texinfo document) must be consulted for fuller descriptions.

Very handy, eh? Fine, I just so happen to know that also later in the document it mentions ‘info sed’. Okay, so I type that.
The information I’m looking for is simply what the command line arguments are, and how to set pattern matches on substitution. The command info sed puts me… into an interactive menu system. Normally, ‘man’ pages are searchable by typing ‘/string’. So I type that. I am now on a page called ‘Less frequently used commands’. Very soon I am hopelessly lost in navigating screens and nodes and commands that have nothing to do with what I’m trying to do, which is simply get a command syntax.
Who POSSIBLY thought that translating the simple single page format of man pages, that every Unix admin on the planet knows how to use, into an interactive mini-Emacs session that requires a fair amount of knowledge on how Emacs works to work with makes ANY sense whatsoever?
Unfortunately, the people who make these sorts of idiotic decisions are the same ones that boot up Emacs and never leave it, and assume the rest of the world must know it as well. I have news for ya fellas, I don’t. And assuming that eveyrone knows how to use emacs, and therefore it’s okay REQUIRING an admin to use an emacs interface to view documentation is narrow sighted and ridiculous.
Stick with the known, standard, common formats. Emacs is not universal. Use the man page system that has been around since the dawn of time. There’s absolutely no reason to change it.

Advertisements

Actions

Information

12 responses

28 08 2005
sandro hawke

I think if you ask around, you’ll find a wide variety of complaints (and praise) about that particular fellow. I’m totally with you on this one, though. At this point I could see the point in using HTML for everything, though.
Going a step back, it often makes me nuts that the option parser, the –help (or whatever) output, the man page, and various other program docs (eg its website) are all maintained separately. I wrote something to solve the problem once, but of course getting the solution adopted is 99.99% of the battle.

28 08 2005
beowabbit

Yeah, I hate the fact that the typical Linux distro has important command documentation scattered around at least four different unconnected places, and lots of it is incorrect or just missing. But to be fair, info is much much more featureful, and tends to have a lot more information than man pages (because info pages are hypertext, and therefore you can get away with being verbose more easily than you can in a man page). Yes, the current tools for working with info pages are more complex and therefore have a very slightly higher learning curve than man pages, but really, if the One True Documentation Format were info pages, and absolutely everything used them, I’d be content. Or if it were HTML pages organized according to some arbitrary but strict set of conventions. I probably wouldn’t be content with every single command understanding –help, unless what it output was comparably copious to man pages.

Short of the One True Documentation Format, what would be nice would be a single tool that aggregates all the various documentation formats. But that’s hard, because lots of them are very free-form (e.g. the contents of /usr/doc), and because they have very different featuresets (e.g., hypertext in info pages). Something that got partway there would still help, though.

The printed AT&T and BSD Unix manuals had a lot more information than online man pages now do — stuff like vi and troff tutorials, for instance — and lots of that is better expressed in info pages than in man pages.

(Which is not to say I don’t get as grumpy as you when I have to deal with info.)

28 08 2005
dilletante

right on! i agree completely.

28 08 2005
Chip

Info is annoying, but I find man pages to be profoundly sucktastic if they’re more than a few pages long. Try looking up something in, say, the bash man page sometime.

28 08 2005
dbs

Try looking up something in, say, the bash man page sometime.
The ‘bash’ man page is somewhat of an exception, since bash is basically a language now, rather than just a small tool. Man pages are definately more useful for quick reference to small tools (in the Unix spirit) than entire language reference.
The Perl folks did a sort of half-way solution by breaking up the man pages into several pages, but even then, they have THEIR OWN documentation format – Perldoc, which really is just a revamp of ‘man’. It is browsed with ${YOUR_FAVORITE_PAGER}.
But going back to your example, things like bash, perl, java, C – language references – are not appropriate for man, admittedly. Those I can see in an ‘info’ like system, but as Sandro says, HTML is just fine (in fact, for bash and java, I do use HTML pages for documentation – Javadoc is wonderful, and scrolling a browser back and forth on a bash man page I find easier than doing it in the command line.)
But ‘sed’? Cmon πŸ™‚

28 08 2005
Mark Amidon

There is a simple solution any time you run into a man page which tells you to use “info”:

konqueror info:sed (or whatever)

I also adamantly refuse to use “info”, pretty much because I want EMACS shorted to ground.

28 08 2005
dbs

Ahhh. HAH! I didn’t know about the konqueror info: kio. That’s wonderful. (fyi, I use ‘alt-f2 info:sed’ for hyper-speedy access).
Thanks Mark!

28 08 2005
Doctor Memory

Nrrrrrrgh. My blood pressure goes up 10 points every time I see one of those goddamned things.
I wouldn’t mind it so much if the actual info program weren’t one of the worst-desgined pieces of crap I’ve ever encountered. Behold, a “hypertext” browser that gives you no indication whatsoever where your anchors/links are! Kill, maim, destroy, fold, spindle, mutilate…

28 08 2005
dbs

By the way, this is an excellent argument against the ‘info’ system.

28 08 2005
Tim Pierce

I’m inclined to agree more with Sandro and Dr Memory. Any non-trivial application is going to require more documentation than you can easily navigate in a pager. Hypertext is the solution the world has chosen, and in principle it’s not a bad solution at all. Texinfo has the additional advantage of being useful to prepare both a printed manual and online documentation, if you’re careful and follow the recommended conventions.
The chief problem with info, like DrM says, is that the standalone application for using it is so annoying. The world has pretty much moved past “info” directly to HTML, and I think that the GNU project would do well to recognize that and focus on HTML as the canonical form of online documentation.
As a point of information, I note that “vim” also has a very brief man page that says:

While running Vim a lot of help can be obtained from the on-line help system, with the “:help” command. See the ON-LINE HELP section below.”

Now, Info has been around for about 15 years and is presently used by several hundred applications. It has a command syntax that has not changed significantly since it was introduced. Vim uses an online documentation format that has been around for something like five years, is used by one application and uses a command syntax shared by no other tool, unless maybe you include nethack.
So which tool is more egregiously breaking established conventions? πŸ™‚

28 08 2005
dbs

So which tool is more egregiously breaking established conventions? πŸ™‚
This can be answered actually in one flat statement.
Show me any other tool that the ‘vim’ folks are pushing their documentation standards onto?
Also, as was noted on the article I linked to, there’s a difference between application documentation (for things like bash, emacs, vi, etc), and tool documentation (sed, ls, tar, etc). Application documentation can use whatever they like. Perl uses perldoc, emacs uses… whatever it uses, and vim uses their internal. Forcing your broken and application specific documentation kludge onto already existing applications and environmetns, and altering them to your own specification is, to me, abhorrent.

29 08 2005
orion

This can be answered actually in one flat statement.
You haven’t answered the question at all. How do you get from “vim doesn’t push their help browser onto other projects” to “vim is not violating (or, perhaps, ignoring) established standards by creating their own help browser”?
Look, I don’t particularly like info, as much as I do happen to like emacs. Info is hard to use (even inside emacs, much less in the standalone browser), fairly inscrutable (how do you get help on info commands?), and in general is an awful implementation of hypertext. I think that moving documentation towards HTML is a much better idea, and generally if I have to deal with info to find help information, I’ll go look it up online instead. But direct your hatred in the appropriate direction, for christ’s sake.
Info sucks, but not because it’s an emacs project. What we need is an implementation of hypertext that can be browsed from the command line (is HTML+lynx good enough?). What we don’t need is more misdirected emacs bashing.
Besides, can’t you produce HTML with links from texinfo? Why haven’t we started doing that?
(IMHO, sed, much like perl, has expanded past the point where you can call it a “simple tool” and expect the full documentation to exist in the man page. There’s plenty of reference material online, why not use it?)
Oh, and just to throw in a little Debian advocacy, if more package maintainers took the contents of /usr/share/doc seriously I’d be a happy man.




%d bloggers like this: