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.
→ http://localhost/cgi-bin/info2www
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.
In the /usr/share/doc/package/ directory there are also some files provided by Debian and 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.
7.1.4. Websites
In most cases, free software programs have websites that are used to distribute it and to unite 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.
TIPS From error to solution
If the software returns a very specific error message, enter it into the search engine (between double quotes, ", in order to search not for individual keywords, but for the complete phrase). In most cases, the first links returned will contain the answer that you need.
In other cases, you will get very general errors, such as “Permission denied”. In this case, it is best to check the permissions of the elements involved (files, user ID, groups, etc.).
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 Freshmeat.net or Framasoft, or search directly with a search engine, such as Google or Yahoo.
→ http://freshmeat.net/
→ http://framasoft.org/
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 as much by developers so as to design and specify their projects, as by users who share their knowledge by writing documents collaboratively.
→ http://wiki.debian.org/
7.1.5. Tutorials (HOWTO)
A howto is a documentation 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:
→ http://www.tldp.org/
To view them locally, just install the doc-linux-html package. Local HTML versions will then be available in the /usr/share/doc/HOWTO/ directory.
Take these documents 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...
7.2. Common Procedures
The purpose of this section is to present some general tips on certain operations that an administrator will frequently have to perform. These procedures will of course not cover every possible case in an exhaustive way, but they may serve as starting points for the more difficult cases.
DISCOVERY Documentation in French
Often, documentation translated into a non-English language is available in a separate package with the name of the corresponding package, followed by -lang (where lang is the two-letter ISO code for the language).
Thus, the apt-howto-fr package contains the French translation of the howto for APT. Likewise, the packages quick-reference-fr and debian-reference-fr (Debian reference) are the French versions of the references guides for Debian (initially written in English by Osamu Aoki).
7.2.1. Configuring a Program
When you want to configure an unknown package, you must proceed in stages. First, you should read what the package maintainer has documented. Reading /usr/share/doc/package/README.Debian will indeed allow you to learn of specific provisions made to simplify the use of the software. It is sometimes essential in order to understand the differences from the original behavior of the program, as described in the general documentation, such as howtos. Sometimes this file also details the most common errors in order for you to avoid wasting time on common problems.
Then, you should look at the software's official documentation — refer to the previous section to identify the various existing documentation sources. The command dpkg -L package gives a list of files included in the package; you can therefore quickly identify the available documentation (as well as the configuration files, located in /etc/). dpkg -s package produces the package headers and shows any possible recommended or suggested packages; in there, you can find documentation or a utility that will ease the configuration of the software.