[ruby-list:19988] Re: RD with method index (again)

Toshです。
RDtoolをいじってたらこっちの返事が遅くなっちゃいました。
あらいさんにパッチしていただいたバグなどを修正したバージョンをRAA
に登録しました。

In message "[ruby-list:19962] Re: RD with method index (again)"
    on 99/12/28, Koji Arai <[e-mail]> writes:
>> 僕の案(ってほど具体的ではないですが)では「先頭の数文字、他のラベルとの
>> 区別が可能なくらいまでの記述でリファレンスになるように判定を甘くする」
>> というものです。つまり上の例だと"((<Class#method>))"の他に、
>> "((<Class#meth>))"とかでも構わないとしてしまう(ただし他に同様に始まる
>> ラベルが無ければ)ということです。この案は既存のHeadline&DescListに対す
>> るリファレンスの方法で、Method indexのことは考慮していません。
>
>メソッドに関しては重複は考慮しなくてもよいと思います。提案し
>た慣習に従えばrubyの名前空間で重複しないはずなので(別ライブ
>ラリ、同名関数なんてのは現在ありましたっけ？)

あ、上の話はそういう意味ではなかったのですが(「僕の案」というのは
「以前話していた、Ruby Reference Manual形式のRDの解析を採用したとき
の話です。)、この話も重要そうですね。

>もちろん、
>= Class#method
>なんて章を作るとダメですけど。仕方ないかな。

この場合にはむしろ既存のラベル重複の問題ですから、解決にはパス指定
のリファレンスみたいなものを採用する、ってことになるでしょう。
もし、"--- Class#method"と"= Class#method"が両方あったならば
((<Class#method>))では"--- Class#method"を優先、くらいはしてもよいかも。

>あと、1つのメソッドで複数の引数形式を書く場合一括で記述する
>必要があります。(リファレンス先を一箇所にするため)
>
>  --- method(hash)
>  --- method(arg1..arg2)
>  --- method(array)
>      メソッドmethodは引数がハッシュの場合は...

こういうメソッドって、どの程度使われているものなんでしょうか？
# 別にこういうのを認めないと言うつもりは無いですが。
Rubyの標準クラスではたぶんArray#[], Array#[]= くらいですね。
リファレンスマニュアルは残念な事に、こういう形にはなってません。

>えっとこれは、
>
>=== (({Code}))
>: ((|Var|))
>
>ってことですね。でもきっと一部だけInlineを使いたいことはありそう
>
>  === ほげな(({HOGE}))の章
>   ...
>
>とか。参照側を((<ほげなHOGEの章>))とするのは簡単にはいかない
>のでしょうか？(いかないのでしょうね)

とりあえず、問題がおきそうなのはReferenceとか、Footnoteとかですね。
  = ((<substitute|label>)) <- 今まだつかえないけど代わりのテキストがある場合。
  # ((<substitute>)) or ((<"substitute|label">))??
  # 後者は"substitute|label"ってラベル、って意味です。
  = Footnote((- Footnoteは長くなりがちなのでラベルにするには無理があります。-))
  = ((<URL:http://www.ruby-lang.org>))はRubyのオフィシャルサイト
  # これもラベルがどうなるか難しかったり。

極端な例をあげましたが、一番悩んでいたのは、ラベルには"((.", ".))"
のようなカッコはないほうがいいのだろうか？ってことです。
# RD書く人は生のRDを見ているので、カッコを省略した形にするのはわかり
# にくいかも？ それとも、カッコをつけたままのほうがわかりにくい？

あと、リファレンスの方も対応するHeadlineと同じように修飾すべきなのか？
ってのもありますね。例えばあらいさんの例だと、"((<ほげなHOGEの章>))"を
  <A HREF="...">ほげな<CODE>HOGE</CODE>の章</A>
というふうに出力すべきなのか。

>  トップレベルの定数:    --- const::Const (または、Const または Object::Const)

トップレベルの定数は"main::Const"では？

>> リファレンスマニュアルみたいな用途を想定されていると思いますが、
>> それ考えると"Class"をいちいち書くのが多少めんどくさいかもしれません。
>
>うーん、クラスの宣言も可ってのはどうです？
>
>@class Class
>
>--- .method
>--- #method
>--- ::Const
>...
>
>・RDtoolのコアの処理では接頭語"Class"を"#method"に繋げるだけ
>  の処理。
>・参照する側はちゃんと((<Class#metod>))と書かないといけない。
>となりますが。

この程度の処理だったら簡単にこの形式のドキュメントを
"--- Class#method"に直すための補助ツールで実現できそうですが、
このやり方がいいかどうかは、わかりませんね。

>> あと、Rubyのリファレンスマニュアルは演算子メソッドは
>>   --- self + other
>> のような書き方になっているので、ここらへんをどうするか、とか。
>
>これは、それが望まれるのなら rb2xxx-lib.rbの仕事になると思い
>ます。RDのフォーマットが rubyでの定義に似ていることはRDの書
>きやすさ(コピーで済む)の点で良いことだと思います。

なるほど。同意します。

>> あれ？Rubyって";"もコメント扱いになるんですか？しらなかった。
>
>空の式ですね。# と ; なら大抵の言語はOKだろうと思いまして。

あ、そうか。なるほど。
# Rubyだと";"つかうのはone-linerのときくらいだから。(^^;;

>年越しになるとは思いますが、一旦暫定で作ってみてRubyのリファ
>レンスマニュアルが書けるかどうか試してみようと思います。
>html2texi使いまわせば簡単に変換できるかなと目論んでます。
>
># これを先にやった方が議論が進むかも知れませんね。

それはありがたいです。
ただ、rubytk.rdを見ても思いましたが、やっぱり一番必要なのは複数ページの
HTMLに分割して出力する機能ですね。(^^;;

---
Tosh
Toshiro Kuwabara