From: Lyle Johnson <ljohnson@...>
Date: 2002-02-10T14:06:49+09:00
Subject: Re: Ruby Embedded Documentation

> Now, I am using Ruby on Linux, and I have downloaded Ruby version
> 1.6.6.  I was pretty surprised to find out that rdtool/rd2 is not
> there.  When I just took the rd2 script from Windows, it did not work in
> Ruby 1.6.6. on Linux because some 'require'd files are not available.

True, I don't think RDtool is actually part of the standard source
distribution. It just happens to be a part of the Ruby-for-Windows
installer -- which, of course, includes a lot of other non-standard Ruby
modules as well. RDtool is listed in the RAA, though, and the home page is
here:

    http://www2.pos.to/~tosh/ruby/rdtool/en/index.html

As Tosh mentions, RDtool depends on some other third-party Ruby modules
(like Racc, forwardable and OptionParser); all of these should be listed in
the RAA somewhere.

> I then searched the Ruby discussion archives, and one person mentioned
> that the emerging standard seems to be rdoc (http://rdoc.sourceforge.net).

I don't know if it's an "emerging standard" or not, but RDoc is very very
nice. Currently, it only has an HTML backend but I think Dave envisions
other output formats as well.

> So, right now, what is the best way to generate the embedded
> documentation?  And if I want to stick with rdtool, how can I obtain a
> working rd2 for Linux?  Thanks.

The "best" way depends on your definition of "best", I guess. I like RDoc
because the documentation comments (and associated markup) are a lot more
legible than those used by RD. RDoc's HTML output is very nicely organized,
hyperlinked, etc. and looks quite professional to me, too. If you haven't
done so already, you might take a look at the sample output from RDoc on the
RDoc home page (http://rdoc.sourceforge.net) and see what you think. On the
other hand, as of this writing, RDoc can't be used to generate Unix man
pages, TeX, or the various other backends supported by RDtool. And, given
RDoc's alpha status, its own markup style will no doubt continue to evolve
as more and more people start to use it and influence its design.

Hope this helps,

Lyle