From: Austin Ziegler <austin@...>
Date: 2002-10-24T02:12:51+09:00
Subject: Re: Ruby.bah! (was Re: XMLParser, NQXML... and also RAA.succ)

On Thu, 24 Oct 2002 02:04:34 +0900, Jim Freeze wrote:
> On Wednesday, 23 October 2002 at 15:32:56 +0900, Austin Ziegler
> wrote:
>> On Wed, 23 Oct 2002 14:07:46 +0900, Sean Chittenden wrote:
>>>> Ruby, on the other hand, has two going on three different
>>>> formats, if I'm understanding what Sean is saying correctly.
>>> Sadly yes... however there is a saving grace with rubydoc, it's
>>> standard is XML and the other utilities export XML... which
>>> means that anyone can write a stylesheet that'll convert rdoc->
>>> rubydoc or rd-> rubydoc. These stylesheets will be included in
>>> the base rubydoc installation.
>> In some ways, though, I still think that this is probably the
>> wrong approach. IMO, either rdoc or rd needs to die. Ideally,
>> rdoc will pick up the ability to parse rd comments cleanly
>> (perhaps spitting out warnings) so that there only needs to be
>> one primary documentation tool.
> I have discussed this issue with the rdtool creators and they are
> on board with the Ruby-Doc effort. All raa app will be converted
> to the new rubydoc standard when it is available.

I still think that rdoc is a better choice for inline documentation,
and that rubydoc should be built on top of rdoc (as a consumer or
formatter). rdoc has the advantage of being relatively easy to read
in the code itself, whereas I find the rd that I've seen in modules
is ... hard.

rdoc, by the way, does SORT OF support rd format, but it's not
clean. (It doesn't ignore certain rd directives.)

> Man, you guys are long winded... ;`

This rant has been coming on for a while. (:

-- Austin Ziegler, austin@halostatue.ca on 2002.10.23 at 13.09.39