plucky (3) Locale::Po4a::TeX.3pm.gz
名前
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 は (段落の先頭や末尾にある場合) 段落からこのコマンドを抽出します。ですから、翻訳者は、翻訳可
能であるとマークされたパラメータを翻訳するべきです。
プラス (+)
アスタリスクのように、コマンドは、ブロックの端に現れる場合に抽出しますが、パラメータを分割して翻
訳することはしません。翻訳者はこのパラメータすべてを結合したコマンドを翻訳しなければなりませ
ん。このため、文脈を保持し、複数の意味 (と翻訳) を持つ、短い単語のパラメータを持つコマンドに対し
て便利です。
注意: この場合、翻訳可能なパラメータを指定する必要はありませんが、po4a がパラメータの型と数を知ら
ねばなりません。
マイナス (-)
この場合、コマンドは、いずれのブロックからも抽出しません。しかし、ブロック内に一つしかないときだ
け、翻訳可能とマークしたパラメータを翻訳者に提示します。これは font コマンドに対して便利です。こ
ういったコマンドは、(文脈を保持するため) 一般的に段落から切り離すべきではありませんが、文字列全体
がそういったコマンドになっている場合は、切り離さずにいて、翻訳者をいらつかせる理由はありません。
parameters 引数は、[] (任意オプション) のセットか、 {} (必須オプション) のセットです。 括弧の間にアン
ダースコア (_) を配置し、パラメータを訳さなければならない ことを指定できます。以下のようになります:
% po4a: command *chapter [_]{_}
これは、chapter コマンドには二つのパラメータがあり、両方とも翻訳の必要が あることを示します: オプショ
ン (短いタイトル) と必須のもの。 href コマンドには二つの必須パラメータがあり、URL (第 1 パラメータ)
を 訳したくなく、さらに、(文の中で翻訳者がリンクを移動できるように) このコマンドを段落から分離したく
ない場合、以下のようになります:
% po4a: command -href {}{_}
この場合、翻訳するべき引数を示す情報は、この href コマンドだけからなる段落の場合にのみ使用されます。
% 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)
この関数は以下のものを返します:
コマンド名
与えられたバッファの先頭にコマンドが見つからない場合、この文字列は空になります。分割できるコマン
ドのみであることが考えられます。%separated_command ハッシュには、これらのコマンドのリストが含まれ
ています。
派生
派生が使われるかを示します。例えば、番号付けされるべきではないことを指定するのに、アスタリスク
(*) を section コマンドの最後に追加できます。この場合、フィールドは "*" を含むでしょう。派生がな
ければ、このフィールドは空文字列となります。
タプル (引数の型と引数) の配列
引数の型は '{' (必須引数) や '[' (オプション引数) のどちらでも可能です。
残りのバッファ
先頭からコマンドやその引数を取り去った後の、バッファの残りです。コマンドがなければ、元のバッファ
に手をつけず、このフィールドに返ります。
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 の引数は続く文字列にアタッチされます。
いくつかのコマンドを環境スタックに追加するべき
これらのコマンドは組で指定するべきです。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 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>. 本プログラムは自由ソフトウェアです。GPL v2.0以降の条項に基づき再頒布と変更を行えます（COPYINGファイルを参 照）。