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:
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.
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
Ruport: So I was looking for an RDoc to PDF option and found this
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):
Is there any best practice solution for writing this kind of print-
formatted documentation in Ruby? Is there some other obvious solution
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 G.
Institute for Chemical Research
Gokasho, Uji, Kyoto 611-0011