From: Dave Thomas <Dave@...>
Date: 2002-07-23T00:28:23+09:00
Subject: rdtool and rdoc

Minero Aoki <aamine@mx.edit.ne.jp> writes:

>   In this thread, Nobuyoshi Nakada has noted that he had imported
>   OptionParser (optparse.rb) to the CVS repository.  This is the
>   preparation to bundle RDtool into the standard package.

At this risk of sounding biased... :)

I'm wondering if any consideration was given to including RDoc in the
base distribution?

I think RDTool is a wonderful utility for creating general purpose
documentation: if I were writing a manual I'd seriously consider using
it. However, I personally find it quite cumbersome when using it to
document source files: the documentation breaks up the source, and the
documentation writer is forced to repeat much of the information that's
in the source itself. That's why I wrote RDoc. Because it understands
the syntax of the languages it's documenting (Ruby, C extensions, and
Fortran currently) , it can produce meaningful output even if the
input file contains no documentation whatsoever. If also has output
options that are useful when working with source code (such as the
pseudo file/module/method browser bar for quick navigation, automatic
hyperlinks, and pop-up source code for method (just click on the
method name).

I've put up a small compare-and-contrast page at

    http://rdoc.sourceforge.net/rd/


So... A suggestion. I'd like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
the text from the PickAxe for the interpreter documentation and for
many of the libraries, and the others could be added as we go along.

For this to be useful, we'd need to bundle RDoc with Ruby.


Cheers


Dave