Linux Documentation

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 fullest extent.

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 for man).

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:

man -S 5 passwd

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 example.

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

man -k intro

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.

Often the 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:

man grep find

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:

man -a passwd

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:

man -k keyword

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:

whatis diff

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:

whereis find

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 input:

info tar

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' (for "help").

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 here.

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.

User Comments: