From: "M. Edward (Ed) Borasky" <znmeb@...>
Date: 2006-10-25T18:58:17+09:00
Subject: Re: Documentation formats (RDoc to PDF output?)

Alex Gutteridge wrote:
> 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
> 
> 
> 
> 
> 
I'm smack dab in the middle of porting some of the R "literate
programming" and "reproducible research" tools to Ruby, using LyX as an
editor and Rake for project management. Some links on the R side:

http://www.bepress.com/bioconductor/paper2/
http://www.stat.umn.edu/~charlie/Sweave/
http://www.ci.tuwien.ac.at/~leisch/Sweave/LyX/

There's some pre-alpha stuff of mine in RubyForge, see

http://rubyforge.org/cgi-bin/viewvc.cgi/Literate_Programming_In_Ruby/Literate_Programming_In_Ruby.lyx?root=cougar&view=co

You'll need LyX (and its dependencies) to read it. What OS are you on?