JM 翻訳作業の手引きに戻る
このドキュメントは、JM プロジェクトにおいて pod ドキュメントの翻訳作業をする手引きです。
JM 翻訳作業の手引き とともに参照してください。
pod とは、 perl スクリプトのドキュメントを記述するためのドキュメント形式です。 以下のような特色を持っています。
roff, html, latex などの他のマークアップ言語と比較すると、 機能は非常に限定されていますが、 ソーステキストが読みやすく書きやすいことが特色です。 通常のマークアップ言語は、 生成されたドキュメントを指定のビューアで見た場合は (当然ながら) 読みやすいのですが、 ソースとなるテキストファイルは読むのが困難です。
pod のソースは、通常のテキストファイルと大きな隔たりがなく、 ソースのままでもある程度読めることが特色です。 そのため、書く側への負担が小さく、気軽に書けるフォーマットであると言えます。
同様の目的のフォーマットとして Ruby 言語のスクリプトでよく使われる、 RD というフォーマットもあります。
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形式のマニュアルと次の点が違います。
podの下がプログラム名になり、その下が original/draft/releaseになることと、 この 3 つのディレクトリの使用法はroff形式の場合と同じで、次のとおりです。
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 Bor B . =end JM-comment キーワードが真偽値(boolean)と書かれていたら、 その値は"B " または "B "でなければならない。
このようにしておくと、htmlやmanに変換した時に原文は削除されます。 また、 以下 に述べるように簡単なコマンドでソースから原文を取り除くこともできます。
JMでは、JM メーリングリストに特定の形式で投稿することで CVS リポジトリに commit する方法が用意されていますが、 現状ではpodマニュアルの場合はこの方法は使用できません。
そのため、pod の翻訳作業を投稿するためには、 CVS のアカウントをもらって CVS committer になるか、 CVS committer に依頼する必要があります。
作業にあたっては、ポストの方法について JM のメーリングリストでご相談下さい。
作業結果の確認のためには、以下のコマンドを使います。
html変換してから表示
$ pod2html podソース名 > 作業用htmlファイル名 $ netscape 作業用htmlファイル名
man変換してから表示
$ mkdir man1 $ pod2man podソース名 > man1/xxxxxx.1 $ man -M . xxxxxx
pod はドキュメントフォーマットの細部が確立してないためか、 pod2html と pod2man で違う結果となる (片方だけでエラーが出る) ことがたまにありますから、 常に両方の結果を確認した方がいいと思います。
また、どちらのコマンドもparagraph単位(段落)のエラー表示で、 エラーの行番号が表示されないし、 エラーメッセージもわかりやすいとは言えません。 そのため、こきざみに変換コマンドを実行した方がいいと思います。 たくさんの作業を一度にしてからエラーを出すと、原因をつきとめるのが困難です。
pod2manは、変換元のpodドキュメントが 以下の条件を満たしていることを前提としているようです。
そのため、=head...の翻訳には注意を要します。
pod2html には段落への HTMLリンクタグを自動生成する機能があるのですが、 pod ドキュメントがこれを使用している場合は、 段落名を翻訳してしまうと、このリンクが正しく張れなくなります。
このため、段落名の翻訳は非常に注意が必要です。 この問題に対する一般的な対応方法はまだ決定していません。 現状では、段落名は原文のままにしておいて、 個別に JM メーリングリストで対応方法を相談してください。
先に述べたような形式 で原文を保持している場合、 この原文を削除するには、次のようなコマンドを使用します。
perl -n -e 'print unless /^=begin\s*JM-comment/../^=end\s*JM-comment/' zebedee.pod > ../release/zebedee.pod