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