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