From: David Douthitt Date: 2002-07-23T04:19:06+09:00 Subject: Re: rdtool and rdoc This is a MIME message. If you are reading this text, you may want to consider changing to a mail reader or gateway that understands how to properly handle MIME multipart messages. ----=_NextPart_ST_14_04_46_Monday_July_22_2002_10666 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable I took a look at your comparison page. I've not used either, but some thin= gs stood out to me... What stands out to me is that the RDTool result is simple, single-paged, an= d presumably easy to print or to convert to other forms via printing. It a= lso is likely to be easy to read in lynx and other similar browsers (includ= ing 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 SHOU= LD 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 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 ----=_NextPart_ST_14_04_46_Monday_July_22_2002_10666 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable

I took a look at your comparison page. I've not used either, but= some=20 things stood out to me...

What stands out to me is that the RDTool result is simple, single-page= d,=20 and presumably easy to print or to convert to other forms via printing.&nbs= p; It=20 also is likely to be easy to read in lynx and other similar browsers (inclu= ding=20 speech-enabled browsers for the blind).

The RDoc result is heavily frames-based and seems specifically designe= d for=20 Web-access. It's cute and quite usable in the Web context, but likely= not=20 as easily accessible outside of the Web.

For me, seems like RDTool is more generally usable. Also, progra= mmers=20 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=20 >>>
Minero Aoki <aamine@mx.edit.ne.jp>=20 writes:

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

At this risk of sounding biased...=20 :)

I'm wondering if any consideration was given to including RDoc in= =20 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 cumbers= ome=20 when using it to
document source files: the documentation breaks up the source, and the
documentation writer is forced to repeat much of the=20 information that's
in the source itself. That's why I wrote RDoc. Becaus= e it=20 understands
the syntax of the languages it's documenting (Ruby, C extens= ions,=20 and
Fortran currently) , it can produce meaningful output even if=20 the
input file contains no documentation whatsoever. If also has=20 output
options that are useful when working with source code (such as the
pseudo file/module/method browser bar for quick navigation,=20 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...=20 A suggestion. I'd like to propose RDoc as the tool used to
document Ruby= =20 libraries and the Ruby interpreter itself. We could use
the text from th= e=20 PickAxe for the interpreter documentation and for
many of the libraries,= and=20 the others could be added as we go along.

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

Cheers

Dave

----=_NextPart_ST_14_04_46_Monday_July_22_2002_10666--