3 Documentation? What Documentation? “One of the advantages of using UNIX to teach an operating systems course is the sources and documentation will easily fit into a stu- dent’s briefcase.” —John Lions, University of New South Wales, talking about Version 6, circa 1976 For years, there were three simple sources for detailed Unix knowledge: 1. Read the source code. 2. Write your own version. 3. Call up the program’s author on the phone (or inquire over the network via e-mail). Unix was like Homer, handed down as oral wisdom. There simply were no serious Unix users who were not also kernel hackers—or at least had ker- nel hackers in easy reach. What documentation was actually written—the infamous Unix “man pages”—was really nothing more than a collection of reminders for people who already knew what they were doing. The Unix documentation was so concise that you could read it all in an afternoon.

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