I've been involved in a discussion of documentation on one of RedHat's mailing lists, which culminated in my posting the following rant:<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.</rant> (from this message.)
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
/etc/httpd and the web pages in
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
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
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,
man pages are neither complete or correct on your
average Linux distribution.
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
manpages 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
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
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
/usr/local/src -- with a
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.