From: bbense+comp.lang.ruby.Sep.06.02@... Date: 2002-09-07T00:31:07+09:00 Subject: Re: Document tools -----BEGIN PGP SIGNED MESSAGE----- In article , Dave Thomas wrote: > writes: > >> An rd2 output format would take care of the first two. I think >> there's a lot of potential in the idea of using rdoc as the >> document creating tool and something POD-like as the output >> format. The one problem that I see is that rdoc produces >> output that is some ways "ruby-smart", it knows methods belong >> to classes. It would be good if the basic output format >> could preserve that knowledge in some way. As far as I know, >> rd2 is just markup. > >I'm not sure I see the benefit in the intermediate rd2 or POD >step. RDoc already generates XML, so just about any format you need is >just an XSL transform away, and I personally believe that RDoc format >is just as readable as POD. - - I'm not argueing that, I guess there's some confusion of terms, I view "rdoc" as a document writing tool. Perhaps we should call "rdoc" the tool and RDoc the formatting conventions. > Remember too that RDoc doesn't just work >on Ruby source: you can feed it text files and it's quite happy. > - - Well as I see it there are two things missing in the ruby doc world. 1. A standard output format 2. A standard place to find it. - - rdoc does not solve either of these problems. POD solves them by a. being trivial b. Always being between the =begin and =end part of the installed module. Once you have these two things, you can write all kinds of document tools. In some ways rdoc is "just too damn smart", it takes plain code and produces useful documentation. However, since the rdoc "src" is scattered all over the original src code, getting docs on the fly is somewhat difficult. I've taken a closer look at rd and it at least knows enough Ruby to differentiate method lists from regular lists. - - If you want to emulate perldoc, then you could use XML as and intermediate format, but IMHO, XML is unreadable and there's the question of where to put it. It also raises the bar for tool writers, although I guess XML is now ubiquitous enough that is not that much of an issue. - - I guess I'm just enough of a Unix Luddite that I think there's a significant advantage to having a document format that I can use /bin/cat on. The other advantages I see are 1. Play nice with the people already happily using rdtool. 2. Possible to include all the tools required to do documentation in a ruby-only code with the standard distribution. - - Perhaps, we could clarify the situation with a couple use cases, I'd like a tool that could answer these questions. "Show me all the installed library objects that have a read method." "Show me the names of all the installed classes." - - I could brute force this by running rdoc on all the installed ruby src and then grepping the XML... I'd kind of like a more elegant solution. How were you planning to generalize ri from rdoc output? - - Booker C. Bense -----BEGIN PGP SIGNATURE----- Version: 2.6.2 iQCVAwUBPXjD8GTWTAjn5N/lAQHgFwP9FJWYZAVtSUfkSNjdb2bhOf9slhtein9T 5soQOK+N3tO5qzPqPWsbLK/vAp7TOVsCsF5SjmryUJQnoYyYDR81MCgU7UOoU4Fx EhRAWmcldVmMvCIf9B5ZjVCa5fx0wCCAXsEbIMMYViattjaAJ/dfz54Nb37JnjrJ Ew2tdc54lYU= =QZee -----END PGP SIGNATURE-----