Debian JP Project

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

Debian ポリシーマニュアル
Chapter 12 - 文書

12.1 マニュアル(man ページ)

マニュアルは nroff 形式で /usr/share/man の適切な場所にインストールするべきです。また、セクションは 1 から 9 までのみを使うべきです (詳しくは FHS 参照)。フォーマット済みの cat 形式のマニュアルをインストールしてはいけません。

各プログラム、ユーティリティ、機能はそれに関連するマニュアルページを同じパッケージに含めるべきです。すべての設定ファイルもそれに関連するマニュアルページを含めることを推奨します。プロトコルや、その他付随的なことがらに関するマニュアルページはオプション扱いです。

マニュアルページが存在していない場合はバグと見なし、Debian バグトラッキングシステムにバグとして報告すべきです (自分で報告しておく、という処理でもかまいません)。適切なマニュアルが収録されるまではバグ報告を閉じないでください。 [110]

上流の作者にマニュアルがないとの苦情を転送し、Debian バグトラッキングシステムでは『転送済み』という処理にしてもかまいません。 GNU プロジェクトではマニュアルがないことは通常バグではないとしていますが、私たちはバグと見なします。彼らがバグではないと連絡してきた場合では、何も処理せずに Debian バグトラッキングシステム上では『未解決』のままにしておいてください。

マニュアルは gzip -9 で圧縮してインストールしなければいけません。

一つのマニュアルページを複数の名前で参照する必要がある場合は、 .so 機能を使うよりもシンボリックリンクを使う方が望ましいやり方です。ただ、上流のソースが .so [111] を使っている場合、それをあえてシンボリックリンクへ変更する必要はありません。それがよほど簡単でないかぎり行わないでください。 man のディレクトリではハードリンクを作成すべきではありません。また、.so 命令の中に絶対パスのファイル名を書くべきではありません。マニュアルの .so 命令では、ファイルはマニュアルツリーの起点 (通常は /usr/share/man です) からの相対参照とすべきです。もし、man ページの別名を指すためにリンク類 (シンボリックリンク、ハードリンクと .so コマンド) をファイルシステム中で使っていない場合、man があなたの man ページの別名を man ページのヘッダだけの情報から見つけることを [112] 期待するべきではありません。

/usr/share/man 以下のロカール依存のサブティレクトリに置かれるマニュアルページは、 UTF-8 か、その言語で通常利用されるレガシーエンコーディング (通常、 /usr/share/i18n/SUPPORTED にその言語関連の最短のロカール名が記載されているもの) を使用することができます。例えば、/usr/share/man/fr のページは、UTF-8 と ISO-8859-1 のいずれかを使用することができます [113]。

国名 (de_DE の DE) は、言語に対して大きな違いを示す場合でなければ、サブディレクトリ名に使用してはいけません。これは、他の国のその言語を利用者を除外することになるからです [114]。

マニュアルページのローカライズされた版を提供する場合、最新版であるか、読み手にとってそれが古いものであるため原語のマニュアルページを使った方が良いことが明確になっていなければいけません。これは、マニュアルページの最初に注記を入れるか、現マニュアルと対象言語との抜けや変更部分を示すことによって達成可能です。

12.2 Info 形式の文書

info 形式の文書は /usr/share/info へインストールしてください。また gzip -9 で圧縮しておくべきです。

install-info プログラムが info リーダープログラムのため /usr/share/info/dir にインストールされた info ドキュメントの管理を行います。このファイルは、install-info 以外のパッケージに含めてはいけません。

install-info は dpkg からのトリガを受けて、適切なタイミングで自動的に起動されます。 install-info 以外のパッケージでは、 install-info を直接起動すべきではなく 、またこの起動の目的で install-info に依存関係 (依存 (Depend)、推奨 (Recommend)、示唆 (Suggest)) を指定すべきではありません。

/usr/share/info/dir ファイルを必要とする Info リーダーは、install-info に依存関係を指定しなければいけません。

info 文書は、install-info で利用できるよう、文書中にセクションとディレクトリエントリ情報を含むようにすべきです。セクションは INFO-DIR-SECTION で始まり、空白を置いて該当文書ページのセクションを指定した行で指定すべきです。ひとつあるいは複数のディレクトリエントリは START-INFO-DIR-ENTRY と END-INFO-DIR-ENTRY 行の間で記載すべきです。例を以下に示します。

     INFO-DIR-SECTION Individual utilities
     START-INFO-DIR-ENTRY
     * example: (example).               An example info directory entry.
     END-INFO-DIR-ENTRY

どのセクションを使うべきかについては、自分のシステムの /usr/share/info/dir を調べて最も関係の深そうなものを (現状に適切なものがない場合には、新規に作成して) 選択してください [115]。

12.3 追加文書

パッケージに付属しているそれ以外の文書はパッケージメンテナの裁量でインストールするかどうかを決めて下さい。プレーンテキスト形式の文書は /usr/share/doc/package (package はパッケージの名称です) にインストールし、小さなものでない限り gzip -9 で圧縮しておくべきです。

対象とするパッケージを使うほとんどのユーザが必要としないような多量の文書を含むようなパッケージは、そのような文書を収録した独立のパッケージを作成して、そのような文書を必要としないか、インストールしたくないユーザがマシンのディスクスペースを消費しなくてもいいようにしておくべきです。

バイナリパッケージ中の /usr/share/doc/package にソースパッケージに付いている各種のテキスト文書 (README や changelog など) を入れるのは通常よい考えです。ただ、まぁ当り前のことですが、パッケージの作成やインストール方法について書かれたものを含める必要はありません。

