Toshです。


> >		    メソッド名で索引、くらいなら他に方法ありますし。
> 
> あれ？そうなんですか？これはヤパイ。私がRDを知らな
> いだけだったらゴメンナサイ。
> 
> もう一度考え直して、意見をまとめます。

あ、いや。これはこの後に書いたメソッドをHeadlineでならべちゃえば、
目次作るくらいの事はできるけどね、ってやつです。それで不十分なら
もちょっと解決策を考えなきゃなりませんね。
もひとつお手軽な(というか今の仕様でやりくりする)方法としては、
"((:Class#Method:))"って書く、とか。これはそのまんまインデクスの
機能です。

> まず大前提
> 1. メソッドの索引を作れる仕組みがあるとよい。
> そして、できれば
> 2. ライブラリのマニュアルは、ある程度スタイルが統一
>    された方がよい。
> このための案として、
> 3. =end\s+(def|class|module) をパースしてはどうだろう？
> 
> ってところです。Texinfoへの変換も1、2が満たされれ
> ばたぶんなんとかなると思います。つまり、3っていう
> のは案の1つであって全然別の方法でも構わないです。

ふむふむ。

> > でも、まずひとつめに、推奨されるスタイルってのもRDのフォーマット自体
> > になにかそういう制約がついてる、よりは、メジャーなライブラリのドキュ
> > メントに共通のスタイルがある、とかそういう「暗黙の了解」みたいなもの
> > の方がいいんじゃないかな、と。
> 
> で、暗黙の了解を作るための材料みたいなのがあった方
> が良いと思うんですが、この点はどうでしょ？
>
> RD側で「別に使う必要はないですよー。でも、これ使え
> ば後々得しますぜ。ダンナ」みたいなものを用意するっ
> てことですが。これは制約を作ることにはならないです
> よね？

そういうのは別に構わないし、あれば便利な物はあったほうがいいかと
思います。
ただ、僕は保守的なのか割とRD自体の機能をどんどん追加していってそれ
を実現するのに消極的な(というか結構きっぱり反対してるかも(^^;;)だけで。

> 具体的な*例*で言えば、例えば以下の3種類の見出しは
> 単にフォーマットしただけならまったく同じ見ためにな
> るようにします。
> 
> == Foo
> =c Foo
> =d Foo
> 
> ただし、=c(lass) にはクラス名、=d(ef) にはメソッド
> 名の意味を持たせているためメソッド名だけの索引を作
> るのが簡単になります。

そういうわけで、これもRD自体のシンタックスに手をいれること
になるので、慎重な態度をとってしまうのですね。

例えば、
== Class#Method
って感じに、メソッド名と*思われる*見出しを見付けて索引を
つくる、ってツールであれば、(RD自体には変更を迫らないので)
反対する理由もありません。
# これだと、Headlineの付け方に制約出て来ちゃうけど、やりたい人だけ
# そうすりゃいいことなので、まぁ、構わないかと。

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

そんな感じでいいんじゃないかと。
黙っていれば自然とノウハウが集まって、標準的な書き方とか
便利なツールとかを誰かが勝手に作ってくれるんじゃないかと
期待してます。
# バザール方式？(^^;;

> > 例えば、「公開メソッド(単にpublicって意味でなく)は見出しにする」とか
> > いうスタイルにすればRDtoolが目次を出力してくれるようになれば、メソッド
> > で索引は実現可能ですよね？
> 
> そうでしょうか？目次と索引は全然別物だと思うんです
> けど、この辺で意見が食い違うのはなぜだろう？
> 
> 私がRDにまだ詳しくないからかもしれないので、全然別
> の例をあげます。
> 
> HTMLで書かれたRubyのリファレンスマニュアルは、メソッ
> ドも変数も見出しもあらゆるものが<A NAME="..."></A>
> でマークされてます。HTMLなんだから当然ですよね。

# 余談。
RDの場合には、HeadlineとDescListのTermに勝手にラベル(HTMLだと
<A NAME="label:n">...</A>がつきます。
そして他の部分にラベルつけるって機能は今のところなし、です。

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

う〜ん。
Headlineにはメソッド名しかつけない、とか、Indexをメソッド名だけにしか
使わないとか、しなきゃ無理じゃないですかねぇ。
やれるとこまでやって、上に挙げたような「Headlineからメソッドらしいもの
を自動で取り出す」ってやりかたが精いっぱいでしょう。
# そういうのはrubyapiの方に任せてしまおうか、って気もちょっとあり。

# ところで、MethodIndex.htmlって手元のリファレンスマニュアルに
# 見当たらないのですが、どこでしょ？

> # 実際、マニュアルからではなくruby本体から
> # Object#methods を使って自動生成しているように見
> # えます。(ん？RDにもその手が使えないかなぁ？)
> 
> RubyのリファレンスマニュアルをRDに書き換えることを
> 考えたとき、これは可能でしょうか？(可能ならよいの
> ですが、話終っちゃうけど)

上に書いた通り、「無理」か「工夫すればできないわけでもないけど、・・」
くらいでしょうか。

> > ruby-talkの方でも「他のRDへの参照」とかの話題も出ていますので
> > 何か御意見があればそちらもよろしくお願いします。
> 
> ruby-talkは一時期流量が多くなってついていけなくなっ
> たのでした。たしかRDのせいだったような(^^; (今、妙
> に古いバグ報告とか読んでたりしてます)

そです。(^^;;＜RDのせい
ただ、ちょっと前にあらかた収束しちゃっいましたが。

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

RD自体のドキュメントも書かなきゃならんような気もしてますが、
さぼってます、すみません。

> > # infoに出力するときにはもろに影響がある問題でしょうし。
> 
> そうなんですよねぇ。結局、
> 
> 4. Texinfoにするための情報がRDに足りない
> 
> んですよ。(結局、私の個人的な要求はこっちだった^^) 
> 理解が足りないだけかも知れませんが。とりあえず、も
> う少しお勉強してから出直したいと思います。

RD自体がとりあえずHTMLとLaTeXあたりを参考に最低限のものだけを
詰め込んだ、って感じなので、本当に情報が足りてない可能性はあり
ますね。僕はtexiわからないので、どこらへんが足らないのかよく
わからないんですが。

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

Texinfoとかは興味あったりもするので、これを機にちょっと調べて
みようかと思ってます。

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

どうもこちらこそ。

---
Tosh
Toshiro Kuwabara