新井です。

>>> From: Toshiro Kuwabara <toshirok / yb3.so-net.ne.jp>
>>> Date: 31 Oct 1999 00:42:03 +0900
>>> Subject: [ruby-list:18154] Re: I want rd2info (or rd2texi). 

> Toshです。

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

あれ？そうなんですか？これはヤパイ。私がRDを知らな
いだけだったらゴメンナサイ。

もう一度考え直して、意見をまとめます。

まず大前提

1. メソッドの索引を作れる仕組みがあるとよい。

そして、できれば

2. ライブラリのマニュアルは、ある程度スタイルが統一
   された方がよい。

このための案として、

3. =end\s+(def|class|module) をパースしてはどうだろう？

ってところです。Texinfoへの変換も1、2が満たされれ
ばたぶんなんとかなると思います。つまり、3っていう
のは案の1つであって全然別の方法でも構わないです。

なので、=end\s+class とかの話は、とりあえず忘れる
ことにします。

> でも、まずひとつめに、推奨されるスタイルってのもRDのフォーマット自体
> になにかそういう制約がついてる、よりは、メジャーなライブラリのドキュ
> メントに共通のスタイルがある、とかそういう「暗黙の了解」みたいなもの
> の方がいいんじゃないかな、と。

で、暗黙の了解を作るための材料みたいなのがあった方
が良いと思うんですが、この点はどうでしょ？

RD側で「別に使う必要はないですよー。でも、これ使え
ば後々得しますぜ。ダンナ」みたいなものを用意するっ
てことですが。これは制約を作ることにはならないです
よね？

(3番はこれを満たさないようにも見えるけど、なんとか
できないわけじゃない。あっ忘れるんだった^^;)

具体的な*例*で言えば、例えば以下の3種類の見出しは
単にフォーマットしただけならまったく同じ見ためにな
るようにします。

== Foo
=c Foo
=d Foo

ただし、=c(lass) にはクラス名、=d(ef) にはメソッド
名の意味を持たせているためメソッド名だけの索引を作
るのが簡単になります。

おそらく、先にRD側で書き方を決めつけるよりは、皆の
書き方を見てその後でRD側がそれに合せた書きやすさを
(必要なら)提供する。ってことを考えてるのですよね？
それはそれで全然構いません。(今、それほどRDに夢中っ
てわけでもないですし)

> 例えば、「公開メソッド(単にpublicって意味でなく)は見出しにする」とか
> いうスタイルにすればRDtoolが目次を出力してくれるようになれば、メソッド
> で索引は実現可能ですよね？

そうでしょうか？目次と索引は全然別物だと思うんです
けど、この辺で意見が食い違うのはなぜだろう？

私がRDにまだ詳しくないからかもしれないので、全然別
の例をあげます。

HTMLで書かれたRubyのリファレンスマニュアルは、メソッ
ドも変数も見出しもあらゆるものが<A NAME="..."></A>
でマークされてます。HTMLなんだから当然ですよね。

あのマニュアルには、MethodIndex.htmlっていう
のもあるんですけど、はたしてあのマニュアルから
MethodIndex.htmlを自動で生成できるでしょうか？

# 実際、マニュアルからではなくruby本体から
# Object#methods を使って自動生成しているように見
# えます。(ん？RDにもその手が使えないかなぁ？)

RubyのリファレンスマニュアルをRDに書き換えることを
考えたとき、これは可能でしょうか？(可能ならよいの
ですが、話終っちゃうけど)

> ruby-talkの方でも「他のRDへの参照」とかの話題も出ていますので
> 何か御意見があればそちらもよろしくお願いします。

ruby-talkは一時期流量が多くなってついていけなくなっ
たのでした。たしかRDのせいだったような(^^; (今、妙
に古いバグ報告とか読んでたりしてます)

RDを理解するには、あちらの議論もしっかり読まないと
いけませんね。

> # infoに出力するときにはもろに影響がある問題でしょうし。

そうなんですよねぇ。結局、

4. Texinfoにするための情報がRDに足りない

んですよ。(結局、私の個人的な要求はこっちだった^^) 
理解が足りないだけかも知れませんが。とりあえず、も
う少しお勉強してから出直したいと思います。

# 別に、Texinfo大好き人間ってわけじゃないんですけ
# どね。信じてもらえないかも知れませんが(^^;

# 長々とすみません。お時間のあるときで構いませんの
# でおつき合いしてくださいませ。

--
新井康司 (Koji Arai)