名前

       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ファイルを参照）。