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

52 Documentation? Mail version SMI 4.0 Sat Apr 9 01:54:23 PDT 1988 Type ? for help. "/usr/spool/mail/chris": 3 messages 3 new N 1 chris Thu Dec 22 15:49 19/643 editor saved “trash1” N 2 root Tue Jan 3 10:35 19/636 editor saved “trash1” N 3 chris Tue Jan 3 14:40 19/656 editor saved “/tmp/ma8” & ? Unknown command: "?" & What production environment, especially one that is old enough to drive, vote, and drink 3.2 beers, should reject the very commands that it tells you to enter? Why does the user guide bear no relationship to reality? Why do the commands have cryptic names that have no bearing on their function? We don’t know what Heiny’s problem was like a few others we’ve men- tioned in this chapter, his bug seems to be fixed now. Or perhaps it just moved to a different application. Date: Tuesday, September 29, 1992 7:47PM From: Mark Lottor mkl@nw.com To: UNIX-HATERS Subject: no comments needed fs2# add_client usage: add_client [options] clients add_client -i|-p [options] [clients] -i interactive mode - invoke full-screen mode [other options deleted for clarity] fs2# add_client -i Interactive mode uses no command line arguments How to Get Real Documentation Actually, the best form of Unix documentation is frequently running the strings command over a program’s object code. Using strings, you can get a complete list of the program’s hard-coded file name, environment vari- ables, undocumented options, obscure error messages, and so forth. For example, if you want to find out where the cpp program searches for #include files, you are much better off using strings than man: next% man cpp No manual entry for cpp. next% strings /lib/cpp | grep /