[ruby-list:23255] Re: readablity of RD

Toshです。

In message "[ruby-list:23246] Re: readablity of RD"
    on 00/06/14, Kenya Ogata <[e-mail]> writes:
>TAKAHASHI Masayoshi <[e-mail]> wrote:
>> 
>> # RDtool-0.6.3より
>> -----------------------------------------------------------------
>>       end # catch
>>     end # apply_to_Include
>>   end # RDVisitor
>> 
>> =begin
>> == module AutoLabel
>> this module provide automatical labeling feature to Visitors.
>> =end  
>>   module AutoLabel
>> 
>> =begin
>>   --- AutoLabel#prepare_labels(tree[, prefix])
>>         initialize method. call it before calling (({((<AutoLabel#refer>))}))
>>         ((|tree|)) is (({RDTree})), and ((|prefix|)) is a (({String})) which
>> -----------------------------------------------------------------
>> 
>> こういうのをぱっと見ても、RD的にAutoLabelの見出しに気づきにくいのです。
>> 
>
>こういう場合、module AutoLabel が重なってしまっていて、ちょっと
>気持ち悪いなと思うのですが、class や module 、def の直後で省略
>できるような記法はだめでしょうか。
>
>例えば、
>
>class Test
>=begin ==
>このクラスの説明です。
>=end
>
>みたいなものです。

う〜ん、これは結構何人かの人から言われているのでずっと考えてはいるの
ですが、「(RDには)書いていないもの」がフォーマッタに通すと現れるという
のが何か気持悪く感じます。そういう風に感じるのは僕だけなのかも知れませ
んが。

あとは、「Headline(見出し)を省略している」というのは結構大胆な省略で、
ドキュメントのGlobalな構造を省略してしまっているわけですから、問題が
起こりそうです。

例えば、上の例だと

  =begin
  = クラス
  =end
  ...
  class Test
  =begin ==
  このクラスの説明です。

  == クラスメソッド

  =end

とこれだけで、結構おかしいでしょ？

上のを
  
  = クラス
  == class Test <= 省略したもの
  ...
  == クラスメソッド

と解釈するとセクションの包含関係が崩れますから。

かと言って、上の「== クラスメソッド」を「=== クラスメソッド」と書くのも
なんか奇妙ですよね。

>あと、RD の処理をエスケープするような物があると
>自由なセパレータを入れられて嬉しいです。
>もっとも、なれている人から見るとかえって誤解を招く
>かもしれませんが。

RDは「処理」が前提にないので、「処理をエスケープ」というものも用意して
いないのです。処理する場合にも処理前のRDと処理して得られた出力(例えば
HTMLです)で(内容的に)違っている部分はなるべく内容にしましょう、という
のが基本原則なので。

# 例えばそういう理由で、Labelを直接に指定する構文は無く、見出しの内容
# そのものをLabelに使っていたりするわけです。

もし、このRDの原則とも矛盾せずに目的の機能が実現できる構文が見付かった
なら採用になるでしょうが、今のままだとと難しいです。

># 使いこなしていないのではずしていたらごめんなさい。

いえ、はずしていてもいませんでしたし、例えはずしていてもばんばん好き
勝手言ってもらって構いませんです。

それに、使いこなしていない人の意見はむしろ歓迎します。
逆に「使いこなしている人」があばたもエクボに見えてしまって間違った事
を言っていることもありますから、色々な人の意見が聞きたいです。

---
Tosh
Toshiro Kuwabara