[ruby-talk:00684] Re: Summary of discussion about RD (Re: Documentation about RD?)

Hi Tosh and all,

Toshiro Kuwabara <[e-mail]> wrote:
> And here comes another suggestion in [ruby-list:16200] from Mr.Takahashi.

Yes, it's me :-)

> : Separater
>   Like HR of HTML.
(snip)
> I think we don't need separater, we should use HeadlineElement instead of 
> separater.

hmmmmm. I agree that we can write docuemnt without separator, but
separator is useful. For example, when I write several classes in one
page, I'd like to use separator.

cf. http://www.netlab.co.jp/ruby/man-1.4/socket.html
     -> use separator between classes.

    http://www.netlab.co.jp/ruby/man-1.4/thread.html
     -> not use separator

I think we will write something like Ruby Manual, Ruby Library Manual,
Ruby tutorial in RD. In other words, RD should be powerful to describe
Ruby Manual and other documents. These document used separator, so
it's better that we can use it in RD, too.

> : Multi-TextElement in definition part of DescListItem(?).
>   Maybe, He want to write more than one paragraph in definition.

Yes. For example, in http://www.netlab.co.jp/ruby/man-1.4/Array.html


  self[start, length] = val 

    Replace the length items from start with val. If val is not an array,
    the type of val will be converted into the Array using to_a. 

    Example: 

       ary = [1, 2, 3, 4, 5]
       ary[0..2] = [0, 0] # Changed to [0, 0, 4, 5]
       ary[1, 0] = [7]    # Changed to [0, 7, 0, 4, 5]


If I cannot use Multi-TextElement, I can write it as follows:

=begin
==== self[start, length] = val 
Replace the length items from start with val. If val is not an array,
the type of val will be converted into the Array using to_a. 

Example: 

   ary = [1, 2, 3, 4, 5]
   ary[0..2] = [0, 0] # Changed to [0, 0, 4, 5]
   ary[1, 0] = [7]    # Changed to [0, 7, 0, 4, 5]
=end

But it's better to use describe methods's description with DescList,
I think. Because it's exactly `Description List' of methods :-)

TAKAHASHI Masayoshi ([e-mail])