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

46 Documentation? Nothing showed up, so I started looking in /usr/man. This is despite the fact that I know that things can be elsewhere, and that my MAN- PATH already contained /usr/man (and every other directory in which I had found useful man pages on any system). I expected to see something like: michael: cd /usr/man michael: ls man1 man2 man3 man4 man5 man6 man7 man8 manl What I got was: michael: cd /usr/man michael: ls local p_man u_man (%*&@#+! SysV-ism) Now, other than the SysV vs. BSD ls-format- ting difference, I thought this was rather weird. But, I kept on, look- ing for anything that looked like cat3 or man3: michael: cd local michael: ls kermit.1c michael: cd ../p_man michael: ls man3 michael: cd ../u_man man1 man4 michael: cd ../p_man/man3 michael: ls Xm Now, there’s something wrong with finding only an X subdirectory in man3. What next? The brute-force method: michael: cd / michael: find / -name lockf.3 -print michael: