Provided by: po4a_0.47-2_all bug

名前

       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
           This permits to define the parameters accepted by the env environment.  This
           information is latter used to check the number of arguments of the \begin command, and
           permit to specify which one must be translated.  The syntax of the parameters argument
           is the same as described for the ??? commands.  The first parameter of the \begin
           command is the name of the environment.  This parameter must not be specified in the
           list of parameters. Here are some examples:
            % 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 ファイルをご覧ください)。