[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/&lt;package-name&gt;/copyright. This file must
	  neither be compressed nor be a symbolic link.-->
	  各パッケージには、著作権と配布条件のライセンス文書が元のままの形式
	  で /usr/share/doc/&lt;package-name&gt;/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/&lt;package-name&gt; 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/&lt;package-name&gt; は、シンボリックリンクの相
	  手先と同じソースファイルから作成されたものであること、および相
	  手先に対して "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