ugh.book

44 Documentation?

On-line Documentation

The Unix documentation system began as a single program called man.

man was a tiny utility that took the argument that you provided, found the

appropriate matching file, piped the file through nroff with the “man” mac-

ros (a set of text formatting macros used for nothing else on the planet), and

finally sent the output through pg or more.

Originally, these tidbits of documentation were called “man pages”

because each program’s entry was little more than a page (and frequently

less).

man was great for its time. But that time has long passed.

Over the years, the man page system has slowly grown and matured. To its

credit, it has not become a tangled mass of code and confusing programs

like the rest of the operating system. On the other hand, it hasn’t become

significantly more useful either. Indeed, in more than 15 years, the Unix

system for on-line documentation has only undergone two significant

advances:

1. catman, in which programmers had the “breakthrough” realization
   that they could store the man pages as both nroff source files and as
   files that had already been processed, so that they would appear
   faster on the screen.
   With today’s fast processors, a hack like catman isn’t need any-
   more. But all those nroff’ed files still take up megabytes of disk
   space.


2. makewhatis, apropos, and key (which was eventually incorporated
   into man -k), a system that built a permuted index of the man pages
   and made it possible to look up a man page without knowing the
   exact title of the program for which you were looking. (These
   utilities are actually shipped disabled with many versions of Unix
   shipping today, which makes them deliver a cryptic error when run
   by the naive user.)

Meanwhile, advances in electronic publishing have flown past the Unix

man system. Today’s hypertext systems let you jump from article to article

in a large database at the click of a mouse button; man pages, by contrast,

merely print a section called “SEE ALSO” at the bottom of each page and

invite the user to type “man something else” on the command line follow-

ing the prompt. How about indexing on-line documentation? These days

you can buy a CD-ROM edition of the Oxford English Dictionary that