From: Trans <transfire@...>
Date: 2008-08-15T00:42:37+09:00
Subject: Re: Documenting DSLs



On Aug 14, 6:33 am, Hongli Lai <hon...@phusion.nl> wrote:
> Thomas Sawyer wrote:
> > Hey, has anyone thought about or worked on a "next gen" documentation
> > system for handling Ruby DSLs?
>
> How about just writing plain old narrative documentation instead of
> using a specialized system?
>
> If you want pretty HTML output, you might want to consider Mizuho [1] or
> Asciidoc [2]. Some Ruby on Rails manuals are in the process of being
> converted to Mizuho/Asciidoc format. See [3] for the output.

Actually I don't see anything very special about this. That's not to
say it's not well done. But it's just a markup format (Asciidoc)
wrapped in an ERB based template tool. That's fairly easy to whip
together. Plus, why use a Python-based markup tool when we have RD and
Markdown (among others) for Ruby?

RDoc ties code to docs, it's an API documentor, not just a format
transformation system. But maybe your point is that coupling is a
waste of time, and we should just write our docs to be processed
indifferent to any relation to code?

T.