The man page Rant

I've been involved in a discussion of documentation on one of RedHat's mailing lists, which culminated in my posting the following rant:

Back in the good old days, I could fire up xman and find out *everything* I needed to know about a Unix system. I could even print out the entire blasted manual (that's what "man" stands for, remember?) with a single find command.

The man pages contained a description, however brief, of *every* program in the system, and a reference to other documentation if there was any. If someone asked me a question about a program, I could tell them to run "man foo" in total confidence that it would return something useful.

If a program had a configuration file with a funny syntax, _it_ had a man page and the program's man page had a reference to it. If I wanted to find out where apache kept its configuration files, I could run "man apache" and find out. On RH7.3 it says they're in /usr/local/apache. Big help.

Even now, when I go to the "help" menu on Emacs, I get a list of options that include printing the version number, browsing the hypertext manual, listing the current key bindings, and submitting a bug report. Try that with, say, gdmconfig and you get an about box. Whee!

One of Unix's biggest strengths was the fact that the online documentation was complete, easily accessed, and all in one place. The current chaotic mess is *not* an improvement.

My main complaint at the time was the fact that RedHat doesn't bother documenting their changes to applications' configuration files. I mention Apache -- the man page for Apache says that all the configuration files and web pages are in subdirectories of /usr/local/apache. But RedHat puts the configuration files in /etc/httpd and the web pages in /var/web! Yes, there's a (somewhat obscure) command you can run to find this out, but the point is that you shouldn't have to. And even rpm will only tell you where the files are, not what changes RedHat made to them.

Before you conclude that this is a RedHat-specific problem, let me assure you that it isn't: almost(?) every distribution has the same problem, and that's not counting the myriad applications, like almost all of Gnome, that don't have any man pages at all, and little if any online help of any kind. Let's face it: programmers don't like to document their code, and technical writers are too busy.

Back in the old days, the man pages were the manual! When you bought a Unix box from Sun, you also got a box full of looseleaf binders -- one for each section of the manual. Pages were alphabetized but unnumbered, so that whenever you installed a new or updated program you could put its pages in their proper place. If you patched a program or changed a compile-time default (like where the configuration files were located), you updated the corresponding information in the man page so that what was online was always accurate.

Of course, the system administrator got the ``official'' copy of the manual, but that was OK because the entire manual was online -- where most users preferred to read it anyway. But any user who felt like tending a printer for a couple of hours could print out their own, using a combination of find and man -t (which produced, as it does now, a typeset page on STDOUT).

You could still do that, but it wouldn't do you nearly as much good, because the man pages are neither complete or correct on your average Linux distribution.

What is to be done?

I could just end it here, and leave the conclusion as an exercise for the reader. But I won't -- I think there are things we can do.

The simplest thing is for the distributions' QA groups to refuse to sign off on any package that doesn't have a complete set of man pages that's been patched for their distro, and for developers to write configuration programs that automatically patch the documentation from the compile-time configuration files. But that would make too much sense -- I don't expect to see it happen in my lifetime.

Note that I'm not calling for yet another book called Linux for the Complete Idiot, or even Linux for the Unsatisfied Expert. What I want is nothing less than a comprehensive, up-to-date, online manual -- something that you can browse on your own machine.

Browse... Now what does that remind me of?

So how does this sound: Gather together all of the available documentation files on your machine, convert it to HTML, sort it, cross-index it, and serve it up to any browser you feel like pointing at it. For good measure, cross-index it to the actual configuration files, the diff's between those and the ones in the original software distribution, and links to anything available on the web -- the developer's website, the bug database, maybe even mailing lists.

Now, this isn't as big an effort as it might seem: a lot of the available documentation is in places like /usr/share and either in HTML already (like Gnome and KDE's help files), or in man or info pages (which are pretty easy to convert to HTML, and there are CGI's floating around that can do the job).

The main index, of course, would be generated by going through the various */bin directories to find out which apps you have and which packages they came from. Then you go to the package installation database, which not only tells you where to look for help and configuration files but gives you a capsule description, too. And if you installed the app from sources, there's probably still a directory somewhere in /usr/local/src -- with a doc subdirectory, if you're lucky.

Finally, if you had a net connection, you could hit the various software information sites (like Freshmeat)and search engines (like Google) to track down the ``official'' website for the application, plus any unofficial sites that may be floating around.

Now, none of this really requires any cooperation at all from either the distributions or the application developers. Even if they haven't written much documentation -- or any at all -- there's going to be a lot of information around just from the fact that it's been packaged up and installed on your system. The documentation, as they say, is out there. On the other hand, if the documentation scrounger existed we might hope that developers and distributors would eventually plan for it, and include the necessary information in their packages.

Now, somebody has to actually write this documentation scrounger. But it's either that, or wait for developers and distributions to keep their man pages up to date.