I took a look at your comparison page. I’ve not used either, but some things stood out to me…
What stands out to me is that the RDTool result is simple, single-paged, and presumably easy to print or to convert to other forms via printing. It also is likely to be easy to read in lynx and other similar browsers (including speech-enabled browsers for the blind).
The RDoc result is heavily frames-based and seems specifically designed for Web-access. It’s cute and quite usable in the Web context, but likely not as easily accessible outside of the Web.
For me, seems like RDTool is more generally usable. Also, programmers SHOULD write documentation - and keep it up to date.
Is it possible to have both available and/or to use both at the same time? Do they interact well or badly?
Dave@PragmaticProgrammer.com 7/22/02 10:28AM >>>
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