Rozdział 7. Rozwiązywanie problemów i poszukiwanie informacji

Manual pages, while relatively terse in style, contain a great deal of essential information. We will quickly go over the command for viewing them, provided by the man-db package. 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 POWTÓRKA Powłoka, interpreter wiersza poleceń).

Man pages not only document commands and programs accessible from the command line, but also configuration files, system calls, 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:

Jest możliwość określenia konkretnej części strony podręcznika, której szukasz: aby zobaczyć dokumentację dla wywołania systemowego read, musiałbyś wpisać man 2 read. Kiedy nie określimy wprost konkretnej strony podręcznika, zostanie wyświetlona pierwsza część, która zawiera stronę z szukaną nazwą. Dlatego też man shadow zwraca shadow(5) ponieważ nie ma stron dla shadow w częściach od 1 do 4.

$ whatis scp
scp (1)              - OpenSSH secure file copy

Oczywiście, jeżeli nie znasz nazw poleceń, podręcznik systemowy na niewiele Ci się zda. Na tę okazję powstało polecenie apropos, które pomaga przeprowadzić wyszukiwanie w podręczniku, lub ściślej mówiąc - w skróconych opisach. Każda strona podręcznika zasadniczo zaczyna się jednolinijkowym podsumowaniem. apropos zwraca listę stron podręcznika, których skrócone opisy zawierają poszukiwane wyrażenie. Jeżeli dobrze się je dobierze, bez problemu znajdzie się szukane polecenie.

$ apropos "copy file"
cp (1)               - copy files and directories
cp (1posix)          - copy files
cpio (1)             - copy files to and from archives
exec (1posix)        - execute commands and open, close, or copy file descriptors
install (1)          - copy files and set attributes
ntfscp (8)           - copy file to an NTFS volume.

The man command is not the only means of consulting the manual pages, since khelpcenter and konqueror (by 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 after following the instructions in /usr/share/doc/man2html/README.Debian:

Zazwyczaj potrzebny jest do tego serwer. Dlatego należy zainstalować ten pakiet na jednym z serwerów: wszyscy użytkownicy będą mogli z niego korzystać (w tym użytkownicy systemów innych niż Linux) a Ty unikniesz ustawiania serwera HTTP na każdej stacji roboczej osobno. Jeżeli Twój serwer jest także dostępny z poziomu innych sieci, możesz chieć ograniczyć dostęp do tej usługi tylko dla użytkowników sieci lokalnej.

Last but not least, you can view all manual pages available in Debian (even those that are not installed on your machine) on the manpages.debian.org service. It offers each manual page in multiple versions, one for each Debian release.

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 default program to view these documents (it is called info) is also slightly more complex. You would be well advised to use pinfo instead (from the pinfo package).

The info documentation has a hierarchical structure, and if you invoke pinfo without parameters, it will display a list of the nodes available at the first level. Usually, nodes bear the name of the corresponding commands.

With pinfo navigating between these nodes is easy to achieve with the arrow keys. Alternatively, you could also use a graphical browser, which is a lot more user-friendly. Again, konqueror and yelp work; the info2www package also provides a web interface.

Note that the info system is not suitable for translation, unlike the man page system. info documents are thus almost always in English. However, when you ask the pinfo 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.

Każdy pakiet zawiera swoją własną dokumentację. Nawet najmniej popularne programy, zasadniczo, posiadają plik README, który zawiera pewne ciekawe lub ważne informacje na jego temat. Taka dokumentacja jest instalowana w katalogu /usr/share/doc/pakiet/ (gdzie pakiet oznacza nazwę pakietu). Jeżeli dokumentacja jest wyjątkowo obszerna, może nie być zawarta w głównym pakiecie programu, ale przerzucona do osobnego pakietu, który zazwyczaj ma nazwę w formie pakiet-doc. W głównym pakiecie ogólnie umieszcza się informację zachęcającą do pobrania pakietu dokumentacji, żeby było ją łatwiej znaleźć.

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 (see Sekcja 6.7.2, „Obsługa Problemów po Uaktualnieniu”).

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. Problems that you may encounter have often 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 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 FSF's Free Software Directory, or search directly with a search engine, such as Google, DuckDuckGo, Yahoo, etc.

You might also want to check the Debian wiki, a collaborative website where anybody, even new 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:

Debian also provides tutorials for its users:

All 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. Further many tutorials nowadays are provided by bloggers, sharing their individual solution with the interested reader. They often lack important information, i.e. the reason why some configuration has been chosen over another, or why some option has been enabled or disabled. Because blogging and creating personal websites made it so easy to share, many of these often short tutorials exist, but only a few are actively maintained and well-kept. This can make it hard to find the "right" one for you. This is all part of the joys of working in a volunteer environment and without constraints…