On-line Documentation 47 Waitaminit. There’s no lockf.3 man page on system? Time to try going around the problem: send mail to a regular user of the machine. He replies that he doesn't know where the man page is, but he gets it when he types “man lockf.” The elements of his MANPATH are less than helpful, as his MANPATH is a subset of mine. So I try something other than the brute-force method: michael: strings `which man` | grep "/" | more /usr/catman:/usr/man michael: Aha! /usr/catman! A directory not in my MANPATH! Now to drop by and see if lockf is in there. michael: cd /usr/catman michael: ls a_man g_man local p_man u_man whatis System V default format sucks. What the hell is going on? michael: ls -d */cat3 g_man/cat3 p_man/cat3 michael: cd g_man/cat3 michael: ls standard michael: cd standard michael: ls Bingo! The files scroll off the screen, due to rampant SysV-ism of / bin/ls. Better to just ls a few files instead: michael: ls lock* No match. michael: cd ../../../p_man/cat3 michael: ls I luck out, and see a directory named “standard” at the top of my xterm, which the files have again scrolled off the screen…

48 Documentation? michael: ls lock* No match. michael: cd standard michael: ls lock* lockf.z Oh, goody. It’s compress(1)ed. Why is it compressed, and not stored as plain text? Did SGI think that the space they would save by com- pressing the man pages would make up for the enormous RISC bina- ries that they have lying around? Anyhow, might as well read it while I’m here. michael: zcat lockf lockf.Z: No such file or directory michael: zcat lockf.z lockf.z.Z: No such file or directory Sigh. I forget exactly how inflexible zcat is. michael: cp lockf.z ~/lockf.Z cd zcat lockf | more lockf.Z: not in compressed format It’s not compress(1)ed? Growl. The least they could do is make it easily people-readable. So I edit my .cshrc to add /usr/catman to already-huge MANPATH and try again: michael: source .cshrc michael: man lockf And, sure enough, it’s there, and non-portable as the rest of Unix. No Manual Entry for “Well Thought-Out” The Unix approach to on-line documentation works fine if you are inter- ested in documenting a few hundred programs and commands that you, for the most part, can keep in your head anyway. It starts to break down as the number of entries in the system approaches a thousand add more entries, written by hundreds of authors spread over the continent, and the swelling, itching brain shakes with spasms and strange convulsions. Date: Thu, 20 Dec 90 3:20:13 EST From: Rob Austein sra@lcs.mit.edu To: UNIX-HATERS Subject: Don’t call your program “local” if you intend to document it