For Programmers, Not Users 53 /lib/cpp /lib/ /usr/local/lib/ /cpp next% Hmm… Excuse us for one second: % ls /lib cpp* gcrt0.o libsys_s.a cpp-precomp* i386/ m68k/ crt0.o libsys_p.a posixcrt0.o next% strings /lib/cpp-precomp | grep / /*%s*/ //%s /usr/local/include /NextDeveloper/Headers /NextDeveloper/Headers/ansi /NextDeveloper/Headers/bsd /LocalDeveloper/Headers /LocalDeveloper/Headers/ansi /LocalDeveloper/Headers/bsd /NextDeveloper/2.0CompatibleHeaders %s/%s /lib/%s/specs next% Silly us. NEXTSTEP’s /lib/cpp calls /lib/cpp-precomp. You won’t find that documented on the man page either: next% man cpp-precomp No manual entry for cpp-precomp. For Programmers, Not Users Don’t blame Ken and Dennis for the sorry state of Unix documentation today. When the documentation framework was laid down, standards for documentation that were prevalent in the rest of the computer industry didn’t apply. Traps, bugs, and potential pitfalls were documented more fre- quently than features because the people who read the documents were, for the most part, the people who were developing the system. For many of these developers, the real function of Unix’s “man” pages was as a place to collect bug reports. The notion that Unix documentation is for naive, or merely inexpert users, programmers, and system administrators is a recent

54 Documentation? invention. Sadly, it hasn’t been very successful because of the underlying Unix documentation model established in the mid 1970s. The Unix world acknowledges, but it does not apologize for, this sorry state of affairs. Life with Unix states the Unix attitude toward documenta- tion rather matter-of-factly: The best documentation is the UNIX source. After all, this is what the system uses for documentation when it decides what to do next! The manuals paraphrase the source code, often having been written at different times and by different people than who wrote the code. Think of them as guidelines. Sometimes they are more like wishes… Nonetheless, it is all too common to turn to the source and find options and behaviors that are not documented in the manual. Some- times you find options described in the manual that are unimple- mented and ignored by the source. And that’s for user programs. Inside the kernel, things are much worse. Until very recently, there was simply no vendor-supplied documentation for writing new device drivers or other kernel-level functions. People joked “anyone needing documentation to the kernel functions probably shouldn’t be using them.” The real story was, in fact, far more sinister. The kernel was not docu- mented because AT&T was protecting this sacred code as a “trade secret.” Anyone who tried to write a book that described the Unix internals was courting a lawsuit. The Source Code Is the Documentation As fate would have it, AT&T’s plan backfired. In the absence of written documentation, the only way to get details about how the kernel or user commands worked was by looking at the source code. As a result, Unix sources were widely pirated during the operating system’s first 20 years. Consultants, programmers, and system administrators didn’t copy the source code because they wanted to compile it and then stamp out illegal Unix clones: they made their copies because they needed the source code for documentation. Copies of Unix source code filtered out of universities to neighboring high-tech companies. Sure it was illegal, but it was justifi- able felony: the documentation provided by the Unix vendors was simply not adequate.