Chapter 11. Documentation and Help

Table of Contents
Man pages
The Texinfo system
Other sources of help

If you make very much use of any computer system, you will find yourself needing help. This may be even more true with unix systems, where much of the strength of the environment depends on typed commands. Luckily, unix systems typically have generous amounts of online documentation.

Man pages

The most traditional form of documentation on a unix system is the collection of man, short for manual, pages. The man page for a program can be accessed using the man command. To learn about a program, type ``man'' and the name of the program, and a browsable set of directions is displayed (shown below in the example). For example, to learn about the ls program, type man ls. Almost all commands have man pages. Even the man program itself has a man page (to read it, do man man).

Example 11-1. Viewing the ls man page


LS(1)                          FSF                          LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List information about the FILEs (the current directory by
       default).  Sort entries alphabetically if none of -cftuSUX
       nor --sort.

       -a, --all
              do not hide entries starting with .

       -A, --almost-all
              do not list implied . and ..

       -b, --escape
              print octal escapes for nongraphic characters

       --block-size=SIZE
              use SIZE-byte blocks

       -B, --ignore-backups
              do not list implied entries ending with ~

       -c     with  -lt:  sort  by, and show, ctime (time of last
              modification of file status information)  with  -l:
              show  ctime  and  sort  by  name otherwise: sort by
              ctime
lines 1-34 

Since the man environment is interactive, it is helpful to know some of the keystrokes for navigating through it. As with most unix pagers (programs that show data one page at a time), Space or f moves one page forward. Use b to move one page backward, / to search for a word, and n to repeat the last search. Finally, use q to quit. To learn other useful keys, see the man pages for more or less, two popular pagers. Also check out the Section called Environment variables in Chapter 4 to learn how to set a default pager.

Sometimes you will need help, but you will not know the name of the command to ask for. When this happens, the apropos command is very helpful. For example, to find help related to web browsers, try apropos browser for a list of possible topics. Apropos will do a keyword search through the description sections of man pages and list the results, in this case including the names of web browsers on your system. Sometimes a little creativity is required as well. For example, to learn how to delete a file, you might be tempted to try apropos delete without success. However, apropos remove lists, among other things, the desired rm command.

One note about man pages. Most beginners find them daunting at first. A good man page is very detailed, usually containing more detail than a beginner wants. Amazingly enough, one day you'll find yourself wishing man pages had more detail. When that happens you will know you are on your way to becoming a skilled unix user.

Another note is in order. More than just programs are documented by man pages. Many programming topics also have man pages, a real convenience for programmers. For example, there is a mkdir command for making a new directory, but there is also a mkdir() function that can be used in C programs to make a new directory. Both have man pages. You may, on some occasions, find man returning a page other than the one you seek. You can get man to return all of the pages in turn by passing the -a switch, as in man -a mkdir.