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:

50 Documentation? Under the Bourne shell (the ‘standard’ Unix shell), the set command sets option switches. Under the c-shell (the other ‘standard’ Unix shell), ‘set’ sets shell variables. If you do a ‘man set,’ you will get either one or the other definition of the command (depending on the whim of the vendor of that particular Unix system) but usually not both, and sometimes neither, but definitely no clue that another, con- flicting, definition exists. Mistakenly using the ‘set’ syntax for one shell under the other silently fails, without any error or warning whatsoever. To top it off, typing ‘set’ under the Bourne shell lists the shell variables! Craig Undocumented shell built-ins aren’t just a mystery for novice, either. When David Chapman, a leading authority in the field of artificial intelli- gence, complained to UNIX-HATERS that he was having a hard time using the Unix fg command because he couldn’t remember the “job num- bers” used by the C-shell, Robert Seastrom sent this helpful message to David and cc’ed the list: Date: Mon, 7 May 90 18:44:06 EST From: Robert E. Seastrom rs@eddie.mit.edu To: zvona@gang-of-four.stanford.edu Cc: UNIX-HATERS Why don’t you just type “fg %emacs” or simply “%emacs”? Come on, David, there is so much lossage in Unix, you don’t have to go inventing imaginary lossage to complain about! grin The pitiful thing was that David didn’t know that you could simply type “%emacs” to restart a suspended Emacs job. He had never seen it docu- mented anywhere. David Chapman wasn’t the only one many people on UNIX-HATERS sent in e-mail saying that they didn’t know about these funky job-control features of the C-shell either. (Most of the people who read early drafts of this book didn’t know either!) Chris Garrigues was angrier than most: Date: Tue, 8 May 90 11:43 CDT From: Chris Garrigues 7thSon@slcs.slb.com To: Robert E. Seastrom rs@eddie.mit.edu Cc: UNIX-HATERS Subject: Re: today’s gripe: fg %3