jmg3000 / gmail.com wrote:
> 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.