I'm a little bit worried about the proliferation of text-based formats like this. Currently we have MarkDown, ReStructured Text, Textile, AsciiDoc, Perl's POD, Wikipedia Wiki markup, and now this. When you pick one of these, you gamble that the one you chose won't fade into oblivion, forcing you to convert all your documentation. Some of them have features that others do not, making an informed choice even more difficult.
I don't know what the answer is, but it makes me hesitant to use any of them.
Me too, actually. I tried to keep Ron 100% markdown compatible but broke that with the `<VAR>` syntax. It'll probably break with Markdown more in the future, as I can already see places (pre-formatted blocks) where I'm going to want slightly different behavior.
One of the best defenses against documentation rot is a free, ultra simple, and portable toolchain. I'd like Ron to eventually be entirely in C (based on Discount, most likely) with very few dependancies, if any. If the format turns out to be useful, I'll start moving in that direction.
I generally agree with this concern, although I think it's likely that it will become unimportant over time as formats congeal.
I guess the mitigating factor is that at least it's readable and well-formatted as ASCII, so it's not that big of a deal if your format isn't supported anymore -- just read the source.
If that ever became a problem, then surely it wouldn't be that much trouble to write a script that outputs it in whatever markup happens to be popular at the time.
Ron is written in Ruby and depends on nokogiri and rdiscount, native extension libraries that are non-trivial to install on some systems. A more portable version of this program would be welcome.
"
I don't know what the answer is, but it makes me hesitant to use any of them.