From: bbense+comp.lang.ruby.Sep.08.02@... Date: 2002-09-09T00:33:01+09:00 Subject: Re: Document tools -----BEGIN PGP SIGNED MESSAGE----- In article , Dave Thomas wrote: > writes: > >> It certainly is possible. POD shows us the way. I think the >> point I'm trying to make is that POD is an output format. >> It just happens to be so trivial that it's accepted in the >> perl community to write raw POD. Once you have a well defined >> simple output format, you can translate that to any other format >> required. > >Here's the start of perlpod.pod in pod format: [snip] > >Doesn't seem to be much difference in readability to me. Why would I >convert RDoc as an input format to POD as an output format. Wouldn't I >be better off adding the extra output processors that folks wanted? > - - That's not what I'm suggesting. What I would like to see is that some readable format appear between the =begin =end tags in every Ruby library file. It's the IDEA of POD that I would like to see in Ruby. If rdoc just wrote skeleton RDoc between =begin and =end I'd be fine with that too. I'm not suggesting that we take anything from POD but ideas. I was suggesting that this format be rd[1], but anything that preserves that readablity would be fine. - - While some people may write quite extensive documentation, I suspect most library writers will stick to few comments in the appropriate places since rdoc does such a nice job of turning that into fairly reasonable documentation. I want a tool that does powerful things with the minimal documentation most libraries provide. IMHO, Rdoc already has enough features what it needs is stuff to work on, more output forms and some powerful searching tools. The hoopiest documentation in the world is useless if I don't know where to find it and don't have the tool to read it[2]. - - Again let's go back to the use case. What's your scheme for addressing these questions? "Show me all the installed classes that have a read method." or "Show me all the installed classes that have the Enumerable module." - - Booker C. Bense [1]- My arguement for using rd is that many libraries already support this model of rd formatted docs between =begin , =end. I'm not interested in writing rd, but if rdoc could take care of that nasty chore for me, that's be great. I'd really like a tool that could search that rd for me. [2]- I fully expect to lose this battle, I've lost it every time I've fought it. Featuritius always wins out over functionality. -----BEGIN PGP SIGNATURE----- Version: 2.6.2 iQCVAwUBPXtrsGTWTAjn5N/lAQFsNgQAm2QcKK4KrGpWwws7UwmtmAimxnV+V8WK L/SA4WSBSL7ocNPmYibHKdoGJB9ao5UjHSfTPvw6aFHmbGm4ljsrEDuM1Y+Qcwo5 2rtEMN6ktoExfhKky6jn0rkKM6yBMT+aMRwuDEKZV8DYY87jYJKnMShZ0aRjhs7N AetvXXDhXA4= =0fmt -----END PGP SIGNATURE-----