Toshです。

In message "[ruby-list:18472] Re: Array doesn't include Comparable"
    on 99/11/10, EGUCHI Osamu <eguchi / shizuokanet.ne.jp> writes:

>そういや、ruby-info.elのポインタを示してなかった。
>  <ftp://ftp.netlab.co.jp/pub/lang/ruby/contrib/ruby-info.el>
>です。[ruby-list:14304]から始まるスレッドを見てもらってもよ
>いです。＞興味を持った人

とりあえず、ruby-texi-1.4と、ruby-info.elをとってきて、試して
みました。
なるほど、たしかにruby-info.elは便利そうです。リファレンスを
調べるのにEmacsの中でできるし、操作も簡単だし。

>> 要はメソッド索引が簡単にできればいいわけですから、RDの仕様に
>> 盛り込む事まで考えなくても、メソッド索引付きのRDの作成を支援
>> するツールとか、rd/rd2html-mindex.rbの様な方向で進めても、目的
>> は果たせそうですね。
>
>率直な意見としては、Headline 等に #, :: を含むかどうかでの判
>断って言うのは多少無理があるかなぁと思います。つまり、RDの仕
>様として盛り込んだ方が綺麗だろうと言うのが私の考え。ただまぁ、
>あまりRDを書いてない人間がごちゃごちゃ言うのも変なので、とり
>あえず戯言として受け取ってもらっても構いません。
>
>要求は利用者からのものの方が良いでしょうし、rd2html-mindex.rb
>は、そのための叩き台としては十分だと思うので、私から言うこと
>は(今のところ)これ以上ありません。

ruby-texi-1.4とTexinfo自体のinfoの@defmethodのトコあたりをちょっと
覗いて見てようやく理解しました。今までは僕はちょっと誤解していたと
思います。
あらいさんが要求していたのは"@findex"のようなものだと思っていたの
ですが、そうでなくて"@defmethod"相当が欲しいってことですよね？

確かにTexinfoのようなものを見ると"@defmethod"相当はあったほうがいい
のかも、と思えてきます。それが自然かも、と。

RDはこれまでのところ、plain text + 文章構造 みたいな感じに仕様が
決められて来ました。それに対して、Texinfoのアプローチは意味領域に
まで踏み込んで人間の意図をコンピュータに伝えようとしているように
見えます。
そのため、Texinfoにはリファレンスみたいなものを書く時に細かい指定
ができるようなコマンドがたくさんあるみたいですね。"@defmethod"と
"@deffn"は別になってたりもしますし。

さて、Texinfoのアプローチは魅力的ですが、Texinfoのようにたくさんの
コマンドを仕様に含む訳にはいかないRD((- RDは読みやすく書きやすいが
モットーなので、なるべくコンパクトに文法をまとめたいのです。-))に
はTexinfoを追っかけるのは無理があります、たぶん。
それじゃあ、どこまでTexinfoのイイトコを取り込むか？

とりあえず、リファレンス的なものはたくさん書かれるだろう、というのは
ほぼわかってるので、ここらへんの部分はなんとかしたいところです。

それで、ぱっと思い付く限りではやりかたは2通り。
 (1) リファレンスみたいなものは、きっとRubyのリファレンスマニュアルと
     だいたい同じ形式で書かれるだろうと仮定します。つまり、あるクラス
     についてのリファレンスの文章構造が、
       = Foo (クラス名)
       クラスについての説明。
       == Class Methods
       === new 
       説明。
       ...
       === Instance Methods
       === hogehoge
       説明。
       ...
     こんな感じになるであろうと仮定して、この形式に沿った文章構造の
     ドキュメントならば、メソッド索引などの付加情報も抽出できるという
     方法。
 (2) メソッド宣言用の専用Headlineの文法を新しく定義する。

1番目のやり方は間接的で、ドキュメントの書き方に制約をつけます。もっとも、
この形式で書かなくてはいけないと言う訳ではありません。恩恵は得られなくなり
ますが。
2番目のやりかたは直接的で単純ですが、問題もあります。定数((-なんか名前も
変わっちゃうみたいですが。-))・クラスメソッド・インスタンスメソッド・
クラス(さらにもしかしたら、モジュールとモジュール関数については別にすべき？)
について別々の文法を用意しなきゃならないので、文法を決めるのがまず
結構大変です。わかりやすく、覚えやすくて、見ためも美しくないとならないので。
それと、文法に組み込むと後で変更ができない、もしくは難しいってのもいや
なところですね。

さて、どうしたらいいでしょうか？

---
Tosh
Toshiro Kuwabara