From: Thomas Hurst Date: 2002-02-10T21:11:57+09:00 Subject: Re: Ruby Embedded Documentation * Lyle Johnson (ljohnson@resgen.com) wrote: > The "best" way depends on your definition of "best", I guess. I like > RDoc because the documentation comments (and associated markup) are a > lot more legible than those used by RD. Yeah, I can barely think of a *worse* way to do inline documentation than something POD-like. > RDoc's HTML output is very nicely organized, hyperlinked, etc. and > looks quite professional to me, too. If you haven't done so already, > you might take a look at the sample output from RDoc on the RDoc home > page (http://rdoc.sourceforge.net) and see what you think. The HTML's a bit messy, with things like using tables+CSS to provide coloured backgrounds and section headers when a simple tag would do. It also uses frames, for which I'm afraid Dave is going to hell ;) > On the other hand, as of this writing, RDoc can't be used to generate > Unix man pages, TeX, or the various other backends supported by > RDtool. To this end, an XML output format would be good. That can then be processed using XSL/Ruby/whatever to turn it into pretty much anything else, including XHTML, DocBook, plaintext etc. -- Thomas 'Freaky' Hurst - freaky@aagh.net - http://www.aagh.net/ - Woman's advice has little value, but he who won't take it is a fool. -- Cervantes