From: Joel VanderWerf <joelvanderwerf@...>
Date: 2010-03-28T02:41:41+09:00
Subject: Re: Ruby and user documentation

Intransition wrote:
> 
> On Mar 26, 4:15 am, Michel Demazure <mic...@demazure.com> wrote:
>> Hi all,
>>
>> I just finished a quite large business project (in 1.9, pure ruby, not
>> Rails, with GUIs in FXRuby). I want to write a documentation for users
>> (not the code doc, I use Yard for it). Of course I can produce doc files
>> or PDF files.
>>
>> But I'd like to stay in the Ruby ecosystem.  What would do suggest ?
>> Prawn, Sinatra ... ? Do you know examples (with reusable patterns) ?
> 
> I would use a markup language for the files, probably Markdown*. HTML
> is the "universal language" so that should be the end product. But you
> can also generate PDFs for print.

I like the combination of markdown (via the kramdown[1] gem) and 
webby[2]. You can embed graphviz diagrams, gnuplots, syntax 
highlighting, TeX formulas, etc, with webby managing the dependencies 
via rake.

Another point for HTML output (which is what webby produces) is that you 
can build CHM, which some windows users may expect.

ps. glad to hear of the major use of fxruby. Congrats!

[1] http://kramdown.rubyforge.org/

[2] http://webby.rubyforge.org/