名前

Locale::Po4a::TeX - PO ファイルと TeX 文書やその派生物の変換

説明

po4a (PO for anything) プロジェクトは、gettext ツールが想定していないドキュメントのような領域で翻訳をしやすくすること (またより興味深いのは、翻訳文の保守がしやすくなること) を目標にしています。

Locale::Po4a::TeX は、TeX ドキュメントをほかの [自然] 言語へ翻訳するのを助けるモジュールです。TeX を元にしたドキュメント用モジュールを作成するベースにもなります。

利用者は恐らくLaTeX モジュールを使用するべきです。これはTeX モジュールから継承しており一般的な LaTeX コマンドを定義してあります。

PO4A::TEX での翻訳

このモジュールは、一般的な TeX ドキュメントを直接扱えます。ドキュメントを小さなブロック (段落、verbatim ブロック、タイトルやインデックスのような同等の小さな部位) に分割します。

振る舞いをカスタマイズできるような、（次節で説明する）オプションがあります。あなたのドキュメントフォーマットに合わない場合は、フォーマットの詳細に合わせて、迷わずここから派生したモジュールを書いてください。その方法の説明については、以下にある「派生モジュールの作成」節を参照してください。

このモジュールは、TeX ファイル中の "% po4a:" で始まる行でもカスタマイズできます。この工程については、インラインカスタマイズ 節で説明します。

このモジュールで使用できるオプション

以下は、このモジュール固有のオプションです:

debug

このモジュールの内部メカニズムのデバッグ機能を有効にします。どの部分でデバッグできるか確認するには、ソースを利用してください。

no_wrap

改行を行うべきでない環境のコンマ区切りリストです。

verbatim 環境と no_wrap 環境には違いがあることに注意してください。verbatim ブロックを解析する、コマンドやコメントはありません。

この環境がすでに登録されていない場合、po4a は、この環境がパラメータを何も取らないとみなすでしょう。

exclude_include

\input や \include で取り込むべきでないファイルのコロン区切りリストです。

definitions

インラインカスタマイズ 節で定義されるような、po4a 用の定義を含むファイル名です。翻訳されるドキュメントに定義を置けない場合、このオプションを利用できます。

verbatim

verbatim として扱うべき環境のコンマ区切りリストです。

この環境がすでに登録されていない場合、po4a は、この環境がパラメータを何も取らないとみなすでしょう。

これらのオプションを使うと定義されたコマンドの既定の振舞いが上書きされます。

インラインカスタマイズ

TeX モジュールは、% po4a: で始まる行によりカスタマイズできます。この行はパーサにコマンドとして解釈されます。以下のコマンドを認識します:

% po4a: command コマンド1 alias コマンド2

コマンド1 コマンドの引数が、コマンド2 コマンドの引数であるかのように扱うことを示します。

% po4a: command コマンド1 パラメータ

コマンド1 コマンドのパラメータの詳細が記述されます。この情報を、引数の数と型を検査するのに使用します。

command1 コマンドの前に置けます

% po4a: environment env parameters

これは env 環境が受け取るパラメータを定義し、翻訳すべきものを指定します。 この情報は後で \begin コマンドの引数の個数を検査するのに使われます。 parameters 引数の構文は他のコマンドで説明したものと同じです。 \begin コマンドの第 1 引数は環境の名前です。このパラメータは、パラメータ のリストに指定してはいけません。以下にいくつか例を示します:
% po4a: environment multicols {}
% po4a: environment equation

command と同様に、env の前にプラス (+) を付けると、その \begin コマンドはすべての引数と一緒に翻訳されることを表します。

% po4a: separator env "regex"

与えた正規表現により環境が分割されることを示します。

正規表現は、引用符で区切られます。後方参照は作られません。グループが必要な場合は (?:) を使用してください。また、エスケープする必要があるでしょう。

例えば、LaTeX モジュールは "(?:&|\\\\)" という正規表現を、表の各セル (行を '\\' で区切り、セルを '&' で区切る) を別個に翻訳するために使用します。

