Documentation formats (RDoc to PDF output?)

[Alex Gutteridge]

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

 

[Kalman Noel]

Alex Gutteridge:

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.

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.

Kalman

 

[M. Edward (Ed) Borasky]

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...e_Programming_In_Ruby.lyx?root=cougar&view=co

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

 

[Farrel Lifson]

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?

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.

Farrel

 

[Gregory Brown]

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

3. Ruport: So I was looking for an RDoc to PDF option and found this
thread:

Ruport does not have RDoc to PDF support. We would accept a patch for
sure if someone made an RDoc to PDF generator though.

 

[Joel VanderWerf]

Alex Gutteridge wrote:
...

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?

Yes! (Once when I needed PDFs from RDoc I loaded the HTML output in
OpenOffice and exported to PDF.)

 

[snacktime]

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.

 

[M. Edward (Ed) Borasky]

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

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

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

http://rubyforge.org/forum/forum.php?forum_id=9775

By the way, I *hate* OpenOffice.org.

 

[Alex Gutteridge]

Alex Gutteridge wrote:
...

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 Gutteridge
Post-Doctoral Researcher

Bioinformatics Center
Institute for Chemical Research
Kyoto University
Gokasho, Uji, Kyoto 611-0011
Japan

 

[Bil Kleb]

Thanks all for your comments - perhaps writing the manual in
LaTeX and providing the PDF is the simplest way in the short-term.

Be sure to check out Peter Wilson's Memoir package for LaTeX:

http://www.ctan.org/tex-archive/macros/latex/contrib/memoir/

Regards,

 

[jmg3000]

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:
[snip]

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?

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.

My advice is to give Texinfo a try.

---John

 

[M. Edward (Ed) Borasky]

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.

 

[Keith Fahlgren]

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/


HTH,
Keith