pod マニュアル翻訳の手引き¶
概要¶
pod とは¶
pod とは、 perl スクリプトのドキュメントを記述するためのドキュメント形式です。 以下のような特色を持っています。
- 単体のドキュメント (.podファイル) としても使えるが、 perlスクリプトに埋めこむこともできる。
- 簡潔で書きやすいフォーマット
- man 形式, html 形式への変換ツールがある
roff, html, latex などの他のマークアップ言語と比較すると、 機能は非常に限定されていますが、ソーステキストが読みやすく書きやすいことが特色です。 通常のマークアップ言語は、生成されたドキュメントを指定のビューアで見た場合は (当然ながら) 読みやすいのですが、 ソースとなるテキストファイルは読むのが困難です。
pod のソースは、通常のテキストファイルと大きな隔たりがなく、 ソースのままでもある程度読めることが特色です。 そのため、書く側への負担が小さく、気軽に書けるフォーマットであると言えます。
同様の目的のフォーマットとして Ruby 言語のスクリプトでよく使われる、 RD というフォーマットもあります。
pod マニュアルをJM向けに翻訳する場合の作業方法¶
リポジトリ内でのディレクトリ構成¶
JM のリポジトリ内でのディレクトリ構成は以下のようになります。 (zebedeeというプログラムの場合)
JM -+- pod -+- zebedee -+- ChangeLog
+- translation_list
+- original -+- zebedee.pod
| +- ftpgw.tcl.pod
|
+- draft -+- zebedee.pod
| +- ftpgw.tcl.pod
|
+- release -+- zebedee.pod
+- ftpgw.tcl.pod
すなわち、通常の roff 形式のマニュアルと次の点が違います。
- トップディレクトリが
JM/manualでなくJM/pod man1,man3のようなセクション別のサブディレクトリがない
pod の下がプログラム名になり、その下が original/draft/release になることと、 この 3 つのディレクトリの使用法は roff 形式の場合と同じで、次のとおりです。
original: オリジナルのソースdraft: 翻訳作業中の日本語ソース(コメントとして原文を含む)release: 翻訳が完了した日本語ソース
translation_list の書式¶
translation_list は以下のようになります。
△:zebedee:2.0.0:2000/05/30:zebedee:pod:2000/6/21:(G):tnaka@brain-tokyo.com:NAKAJIMA Taku:::
×:zebedee:2.0.0:2000/05/30:ftpgw.tcl:pod:::::::
すなわち、セクション名 (6 番目のフィールド) が pod になります。 それ以外は、roff 形式のマニュアルと同じです。
原文のコメント化¶
JM では、draft文書については、 校正者の便宜のために原文をコメントで残すことが推奨されています。
pod ドキュメントの一般的なコメントの形式は =begin/=end ですが、
原文をコメント化した部分と通常のコメントを区別するため、
以下のような JM-comment というタグ付きのコメントを使用してください。
=begin JM-comment
If a key is described as being a boolean then its value must be one of the
words B or B.
=end JM-comment
キーワードが真偽値 (boolean) と書かれていたら、
その値は "B" または "B" でなければならない。
このようにしておくと、htmlやmanに変換した時に原文は削除されます。 また、 原文の削除 に述べるように簡単なコマンドでソースから原文を取り除くこともできます。
ポストの方法¶
JMでは、JM メーリングリストに特定の形式で投稿することで git リポジトリに commit する方法が用意されていますが、 現状ではpodマニュアルの場合はこの方法は使用できません。
そのため、pod の翻訳作業を投稿するためには、 sourceforge.jp の linuxjm プロジェクトで git commit 権を付与してもらうか、 git committer に依頼する必要があります。
作業にあたっては、ポストの方法について JM のメーリングリストでご相談下さい。
pod マニュアル翻訳上の注意、TIPS¶
翻訳確認の方法¶
作業結果の確認のためには、以下のコマンドを使います。
html変換してから表示
$ pod2html podソース名 > 作業用htmlファイル名 $ netscape 作業用htmlファイル名
man変換してから表示
$ mkdir man1 $ pod2man podソース名 > man1/xxxxxx.1 $ man -M . xxxxxx
pod はドキュメントフォーマットの細部が確立してないためか、 pod2html と pod2man で違う結果となる (片方だけでエラーが出る) ことがたまにありますから、 常に両方の結果を確認した方がいいと思います。
また、どちらのコマンドもparagraph単位(段落)のエラー表示で、 エラーの行番号が表示されないし、 エラーメッセージもわかりやすいとは言えません。 そのため、こきざみに変換コマンドを実行した方がいいと思います。 たくさんの作業を一度にしてからエラーを出すと、原因をつきとめるのが困難です。
段落名の翻訳の注意点¶
pod2manは、変換元のpodドキュメントが 以下の条件を満たしていることを前提としているようです。
- 最初の段落が``=head1 NAME`` から初まること
=head1 DESCRIPTIONという段落が存在すること=head1,=head2以外の見出しを使わない
そのため、 =head... の翻訳には注意を要します。
pod2html には段落への HTMLリンクタグを自動生成する機能があるのですが、 pod ドキュメントがこれを使用している場合は、 段落名を翻訳してしまうと、このリンクが正しく張れなくなります。
このため、段落名の翻訳は非常に注意が必要です。 この問題に対する一般的な対応方法はまだ決定していません。 現状では、段落名は原文のままにしておいて、 個別に JM メーリングリストで対応方法を相談してください。