On-line Documentation 49It 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 <[email protected]>
To: UNIX-HATERS
Subject: consistency is too much of a drag for Unix weeniesI recently had to help a frustrated Unix newbie with these gems: