テキストの折り返し¶

インデントされていない段落は、翻訳者向けに、自動的に折り返し直します。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> を使用してください。

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"と呼びます ;) そのような場合は、可能であれば直し方とともに、ぜひ報告してください……