"Philip Mateescu" <philip / dynasty.com> writes:

> However, that still doesn't respond to my question ... (sorry to bug
> you with this, I'm just curious about the way Ruby tools evolve).

OK, here's the plan.

RDoc can handle C and Ruby files, currently producing HTML and XML
documentation from them.

The plan is:

1. Enhance RDoc to generate ri-compatible output (and add support to
   the C parsing for a couple of facilities used in the interpreter).

2. Take the existing documentation from the reference section of
   Programming Ruby and munge it into RDoc format.

3. Matz has given us permission to insert this RDoc documentation into
   the Ruby source files (both of the interpreter and of the library
   files that come with it). When we're ready, we'll coordinate a
   small army of volunteers, and everyone gets to edit the Ruby
   distribution to insert RDoc comments in the correct places. Details
   of this haven't been worked out, so please don't volunteer just
   yet :)

4. We'll check all the annotated source back in to ruby-lang.org.

5. From then on, all documentation of the libraries and builtins that
   come with Ruby will be generated from the Ruby source itself. RDoc
   will generate it in HTML, CHM, XML, RDF, and ri format, and in
   LaTeX for printing.

6. When people add new functions to the interpreter, or change
   existing functions, the documentation is right there in a comment
   block next to the C method, so hopefully they'll make whatever
   minor changes are needed (one of the reasons that RDoc markup is
   lightweight is to make it easy to to this). This means that the
   documentation will _always_ be up-to-date, and up-to-date in all
   formats, from ri to HTML to ...  If anyone ever wants to write a
   Ruby book that has a reference section for this material (including
   any updated PickAxe), they'll be able to cull it from the latest
   sources.

7. Phase two of the plan is to have RDoc create a local database on
   each user's machine of documentation for _every_ Ruby module,
   library, etc on that machine. When something new is downloaded, its
   documentation will be incorporated into the hyperlinked whole. If a
   user or library developer writes a class that subclasses Hash, then
   you'll be able to click on 'Hash' in that class's documentation and
   be hyperlinked to the interpreter's Hash class documentation. This
   latter stuff is slightly further away.


Anyway, that's the plan. Just add time and stir.


Dave