新井です。

>>> From: Toshiro Kuwabara <toshirok / yb3.so-net.ne.jp>
>>> Date: 20 Nov 1999 02:37:49 +0900
>>> Subject: [ruby-list:18766] Re: RD with Method Index (Re: I want rd2info (or rd2texi).)

> Toshです。

> あらいさんが要求していたのは"@findex"のようなものだと思っていたの
> ですが、そうでなくて"@defmethod"相当が欲しいってことですよね？

@findexなものよりは、@defmethodなものの方が好みなのはそうだ
と思います。単に慣れの問題かもしれませんけど。

ただ、元々の、西本さんの要求がそうであったように、
ruby-info.el 相当のことができる仕組み／情報を提供しさえすれ
ば、形式にこだわりはありません。

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

Texinfoは、リファレンスマニュアルを書くためにあると言っても
過言ではないように思います。逆に、RDはリファレンスマニュアル
のことを考慮しなさすぎだったかと。書けないわけじゃないけどそ
れを支援するもの、書きやすくするものがないんではないかな？

もちろん、HTMLによるrubyリファレンスマニュアルのようにRD で
作ることはできるとは思いますけど、それでは満足できないわけで
す。

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

>  (2) メソッド宣言用の専用Headlineの文法を新しく定義する。
> 
> 1番目のやり方は間接的で、ドキュメントの書き方に制約をつけます。もっとも、
> この形式で書かなくてはいけないと言う訳ではありません。恩恵は得られなくなり
> ますが。

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

(1) は、rubyのgetopts.html のようなクラスを持たないライブラ
リで苦しいですね。(Texinfo版でもインデックスに現れてない) こ
の形式のフォーマットも決めた方がよいでしょうね。

XMLのような簡易DTDがあるとよいかも。

今、個人的にRuby/Tkのリファレンスが必要になりそうなのですが、
(1)の方法でrubytk.rdを書いて見ました。書いてる途中なのでまだ
まだ記述は足りませんけど、叩き台にはなるかと思います。

templateを最後に付けます。特にRuby/Tkでは、extend を多用する
ので「extendしているモジュール」を追加しました。

# rubytk.rd.gz をin.comingに置きました。しばらくin.comingに
# 置かせてください。＞まつもとさん

これを書く上で、思ったのは。

=== method1
=== method2

のようなことをしても(見出しと見出しの間が離れるので)綺麗にエ
イリアスを表せないってのが気になりました。やっぱ、「見出し」
とは役割が違うよなぁっと。あと、引数とかも同じフォントになる
のが綺麗じゃない点で「見出し」の流用は苦しいかな。

このフォーマット専用のrd2xxx-lib.rdを作るなら、この辺りを考
慮するとより良いですね。

ところで、やっぱりRDって書きやすいですね。

=begin
= hoge
((<hoge>>)
=end
とかで、
/usr/local/lib/ruby/1.5/site_ruby/parser.rb:131:in `on_error':  (ParseError)
このエラーに苦しみましたけどね(さて、間違いはどこでしょう？^^;)


=begin
= CLASS/MODULE NAME
== スーパークラス:

((<>))

== インクルードしているモジュール:

((<>))

== extendしているモジュール

((<>))

== クラスメソッド:
=== 
== メソッド:
=== 
== モジュール関数:
=== 
== 定数:
=== 
=end