環境の概念は PO ファイルに表示される型に使われます。これは title コマンドの先頭の必須引数を "\\\\" で分割するのに使用できます。この場合、環境は title{#1} になります。

% po4a: verbatim environment env

env が verbatim 環境であることを示します。この環境では、コメントとコマンドは無視されます。

この環境がすでに登録されていない場合、po4a は、この環境がパラメータを何も取らないとみなすでしょう。

派生モジュールの作成

pre_trans

post_trans

add_comment

次に翻訳される要素の周りに追加されるコメントとして文字列を追加します。TeXではコメントは自動的に処理されるため、これは主にtexinfoモジュールに有用です。

translate

Transtractor の translate 関数のラッパーで、前処理や後処理のフィルタになります。

段落のコメントを、その段落の最初の翻訳文字列の PO コメントに挿入します。

get_leading_command($buffer)

この関数は以下のものを返します:

get_trailing_command($buffer)

get_leading_command と同じですが、バッファの後ろからコマンドを取ります。

translate_buffer

前後に付けられた (分割して翻訳すべき) コマンドで区切られたバッファを、再帰的に翻訳します。

現在の環境の %translate_buffer_env で関数が定義されると、translate_buffer() に代えてこの関数がバッファの翻訳に使用されます。

read

Transtractor の read() で上書きします。

read_file

再帰的にファイルを読み込み、@exclude_include 配列にリストされていない取り込みファイルを追加します。取り込みファイルを、kpsewhich コマンドを使用して、Kpathsea ライブラリから探します。

ファイル取り込み部を除いて、Transtractor の read からカット & ペーストしたものです。

parse_definition_file

po4a ディレクティブがあるファイルのパース用サブルーチンです (新しいコマンドを定義します)。

parse_definition_line

"% po4a: " の形の定義行をパースします。

詳細は、インラインカスタマイズ 節を参照してください。

is_closed

parse

docheader

派生パーサ作成時に使用する内部関数

コマンド関数と環境関数は、($self オブジェクトに加えて) 以下の引数を取ります:

コマンド名

派生

(型、引数の) タプルの配列

現在の環境

先頭の 3 つの引数は get_leading_command や get_trailing_command で抽出されます。

コマンド関数や環境関数は、引数や新しい環境でのコマンドの翻訳を返します。

環境関数は \begin コマンドが見つかると呼ばれます。これらは \begin コマンドとその引数により呼ばれます。

TeX モジュールは一つのコマンド関数と一つの環境関数しか提案しません。generic_command と generic_environment です。

generic_command は、register_generic_command や TeX ファイルへの追加定義で指定した情報を使用します:
% po4a: command command1 parameters

generic_environment は、register_generic_environment や TeX ファイルへの追加定義で指定した情報を使用します:
% po4a: environment env parameters

どちらの関数も、翻訳可能であると ('_' で) 指定したパラメータのみを翻訳します。generic_environment は環境スタックに環境名を追加し、generic_command は、({#7} や [#2] のような) パラメータの識別子が続くコマンド名を追加します。

このモジュールの状態

このモジュールはもっとテストが必要です。

本と Python ドキュメントでテストされました。

TODO リスト

新しいコマンドの自動検出

TeX モジュールは、newcommand の引数をパースし、引数の数や型、翻訳するべきか否かを推測できるはずです。

環境セパレータの翻訳

\item が環境セパレータとして使われている場合、item の引数は続く文字列にアタッチされます。

いくつかのコマンドを環境スタックに追加するべき

These commands should be specified by couples. This can be used to specify commands beginning or ending a verbatim environment.

その他

ソースの様々なほかの場所に TODO タグが付いています。

既知のバグ

ソースの様々な場所に FIXME タグが付いています。

関連項目

Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

著者

 Nicolas François <nicolas.francois@centraliens.net>

訳者

 倉澤 望 <nabetaro@debian.or.jp>
 Debian JP Documentation ML <debian-doc@debian.or.jp>

著作権とライセンス

Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます (COPYING ファイルを参照してください)。