7.1. Documentation Sources
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 can be scattered far and wide, you should know all the places where they can be found.
Manual pages, while relatively terse in style, 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).
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 read system call. 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 (on Unix-like systems, these are special files, usually placed in the /dev/ directory);
configuration 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.
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 whose summary mentions the requested keyword(s). 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
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:
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.
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.
The navigation controls in the documentation are not particularly intuitive. The best method to familiarize yourself with the program is probably to invoke it, then enter
h (for “help”), and then follow the instructions to learn through practice. Alternatively, you could also use a graphical browser, which is a lot more user-friendly. Again,
konqueror and
yelp work; the
info2www also provides a web interface.
Note that the info system does not allow translation, unlike the man page system. info documents are thus always in English. However, when you ask the info program to display a non-existing info page, it will fall back on the man page by the same name (if it exists), which might be translated.
7.1.3. Specific Documentation
Each package includes its own documentation. Even the least well documented programs generally have a README file containing some interesting and/or important information. This documentation is installed in the /usr/share/doc/package/ directory (where package represents the name of the package). If the documentation is particularly large, it may not be included in the program's main package, but might be offloaded to a dedicated package which is usually named package-doc. The main package generally recommends the documentation package so that you can easily find it.
The /usr/share/doc/package/ directory also contains some files provided by Debian which complete the documentation by specifying the package's particularities or improvements compared to a traditional installation of the software. The README.Debian file also indicates all of the adaptations that were made to comply with the Debian Policy. The changelog.Debian.gz file allows the user to follow the modifications made to the package over time: it is very useful to try to understand what has changed between two installed versions that do not have the same behavior. Finally, there is sometimes a NEWS.Debian.gz file which documents the major changes in the program that may directly concern the administrator.
In most cases, free software programs have websites that are used to distribute it and to bring together the community of its developers and users. These sites are frequently loaded with relevant information in various forms: official documentation, FAQ (Frequently Asked Questions), mailing list archives, etc. Often, problems that you may have have already been the subject of many questions; the FAQ or mailing list archives may have a solution for it. A good mastery of search engines will prove immensely valuable to find relevant pages quickly (by restricting the search to the Internet domain or sub-domain dedicated to the program). If the search returns too many pages or if the results do not match what you seek, you can add the keyword debian to limit results and target relevant information.
If you do not know the address for the software's website, there are various means of getting it. First, check if there is a
Homepage field in the package's meta-information (
apt-cache show package). Alternately, the package description may contain a link to the program's official website. If no URL is indicated, look at
/usr/share/doc/package/copyright. The Debian maintainer generally indicates in this file where they got the program's source code, and this is likely to be the website that you need to find. If at this stage your search is still unfruitful, consult a free software directory, such as Freecode.com (formerly Freshmeat.net), or search directly with a search engine, such as Google or Yahoo.
You might also want to check the Debian wiki, a collaborative website where anybody, even simple visitors, can make suggestions directly from their browsers. It is used equally by developers who design and specify their projects, and by users who share their knowledge by writing documents collaboratively.
A howto is a document that describes, in concrete terms and step by step, “how to” reach a predefined goal. The covered goals are relatively varied, but often technical in nature: for example, setting up IP Masquerading, configuring software RAID, installing a Samba server, etc. These documents often attempt to cover all of the potential problems likely to occur during the implementation of a given technology.
Many such tutorials are managed by the Linux Documentation Project (LDP), whose website hosts all of these documents:
These documents should be taken with a grain of salt. They are often several years old; the information they contain is sometimes obsolete. This phenomenon is even more frequent for their translations, since updates are neither systematic nor instant after the publication of a new version of the original documents. This is part of the joys of working in a volunteer environment and without constraints…
