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
possible.
Ruport: So I was looking for an RDoc to PDF option and found this
thread:
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
I’m missing?
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.
Post-Doctoral Researcher
Bioinformatics Center
Institute for Chemical Research
Kyoto University
Gokasho, Uji, Kyoto 611-0011
Japan
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.
If PDF document that will look beautiful is a priority, than I’d state
that Tex
(generated howsoever) is the way to go. I don’t see a major disadvantage
in
shipping the PDF file itself.
Texinfo: RPy, on which RSRuby is based, provides a nice manual in
Looking at the RDoc source, it doesn’t look that difficult to write a
2. Would anyone be interested if I took the time to write a PDF
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:
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?
I think an output to LaTeX (which can easily generate PostScript or
PDF) might be easier and would reduce the hassle of having to worry
about formatting.
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?
Yes! (Once when I needed PDFs from RDoc I loaded the HTML output in
OpenOffice and exported to PDF.)
Documentation formats for things like user guides and software
documentation have been a pain in my *** now for quite a while. If
you want to produce professional looking documentation with nice
headers/footers, graphics, and also have the formatting carried over
correctly to your pdf’s, then the only open source application I have
found that doesn’t require major amounts of effort to make this happen
is Openoffice. We messed around for weeks with things like Docbook
and Tex with poor results. Sure they can work, but the amount of
effort and knowledge required to make them work is crazy if you aren’t
a publishing house or larger company.
Well, assuming you have decided to use TeX, there are two reasonable
editors. LyX is easier to use and supports “literate programming” out of
the box (NoWeb dependency – automatically installed on most Linux
distros). TeXmacs is more powerful and supports “sessions” of many
applications, though not Ruby as far as I know. IIRC both support
DocBook.
There are some “lighter” TeX editors, including modes for Emacs and Vi,
but I’m happy with LyX. As I noted earlier, I’m right in the middle of a
project to do “reproducible research” and “literate programming” in
Ruby, and some pre-alpha stuff is in RubyForge at
You’ll need LyX to read it; it’s available at http://www.lyx.org. I know
it’s on most Linux distros, CygWin and native Windows binary, but I
don’t know about Macs.
Since there seem to be at least four people interested in this (myself,
Alex G., yourself and someone else whose name I’ve forgotten), I’ve
created a RubyForge forum at
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?
Alex,
I think the best-practice solution for writing software manuals isn’t
Ruby-specific. The three industrial-strength top choices tend to be
DocBook, LaTeX, and Texinfo. IMO, you’re very likely to feel way too
limited trying to use RDoc to write your manual.
Both LaTeX and Texinfo are high-level layers on top of TeX, and are
both pretty easy to get started with. They will both generate beautiful printed docs (since they’ve got TeX doing all the low-level
formatting). Of those two, Texinfo is the smaller and simpler one, and
IMO has higher-quality docs (though LaTeX has tons of docs all over
the web). For a quick 10-second look at Texinfo, here’s my brief notes
on it: http://www.simisen.com/jmg/notes/texinfo.html . If using
Texinfo, you can quite easily generate html, pdf, dvi, plain text, and
info docs. With LaTeX, although there’s options for transformation to
html, it’s not necessarily neat and tidy.
Note, with LaTeX, you can have much more control over the formatting of
the final dvi/pdf output (margins, fonts, paragraph spacing, etc.). You
could have that same control with Texinfo – but you’d have to be able
to write plain TeX to do it. Anyhow, Texinfo’s defaults are quite nice,
so it shouldn’t be an issue (as long as you don’t have someone
insisting you change margins or paragraph indents or something ).
DocBook has its fans, and it’s a very large and flexible system likely
capable of generating any kind of output you could possibly want
(though I doubt it would do mathematics as nicely as LaTeX or Texinfo).
You have to type (and learn) loads of tags when writing with DocBook,
but your editor should be able to help a lot with that. I tried
learning to use DocBook once, but the whole system seemed way too big
and complicated so I slowly backed away.
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?
Yes! (Once when I needed PDFs from RDoc I loaded the HTML output in
OpenOffice and exported to PDF.)
I will certainly have a poke around RDoc to see if I can get
something working. Thanks all for your comments - perhaps writing the
manual in LaTeX and providing the PDF is the simplest way in the
short-term.
Ed: The literate programming stuff looks very interesting. I am
installing LyX as I write…
Dr Alex G.
Post-Doctoral Researcher
Bioinformatics Center
Institute for Chemical Research
Kyoto University
Gokasho, Uji, Kyoto 611-0011
Japan
DocBook has its fans, and it’s a very large and flexible system likely
capable of generating any kind of output you could possibly want
(though I doubt it would do mathematics as nicely as LaTeX or Texinfo).
You have to type (and learn) loads of tags when writing with DocBook,
but your editor should be able to help a lot with that. I tried
learning to use DocBook once, but the whole system seemed way too big
and complicated so I slowly backed away.
Yeah, times have changed (though a lot of people got turned off in the
past), and writing DocBook these days is not so different from using
Word. For anyone interested, investigate one of the new, free DocBook
editors (perhaps XMLMind’s XMLEditor). DocBook homepage here: http://docbook.org/
I think the best-practice solution for writing software manuals isn’t
Ruby-specific. The three industrial-strength top choices tend to be
DocBook, LaTeX, and Texinfo. IMO, you’re very likely to feel way too
limited trying to use RDoc to write your manual.
Yeah … you basically have to write the manual into the code as
comments if you want anything more than just basic API documentation out
of RDoc.
I think, though, that since Alex is coming from the bioinformatics realm
and has familiarity with R, he would do well to use the documentation
tools that come with R and those that can be installed from the
BioConductor repository. The people up at Fred Hutchinson Cancer
Research Center in Seattle, and their colleagues around the world, have
something that works fairly well. Those tools are built on top of LaTeX.
As I noted before, I would add LyX and/or TeXmacs on top of the R tools.
TeXmacs is better for “live capture” of sessions, and the keyboard
shortcuts are familiar if you’re an Emacs user. LyX is slightly easier
to use and has built-in interfaces with NoWeb.
This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.
