Software documentation is a very hot subject. It continues to be debated in all sorts of forums
from USENET newsgroups to user groups. Unless the product is very intuitive, improperly documented
software can be almost worthless to use. Even if intuitive to use, many functions remain hidden
unless you have decent documentation. Unfortunately for many, UNIX
is not very intuitive. Therefore, good documentation is essential to be able to use Linux to its
Unlike a commercial UNIX
implementation, Linux does not provide you with a bound set of manuals
that you can refer to. The documentation that is available is found in a large number of documents
usually provided with your Linux distribution. Because the documentation was developed by many
different people at many different locations, there is no single entity that manages it all.
The Linux Documentation Project (LDP) was organized for this very reason. More and more
documents are being produced as Linux develops. There are many HOWTOs available that give
step-by-step instructions to perform various tasks. These are typically quite long, but go into
the detail necessary
to not only solve specific problems, but help you configure detailed aspects of your system.
There are also a number of "mini" HOWTOs, which discuss less extensive topics.
In many cases, these were written by the program
developers themselves, giving you insights into the software that you normally wouldn't get.
You'll find ASCII
versions on the CD under the doc/HOWTO directory and
HTML versions under doc/HTML. The most current HOWTOs can be found on the
LDP Web site.
Many HOWTOs will have a section of frequently asked questions (FAQs). As their name implies,
these are lists of questions that are most frequently asked about the particular topic.
Sometimes these are questions about specific
error messages, but are often questions about implementing certain features.
These can also be found on the LDP Web site.
The Brief Linux FAQ (BLFAQ) provides answers to basic questions about
working with Linux.
Unfortunately, in my experience in tech support, few administrators and even fewer users take
the time to read the manuals. This is not good for two important reasons. The first is obviously the
wasted time spent calling support or posting messages to the Internet for help on things in the
manual. The second is that you miss many of the powerful features of the various programs. When you
call support, you usually get a quick and simple answer. Tech support does not have the time to
train you how to use a particular program. Two weeks later, when you try to do something else with
the same program, you're on the phone again.
The biggest problem is that people see the long list of files containing the necessary
information and are immediately intimidated. Although they would rather spend the money to have
support explain things rather than spend time "wading" through documentation, it is not as
easy with Linux. There is no tech support office. There is an increasing number of consulting firms
specializing in Linux, but most companies cannot afford the thousands of dollars needed to get that
kind of service.
The nice thing is that you don't have to. You neither have to wade through the manuals nor
spend the money to have support hold your hand. Most of the necessary information is available
on-line in the form of manual pages (man-pages) and other documentation.
Built into the system is a command to read these man-pages: man.
By typing man <command>,
you can find out many details about the command <command>. There are several different options
to man that you can use. You can find out more about them by typing man man, which will bring up
the man man-page (or, the man-page
When referring to a particular command in Linux documentation, you very often will see the name
followed by a letter or number in parenthesis, such as ls(1). This indicates that the
ls command can
be found in section 1 of the man-pages. This dates back to the time when man-pages came in books (as
they often still do). By including the section, you could more quickly find what you were looking
for. Here I will be making references to files usually as examples. I will say only what section the
files are in when I explicitly point you toward the man-page.
For a list of what sections are available, see the table below or the man man-page. If you are
looking for the man-page of a particular command and know what section it is in, it is often better to specify the
section. Sometimes there are multiple man-pages in different sections. For
example, the passwd man-page in section 1 lists the details of the passwd
command. The passwd man-page in section 5, lists the details of the /etc/passwd
file. Therefore,if you wanted the man-page on the passwd file, you would use the -S option (for "section")
and then to specify section 4, you would call up the man-page like this:
Table - Manual Page Sections
||Commands, Utilities and other executable programs, which are
||Special files, typically device files in /dev
||File formats and their respective conventions, layout
||System administration commands
Man-pages usually have the same basic format, although not all of the different sections are there
for every man-page. At the very top is the section NAME. This is simply the name of the command or
file being discussed. Next is the SYNOPSIS section, which provides a brief overview of the
command or file. If the man-page is talking about a command or utility, the SYNOPSIS section may
list generalized examples of how the command syntax is put together. The tar man-page is a good
The DESCRIPTION section, is just that: a description of the command. Here you get a
detailed overview about what the command does or what information a particular file contains.
Under OPTIONS, you will find details of the various command line switches and parameters, if any.
The SEE ALSO section lists other man-pages or other documentation, if any, that contain addition
information. Often if there is an info page (see below) for this man-page it is listed here. BUGS
is a list of known bugs, other problems and limitations the program might have. Sometimes, there is
an AUTHOR section, which lists the author(s) of the program and possibly how to contact them.
Note that these sections are just a sampling and not all man-pages have these sections. Some
man-pages have other sections that are not applicable to other man-pages. In general, the section
headings are pretty straightforward. If all else fails, look at the man man-page.
In many cases, each section has its own man page. By running
you can see which sections have an introduction, which sometimes provides useful information about
that section of man-pages.
Sometimes applications will provide their own man-pages and end up putting them in a directory that
the normal man command doesn't use. If the installation routine for the application is well
written, then you should not have a problem. Otherwise you need to tell the man command where to
look. Some distributions use the /etc/manpath.config file (which has its own man-page), which contains (among
other things) the directories that man should search. You might
also have to define the MANPATH variable explicitly to tell the system where to look. Note that
typically, if the MANPATH variable is set., the manpath.config file is ignored.
manual pages are not stored in the original form, but in a pre-formatted form "cat pages". This is
done to speed up the display, so that the man pages do not need to be processed each time they are
called. I have worked on some systems where these pages are not created by default and every single
man-page reports "No manual entry for (whatever)". To solve this problem simply run the command
catman. It may take a while so be patient.
If you want to look at multiple man-pages, you can simply input them on the same line. For example, to look
at the grep and find man-pages, you might have a command that looks like this:
By pressing 'q' or waiting until the page is displayed, you will be prompted to go to the next file. If the same term
is in multiple sections, you can use the -a option to display all of them. For example:
Sometimes it will happen that you know there is a
command that performs a certain function, but you are not sure what the name is. If you don't know
the name of the command, it is hard to look for the man-page. Well, that is what the -k option is
for (-k for "keyword"). The basic syntax is:
where "keyword" is a keyword in the description of the command you are looking for. Note
that "man -k" is the same thing as the apropos command. If you have a command and want to know
what the command does, you can use the whatis command. For example, like this:
which would give you this:
diff (1) - find differences between two files
Paired with whatis is the whereis command. The
whereis command will tell you the path to the command that is being executed, just
like the which that we discussed in the section on directory path.
However, whereis will also show you other information like the location of the man-pages,
source code, and so forth. This might give us something like this:
find: /usr/bin/find /usr/share/man/man1/find.1.gz /usr/share/man/mann/find.n.gz
Should there be other, related files (like /usr/bin/passwd and /etc/passwd), whereis will display these, as well.
For many commands, as well as general system information, there are additional info files that you
access using the info command. Although there are not as many info files as there are commands,
the info files contain information on more aspects of your system. In many cases, the information
contained in the info files is identical with the man-pages. To get started, simply type "info"
and the command line. To get the information page for particular command, like with man you give the
command name as an option to the info command. So, to get information about the tar command, you would
which would bring up something like this:
An info page. (interactive)
If you are familiar with the emacs editor, then navigation is fairly easy. However, for the most part, you can move
around fairly well using the arrow keys and the enter key. As you can see in the image above, menu items are
indicated with an asterisk (*). Move with an arrow key or the tab key until the desired item is highlighted and then press enter to
select that item. Depending how your keyboard is layed out, you can move up and down within each page using
the page-up and page-down keys.
Rather than moving through the menu items, you can simply press 'm' which will prompt you to input the text
of the menu item you want to select. You don't have to input the complete text, but just enough to differentiate it
from other items.
Some commands (including info itself) have a tutorial section. This provides examples and step-by-step
instructions how to use the specific command. To reach the info tutorial from the info page for any command, simply press 'h'
SuSE takes this even further by providing you an online copy of their online
support knowledge base. This can also be accessed on the internet
Before installing any Linux system it is best to know if there is anything to watch out for. For
commercial software, this is usually the release notes. Often there is a file in the root directory
of the CD (if that's what you are installing from) called README or README.1ST
which mentions the things to look out for. Typically when you download software or even source
code from the Internet, there is a README file. If this file does not give you specific information
about installing the software, it will tell you where to find it.