Section 4.13. Manual Pages

4.13. Manual Pages

The most empowering information you can get is how to conduct your own research. Following this precept, we'll now tell you about the online help system that comes built into Unix systems. It is called manual pages , or manpages for short.

Actually, manual pages are not quite the boon they ought to be. This is because they are short and take a lot of Unix background for granted. Each one focuses on a particular command and rarely helps you decide why you should use that command. Still, they are critical. Commands can vary slightly on different Unix systems, and the manual pages are the most reliable way to find out what your system does. (The Linux Documentation Project deserves a lot of credit for the incredible number of hours they have put into creating manual pages.) To find out about a command, enter a command, such as the following:

 $ man ls 

Manual pages are divided into different sections depending on their purpose. User commands are in section 1, Unix system calls in section 2, and so on. The sections that will interest you most are 1, 5 (file formats), and 8 (system administration commands). When you view manpages online, the section numbers are conceptual; you can optionally specify them when searching for a command:

 $ man 1 ls 

But if you consult a hardcopy manual, you'll find it divided into actual sections according to the numbering scheme. Sometimes an entry in two different sections can have the same name. (For instance, chmod is both a command and a system call.) So you will sometimes see the name of a manual page followed by the section number in parentheses, as in ls(1).

There is one situation in which you will need the section number on the command line: when there are several manual pages for the same keyword (e.g., one for a command with that name and one for a system function with the same name). Suppose you want to look up a library call, but the man command shows you the command because its default search order looks for the command first. In order to see the manual page for the library call, you need to give its section number.

Look near the top of a manual page. The first heading is NAME. Under it is a brief one-line description of the item. These descriptions can be valuable if you're not quite sure what you're looking for. Think of a word related to what you want, and specify it in an apropos command:

 $ apropos edit 

The previous command shows all the manual pages that have something to do with editing. It's a very simple algorithm: apropos simply prints out all the NAME lines that contain the string you request.

Many other utilities, particularly those offered by the desktops discussed in Chapter 3, present manual pages attractively.

Like commands, manual pages are sometimes installed in strange places. For instance, you may install some site-specific programs in the directory /usr/local, and put their manual pages in /usr/local/man. The man command will not automatically look in /usr/local/man, so when you ask for a manual page you may get the message "No manual entry." Fix this by specifying all the top man directories in a variable called MANPATH. For example (you have to put in the actual directories where the manual pages are on your system):

 $ export MANPATH=/usr/man:/usr/local/man 

The syntax is like PATH, described earlier in this chapter. Each pair of directories is separated by a colon. If your shell is csh or tcsh, you need to say:

 $ setenv MANPATH /usr/man:/usr/local/man 

Another environment variable that you may want to set is MANSECT. It determines the order in which the sections of the manual pages are searched for an entry. For example:

 $ export MANSECT="2:3:1:5:4:6:7:8:n:9" 

searches in section 2 first.

Have you read some manual pages and still found yourself confused? They're not meant to be introductions to new topics. Get yourself a good beginner's book about Unix, and come back to manual pages gradually as you become more comfortable on the system; then they'll be irreplaceable.

Manual pages are not the only source of information on Unix systems. Programs from the GNU project often have Info pages that you read with the program info. For example, to read the Info pages for the command find, you would enter:

 info find 

The info program is arcane and has lots of navigation features; to learn it, your best bet is to type Ctrl-H in the info program and read through the Help screen. Fortunately, there are also programs that let you read Info pages more easily, notably tkinfo and kdehelp. These commands use the X Window System to present a graphical interface. You can also read Info pages from Emacs (see "Tutorial and Online Help" in Chapter 19) or can use the command pinfo, available on some Linux distributions, which works more like the Lynx web browser.

In recent times, more and more documentation has been provided in the form of HTML pages. You can read those with any web browser (see Chapter 5). For example, in the Konqueror web browser, you select Open Location from the Location menu and press the button with the folder symbol, which opens an ordinary file selection dialog where you can select your documentation file. Some documentation may also come in PDF files ; these can be read with either the proprietary Acrobat Reader, which comes with many Linux distributions and can otherwise be downloaded from http://www.adobe.com, or with xpdf and the KDE program KGhostview.