snacktime wrote:
> 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.cgi/Literate_Programming_In_Ruby/Literate_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. :)