Provided by: po4a_0.57-2_all 
名前
Locale::Po4a::Man - PO ファイルと man ページの変換
説明
po4a (PO for anything) プロジェクトは、gettext ツールが想定していないドキュメントのような
領域で翻訳をしやすくすること (またより興味深いのは、翻訳文の保守がしやすくなること) を目標
にしています。
Locale::Po4a::Man は、nroff フォーマット (man ページの言語) のドキュメントをほかの [自然]
言語へ翻訳するのを助けるモジュールです。
PO4A::MAN での翻訳
このモジュールは、翻訳者を楽にするためにちょっと面倒な動作をします。 というのは、翻訳者に
提供されたテキストは、man ページに現れるテキストの逐語コピーではないということです。実際
に、nroff フォーマットの生の部分は隠され、翻訳者がそれにより混乱しなくてすみます。
テキストの折り返し
インデントされていない段落は、翻訳者向けに自動的に折り返し直します。groff で使用される折り
返し直すルールはあまり明確ではないため、これで生成した出力は多少差異が発生します。例え
ば、丸括弧の後の二つの空白が、しばしば保持されます。
いずれにしろ、違いは折り返した段落にある余分な空白の位置についてのみとなるでしょう。そして
そこに価値があると思います。
フォント指定
最初の変更は、フォントの変更仕様についてです。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 ページが別の形式から生
成されたかどうかを検出しようとしないことを指定します。man ページを生成するのに po4a を
使用することが可能となります。このオプションは、いずれの引数も取りません。
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 のリストを引数に取ります。ここで、begin
と end は、折り返し直すべきでない節の始めと終わりを区切るコマンドです。
注意: end コマンドが begin コマンドと一致するかどうかのテストはしません。終了コマンド
があればそこで no_wrap モードは終了します。対応する end がない begin マクロや対応する
begin がない end マクロがある場合、既存の end (fi など) や begin (nf など) を対応する
ものとして指定できます。これらのマクロ (とその引数) は翻訳されません。
inline
このオプションは、段落を分けるべきでないコンマ区切りマクロのリストを指定します。翻訳す
る文字列に foo <.bar baz qux> quux が含まれるとき、bar がインラインにすべきコマンド
で、baz qux がその引数です。
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 を翻訳するべきではありません。そして、後者
は 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 で有効だということは知っています。でも、パーサが扱うにはあまりに複雑すぎるので
す。
Of course, another possibility is to use another format, more translator friendly (like
POD using po4a::pod, or one of the XML family like SGML), but thanks to po4a::man it isn't
needed anymore. That being said, if the source format of your documentation is POD, or
XML, it may be clever to translate the source format and not this generated one. In most
cases, po4a::man will detect generated pages and issue a warning. It will even refuse to
process POD generated pages, because those pages are perfectly handled by po4a::pod, and
because their nroff counterpart defines a lot of new macros I didn't want to write support
for. On my box, 1432 of the 4323 pages are generated from POD and will be ignored by
po4a::man.
In most cases, po4a::man will detect the problem and refuse to process the page, issuing
an adapted message. In some rare cases, the program will complete without warning, but the
output will be wrong. Such cases are called "bugs" ;) If you encounter such case, be sure
to report this, along with a fix when possible…
このモジュールの状態
既存の man ページの大半に、このモジュールを使用できます。
以下の複数のテストを Linux 機で定期的に実行しています:
• 全 man ページの 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 SPI, Inc.
本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます
(COPYING ファイルを参照してください)。