

Ron : Humane text format and toolchain for creating UNIX man pages - r11t
http://github.com/rtomayko/ron

======
haberman
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.

~~~
rtomayko
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.

------
josephruscio
Perl's Pod (Plain Old Documentation) is actually a pretty humane format that
exports to manpage, HTML, text, etc: <http://perldoc.perl.org/perlpod.html>

We did all of our command line tool man pages in it, and it only took a few
minutes to get up to speed on the syntax.

~~~
chromatic
I write _books_ in it (well, PseudoPOD...).

------
davidu
So obvious but very neatly done. POD is like this for perlish folks.

------
imd
FWIW, pandoc is a Markdown-based tool that does all this very nicely:
<http://johnmacfarlane.net/pandoc/>

------
boris
From its man page:

" BUGS

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. "

