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

On-line Documentation 49 It turns out that there is no way to obtain a manual page for a pro- gram called “local.” If you try, even if you explicitly specify the manual section number (great organizational scheme, huh?), you get the following message: sra@mintaka man 8 local But what do you want from section local? Shell Documentation The Unix shells have always presented a problem for Unix documentation writers: The shells, after all, have built-in commands. Should built-ins be documented on their own man pages or on the man page for the shell? Tra- ditionally, these programs have been documented on the shell page. This approach is logically consistent, since there is no while or if or set com- mand. That these commands look like real commands is an illusion. Unfor- tunately, this attitude causes problems for new users—the very people for whom documentation should be written. For example, a user might hear that Unix has a “history” feature which saves them the trouble of having to retype a command that they have previ- ously typed. To find out more about the “history” command, an aspiring novice might try: % man history No manual entry for history. That’s because “history” is a built-in shell command. There are many of them. Try to find a complete list. (Go ahead, looking at the man page for sh or csh isn’t cheating.) Of course, perhaps it is better that each shell’s built-ins are documented on the page of the shell, rather than their own page. After all, different shells have commands that have the same names, but different functions. Imagine trying to write a “man page” for the set command. Such a man page would probably consist of a single line: “But which set command do you want?” Date: Thu, 24 Sep 92 16:25:49 -0400 From: Systems Anarchist clennox@ftp.com To: UNIX-HATERS Subject: consistency is too much of a drag for Unix weenies I recently had to help a frustrated Unix newbie with these gems: