Before you can understand what is really going on when there is a problem, you need to know the theoretical role played by each program involved in the problem. To do this, the best reflex to have is consult their documentation; but since these documentations are many and widely dispersed, you should know all the places where they can be found.
7.1.1. Manual Pages
CULTURE RTFM
This acronym stands for “Read the F**king Manual”, but can also be expanded in a friendlier variant, “Read the Fine Manual”. This phrase is sometimes used in (terse) responses to questions from newbies. It is rather abrupt, and betrays a certain annoyance at a question asked by someone who has not even bothered to read the documentation. Some say that this classic response is better than no response at all (since it indicates that the documentation contains the information sought), or than a more verbose and angry answer.
In any case, if someone responds “RTFM” to you, it is often wise not to take offense. Since this answer may be perceived as vexing, you might want to try and avoid receiving it. If the information that you need is not in the manual, which can happen, you might want to say so, preferably in your initial question. You should also describe the various steps that you have personally taken to find information before you raised a question on a forum. You can, before using forums, follow a few common sense recommendations, which have been listed by Eric Raymond.
→ http://catb.org/~esr/faqs/smart-questions.html
Manual pages, while relatively terse, contain a great deal of essential information. We will quickly go over the command for viewing them. Simply type man manual-page — the manual page usually goes by the same name as the command whose documentation is sought. For example, to learn about the possible options for the cp command, you would type the man cp command at the shell prompt (see sidebar).
BACK TO BASICS The shell, a command line interpreter
A command line interpreter, also called a “shell”, is a program that executes commands that are either entered by the user or stored in a script. In interactive mode, it displays a prompt (usually ending in $ for a normal user, or by # for an administrator) indicating that it is ready to read a new command. Appendix B, Short Remedial Course describes the basics of using the shell.
The default and most commonly used shell is bash (Bourne Again SHell), but there are others, including dash, csh, tcsh and zsh.
Among other things, most shells offer help during input at the prompt, such as the completion of command or file names (which you can generally activate by pressing the tab key), or recalling previous commands (history management).
Man pages not only document programs accessible from the command line, but also configuration files, system calls, C library functions, and so forth. Sometimes names can collide. For example, the shell's read command has the same name as the system call read. This is why manual pages are organized in numbered sections:
commands that can be executed from the command line;
system calls (functions provided by the kernel);
library functions (provided by system libraries);
devices (under Unix, these are special files, usually placed in the /dev/ directory);
config files (formats and conventions);
games;
sets of macros and standards;
system administration commands;
kernel routines.
It is possible to specify the section of the manual page that you are looking for: to view the documentation for the read system call, you would type man 2 read. When no section is explicitly specified, the first section that has a manual page with the requested name will be shown. Thus, man shadow returns shadow(5) because there are no manual pages for shadow in sections 1 to 4.
TIP whatis
If you do not want to look at the full manual page, but only a short description to confirm that it is what you are looking for, simply enter whatis command.
$ whatis scp
scp (1) - secure copy (remote file copy program)
This short description is included in the NAME section at the beginning of all manual pages.
Of course, if you do not know the names of the commands, the manual is not going to be of much use to you. This is the purpose of the apropos command, which helps you conduct a search in the manual pages, or more specifically in their short descriptions. Each manual page begins essentially with a one line summary. apropos returns a list of manual pages that mention the keyword(s) requested. If you choose them well, you will find the name of the command that you need.
Example 7.1. Finding cp with apropos
$ apropos "copy file"
cp (1) - copy files and directories
cpio (1) - copy files to and from archives
hcopy (1) - copy files from or to an HFS volume
install (1) - copy files and set attributes
TIP Browsing by following links
Many manual pages have a “SEE ALSO” section, usually at the end. It refers to other manual pages relevant to similar commands, or to external documentation. In this way, it is possible to find relevant documentation even when the first choice is not optimal.
The man command is not the only means of consulting the manual pages, since konqueror (in KDE) and yelp (under GNOME) programs also offer this possibility. There is also a web interface, provided by the man2html package, which allows you to view manual pages in a web browser. On a computer where this package is installed, use this URL:
→ http://localhost/cgi-bin/man/man2html
This utility requires a web server. This is why you should choose to install this package on one of your servers: all users of the local network could benefit from this service (including non-Linux machines), and this will allow you not to set up an HTTP server on each workstation. If your server is also accessible from other networks, it may be desirable to restrict access to this service only to users of the local network.
DEBIAN POLICY Required man pages
Debian requires each program to have a manual page. If the upstream author does not provide one, the Debian package maintainer will usually write a minimal page that will at the very least direct the reader to the location of the original documentation.
7.1.2. info Documents
The GNU project has written manuals for most of its programs in the info format; this is why many manual pages refer to the corresponding info documentation. This format offers some advantages, but the program to view these documents is also slightly more complex.
It is of course called info, and it takes the name of the “node” to be consulted as argument. The info documentation has a hierarchical structure, and if you invoke info without parameters, it will display a list of the nodes available at the first level. Usually, nodes bear the name of the corresponding commands.