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

This Is Internal Documentation? 51 Is this documented somewhere or do I have to buy a source license and learn to read C? “man fg” gets me the CSH_BUILTINS man page[s], and I’ve never been able to find anything useful in there. If I search this man page for “job” it doesn’t tell me this anywhere. It does, however, tell me that if I type “% job &” that I can take a job out of the background and put it back in the background again. I know that this is function- ality that I will use far more often than I will want to refer to a job by name. This Is Internal Documentation? Some of the larger Unix utilities provide their own on-line documentation as well. For many programs, the “on-line” docs are in the form of a cryptic one-line “usage” statement. Here is the “usage” line for awk: % awk awk: Usage: awk [-f source | 'cmds'] [files] Informative, huh? More complicated programs have more in-depth on-line docs. Unfortunately, you can’t always rely on the documentation matching the program you are running. Date: 3 Jan 89 16:26:25 EST (Tuesday) From: Reverend Heiny Heiny.henr@Xerox.COM To: UNIX-HATERS Subject: A conspiracy uncovered After several hours of dedicated research, I have reached an impor- tant conclusion. Unix sucks. Now, this may come as a surprise to some of you, but it’s true. This research has been validated by independent researchers around the world. More importantly, this is no two-bit suckiness we are talking here. This is major league. Sucks with a capital S. Big time Hooverism. I mean, take the following for example: toolsun% mail