From: Toshiro Kuwabara <toshirok@...3.so-net.ne.jp>
Date: 2000-02-24T12:02:33+09:00
Subject: [ruby-talk:01553] Re: rdtool documentation for library modules

Hi,

Sorry I don't know about NetNews well, so I post this to this ruby-talk
instead of comp.lang.misc.

In message "[ruby-talk:01549] rdtool documentation for library modules"
    on 00/02/23, Dave Thomas <Dave@thomases.com> writes:
>Has rdtool matured sufficiently that it has been agreed what the
>section headings would be when documenting a library module? I saw
>that Tempfile has rd documentation--is that in the correct format?

  * RDtool can't make TOC of RD yet. but , I think, it is not so
    hard to make TOC. I push it into my jobs queue.
  * Tempfile.rd is correct format. but RD have changed last month,
    and Tempfile.rd is now obsolete.
  * We have discussed and worked about RD. RD is matured enough
    to write documents. but some future is lack now. One of them is
    something like header.

I'll show you what RD has changed last month.

  * MethodList, new RDElement which is special type of DescList for Method
    of Ruby(and other languages).

      EX: Tempfile.rd should be written such like...
       == Class Methods
       --- Tempfile.new(basefile[, tmpdir])
       --- Tempfile.open(basefile[, tmpdir])
             Create a tempfile named (...)

       == Instance Methods
       --- Tempfile#close([real])
             Close tempfile. (...)
       
       --- Tempfile#open
             Reopen tempfile.
       
       --- Tempfile#path
             (...)

  * method indexing(very prototype). 
    Example: <URL:http://www2.pos.to/~tosh/ruby/rdtool/ruby-man-mindex.html>

  * We come to be able to use Inline in Headline and term of DescList partly.

The newest version of RDtool is at
  <URL:http://www2.pos.to/~tosh/ruby/rdtool/rdtool-0.6.0-pre3.tar.gz>
But this version is not stable, not enough documented, and changable. 
Be carefull.
And new RDtool comes to require nakada's OptionParser
  <URL:http://www.ruby-lang.org/en/raa-list.rhtml?name=OptionParser>

>The reason I ask is that right now I'm documenting the library modules
>for the book. If people want, I could transfer this same documentation
>to the actual library source files in rd format, killing two birds
>with one stone. If that sounds like a good idea, I just need to know
>what format to use.

If you try to use RD for it, we will understand what isn't enough for RD.
I'll welcome it very much. :-)

rubyapi is another option. It is XML-base API document format which used for 
API documents of Ruby/Gtk. But I don't know rubyapi so well.

---
Tosh
Toshiro Kuwabara