po4a-build.conf -
翻訳内容構築用設定ファイル
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
- 通常、POD
のような自分のドキュメントフォーマットがない、シェルスクリプトやその他のインタプリタが使用します。既存の
manpage から "doclifter"
を用いて直接適合する
XML
を生成でき、余計な作業負荷もなく
"po4a-build" で POT
ファイルを生成できます。そこから翻訳用
POT
ファイルを提供でき、関連する
po/ ディレクトリに PO
ファイルを配置できます。さらに、"po4a-build"
は "doclifter" XML
による未訳 manpage
だけでなく、PO
ファイルによる翻訳
XML の準備をするため
"po4a" を用い、XML
から翻訳 manpage
を構築します。
デフォルトでは 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 <linux@codehelp.co.uk>
