第 7 章 問題の解決と関連情報の探索

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 「BACK TO BASICS シェル、コマンドラインインタプリタ」).

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:

探しているマニュアルページのセクション番号を指定することも可能です。すなわち read システムコールに関する文書を見るには、man 2 read と入力してください。セクション番号を指定しなかった場合、指定した名前に関するマニュアルページが最初に見つかったセクションから内容が表示されます。そんなわけで、man shadow は shadow(5) を表示します。なぜなら、shadow に関するマニュアルページは第 1 セクションから第 4 セクションの間に存在しないからです。

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

もちろん、コマンドの名前を知らなければ、マニュアルページは役に立ちません。コマンドの名前がわからない場合に役立つのが apropos コマンドです。apropos コマンドはマニュアルページ内、正確に言うと短い説明文内を検索します。それぞれのマニュアルページは基本的に 1 行の要旨から始まります。apropos はマニュアルページの要旨にキーワードを含むプログラムのマニュアルページのリストを返します。キーワードをうまく選べば、必要なコマンドの名前を見つけることができるでしょう。

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

man2html ユーティリティを動かすにはウェブサーバが必要です。このため、man2html サービスをインストールするマシンは管理下にあるサーバの 1 台だけにするべきです。こうすることで、ローカルネットワークのユーザは全員 (非 Linux マシンでも) man2html サービスからの恩恵を受けることができますし、HTTP サーバを各ワークステーションにセットアップする必要がなくなります。man2html サービスをインストールしたマシンに他のネットワークからもアクセスできる場合、man2html サービスにアクセスできるのはローカルネットワークのユーザだけに制限することが望ましいです。

最後に重要なことですが、Debian が運営する manpages.debian.org サービスを使えば、自分のコンピュータにインストールされていないマニュアルを含むすべてのマニュアルを見ることができます。このサービスはすべてのマニュアルページを Debian リリース毎に提供しています。

これまでずっと GNU プロジェクトはほとんどのプログラムのマニュアルを info フォーマットで書き続けてきました。そのため、多くのマニュアルページでは対応する info 文書を参照することが求められています。info フォーマットにはいくつかの利点がありますが、info 文書を表示するためにデフォルトで用意されているプログラム (これは info と呼ばれています) は若干理解に苦労するものです。info の代わりに pinfo (pinfo パッケージに含まれます) を使うのが賢明かもしれません。

info 文書は階層的な構造をしており、pinfo をパラメータなしで実行した場合、最初の階層から利用できるノードのリストが表示されます。通常、ノードには対応するコマンドの名前が付けられています。

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.

info システムは man ページシステムと異なり翻訳に適さないシステムであるという点に注意してください。そんなわけで、info 文書はほとんど常に英語で書かれています。しかしながら、pinfo プログラムに対して存在しない info ページを表示するよう要求した場合、プログラムは同名の man ページを (存在すれば) 表示します。これは翻訳されているかもしれません。

各パッケージには独自の文書が含まれています。最も貧弱な文書しか持たないプログラムの場合でも、興味深く重要な情報を含む README ファイルは提供されています。README ファイルは /usr/share/doc/package/ ディレクトリにインストールされます (ここで package はパッケージ名を示します)。README ファイルのサイズが著しく大きな場合、README ファイルはプログラムのメインパッケージに含まれないかもしれません。この場合、通常 package-doc と名付けられた専用の文書パッケージに含まれています。メインパッケージは通常文書パッケージを推奨します。そうすれば、ユーザが簡単に文書を見つけられるからです。

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 第 6.7.2 節「アップグレードの後から問題を取り扱う」).

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.

ソフトウェアのウェブサイトのアドレスがわからない場合、さまざまな手段でそれを知ることができます。最初に、パッケージのメタ情報を表示して (apt show package) Homepage フィールドがあるか確認してください。別の方法として、パッケージ説明文にプログラムの公式サイトへのリンクが載っているかもしれません。URL が見つからなければ、/usr/share/doc/package/copyright を確認してください。Debian メンテナは通常このファイルの中に、プログラムのソースコードを手に入れた場所を示しており、これこそが探しているウェブサイトのものである可能性が高いです。それでもなおウェブサイトがわからない場合、たとえば FSF の フリーソフトウェアディレクトリなどのフリーソフトウェアディレクトリを確認するか、Google、DuckDuckGo、Yahoo などの検索エンジンで直接検索してください。

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…