From: Austin Ziegler <austin@...>
Date: 2003-07-11T13:08:51+09:00
Subject: Re: A Ruby XSL stylesheet for DocBook?

On Fri, 11 Jul 2003 11:35:31 +0900, Jim Cain wrote:
>Austin Ziegler wrote: 
>>On Fri, 11 Jul 2003 08:54:59 +0900, Jim Cain wrote: 
>>Might it be easier to document the library with rdoc? You can cause
>>it to output to XML.
>Perhaps, but I prefer not to clutter my source code with an 
>abundance of commends. I would ultimately like to have more than
>just an API reference for my library, and I don't feel that the
>source code is the place for all that text.

Odd. I do consider the source the place for all that text -- I often look at the source code of what I'm using to see how I should be using it. Plus, by having the source and the documentation together (at least for English, in my case), I don't neglect to do the documentation or forget to do it. I just document everything. Sometimes this has also helped me identify when I've made things public when I meant them to be private.

>Something that would be really useful is if a tool could generate a 
>DocBook XML skeleton for all of the classes and methods in a 
>project.

>That would be a great basis for filling in the documentation.
>Hmmm.... :) 

rdoc --fmt xml outputs to the rdoc XML schema; because it's XML, it can be transformed to other formats. By putting basic documentation in the source, you can then have something that you can translate (with XSLT, presumably) to DocBook format.

I program against Oracle a lot, and I'm not sure how much I'd see myself using an application/library that I can't drop into the documentation quickly and easily, which I can with many other Ruby apps. I don't necessarily want to fire up a browser session when I'm coding.

-austin
--
austin ziegler    * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.07.10
                                         * 23:52:57