Hi,
I'm in the process of writing a manual/tutorial for RSRuby (http://rubyforge.org/projects/rsruby/), but I'm not sure what the best format for this kind of document is. The source code is documented using RDoc, but for the manual I was thinking more in terms of something like a LaTeX formatted article/book. i.e. This will be a print formatted document and maybe 20+ pages. At the moment I'm considering a few options based on things I've seen in other projects:
1. Texinfo: RPy, on which RSRuby is based, provides a nice manual in texinfo format which outputs a lovely PDF document. However, perhaps not everyone with Ruby has texinfo installed (or do they?). Adding an extra dependency just to generate documentation seems unnecessary so I was looking for Ruby solutions.
2. RDoc: Tioga (http://www.kitp.ucsb.edu/~paxton/tioga.html) has a nice tutorial in RDoc format and RDoc is part of the Ruby stdlib (so no extra dependency), but RDoc (as far as I know) only outputs to XML, HTML, Windows help and ri. I know I can load HTML into a browser and print it, but I'd prefer a 'proper' dead-tree formatted manual if possible.
3. Ruport: So I was looking for an RDoc to PDF option and found this thread:
http://groups.google.com/group/comp.lang.ruby/browse_thread/thread/b394f8e59397d3e3/6252a6151c283431
which mentions the possibility of doing it in Ruport (if I understood correctly), but again that just gives an extra dependency (Ruport) for any user who wants to generate the manual for RSRuby.
Looking at the RDoc source, it doesn't look *that* difficult to write a new generator which would enable direct RDoc to PDF conversion if the user had PDF::Writer installed (though that's just another dependency I guess).
So, my question(s):
1. Is there any best practice solution for writing this kind of print-formatted documentation in Ruby? Is there some other obvious solution I'm missing?
2. Would anyone be interested if I took the time to write a PDF generator for RDoc? If so I'm assuming PDF::Writer would be the best/easiest PDF generating engine to use?
Thanks in advance for any hints!
Dr Alex Gutteridge
Post-Doctoral Researcher
Bioinformatics Center
Institute for Chemical Research
Kyoto University
Gokasho, Uji, Kyoto 611-0011
Japan