概要

po4a-build.conf は、既訳・未訳ドキュメントを未訳ドキュメントと対応する PO ファイルから、"po4a-build" がどのように構築するかを説明します。

すべてのサポートするフォーマットは、すべての組み合わせを、ひとつの po4a-build.conf 設定ファイルで扱い、"po4a-build" を一度呼び出すだけですみます。しかし、po/ ディレクトリを分割し、各実行をひとつの設定ファイルで扱うことも選択できます (それぞれ "po4a-build -f FILE" を呼び出してください)。

po4a-build に、スクリプト出力メッセージ翻訳用の gettext サポート追加が含まれているといっても、po4a-build.conf 自身には、そのような翻訳をサポートしていないことに注意してください。po4a-build.conf は、manpage のような静的内容の翻訳にのみ関係します。

po4a-build がランタイムメッセージの翻訳をサポートするには、po4a-runtime (7) をご覧ください。

サポートするフォーマット

現在、"po4a-build" は以下の組み合わせをサポートしています。

セクション 1, 3 用 DocBook XML

Typically used for manpages for shell scripts or other interpreters that do not have their own documentation format like POD. Suitable XML can be generated directly from an existing manpage using "doclifter"(1) and "po4a-build" will then generate a POT file with no extra workload. The POT file can then be offered for translation and the PO files added to the relevant po/ directory. "po4a-build" will then prepare not only the untranslated manpage from the "doclifter" XML but also use "po4a" to prepare translated XML from the PO files and then build translated manpages from the XML.

デフォルトでは docbook-xsl を用いて manpage を生成します。"po4a-build" 設定ファイルの "XSLFILE" 設定を用いて使用するスタイルシートを上書きできます。

HTML 用 DocBook XML

最終的に HTML を準備するスタイルシートは、デフォルトのままにしておけます。また、"po4a-build" 設定ファイルの "HTMLXSL" 設定を用いて上書きできます。

セクション 1, 3, 5, 7 用 POD

サポートする各セクション用に、POD 内容を pod2man で変換します。

セクション 1 向けに "PODFILE"、セクション 3 向けに "PODMODULES"、セクション 5 向けに "POD5FILES"、セクション 7 向けに "POD7FILES" を使用してください。

(セクション 1 の内容でも使われるファイル名にしなければならない傾向がある) セクション 5, 7 の内容向けに、ファイル名の一部に 5 や 7 が含まれる場合、(ファイル名の拡張子と共に) 自動的に取り除かれます。

例えば、/usr/share/man/man7/po4a.7.gz の準備をするには以下のようにします。

 # セクション 7 用 POD
 POD7FILES="doc/po4a.7.pod"

ファイル内容

設定値は設定ファイル内で、どのような順番でもかまいません。

'#' 以降の内容を無視します。

常に空になる値は、ファイルから取り除けます。

設定フィールドのいくつかは必須です。必須フィールドを空にすると、po4a-build は何もせずに終わります。

CONFIG

必須です。

"po4a-build" が生成・管理する (一時的な) "po4a" 設定ファイルの名前・場所です。このファイルは、バージョン管理システムの管理下にある必要はなく、パッケージの構築が終わると安全に削除できます。

 # 設定ファイルの場所・名前
 CONFIG="_build/po4a.config"

PODIR

必須です。

この設定ファイルにより、すべての翻訳を扱う POファイルを格納するディレクトリです。文字列はすべてこのディレクトリにある POT ファイルにマージされ、全 PO ファイルを このPOT ファイルとマージします。KEEP 閾値 (後述) は、このファイルで指定した全入力ファイルの全文字列と、このディレクトリにある全 PO ファイルに適用されます。ディレクトリは 'po' と言う名前である必要はありません。しかし、このディレクトリ名が 'po' であることを想定している統計ツールがあるため、この名前にしておくことをお勧めします。

 # manpage/doc 用 po ディレクトリ
 PODIR="po/pod"

POTFILE

必須です。

POT ファイルへのパス (この設定ファイルの場所からの相対パス) です。ここに対して "po4a-build" が翻訳を生成・保守・更新を行います。

 # POT ファイルパス
 POTFILE="po/pod/po4a-pod.pot"

BASEDIR

必須です。

翻訳内容を書き出すベースディレクトリです。

 # 生成したファイルのベースディレクトリ。例: doc
 BASEDIR="_build"

BINARIES

必須です。

単一パッケージを構築するとしても、少なくともひとつは値が必要です。

この文字列は任意ですが、通常パッケージ名からできています。生成した内容は、以下のように BASEDIR/BINARIES のサブディレクトリに現れます。

 _build/po4a/man/man1/foo.1

複数のパッケージを構築する (つまり、ひとつのソースパッケージから、複数の .deb ファイルや .rpmファイルを構築する) 場合 、構築プロセスの自動化を簡単にするため、このフィールドは各ターゲット向けの内容を隔離するのを助けます。

空白で文字列を分割します。

 # 生成した manpage を含むバイナリパッケージ
 BINARIES="po4a"

KEEP

"po4a -k" に直接渡される閾値で、構築前に翻訳を除外し、翻訳完了した内容にします。空のままにしたり、削除したりするとデフォルト値 (80%) を使用します。また、0 にすると、まったく訳されていなくても、強制的にすべての内容を含めるようになります。

そのような挙動をすべて制御するために、どのファイルをどの po4a-build.conf 設定ファイルに割り当てるかを、慎重に決めてください。