パッケージは、動作のために /usr/share/doc/ 以下のファイルが存在することを要求していてはいけません。 [116] プログラムから参照されるが、同時に単独のドキュメントとしても役に立つようなファイルは /usr/share/package/ 以下にインストールして、 /usr/share/doc/package からシンボリックリンクを張ってください。

/usr/share/doc/package が、 /usr/share/doc 以下に置かれている他のディレクトリへのシンボリックリンクとすることは、この両方のパッケージが同じソースから作成されたもので、かつ前者から後者へ Depends が指定されているときのみ許されています [117]。

以前の Debian リリースでは添付文書類は /usr/doc/package ディレクトリに収録されていました。これは、現在は、 /usr/share/doc/package に変更になっており、パッケージはディレクトリ /usr/doc/package に文書を置いてはいけません [118]。

12.4 好ましい文書形式

Debian プロジェクトでは文書の形式の統一化は HTML により行なわれています。

パッケージに各種書式に変換可能なマークアップ形式の詳細文書が付属している場合は、バイナリパッケージには可能なかぎり HTML 形式のものを [119] /usr/share/doc/appropriate-package、およびそのサブディレクトリにインストールしてください。

PostScript のような他の形式はパッケージメンテナの裁量で提供してください。

12.5 著作権関連情報

各パッケージには、著作権情報と配布条件のライセンス文書が元のままの形式で /usr/share/doc/package/copyright に収録されていなければいけません。このファイルは圧縮されていたり、シンボリックリンクであったりしてはいけません [120]。

また、著作権情報ファイル中には元となった上流のソースをどこから手に入れたかを記載しなければなりません。またパッケージの原作者の名前を載せるべきです。

contrib または non-free アーカイブエリアのパッケージは、著作権情報ファイルにこのパッケージが Debian の一部ではないこと、およびその簡潔な理由を示すべきです。

/usr/share/doc/package/copyright にインストールされるファイルのコピーは debian/copyright に収録しておくべきです。

/usr/share/doc/package は、/usr/share/doc 以下の他のディレクトリ中のシンボリックリンクの相手先と同じソースファイルから作成されたものであること、および相手先に対して "Depends" で依存していることが宣言されていること、の二つの条件を満たすときのみ、シンボリックリンクとすることができます。この規則は、copyright(著作権関連ファイル) が機械的に抽出できるようにするために大切になるものです。

パッケージが Apache ライセンス (version 2)、 Artistic License、the GNU GPL (version 1、2 または 3), GNU LGPL (versions 2, 2.1, または 3) または the GNU FDL (version 1.2 または 1.3) に基づいて配布されている場合には、copyright ファイルで引用するのではなく、/usr/share/common-licenses 以下の各ファイル[121] を参照するようにしてください。カリフォルニア大 BSD ライセンスも、 base-files に /usr/share/common-licenses/BSD として収録されていますが、ライセンスが簡潔なこと、明示的に著作権を Regents of the University of California としていること、そして細かい用語の変更の頻度が高いことから、このファイルを参照するのではなく著作権情報ファイルに本文を含めるようにしてください。

copyright ファイルを一般的な README として使うべきではありません。パッケージがそのような README ファイルとして書くべき内容を持っている場合は /usr/share/doc/package/README、あるいは README.Debian やその他の適切な場所にインストールされるべきです。

12.5.1 機械可読な著作権情報

debian/copyright の、標準の機械可読な形式の仕様は debian-policy の一部として維持管理されています。仕様書は debian-policy に収録されている copyright-format です。また、以下の Debian ウェブミラーからも取得できます。 /doc/packaging-manuals/copyright-format/1.0/

このフォーマットの利用は任意です。

12.6 設定例など

設定ファイルやソースファイルなどの例は /usr/share/doc/package/examples ディレクトリにインストールしてください。これらのファイルをプログラムから参照してはいけません。これらはシステム管理者やユーザの便宜のため、説明用として置かれている文書です。アーキテクチャ固有の設定ファイル類は /usr/lib/package/examples にインストールし、 /usr/share/doc/package/examples から各ファイルにシンボリックリンクを張ってください。または、 /usr/share/doc/package/examples が /usr/lib/package/examples ディレクトリへのシンボリックリンクであってもかまいません。

パッケージの目的が例を提供することである場合、その例を /usr/share/doc/package へインストールしてもかまいません。

12.7 Changelog ファイル

Debian 由来のものでないパッケージには、Debian ソースツリー内の debian/changelog の圧縮されたコピーが /usr/share/doc/package 中に changelog.Debian.gz として含まれていなければいけません。

上流の changelog がある場合は、それはプレーンテキスト形式で、 /usr/share/doc/package/changelog.gz としてアクセスできるようにすべきです。 changelog ファイルが HTML 形式で配布されているならば /usr/share/doc/package/changelog.html.gz という名称で参照できるようにすべきで [122] 、changelog.gz はプレーンテキスト形式として、例えば lynx -dump -nolist で HTML ファイルから作成すべきです。上流の changelog ファイルがここで書いている命名規則に沿っていない場合での、ファイル名を変更する、あるいはシンボリックリンクを使うなどの処置はパッケージ開発者の裁量に任せます。

これらすべてのファイルは、はじめは小さくとも時間と共に大きくなるため、 gzip -9 を使って圧縮してインストールすべきです。

上流の開発者と Debian メンテナが同一人物であるため Debian changelog と元々の changelog が一つの changelog となっている場合は、 changelog は /usr/share/doc/package/changelog.gz; にインストールしてください。上流に別の原作者がいるけれども元々の changelog がない場合にも、Debian の changelog は changelog.Debian.gz のままにしてください。