From: jihg Date: 2002-02-27T01:35:25+09:00 Subject: [ruby-list:34095] Re: localized document jihg です。 まったく見当違いかもしれないけど、不思議に思うことがあるので書いて見ま す。 From: HIDAKA Takahiro [mailto:cv8t-hdk@asahi-net.or.jp] Subject: [ruby-list:34093] Re: localized document ＞　ひだかです。 ＞ ＞　本題というかコメントの話ですが、ファイルを分割するとして、 ＞ ＞1. ソース(foo.rb)からコメントだけを抜き出して foo.rdoc.ja を作る。 ＞2. foo.rdoc.ja に日本語のコメントを書くときは対訳形式で書く。もとのコ メントは ＞ 一切変更しないで残して、対訳部分は # 以外の別の記号をつける ＞ ＞ 例) ＞ # This library is... ＞ % このライブラリは... ＞ # This function is... ＞ % この関数は... ＞ ＞3. RDoc では、両方のファイルを読んで、一致するコメントの対訳部分だけを ＞ 置き換える。 ＞4. 一致しないコメントがあれば警告を出力する ＞ - 翻訳もれや元ドキュメントの更新をチェックできる。 ＞ - foo.rb → foo.rdoc.ja の同期スクリプトがいるかも。。 ＞5. もともと日本語で書いていて、英語コメントをつけたいときのために、 ＞ foo.rb(日本語) と foo.rdoc.en を用意すれば入れ替えることのできる ＞ ツールも用意する? ※言語と表記すると混乱を生みそうなので"言葉"と書きます。意味は同じです。 正しく解釈できてると思うけど、一応、僕の理解を。 ◆作成者側 1.僕は日本語しか分からないので、コメントは日本語で書きたい。 2.で、作成者(僕）と利用者（誰か）の理解できる言葉が違うとき、利用者が 理解しやすいように、そっちの言葉のコメントも用意したい。 3.そうするためにはどうしたらいいか？ 4.コメント部分を別ファイルに抜き出す。 5.拡張子は、例えば英語なら、元ファイル名.rdoc.en 6.ファイルは対訳形式で、行ごとに原文と訳文を併記する。 7.ひとまとめにして配布する。 ◆利用者側 1.ファイルを RDoc に渡すときスイッチをつける。たとえば英語なら -en と か。 2.RDoc はファイル名.rdoc.en を探す。 3.あればそれで置き換える。 4.原文をキーにして訳文で置換する。 5.一致するキーがないときは警告する。 で、思うんだけど、元のスクリプトのコメントを直接置き換えてみるのはどう？ ソースを読む人の助けになりそうなんだけど。 ※問題は、パッチを提供する場合。ちょっと面倒。 ＞このくらいやると使いやすくなるでしょうか。まだまるっきり妄想ですが。 ＞でも、こんなに複雑なら、最初から一体化して書いたほうがましなのかな。 対応する言葉が多くなるとコメントが肥大化する。そうなると、英語に統一すれ ばいいってはなしが出てくる。併記する必要ある？ って話。 「自前でファイルを用意すれば、対応してない言葉でもメニューなどの表示を変 えられます」 って、あるソフトの説明に書いてたんだけど、フォントを変えられなくて、悲し い思いをしたことがあります。便利なんだけど、EU 圏のことしか考えてないっ ていうのがねえ。 RDoc はフォントは考慮しないだろうから、こういうことができるし。一本化す るより別ファイルにしたほうが、より多くの言葉に対応できていいんじゃな い？。