新井です。

>>> From: Toshiro Kuwabara <toshirok / yb3.so-net.ne.jp>
>>> Date: 28 Dec 1999 01:29:43 +0900
>>> Subject: [ruby-list:19937] Re: RD with method index (again)

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

あらまぁ、今回ははずしてしまいましたね。

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

メソッドに関しては重複は考慮しなくてもよいと思います。提案し
た慣習に従えばrubyの名前空間で重複しないはずなので(別ライブ
ラリ、同名関数なんてのは現在ありましたっけ？)

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

あと、1つのメソッドで複数の引数形式を書く場合一括で記述する
必要があります。(リファレンス先を一箇所にするため)

  --- method(hash)
  --- method(arg1..arg2)
  --- method(array)
      メソッドmethodは引数がハッシュの場合は...

> 他の案では、「Headline&DescListのInline付加は特殊記号のすぐ後にInline
> に使っている記号を置く事で行う」ってものです。こんな感じ。
>   ==={ Code
>   :| Var
> とか。(この例だと美しくないですが)

えっとこれは、

=== (({Code}))
: ((|Var|))

ってことですね。でもきっと一部だけInlineを使いたいことはありそう

  === ほげな(({HOGE}))の章
   ...

とか。参照側を((<ほげなHOGEの章>))とするのは簡単にはいかない
のでしょうか？(いかないのでしょうね)

> >その代わり、
> >  クラスメソッド:       --- Class.method
> >  インスタンスメソッド: --- Class#method
> >  クラス定数:           --- Class::Const
> >  ネストしたクラスのメソッド:
> >                        --- Class1::Class2.method
> >  関数:                 --- function#method (または --- method)
> >  演算子形式のメソッド:
> >                        --- Class#[]=(arg1, arg2)
> >                        --- Class#+(arg)
> >  グローバル変数:       --- $var
> >
> >などの*慣習*を提案します。

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

> リファレンスマニュアルみたいな用途を想定されていると思いますが、
> それ考えると"Class"をいちいち書くのが多少めんどくさいかもしれません。

うーん、クラスの宣言も可ってのはどうです？

@class Class

--- .method
--- #method
--- ::Const
...

・RDtoolのコアの処理では接頭語"Class"を"#method"に繋げるだけ
  の処理。
・参照する側はちゃんと((<Class#metod>))と書かないといけない。

となりますが。

> あと、Rubyのリファレンスマニュアルは演算子メソッドは
>   --- self + other
> のような書き方になっているので、ここらへんをどうするか、とか。

これは、それが望まれるのなら rb2xxx-lib.rbの仕事になると思い
ます。RDのフォーマットが rubyでの定義に似ていることはRDの書
きやすさ(コピーで済む)の点で良いことだと思います。

> >「WHITELINEはわかりにくい」

> これは前にこの方式に決めた時にも問題点に挙げられていたような。
> それとも、僕が問題点だと思っていながら発言しなかったのかも。
> 
> とりあえず、rd-mode.el使ってると\C-jで前の行とインデント揃えて
> くれるので、多少の手助けにはなるかと思います。

さらに、手元の新井版rd-mode.elではfont-lockでWHITELINEに色が
付きます(^^) (make-mode.el からdeffaceを拝借した)

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

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

そういう場合は現状のWHITELINE使えばいいかと思います。
Toshさんが「美しくない」と思うのと同じくらい私は行末の空行を
気にしてます。きっと^^

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

空の式ですね。# と ; なら大抵の言語はOKだろうと思いまして。

> >さらに、
> >
> >・RDにコメントが欲しい
> >
> >  行頭が"###"で始まる行をコメントとして扱うなんてのは？
> 
> 行毎だったら"=begin ###"と"=end"で囲んだ部分はフォーマッタからも無視される
> ので("###"の部分はほとんどなんでもよし)、それ使えば十分かなと。

なるほどrubyスクリプトにRDを埋め込む場合はこのようにすればい
いのですね。rubytkのようなすべてRD なファイルでは 
=end ... =begin で囲んでます。

> ただ、rubytk.rdを見た限りでは、あれは読み手にとっても意味のある情報かと
> 思いますので、多少ごちゃごちゃしてもコメントにしない方がいいんじゃないかと
> 思います。

以前どういう場合に使ってたか忘れましたが(^^;、現在の(手元の)
rubytk.rdでは1行だけコメントというのがちょこちょこあります。
これはRuby/Tkの特殊な実装のためなんですが・・・まぁとりあえ
ずコメントの件は保留にしておいても良いです(って別メールにも
書きましたが)。

> [REQ]のものは取り込むかどうかは、検討を加えた後でですね。

ですね。いろんな人の意見を聞いてみたいところです。

年越しになるとは思いますが、一旦暫定で作ってみてRubyのリファ
レンスマニュアルが書けるかどうか試してみようと思います。
html2texi使いまわせば簡単に変換できるかなと目論んでます。

# これを先にやった方が議論が進むかも知れませんね。

--
新井康司 (Koji Arai)