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

On-line Documentation 45 indexes every single word in the entire multivolume set man pages, on the other hand, are still indexed solely by the program’s name and one-line description. Today even DOS now has an indexed, hypertext system for on-line documentation. Man pages, meanwhile, are still formatted for the 80-column, 66-line page of a DEC printing terminal. To be fair, some vendors have been embarassed into writing their own hypertext documentation systems. On those systems, man has become an evolutionary deadend, often times with man pages that are out-of-date, or simply missing altogether. “I Know It’s Here … Somewhere.” For people trying to use man today, one of the biggest problems is telling the program where your man pages actually reside on your system. Back in the early days, finding documentation was easy: it was all in /usr/man. Then the man pages were split into directories by chapter: /usr/man/man1, /usr/man/man2, /usr/man/man3, and so on. Many sites even threw in / usr/man/manl for the “local” man pages. Things got a little confused when AT&T slapped together System V. The directory /usr/man/man1 became /usr/man/c_man, as if a single letter somehow was easier to remember than a single digit. On some systems, / usr/man/manl was moved to /usr/local/man. Companies that were selling their own Unix applications started putting in their own “man” directories. Eventually, Berkeley modified man so that the program would search for its man pages in a set of directories specified by an environment variable called MANPATH. It was a great idea with just one small problem: it didn’t work. Date: Wed, 9 Dec 92 13:17:01 -0500 From: Rainbow Without Eyes michael@porsche.visix.com To: UNIX-HATERS Subject: Man page, man page, who's got the man page? For those of you willing to admit some familiarity with Unix, you know that there are some on-line manual pages in /usr/man, and that this is usually a good place to start looking for documentation about a given function. So when I tried looking for the lockf(3) pages, to find out exactly how non-portable lockf is, I tried this on a SGI Indigo yesterday: michael: man lockf