From: Toshiro Kuwabara <toshirok@...3.so-net.ne.jp>
Date: 1999-10-31T00:42:03+09:00
Subject: [ruby-list:18154] Re: I want rd2info (or rd2texi).

Toshです。


> この例は、"=end\s+class" をパースする提案を含みま
> す？この点が重要なんですが。

いえ、入りません。メソッド名で索引、くらいなら他に方法ありますし。

まぁ、正直めんどいってのもありますが。ちゃんとやろうと思ったら、
Ruby本のrtagsくらいのことをやらないといけなくなるんじゃないかと。
それと、今は前処理の段階でRDの部分だけ抜きだしてしまっているんですが、
これをスクリプトファイルまるごとちゃんとパースしようとしだすと、
字句処理とかがかなり複雑になりそうなんですよね。

> > Rubyスクリプトのパースをする手間はともかく、なんか制限がついてしまうのは
> > あまり賛同できないんですよね。
> 
> これは、よくわかります。でも、今のRDっていろんな面
> でHTML的なところがあって、普及は早いだろうけど、デー
> タの再利用は難しいだろうなと思ってます。ruby用のド
> キュメントなんだからruby のclassやmethodに関しての
> なんらかの便宜はあっても良いんではないかな・・・と。
> (書いたことないくせになんかエラそうなこと言ってる 
> ^^;)
> 前回の私の提案は、「普通、クラスの説明はクラス定義
> の直前に書くよね？」っていう前提を置いた上で、あま
> り制限にならないかなと判断しました。

う〜ん、例えばライブラリのドキュメントの書き方に推奨されるスタイル
みたいなものは、確かにあってもいいと思うんですよ。
でも、まずひとつめに、推奨されるスタイルってのもRDのフォーマット自体
になにかそういう制約がついてる、よりは、メジャーなライブラリのドキュ
メントに共通のスタイルがある、とかそういう「暗黙の了解」みたいなもの
の方がいいんじゃないかな、と。
RDのポリシーもRubyと同じで「楽しくお手軽」だから、そういうスタイルを
意識しすぎる事でドキュメントが書きづらくなっちゃうのは良くないかなと。
# んで、バベル-17(洗脳)が理想と。(^^;;
もう一つはたぶん実際にはRDの使い方の半分はスクリプトに埋め込まない形
の物になるんじゃないか、と思ってるので。実際、ファイルがいくつかに
わかれていたりするとスクリプトに埋め込み、ってのはどうしても無理が
でてくる場合もあるでしょうから。

> # でも、スクリプトじゃないもの(ruby本体とか)で、リ
> # ファレンスマニュアルを作るのに通用しない。(- -;

> > この書き方もライブラリみたいな物にはいいけど、コマンドのスクリプトのRD
> > としては(どんなメソッドがあるかなんてツール使う人にはどうでもいいわけで
> > すから)不適切だと思いますし。
> 
> rd2htmlとは、別のコマンドにするってのはどうでしょ
> うか？

御提案はRD自体のセマンティクスに関わってますから、ツールを分けるのは
簡単でも、そうすると微妙に違う2種類のRDがあることになっちゃいます。
# それが悪い事か？っていうのは色々意見が出てくるかと思いますが。

> 例えば、青山さんのCGI.rb は、ちょうどToshさんの意
> 見のようになってますが、
> 
> =begin
> === ESCAPE HTML &"<>
>         CGI::escapeHTML("string")
> =end
>   def CGI::escapeHTML(string)
>     ...
>   end
> 
> =end\s+def をパースすれば、こいつからメソッド名に
> よる索引が作れるんですね。rd2html-index.rb とか作っ
> て、メソッド名→見出しへの索引ページが作れる仕組み
> があるだけでもありがたいのではないでしょうか？そし
> て、そういうツールがあってウケれば、やわらかい強制
> 力(?)が働いて、そういう書き方が増えて行く。

例えば、「公開メソッド(単にpublicって意味でなく)は見出しにする」とか
いうスタイルにすればRDtoolが目次を出力してくれるようになれば、メソッド
で索引は実現可能ですよね？
僕はそういう方がいいと思ってるんです。必ずしもメソッドをずらっと並べる
リファレンス的なスタイルがあらゆる場合に最適ってわけじゃないでしょうし。
それに、ドキュメントで望ましいメソッドの順番とプログラムのメソッドの
順番が必ずしも一致するわけでもないんじゃないかと。

> 以上、思い付きで書いてみました(なにかうまく頭の中
> が整理できてないらしい)。rdtool触ったのがつい先日
> のことなので、考えが浅はかな点はご容赦願います
> (_ _)

いえいえ、貴重な御意見をどうもです。
ruby-talkの方でも「他のRDへの参照」とかの話題も出ていますので
何か御意見があればそちらもよろしくお願いします。
# infoに出力するときにはもろに影響がある問題でしょうし。

---
Tosh