I’m writing documentation for my Oracle library, and I was wondering if
anyone has come across or has written an XSL stylesheet for DocBook that
is customized for Ruby? The standard language choices (C, C++, Java,
Perl) do not produce an acceptable syntax for method prototypes.
Cheers,
Jim
Might it be easier to document the library with rdoc? You can cause it to output to XML.
-austin
On Fri, 11 Jul 2003 08:54:59 +0900, Jim Cain wrote:
I’m writing documentation for my Oracle library, and I was wondering
if anyone has come across or has written an XSL stylesheet for
DocBook that is customized for Ruby? The standard language choices
(C, C++, Java, Perl) do not produce an acceptable syntax for method
prototypes.
–
austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.07.10
* 20:24:20
Jim Cain wrote:
I’m writing documentation for my Oracle library, and I was wondering if
anyone has come across or has written an XSL stylesheet for DocBook that
is customized for Ruby? The standard language choices (C, C++, Java,
Perl) do not produce an acceptable syntax for method prototypes.
I have not come across such a DocBook stylesheet, but would be
interested in hearing about one if you get any leads.
As an aside, an emerging (or is it official?) standard for Ruby module
documentation is RDoc (http://rdoc.sourceforge.net). If you’re not
already aware of it, you might want to investigate this as an
alternative or at least an addition to DocBook-style documentation.
Austin Ziegler wrote:
I’m writing documentation for my Oracle library, and I was wondering
if anyone has come across or has written an XSL stylesheet for
DocBook that is customized for Ruby? The standard language choices
(C, C++, Java, Perl) do not produce an acceptable syntax for method
prototypes.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.
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… 
In any case, I think I’ll look into writing some XSL for Ruby myself.
On Fri, 11 Jul 2003 08:54:59 +0900, Jim Cain wrote:
Austin Ziegler 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
On Fri, 11 Jul 2003 11:35:31 +0900, Jim Cain wrote:
On Fri, 11 Jul 2003 08:54:59 +0900, Jim Cain wrote:
–
austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.07.10
* 23:52:57
Austin Ziegler 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.[snip]
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.
Maybe I’m strange, but I just like having code and doc in separate
places. I like being able to absorb the code at a glance, and for me
embedded documentation just gets in the way. Also, I’m rather into how
my code “looks,” and embedded docs detract from that “look.” Perhaps I’m
the only one who’s that way.
When I’m coding, I typically have Mozilla open for reference purposes,
most often with multiple docs (the browser tabs are perfect for this).
But even with embedded docs, the source of the library (and therefore
its docs) would be open in a separate window from where I’m coding,
unless I’m editing the library itself.
On Fri, 11 Jul 2003 11:35:31 +0900, Jim Cain wrote:
You can use folding if your editor supports it.
On Fri, Jul 11, 2003 at 02:15:27PM +0900, Jim Cain wrote:
Maybe I’m strange, but I just like having code and doc in separate
places. I like being able to absorb the code at a glance, and for me
embedded documentation just gets in the way.
–
_ _
__ __ | | ___ _ __ ___ __ _ _ __
'_ \ /| __/ __| '__ \ / ` | ’ \
) | (| | |__ \ | | | | | (| | | | |
.__/ _,|_|/| || ||_,|| |_|
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com
Mauricio Fernández wrote:
Maybe I’m strange, but I just like having code and doc in separate
places. I like being able to absorb the code at a glance, and for me
embedded documentation just gets in the way.You can use folding if your editor supports it.
Besides folding, I find it helpful to switch syntax coloring to a scheme
that makes commen texts almost invisible, such that the code stands out.
I also try to write smaller, though more numerous, files, so each file
really shouldn’t have scads of text. If I want something that ties
together all the clasess, and describes the overall application use and
design, then I’ll use a separate RDoc or XHTML file.
James
On Fri, Jul 11, 2003 at 02:15:27PM +0900, Jim Cain wrote:
Mauricio Fernández wrote:
On Fri, Jul 11, 2003 at 02:15:27PM +0900, Jim Cain wrote:
Maybe I’m strange, but I just like having code and doc in separate
places. I like being able to absorb the code at a glance, and for me
embedded documentation just gets in the way.You can use folding if your editor supports it.
That is true. I’ve just never investigated the feature before.