[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Debian Policy Manual Chapter 6
かねこです。表題通りで、potato パッケージの sgml を切り出して
作業しました。で、タグは sgml のままです。チェックお願いします。
--
<!-- <chapt><heading>Documentation</heading> -->
<chapt><heading>文書</heading>
<!-- -------------------------------------------- -->
<sect>
<!-- <heading>Manual pages</heading> -->
<heading>マニュアル(man ページ)</heading>
<p><!--
You must install manual pages in <prgn>nroff</prgn> source
form, in appropriate places under <tt>/usr/share/man</tt>. You
should only use sections 1 to 9 (see the FHS for more
details). You must <em>not</em> install a preformatted `cat
page'.-->
マニュアルは <prgn>nroff</prgn>ソース形式で <tt>/usr/share/man</tt>
の適切な場所にインストールしなければなりません。また、セクションは
1 から 9 までのみをつかうべきです (詳しくはFSSTND参照)。フォーマット
済みの 'cat' 形式のマニュアルをインストールしては<em>いけません</em>。
<
/p>
<p>
<!-- If no manual page is available for a particular program,
utility or function and this is reported as a bug on
debian-bugs, a symbolic link from the requested manual page
to the <manref name="undocumented" section="7"> manual page
should be provided. This symbolic link can be created from
<tt>debian/rules</tt> like this:
<example>
ln -s ../man7/undocumented.7.gz \
debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
</example>
This manpage claims that the lack of a manpage has been
reported as a bug, so you may only do this if it really has
(you can report it yourself, if you like). Do not close the
bug report until a proper manpage is available. -->
特定のプログラム、ユーティリティ、関数でマニュアルが存在せず、，
debuan-bugs で bug として報告済みになっている場合、対応するマ
ニュアルページは <manref name="undocumented" section="7"> マ
ニュアルへのシンボリックリンクにしておくべきです．
このシンボリックリンクは以下のようにして <tt>debian/rules</tt>
で作成することができます．
<example>
ln -s ../man7/undocumented.7.gz \
debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
</example>
このマニュアルページにはマニュアルの欠如はバグとして既に報告されて
いると書かれているため、上記のように処理していいのは本当にバグと
して報告がなされている場合のみです (自分で報告しておいてもかまい
ません)。
適切なマニュアルが提供されるまではバグ報告を閉じないでください。
</p>
<p>
<!-- You may forward a complaint about a missing manpage to the
upstream authors, and mark the bug as forwarded in the
Debian bug tracking system. Even though the GNU Project do
not in general consider the lack of a manpage to be a bug,
we do--if they tell you that they don't consider it a bug
you should leave the bug in our bug tracking system open
anyway. -->
上流の作者にマニュアルがないとの苦情を転送し、Debian バグトラ
ッキングシステムでは『転送済み』という処理にしてもかまいません。
GNU プロジェクトではマニュアルがないことは通常バグではな
いとしていますが、我々はバグとみなします．彼らがバグではない
と連絡してきた場合では、何も処理せずに Debian バグトラッキング
システム上では『未解決』のままにしておいてください。
</p>
<p>
<!-- Manual pages should be installed compressed using <tt>gzip
-9</tt>.-->
マニュアルは<tt>gzip -9</tt>で圧縮してインストールしなければい
けません。
</p>
<p>
<!-- If one manpage needs to be accessible via several names it
is better to use a symbolic link than the <tt>.so</tt>
feature, but there is no need to fiddle with the relevant
parts of the upstream source to change from <tt>.so</tt> to
symlinks--don't do it unless it's easy. Do not create hard
links in the manual page directories, and do not put
absolute filenames in <tt>.so</tt> directives. The filename
in a <tt>.so</tt> in a manpage should be relative to the
base of the manpage tree (usually
<tt>/usr/share/man</tt>). -->
一つのマニュアルページを複数の名前で参照する必要がある場合は、
<tt>.so</tt> 機能を使うよりもシンボリックリンクを使う方が望
ましいのですが、上流のソースの部分を<tt>.so</tt>からシンボリ
ックリンクへ変更する必要はありません。それが余程簡単で
ないかぎり行わないでください。マニュアルのディレクトリではハ
ードリンクを作成してはいけません。また、<tt>.so</tt> 命令の中
に絶対パスのファイル名を書いてはいけません。マニュアルの
<tt>.so</tt> 命令ではファイルはマニュアルツリーの起点 (通常は
<tt>/usr/man</tt>です) からの相対参照とすべきです．
</p>
</sect>
<!-- -------------------------------------------- -->
<sect>
<!-- <heading>Info documents</heading> -->
<heading>Info 形式の文書</heading>
<p>
<!-- Info documents should be installed in <tt>/usr/share/info</tt>.
They should be compressed with <tt>gzip -9</tt>. -->
info 形式の文書は <code>/usr/share/info</code> へインストール
してください。また <tt>gzip -9</tt>で圧縮しておいてください。
</p>
<p>
<!-- Your package must call <prgn>install-info</prgn> to update the
Info <tt>dir</tt>
file, in its post-installation script:-->
パッケージは info 文書の <tt>dir</tt> ファイルを更新するために
postinst スクリプト中で <prgn>install-info</prgn> を呼び出さな
ければなりません。
<example>
install-info --quiet --section Development Development \
/usr/share/info/foobar.info
</example>
</p>
<p>
<!-- It is a good idea to specify a section for the location of
your program; this is done with the <tt>--section</tt>
switch. To determine which section to use, you should look
at <tt>/usr/share/info/dir</tt> on your system and choose the most
relevant (or create a new section if none of the current
sections are relevant). Note that the <tt>--section</tt>
flag takes two arguments; the first is a regular expression
to match (case-insensitively) against an existing section,
the second is used when creating a new one.-->
あなたのプログラムの場所を示すためにセクションを指定するのは良
いことです。それには <tt>--section</tt> オプションを使用し
てください。どのセクションにするかは、自分のシステムの
<tt>/usr/share/info/dir</tt> を見て最もふさわしいものを選んで
ください。適当なものが見付からない場合は新しいセクションを作
成してください。<tt>--section</tt>オプションは 2 つの引数を取る
ことに注意してください。最初の引数は存在しているセクションと一
致させる正規表現 (大文字小文字は区別しません) で、もう一つは新
しいものを作るときに使います。
</p>
<p>
<!-- You must remove the entries in the pre-removal script:-->
prerm スクリプト中で上記エントリを以下のようにして削除してください。
<example>
install-info --quiet --remove /usr/share/info/foobar.info
</example>
</p>
<p>
<!-- If <prgn>install-info</prgn> cannot find a description entry
in the Info file you will have to supply one. See <manref
name="install-info" section="8"> for details.-->
<prgn>install-info</prgn> が info ファイル中に説明部のエントリ
ポイントを見つけられない場合、エントリポイントを付け足さなければ
なりません。この件の詳細は <manref name="install-info" section="8">
を参考にしてください。
</p>
</sect>
<!-- -------------------------------------------- -->
<sect>
<!-- <heading>Additional documentation</heading> -->
<heading>追加文書</heading>
<p>
<!-- Any additional documentation that comes with the package can
be installed at the discretion of the package maintainer.
Text documentation should be installed in a directory
<tt>/usr/share/doc/<var>package</var></tt>, where
<var>package</var> is the name of the package, and
compressed with <tt>gzip -9</tt> unless it is small.-->
パッケージに付属しているそれ以外の文書はパッケージメンテナの裁量で
インストールの可否を決めて下さい。テキスト形式の文書は
<tt>/usr/share/doc/<var>package</var></tt> (<var>package</var>は
パッケージの名称です) にインストールし、小さなものでない限り
<tt>gzip -9</tt> で圧縮しておいてください。
</p>
<p>
<!-- If a package comes with large amounts of documentation which
many users of the package will not require you should create
a separate binary package to contain it, so that it does not
take up disk space on the machines of users who do not need
or want it installed. -->
対象とするパッケージを使う殆どのユーザが必要としないような多量の
文書を含むようなパッケージは、そのような文書を収録した独立のパッ
ケージを作成して、そのような文書を必要としないか、インストール
したくないユーザがマシンのディスクスペースを消費しなくてもいいよ
うにしておくべきです。
</p>
<p>
<!-- It is often a good idea to put text information files
(<tt>README</tt>s, changelogs, and so forth) that come with
the source package in <tt>/usr/share/doc/<var>package</var></tt>
in the binary package. However, you don't need to install
the instructions for building and installing the package, of
course!-->
バイナリパッケージ中の <tt>/usr/share/doc/<var>package</var></tt>
にソースパッケージに付いている各種のテキスト文書（<tt>README</tt>
やchangelogなど）を入れるのは通常よい考えです。ただ、まぁ当り前
のことですが、パッケージの作成やインストール方法についてかかれた
ものを含める必要はありません。
</p>
</sect>
<!-- -------------------------------------------- -->
<sect id="usrdoc">
<!-- <heading>Accessing the documentation</heading> -->
<heading>文書の管理</heading>
<p>
<!-- Former Debian releases placed all additional documentation
in <tt>/usr/doc/<var>package</var></tt>. To realize a
smooth migration to
<tt>/usr/share/doc/<var>package</var></tt>, each package
must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
that points to the new location of its documentation in
<tt>/usr/share/doc/<var>package</var></tt><footnote>These
symlinks will be removed in the future, but they have to be
there for compatibility reasons until all packages have
moved and the policy is changed accordingly.</footnote>.
The symlink must be created when the package is installed;
it cannot be contained in the package itself due to problems
with <prgn>dpkg</prgn>. One reasonable way to accomplish
this is to put the following in the package's
<prgn>postinst</prgn>:-->
以前の Debian リリースでは添付文書類は
<tt>/usr/doc/<var>package</var></tt> ディレクトリに収録されていま
した。現在使われている <tt>/usr/share/doc/<var>package</var></tt>
ディレクトリへのスムーズな移行のために各パッケージは
<tt>/usr/doc/<var>package</var></tt> から新しい文書の位置
<tt>/usr/share/doc/<var>package</var></tt> へのシンボリックリンク
を管理しなければいけません。
<footnote>
このシンボリックリンクはいずれは削除されるでしょうが、全パッケ
ージの移行が完了してポリシーの変更がなされるまでは互換性のため
に置かなければいけません。
</footnote>
このシンボリックリンクはパッケージをインストールしたときに作成し
なければなりませんが、<prgn>dpkg</prgn> の問題のために単にパッケ
ージにそのリンクを含めておくことはできません。妥当な方法は、パッ
ケージの <prgn>postinst</prgn> スクリプトに以下を含めておくことで
す。
<example>
if [ "$1" = "configure" ]; then
if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
-a -d /usr/share/doc/#PACKAGE# ]; then
ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
fi
fi
</example>
<!-- And the following in the package's <prgn>prerm</prgn>: -->
そして以下をパッケージの <prgn>prerm</prgn> に入れてください。
<example>
if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
-a -L /usr/doc/#PACKAGE# ]; then
rm -f /usr/doc/#PACKAGE#
fi
</example>
</p>
</sect>
<!-- -------------------------------------------- -->
<sect>
<!-- <heading>Preferred documentation formats</heading>-->
<heading>好ましい文書形式</heading>
<p>
<!-- The unification of Debian documentation is being carried out
via HTML.-->
Debian文書の形式の統一化は HTML を通して行なわれています。
</p>
<p>
<!-- If your package comes with extensive documentation in a
mark up format that can be converted to various other formats
you should if possible ship HTML versions in a binary
package, in the directory
<tt>/usr/share/doc/<var>appropriate package</var></tt> or its
subdirectories.-->
パッケージに各種書式に変換可能なマークアップ形式の詳細文書が付属
している場合は、バイナリパッケージには可能なかぎり HTML 形式のも
のを <tt>/usr/share/doc/<var>appropriate package</var></tt>、お
よびそのサブディレクトリにインストールしてください。<P>
<footnote>
<p><!-- The rationale: The important thing here is that HTML
docs should be available in <em>some</em> package, not
necessarily in the main binary package, though. -->
原則論：ここで重要なことは、HTML 形式の文書は<em>一部</em>の
パッケージに収録されているとしても、main のバイナリパッケージ
全部に収録されているわけではないということです。
<!-- 脚注の意図不明。バグレポート回避用？ -->
</p>
</footnote>
</p>
<p>
<!-- Other formats such as PostScript may be provided at your
option.-->
PostScriptのような他の形式は自分の好みで提供してください．</p>
</sect>
<!-- -------------------------------------------- -->
<sect id="copyrightfile">
<!-- <heading>Copyright information</heading> -->
<heading>著作権関連情報</heading>
<p>
<!-- Every package must be accompanied by a verbatim copy of its
copyright and distribution license in the file
/usr/share/doc/<package-name>/copyright. This file must
neither be compressed nor be a symbolic link.-->
各パッケージには、著作権と配布条件のライセンス文書が元のままの形式
で /usr/share/doc/<package-name>/copyright に収録されていな
ければいけません。このファイルは圧縮されていたり、シンボリックリンク
であったりしてはいけません。
<footnote>
訳注：本節後半の GPL ほかの項参照
</footnote>
</p>
<p>
<!-- In addition, the copyright file must say where the upstream
sources (if any) were obtained, and explain briefly what
modifications were made in the Debian version of the package
compared to the upstream one. It must name the original
authors of the package and the Debian maintainer(s) who were
involved with its creation. -->
また、著作権情報ファイル中には元となった上流のソースをどこから手に
入れたか、元のソースから Debian パッケージを作成するためにどのよう
な変更を行なったかを簡潔に書いてください。パッケージの原作者の名前
とパッケージ作成に関与した Debian メンテナの名前を載せてください。
</p>
<p>
<!-- /usr/share/doc/<package-name> may be a symbolic link to a
directory in /usr/share/doc only if two packages both come from
the same source and the first package has a "Depends"
relationship on the second. These rules are important
because copyrights must be extractable by mechanical
means.-->
/usr/share/doc/<package-name> は、シンボリックリンクの相
手先と同じソースファイルから作成されたものであること、および相
手先に対して "Depends" で依存していることが宣言されていること、
の二つの条件を満たすときのみ、シンボリックリンクとすることがで
きます。この規則は著作権関連ファイルが機械的に抽出できるように
するために大切になるものです。
</p>
<p>
<!-- Packages distributed under the UCB BSD license, the Artistic
license, the GNU GPL, and the GNU LGPL should refer to the
files /usr/share/common-licenses/BSD,
/usr/share/common-licenses/Artistic,
/usr/share/common-licenses/GPL, and
/usr/share/common-licenses/LGPL.-->
パッケージがカリフォルニア大学バークレイ校の BSD ライセンス、
Artistic Licence、GNU の GPL、GNU の LGPL に基づいて配布され
ている場合には、おのおの /usr/share/common-licenses/BSD、
/usr/share/common-licenses/Artistic、
/usr/share/common-licenses/GPL、
/usr/share/common-licenses/LGPL の各ファイルを参照するよう
にしてください。
<footnote>
<p>
<!-- Why "licenses" and not "copyright"? Because
<tt>/usr/doc/copyright</tt> used to contain all the
copyright files, plus the four common licenses GPL,
LGPL, Artistic and BSD. Now individual copyright files
for packages are no longer in a common directory. Once
<tt>/usr/doc/copyright</tt> is almost empty it makes
sense to rename "copyright" to "licenses"-->
『ライセンス』であって『著作権』となっていない理由ですが、
<tt>/usr/doc/copyright</tt> に以前は全パッケージの著作権
情報と上記 4 つ (GPL、LGPL、Artistic と BSD) の汎用ライ
センスが収録されていましたが、現在は個別の著作権情報は共用
のディレクトリには置かなくなった、という経緯のためです。
<tt>/usr/doc/copyright</tt> はとりあえずほとんど空に近い
状態になり、ライセンスのみが置かれていますので、
"copyright" から "licenses" に名称を変更しました。
</p>
<p>
<!-- Why "common-licenses" and not "licenses"? Because if I
put just "licenses" I'm sure I will receive a bug report
saying "license foo is not included in the licenses
directory. They are not all the licenses, just a few
common ones. I could use /usr/share/doc/common-licenses
but I think this is too long, and, after all, the GPL
does not "document" anything, it is merely a license.
-->
ディレクトリ名称が "common-licenses" であって "licenses" では
ないのは、単に "licenses" としておいた場合には「ほげふがライ
センスがライセンスディレクトリに収録されていない」というバグ
レポートを受け取る羽目になることがほとんど確実だからです。ここ
に置かれるのはライセンス全部、という訳ではなく少数のよく使わ
れているもののみです。/usr/share/doc/common-licenses でもいい
んですが、ちょっと長すぎるのと、GPL は結局のところ『ライセンス』
であって文書ではないからです。
<!-- ちょっと意訳 -->
</p>
</footnote>
</p>
<p>
Do not use the copyright file as a general <tt>README</tt>
file. If your package has such a file it should be
installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
<tt>README.Debian</tt> or some other appropriate place.
copyrightファイルを一般的な <tt>README</tt> として使わないで
ください。パッケージがそのような <tt>README</tt> ファイルを持
っている場合は <tt>/usr/share/doc/<var>package</var>/README</tt>、
あるいは <tt>README.Debian</tt> やその他の適切な場所にインス
トールされるべきです。
</p>
</sect>
<!-- -------------------------------------------- -->
<sect>
<!-- <heading>Examples</heading> -->
<heading>設定例など</heading>
<p>
<!-- Any examples (configurations, source files, whatever),
should be installed in a directory
<tt>/usr/share/doc/<var>package</var>/examples</tt>. These
files should not be referenced by any program--they're there
for the benefit of the system administrator and users, as
documentation only. Architecture-specific example files
should be installed in a directory
<tt>/usr/lib/<var>package</var>/examples</tt>, and files in
<tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
to files in it. Or the latter directory may be a symlink to
the former. -->
設定ファイルやソースファイルなどの例は
<tt>/usr/share/doc/<var>package</var>/examples</tt>ディレク
トリにインストールしてください。これらのファイルをプログラム
から参照してはいけません。これらはシステム管理者やユーザの便
宜のため、説明用として置かれている文書です。アーキテクチャ固
有の設定ファイル類は <tt>/usr/lib/<var>package</var>/examples</tt>
にインストールし、<tt>/usr/share/doc/<var>package</var>/examples</tt>
から各ファイルにシンボリックリンクを張ってください。または、
<tt>/usr/share/doc/<var>package</var>/examples</tt> が
<tt>/usr/lib/<var>package</var>/examples</tt> へのシンボリッ
クリンクであってもかまいません。
</p>
</sect>
<!-- -------------------------------------------- -->
<sect id="instchangelog">
<!-- <heading>Changelog files</heading> -->
<heading>Changelog ファイル</heading>
<p>
<!-- This installed file must contain a copy of the
<tt>debian/changelog</tt> file from your Debian source tree,
and a copy of the upstream changelog file if there is one.
The debian/changelog file should be installed in
<tt>/usr/share/doc/<var>package</var></tt> as
<tt>changelog.Debian.gz</tt>. If the upstream changelog
file is text formatted, it must be accessible as
<tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>. If
the upstream changelog file is HTML formatted, it must be
accessible as
<tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>.
A plain text version of the changelog must be accessible as
<tt>/usr/doc/<var>package</var>/changelog.gz</tt> (this can
be created by <tt>lynx -dump -nolist</tt>). If the upstream
changelog files do not already conform to this naming
convention, then this may be achieved by either renaming the
files or adding a symbolic link at the packaging developer's
discretion. -->
インストールされたファイルの中には Debian ソースツリー内の
<tt>debian/changelog</tt> の写しと、もしあれば元々ついている
上流の changelog ファイルの写しが含まれていなければなりません。
debian/changelog ファイルは
<tt>/usr/share/doc/<var>package</var></tt> に
<tt>changelog.Debian.gz</tt> という名称でインストールしてください。
上流の changelog ファイルがテキスト形式ならば
<tt>/usr/share/doc/<var>package</var>/changelog.gz</tt> という
名称で参照できるようにしてください。上流の changelog ファイル
が HTML 形式ならば
<tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>
という名称で参照できるようにしてください。また、この場合には
テキスト形式の changelog ファイルが
<tt>/usr/doc/<var>package</var>/changelog.gz</tt> という名称
で参照できるようにしてください (形式変換は
<tt>lynx -dump -nolist</tt> で可能です)。上流の changelog ファイル
がここで書いている命名規則に沿っていない場合での、ファイル名を
変更する、あるいはシンボリックリンクを使うなどの処置はパッケージ
開発者の裁量に任せます。
</p>
<p>
<!-- Both should be installed compressed using <tt>gzip -9</tt>,
as they will become large with time even if they start out small.-->
両方とも、始めはとても小さいものかもしれませんが時が経てば大き
くなるので、<tt>gzip -9</tt>を使って圧縮してインストールしてく
ださい。
</p>
<p>
<!-- If the package has only one changelog which is used both as
the Debian changelog and the upstream one because there is
no separate upstream maintainer then that changelog should
usually be installed as
<tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
there is a separate upstream maintainer, but no upstream
changelog, then the Debian changelog should still be called
<tt>changelog.Debian.gz</tt>.-->
上流の開発者が独立に存在していないために Debian changelog と
元々の changelog が一つの changelog となっている場合は、
changelog は
<tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>;
にインストールしてください。上流に別の原作者がいるけれども元々の
changelog がない場合にも、Debian の changelog は
<tt>changelog.Debian.gz</tt> のままにしてください。<P>
</p>
</sect>
</chapt>
--
--
Seiji Kaneko skaneko@xxxxxxxxxxxx
--------------------------- http://plaza25.mbn.or.jp/~efialtes