Provided by: po4a_0.47-2_all bug

名前

       Locale::Po4a::Man - PO ファイルと man ページの変換

説明

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

       Locale::Po4a::Man は、nroff フォーマット (man ページの言語) のドキュメントを他の [自然] 言
       語へ翻訳するのを助けるモジュールです。

PO4A::MAN での翻訳

       このモジュールは、翻訳者を楽にするためにちょっと面倒な動作をします。 というのは、翻訳者に
       提供されたテキストは、man ページに現れるテキストの逐語コピーではないということです。実際
       に、nroff フォーマットの生の部分は隠され、翻訳者がそれにより混乱しなくてすみます。

   テキストの折り返し
       インデントされていない段落は、翻訳者向けに、自動的に折り返し直します。groff で使用される折
       り返し直すルールはあまり明確ではないため、これで生成した出力は多少差異が発生します。例え
       ば、丸括弧の後の 2 つの空白が、しばしば保持されます。

       いずれにしろ、違いは折り返した段落にある、余分な空白の位置についてのみとなるでしょう。そし
       てそこに価値があると思います。

   フォント指定
       最初の変更は、フォントの変更仕様についてです。nroff には、与えられた単語を縮小・太字・斜体
       で書くべきかどうかを指定する方法が、複数あります。翻訳するテキストには、POD (Perl online
       documentation) フォーマットから借りてきた、以下の一つの方法しかありません。

       I<text> -- イタリックテキスト
           \fItext\fP や ".I text" と等価

       B<text> -- 太字テキスト
           \fBtext\fP や ".B text" と等価

       R<text> -- 通常テキスト
           \fRtext\fP と等価

       CW<text> -- 等幅テキスト
           \f(CWtext\fP や ".CW text" と等価

       所見: CW フェイスはどの groff デバイスでも有効というわけではありません。使用はお奨めしませ
       ん。利便性のために提供しています。

   自動文字列変換
       po4a  は、翻訳や訳のレビューが簡単になるように、特定の文字を自動的に変換します。以下に変換
       する文字を列挙します。

       ハイフン
           man ページ中のハイフン (-) とマイナス記号 (\-) を、PO ファイル内ではシンプルなダッ
           シュ(-) に変換します。さらに出力ドキュメントに訳を挿入する際に、すべてのダッシュを
           roff のマイナス記号 (\-) に変換します。

           翻訳者は、自分の翻訳内では roff グリフ '\[hy]' の使用を押し通せます。

       非改行スペース
           翻訳者は、非改行スペースを翻訳内で使用できます。非改行スペース (latin1 では 0xA0) を
           roff 非改行スペース ('\ ') に変換します。

       クオートの変換
           `` と '' を、それぞれ  \*(lq と \*(rq に変換します。

           変換しないようにするには、翻訳者は幅なし roff 文字を挿入してください (例: それぞれ
           `\&` や '\&' とします)。

   翻訳内に '<'  '>' を書く方法
       こういった文字はフォント変更の区切り文字として使われるので、そのままでは使用できませ
       ん。(POD のようにもう一度) 代わりに E<lt> や E<gt> を使用してください。

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

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

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

       verbose
           プログラムの冗長度を上げます。

       groff_code
           このオプションは、.de, .ie, .if セクションがある場合に、モジュールの振る舞いを変更でき
           ます。以下の値を取ることができます。

           fail
               これはデフォルト値です。.de, .ie, .if セクションがある場合、モジュールは失敗しま
               す。

           verbatim
               .de, .ie, .if セクションは、オリジナルドキュメントから、翻訳済みドキュメントへコ
               ピーされなければならないことを表します。

           translate
               .de, .ie, .if セクションは翻訳するように提案されることを表します。それらのセクショ
               ンに、翻訳可能な文字列が含まれている場合にのみ、このオプションを指定するべきで
               す。そうでなければ、verbatim を選択するべきです。

       generated
           このオプションは、ファイルが生成され、po4a は man ページが生成されたかどうかを検出する
           必要がないことを指定します。これにより、po4a を生成した man ページに使用できます。この
           オプションには、いずれの引数もありません。

       mdoc
           このオプションは mdoc ページでのみ有用です。

           'NAME' セクションの翻訳を行わないよう po4a に伝え、mdoc 形式の厳密なサポートを選択しま
           す。'NAME' セクションが翻訳された mdoc ページは、いずれのヘッダ・フッタを生成しませ
           ん。

           groff_mdoc ページによると、NAME, SYNOPSIS, DESCRIPTION セクションは必須です。 翻訳した
           SYNOPSIS, DESCRIPTION セクションによる問題は知られていませんが、 以下のようにも指定で
           きます。
            -o mdoc=NAME,SYNOPSIS,DESCRIPTION

           この mdoc の問題は、以下のように追加内容を使用して解決することもできます。
            PO4A-HEADER:mode=before;position=^.Dd
            .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

       以下のオプションにより、新しいマクロ (.de 要求で定義される) や、po4a がサポートしていない
       マクロの振る舞いを指定できます。カンマで区切ったマクロのリストを引数に取ります。以下の例の
       ようになります。

        -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

       注: マクロがpo4aにサポートされておらず、標準 roff マクロだと思われる場合、po4a 開発チーム
       に伝えた方がいいでしょう。

       untranslated
           untranslated は、この (引数に指定された) マクロを翻訳する必要はないと指定します。

       noarg
           noarg は、untranslated と同様ですが、このマクロに引数が追加されていないことを、po4a が
           確認するところが異なります。

       translate_joined
           translate_joined は、po4a がマクロの引数を翻訳しなければならないと指定します。

       translate_each
           translate_each を使っても、引数を翻訳するよう指定しますが、それぞれ別々に翻訳するよう
           になるところが異なります。

       no_wrap
           このオプションは、カンマで区切った begin:end のリストを引数に取ります。ここで、beginend は、折り返し直すべきでないセクションの始めと終わりを区切るコマンドです。

           注意: end コマンドが begin コマンドと一致するかどうかのテストはしません。いずれかの終
           了コマンドにより、no_wrap は終了します。end (または begin) がない begin (または end)
           マクロがある場合、既存の end (fi など) や begin (nf など) を対応するものとして指定でき
           ます。このマクロ (とその引数) は翻訳されません。

       inline
           このオプションは、段落を分けるべきでないマクロの、カンマ区切りリストを指定します。bar
           がインラインにすべきコマンドで、baz qux を引数とした場合、翻訳する文字列は foo <.bar
           baz qux> quux となります。

       unknown_macros
           このオプションは、不明なマクロを検出した場合の po4a の挙動を指定します。デフォルトで
           は、po4a は警告を表示して失敗します。以下の値を取ることができます。failed (デフォルト
           値), untranslated, noarg, translate_joined, translate_each (値の説明は上記参照)。

PO4A::MAN 準拠の man ページの作成

       このモジュールは、真の nroff インタプリタでないので、まだ非常に制限があり解消のめどは立ち
       ません。既存のマクロがすべて使え、さらに新しいマクロを定義できるような、真の nroff インタ
       プリタであれば、制限を解消できたでしょうが、私たちはそうしませんでした。それは難しすぎまし
       たし、必要でないと考えたのです。man ページの作者が、自身の創作物を翻訳したものを目にしたい
       のであれば、翻訳者にとって作業しやすいように適合した方がいいと思います。

       ですから、po4a で実装した man のパーサは、修正予定のない既知の制限があります。これは、翻訳
       者があなたのドキュメントを保守するのを目にしたければ、避けるべき落とし穴の構成要素となるで
       しょう。

   nroff 内にプログラムを書かないでください
       nroff は、マクロ定義や条件分岐等を備えた完全なプログラム言語です。本パーサは nroff イン
       タープリタの全機能を持っているわけではありませんので、こういった機能を使ったページは失敗し
       ます (私の手元には 200 ページほどあります)。

   プレーンマクロセットを使用してください
       po4a::man がサポートしていないマクロはまだあります。これは単に、それについてのドキュメント
       が見つからなかったからです。以下にサポートしていないマクロのリストを掲げます。サポートして
       いないマクロが出てくると、プログラムが失敗してしまいますので、このリストは完全ではないこと
       に注意してください。このマクロに関して何か情報がありましたら、ありがたくサポートに追加しま
       す。これらのマクロのために、私の機械にある 250 ページは po4a::man でアクセスできないので
       す。

        ..               ."              .AT             .b              .bank
        .BE              ..br            .Bu             .BUGS           .BY
        .ce              .dbmmanage      .do                             .En
        .EP              .EX             .Fi             .hw             .i
        .Id              .l              .LO             .mf
        .N               .na             .NF             .nh             .nl
        .Nm              .ns             .NXR            .OPTIONS        .PB
        .pp              .PR             .PRE            .PU             .REq
        .RH              .rn             .S<             .sh             .SI
        .splitfont       .Sx             .T              .TF             .The
        .TT              .UC             .ul             .Vb             .zZ

   po4a から隠したいテキスト
       時には、筆者は翻訳できない部分があり、po4a で抽出するべきでないことを知っています。例え
       ば、オプションは other 引数を受け付けてもよく、また other はリストの最後の項目として現れて
       もよいとします。始めのケースでは、other は翻訳するべきではありませんが、2 番目のケースで
       は、other を訳すべきです。

       この場合、作者は、以下のような特殊な groff 構造を利用して、po4a がテキストを抽出しないよう
       にできます。

        .if !'po4a'hide' .B other

       (これには -o groff_code=verbatim オプションが必要になります)

       これを自動化するのに、以下のような新しいマクロを定義することもできます。
        .de IR_untranslated
        .    IR \\$@
        ..

        .IR_untranslated \-q ", " \-\-quiet

       (この構造には、-o groff_code=verbatim オプションと -o untranslated=IR_untranslated オプ
       ションが必要です。po4a はマクロ定義の内部をパースする必要はないため、.if !'po4a'hide' 条件
       文は、厳密には必要ありません)

       または、以下のようにエイリアスを使用します。
        .als IR_untranslated IR

        .IR_untranslated \-q ", " \-\-quiet

       (これには -o untranslated=als,IR_untranslated オプションが必要になります)

   結論
       このセクションをまとめると、シンプルなままにしておき、man ページを書く際に、賢く振る舞おう
       としないでください。nroff ではたくさんのことができますが、このパーサではサポートしていませ
       ん。例えば、テキスト処理を中断するのに、\c をいじらないでください (私の機械にある 40 ペー
       ジのように)。もしくは、マクロの引数をそのマクロと同じ行に、必ず配置してください。nroff と
       しては適切なのは解っていますが、パーサが扱うには複雑すぎるのです。

       もちろん別の可能性として、もっと翻訳者に優しい (po4a::pod で使用する POD や、SGML のような
       XML ファミリーなど) 別のフォーマットを使用することが挙げられます。しかし po4a::man のおか
       げで、もう必要ありません。そうはいっても、あなたのドキュメントのソースフォーマットが POD
       や XML の場合、ソースフォーマットを翻訳し、生成したものを翻訳しない方が賢明かと思いま
       す。多くの場合、po4a::man は生成されたページを検出し、問題を警告します。po4a::pod がその
       ページを完璧に扱え、その対応する nroff では、サポートするように書きたくない新しいマクロが
       多く定義されているため、 POD が生成したページを処理するのを、拒否することさえあります。私
       の機械では、1432/4323 ページが POD から生成され、po4a::man に無視されます。

       多くの場合、po4a::man は問題を検出し、適合するメッセージを出力して、ページの処理を拒否しま
       す。まれなケースでは、プログラムが警告なく完了したのに、出力が誤っている場合があります。そ
       のような場合は、"bugs"と呼びます ;) そのような場合は、可能であれば直し方とともに、ぜひ報告
       してください……

このモジュールの状態

       既存の man ページの大半に、このモジュールを使用できます。

       以下の複数のテストを Linux 機で定期的に実行しています。

       ·   ページの 1/3 は、po4a がサポートする別のフォーマット (例: POD や SGML) から生成された
           ので不合格になります。

       ·   残りのページの 10% は、エラー (例: groff マクロがサポートされていないなど) で不合格に
           なりました。

       ·   そして、1% に満たないページは po4a は何も言いませんが、重要な問題 (言い換えると、単語
           が消えていたり、新しい単語が挿入されたりします) があります。

       ·   その他のページは、通常、空白のみの差異や行の折り返しなどよりも、もっと重要な差異がない
           として扱われます (フォントの問題は処理したページの 10% 以下です)。

関連項目

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

著者

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

訳者

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

著作権・ライセンス

       Copyright 2002-2008 by SPI, inc.

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