翻訳者にとって、POT ファイルにたくさんのファイルが含まれていると (特に共通する文字列が多いと) 都合がよいですが、逆に POT ファイルにたくさんの長い文字列があると、文字列の確定に時間がかかり、翻訳者の気力を奪ってしまうということに注意してください。

 # 維持する翻訳率の最小閾値
 KEEP=

XMLMAN1

セクション 1 の manpage を生成するための DocBook XML です。ファイル名は空白で区切られます。すべてのファイルが、XMLDIR ディレクトリにある必要があります。

目次などを提供するために、複数の XML ファイルをひとつの book にまとめるのは、一般的な手法です。book に XMLMAN3 で指定したファイルも含む場合、book 自体ではなく、セクション 1 の XML ファイルだけをここに指定してください。book にこのセクションの内容だけがある場合、book ファイルを指定してください。

 # セクション 1 用 DocBook XML ファイル
 XMLMAN1="po4a-build.xml po4aman-display-po.xml po4apod-display-po.xml"

XMLMAN3

セクション 3 の manpage を生成するための DocBook XML です。ファイル名は空白で区切られます。すべてのファイルが、XMLDIR ディレクトリにある必要があります。

目次などを提供するために、複数の XML ファイルをひとつの book にまとめるのは、一般的な手法です。book に XMLMAN1 で指定したファイルも含む場合、book 自体ではなく、セクション 3 の XML ファイルだけをここに指定してください。book にこのセクションの内容だけがある場合、book ファイルを指定してください。

 # セクション 3 用 DocBook XML manpage
 XMLMAN3=""

XMLDIR

すべての DocBook XML ファイルの場所です。現在 "po4a-build" は、このディレクトリにある *.xml ファイルを探すと、XMLMAN1 と XMLMAN3 に列挙したすべてのファイルが見つかることを期待しています。

XMLMAN1 や XMLMAN3 を使用する場合、指定しなければなりません。設定ファイルの場所からの、相対パスです。

 # XML ファイルの場所
 XMLDIR="share/doc/"

XMLPACKAGES

BINARIES のリスト外で、どのパッケージが XML ソース内容を使用するかを指定します。

XMLMAN1 や XMLMAN3 で与えた値は、ここにも同様に与えなければなりません。

 # DocBook XML & xsltproc を使用するバイナリパッケージ
 XMLPACKAGES="po4a"

DOCBOOKDIR

XMLDIR と同様ですが、翻訳された DocBook ファイルを準備するために使用します。パッケージで .sgml ファイルを使用したい場合は、どのように構築するべきか、po4a-devel メーリングリストで議論してください。

 # .docbook ファイルを検索するパターン
 DOCBOOKDIR=""

XSLFILE

DocBook XML ファイルから、既訳・未訳の内容を処理するために使用する、XSL スタイルシート です。

 # DocBook XML に使用する XSL ファイル
 XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"

PODFILE

セクション 1 の manpage を生成するための POD ファイルです。POD ファイルを空白で区切ります。使用する場合、設定ファイルの場所からの相対パスを指定する必要があります。

 # man1 用 POD ファイル
 PODFILE="po4a po4a-gettextize po4a-normalize scripts/msguntypot"

PODMODULES

POD 内容を含む Perl モジュールに特化したサポートです。モジュール名はパスから再構築します (そのため一般的な Perl のレイアウトであるべきです)。また、manpage を自動的にセクション 3 に配置します。

 # man3/ 用 POD ファイル - モジュール名はパスから再生成します。
 PODMODULES="lib/Locale/Po4a/*.pm"

POD5FILES

セクション 5 の manpage を生成する、任意の POD 内容です。使用する場合、設定ファイルの場所からの相対パスを指定する必要があります。

(セクション 1 の内容でも使われるファイル名にしなければならない傾向がある) セクション 5, 7 の内容向けに、ファイル名の一部に 5 や 7 が含まれる場合、(ファイル名の拡張子と共に) 自動的に取り除かれます。

 # セクション 5 用 POD ファイル
 POD5FILES="doc/po4a-build.conf.5.pod"

POD7FILES

セクション 7 の manpage を生成する、任意の POD 内容です。使用する場合、設定ファイルの場所からの相対パスを指定する必要があります。

(セクション 1 の内容でも使われるファイル名にしなければならない傾向がある) セクション 5, 7 の内容向けに、ファイル名の一部に 5 や 7 が含まれる場合、(ファイル名の拡張子と共に) 自動的に取り除かれます。

 # セクション 7 用 POD
 POD7FILES="doc/po4a.7.pod"

PODPACKAGES

XMLPACKAGES と同様です。内容を POD ファイルから構築するパッケージは、PODPACKAGES の値に含まれている必要があります。PODFILE, PODMODULES, POD5FILES, POD7FILES に何か値を指定する場合必須です。

 # POD を使用するバイナリパッケージ
 PODPACKAGES="po4a"

HTMLDIR

未訳・既訳 HTML を出力する BASEDIR のサブディレクトリです。

 # HTML 出力先 (BASEDIR のサブディレクトリ)
 HTMLDIR=""

HTMLFILE

HTML に変換される DocBook ファイルです (XMLMAN1 や XMLMAN3 にあるファイルと同じかも)。節は HTML 出力と関連がないので、HTML に目次などを作るため、気軽に単一 book ファイルを使用してください。

 # HTML DocBook ファイル
 HTMLFILE=""

HTMLXSL

chunk XSL スタイルシートを使用する際のデフォルト値です。現在、HTML の実行ごとの、複数のスタイルシートの使用はサポートしていません。

 # HTML に使用する XSL ファイル
 HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"

著者

 Neil Williams <[email protected]>

訳者

 倉澤 望 <[email protected]>
 Debian JP Documentation ML <[email protected]>