Provided by: po4a_0.45-1_all 
名前
Locale::Po4a::TeX - PO ファイルと TeX ドキュメントや派生物の変換
説明
po4a (PO for anything) プロジェクトは、gettext ツールが想定していないドキュメントのような
領域で翻訳をしやすくすること (またより興味深いのは、翻訳文の保守がしやすくなること) を目標
にしています。
Locale::Po4a::TeX は、TeX ドキュメントを他の [自然] 言語へ翻訳するのを助けるモジュールで
す。TeX を元にしたドキュメント用モジュールを作成するベースにもなります。
ユーザは、TeX モジュールから継承し、一般的な LaTeX コマンドを定義してある、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 command1 alias command2
command1 コマンドの引数が、command2 コマンドの引数であるかのように扱うことを示します。
% po4a: command command1 parameters
command1 コマンドのパラメータの詳細を記述できます。この情報を、引数の数と型をチェック
するのに使用します。
command1 コマンドの前に置けます。
アスタリスク (*)
po4a は (段落の先頭や末尾にある場合) 段落からこのコマンドを抽出します。ですか
ら、翻訳者は、翻訳可能であるとマークされたパラメータを翻訳するべきです。
プラス (+)
アスタリスクのように、コマンドは、ブロックの端に現れる場合に抽出しますが、パラメー
タを分割して翻訳することはしません。翻訳者はこのパラメータすべてを結合したコマンド
を訳さねばなりません。このため、文脈を保持し、複数の意味 (と翻訳) を持つ、短い単語
のパラメータを持つコマンドに対して便利です。
注意: この場合、翻訳可能なパラメータを指定する必要はありませんが、po4a がパラメー
タの型と数を知らねばなりません。
マイナス (-)
この場合、コマンドは、いずれのブロックからも抽出しません。しかし、ブロック内にひと
つしかないときだけ、翻訳可能とマークしたパラメータを翻訳者に提示します。これは
font コマンドに対して便利です。こういったコマンドは、(文脈を保持するため) 一般的に
段落から切り離すべきではありませんが、文字列全体がそういったコマンドになっている場
合は、切り離さずにいて、翻訳者をいらつかせる理由はありません。
parameters 引数は、[] (任意オプション) のセットか、{} (必須オプション) のセットで
す。括弧の間にアンダースコアを配置し、パラメータを訳さなければならないことを指定できま
す。以下のようになります。
% po4a: command *chapter [_]{_}
これは、chapter コマンドには 2 つのパラメータ (任意の短いタイトルと必須のもの) があ
り、どちらも訳さなければならないことを表しています。href コマンドに 2 つ必須パラメータ
があり、URL (第 1 パラメータ) を訳したくなく、さらに、 (文の中で翻訳者がリンクを移動で
きるように) このコマンドを段落から分離したくない場合、以下のようになります。
% po4a: command -href {}{_}
この場合、翻訳するべき引数を示す情報は、この href コマンドだけからなる段落の場合にのみ
使用されます。
% po4a: environment env parameters
これは env 環境が受け取るパラメータを定義できます。この情報は、\begin コマンドの引数の
数をチェックするのに後で使用し、翻訳すべきものを指定できます。parameters 引数の構文は
command で説明したものと同じです。\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
translate
Transtractor の translate 関数のラッパーで、前処理や後処理のフィルタになります。
段落のコメントを、その段落の最初の翻訳文字列の PO コメントに挿入します。
get_leading_command($buffer)
この関数は以下のものを返します。
コマンド名
与えられたバッファの先頭にコマンドが見つからない場合、この文字列は空になります。分
割できるコマンドのみであることが考えられます。%separated_command ハッシュには、こ
れらのコマンドのリストが含まれています。
派生
派生が使われるかを示します。例えば、番号付けされるべきではないことを指定するの
に、アスタリスク (*) を section コマンドの最後に追加できます。この場合、フィールド
は "*" を含むでしょう。派生がなければ、このフィールドは空文字列となります。
タプル (引数の型と引数) の配列
引数の型は '{' (必須引数) や '[' (オプション引数) のどちらでも可能です。
残ったバッファ
先頭からコマンドやその引数を取り去った後の、バッファの残りです。コマンドがなけれ
ば、元のバッファに手をつけず、このフィールドに返ります。
get_trailing_command($buffer)
get_leading_command と同じですが、バッファの後ろからコマンドを取ります。
translate_buffer
前後に付けられた (分割して翻訳すべき) コマンドで区切られたバッファを、再帰的に翻訳しま
す。
現在の環境の %translate_buffer_env で関数が定義されると、この関数を translate_buffer()
に代わって、バッファを翻訳するのに使用します。
read
Transtractor の読み込みで上書きします。
read_file
再帰的にファイルを読み込み、@exclude_include 配列にリストされていない取り込みファイル
を追加します。取り込みファイルを、kpsewhich コマンドを使用して、Kpathsea ライブラリか
ら探します。
ファイル取り込み部を除いて、Transtractor の read からカット & ペーストしたものです。
parse_definition_file
po4a ディレクティブがあるファイルの、パース用サブルーチンです (新しいコマンドを定義し
ます)。
parse_definition_line
"% po4a: " の形の定義行をパースします。
詳細は、インラインカスタマイズ セクションをご覧ください。
is_closed
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 の引数は続く文字列にアタッチされま
す。
いくつかのコマンドを環境スタックに追加するべき
これらのコマンドは組を指定するべきです。verbatim 環境の開始コマンドと終了コマンドを指
定できます。
その他
ソースの様々な他の場所に 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 by Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます
(COPYING ファイルをご覧ください)。