Ron : Humane text format and toolchain for creating UNIX man pages | Hacker News Reader

Ron : Humane text format and toolchain for creating UNIX man pages

github.com

18 pointsr11t9 comments

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.

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.

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.

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.

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.

I write books in it (well, PseudoPOD...).

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

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

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

Reply on news.ycombinator.com