From: Toshiro Kuwabara <toshirok@...3.so-net.ne.jp>
Date: 1999-12-28T01:29:43+09:00
Subject: [ruby-list:19937] Re: RD with method index (again)

Toshです。

今日、RDtoolのver.0.5.3を出してRAAに登録しました。

In message "[ruby-list:19934] RD with method index (again)"
    on 99/12/28, Koji Arai <JCA02266@nifty.ne.jp> writes:
>RDのメソッドインデックスに関して自分の中で大体案が固まってき
>ました。
>
>  --- Class#method(arg1, arg2, ...)
>      description...
>
>という"---"によるDESCLISTを提案します。("---"は単なる例です。
>Baseline下げすぎかなとも思うので)
>
>ただし、既存のDESCLISTである ":" との違いは、
>
>・エイリアスの表現が可能。
>
>  --- Class#method1
>  --- Class#method2
>      description...
>
>  (これは、":"にも欲しい)

これはver.0.5.3で修正済みです。

>・メソッド名部分だけをラベルと見倣す
>
>  "---" の後のSTRINGLINEのうち空白または開き括弧"("までをラ
>  ベルと見倣す。したがって、
>
>  --- Class#method(arg1, arg2)
>
>  に対するリファレンスは、((<Class#method>)) と書く。

リファレンスは結構色々悩んでるところです。ラベル重複をどう解決するか
もですが、このことも頭の中にはありました。

僕の案(ってほど具体的ではないですが)では「先頭の数文字、他のラベルとの
区別が可能なくらいまでの記述でリファレンスになるように判定を甘くする」
というものです。つまり上の例だと"((<Class#method>))"の他に、
"((<Class#meth>))"とかでも構わないとしてしまう(ただし他に同様に始まる
ラベルが無ければ)ということです。この案は既存のHeadline&DescListに対す
るリファレンスの方法で、Method indexのことは考慮していません。

この案はむしろ、現時点では不可能な、「Headline&DescListの中でのInline
の使用」を可能にする為に考えていたものでした。これが無いとメソッドの
名前とかをDescListのtermにするときに気持悪いので。
他の案では、「Headline&DescListのInline付加は特殊記号のすぐ後にInline
に使っている記号を置く事で行う」ってものです。こんな感じ。
  ==={ Code
  :| Var
とか。(この例だと美しくないですが)
これはTexinfoのtableのやりかたからもらってきました。

>  ラベル "Class#method" の部分に関してRDtoolのパーサは一切特
>  別扱いしない。つまり、"Class"の部分がクラス名であることや
>  "#"がインスタンスメソッドを表すことを意識しない。
>  (rd2xxx-lib.rbは意識しても良い。rd2texi-lib.rbを作ったとき
>  意識せざるを得ないので)
>
>といった感じです。開き括弧"("は特別扱いしない方が制約が少な
>くて良いかも知れません。その場合
>  --- Class#method (arg1, arg2)
>や、
>  --- Class#method arg1, arg2
>
>という書き方になります。結局最初の単語だけをラベルにした
>DESCLISTです。Rubyのメソッドインデックスの実現はこれだけで十
>分であると自分の中でほぼ結論付けました。(ただ、Texinfoに
>変換することを考えると、もう少しありそう)
>
>その代わり、
>  クラスメソッド:       --- Class.method
>  インスタンスメソッド: --- Class#method
>  クラス定数:           --- Class::Const
>  ネストしたクラスのメソッド:
>                        --- Class1::Class2.method
>  関数:                 --- function#method (または --- method)
>  演算子形式のメソッド:
>                        --- Class#[]=(arg1, arg2)
>                        --- Class#+(arg)
>  グローバル変数:       --- $var
>
>などの*慣習*を提案します。

リファレンスマニュアルみたいな用途を想定されていると思いますが、
それ考えると"Class"をいちいち書くのが多少めんどくさいかもしれません。
あと、Rubyのリファレンスマニュアルは演算子メソッドは
  --- self + other
のような書き方になっているので、ここらへんをどうするか、とか。

>以下、ちょっとしたRDに対する要望。
>
>「WHITELINEはわかりにくい」
>
>DESCLISTで、説明文の段落が複数あると間にWHITELINEを挿入しな
>ければなりませんが、スペースだから見えないんです。これは、
>DESCLISTを書きにくくしてしまうように思います。(私は行末の余
>計な空白を消したくなる人間です^^;)

これは前にこの方式に決めた時にも問題点に挙げられていたような。
それとも、僕が問題点だと思っていながら発言しなかったのかも。

とりあえず、rd-mode.el使ってると\C-jで前の行とインデント揃えて
くれるので、多少の手助けにはなるかと思います。

>で、
>
>・行頭の単体の";"または"#"もWHITELINEとして扱う

ええっと、どうしますかね。
WHITELINEが紛らわしいのはよくわかりますが、
なんか行頭にそういうのがあると美しくない気もしますし。

>というのも提案します。これらの文字にこだわるのは、Verbatimで
>rubyスクリプトを書いたときに
>
>   require "hoge.rb"
>;
>   hogehoge = "hoge"
>;
>   p hogehoge
>のように、WHITELINE文字があっても、そのまま切り出してrubyス
>クリプトとして実行できるからです。

あれ？Rubyって";"もコメント扱いになるんですか？しらなかった。

>さらに、
>
>・RDにコメントが欲しい
>
>  行頭が"###"で始まる行をコメントとして扱うなんてのは？

行毎だったら"=begin ###"と"=end"で囲んだ部分はフォーマッタからも無視される
ので("###"の部分はほとんどなんでもよし)、それ使えば十分かなと。
ただ、rubytk.rdを見た限りでは、あれは読み手にとっても意味のある情報かと
思いますので、多少ごちゃごちゃしてもコメントにしない方がいいんじゃないかと
思います。

>以上言いたいこと言ってますが。いかがでしょうか？(って
>ruby-talkに書かなきゃダメ？^^;)

ま、いいんじゃないでしょうか。僕も日本語の方が楽です。(^^;;;

>最後にrdtool-0.5.2に対するパッチを付けます。
>修正の順に
>・[REQ] 行頭の;をWHITELINEにする
>・[BUG] Verbatimの中にWHITELINEを入れると[BUG]と言われるバグの修正
>・[REQ] 行頭の###をコメントにする
>・[BUG] (('a')) ... (('b')) とすると 「a')) ... (('b」がVerbになる
>です。("--- method"はまだ修正中。その前に意見を聞こうと思いまして)

あ〜、またタイミングが。前にも書いた通り今日ver.0.5.3だしたのです。
# あらいさんとはタイミングいいのか悪いのか。(^^;;;

[REQ]のものは取り込むかどうかは、検討を加えた後でですね。
バグフィックスはなるべく早いうちに取り込みます。ありがとうございました。

---
Tosh
Toshiro Kuwabara