[Chapter 50] Help--Online Documentation, etc.

UNIX Power Tools

UNIX Power ToolsSearch this book
Previous: 49.9 Business Graphics with ipl Chapter 50Next: 50.2 The apropos Command
 

50. Help--Online Documentation, etc.

Contents:
UNIX Online Documentation
The apropos Command
apropos on Systems Without apropos
whatis: One-Line Command Summaries
whereis: Finding Where a Command Is Located
Searching Online Manual Pages
How UNIX Systems Remember Their Name
Which Version Am I Using?
Reading a Permuted Index
Make Your Own Man Pages Without Learning troff
Writing a Simple Man Page with the -man Macros
Common UNIX Error Messages

50.1 UNIX Online Documentation

The UNIX operating system was one of the first to include online documentation. It's not the best in the world - most users who haven't internalized the manual set curse it once a week - but it has proven surprisingly resilient. What's particularly interesting about UNIX's online documentation is that, unlike other early help systems, it isn't an adjunct to another set of printed documentation that contains the "real" truth. The online manual is complete, authoritative, and usually more current than any printed documentation.

The basis for UNIX's online documentation is the man command. Most simply, you use it as follows:

% man topic

where topic is usually the name of some command; but it can also be the name of a system call, a library routine, an I/O device, or an administrative file (or file type). The output from man is usually sent to a pager like more (25.3), which allows you to page through.

The manual pages are grouped into a number of categories. Unfortunately, there are three slightly different groupings: one for Berkeley-based systems, one for System V, and one for systems derived for XENIX. Table 50.1 lists these categories.

Table 50.1: UNIX Manual Page Categories
CategoryBSDSystem VXenix
User commands11u_man
System calls22p_man
Library routines33p_man
I/O and special files47p_man
Administrative files54a_man
Games66 or 1u_man
Miscellaneous75anything goes
Administrative commands88a_man
Maintenance commands81Mu_man or a_man
Local commandsl (letter)*
Obsolete commandso (letter)*

[1] As you can see, System V makes a strange distinction between "administration" and "maintenance"; if you can figure out what they really mean, please let us know! To a poor Berkeley soul, this has never made sense. Some of these categories are subdivided further; for example, you may see section 3S (the standard I/O library), 3M (the mathematics library), 1G (Berkeley graphics), 1V (commands derived from System V), and so on.

[1] System V and Xenix make no provision for "local" or "obsolete" commands in their man system.

If you want to refer to a manual entry in a specific section of the manual, you can give a command like one of these:

% man section topic
% man -s section topic

Some systems require the -s "section" option. For example, if you want to read documentation about the /etc/passwd file (rather than the passwd command) on a System V machine, give the command:

% man -s 4 passwd

This is an easy way to distinguish between topics with the same name, but in different groups.

- ML


Previous: 49.9 Business Graphics with ipl UNIX Power ToolsNext: 50.2 The apropos Command
49.9 Business Graphics with ipl Book Index50.2 The apropos Command

The UNIX CD Bookshelf NavigationThe UNIX CD BookshelfUNIX Power ToolsUNIX in a NutshellLearning the vi Editorsed & awkLearning the Korn ShellLearning the UNIX Operating System