5 ms·

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

18 points by r11t 17y ago

boris 17y ago
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. "
josephruscio 17y ago
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 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 17y ago
  I write books in it (well, PseudoPOD...).
haberman 17y ago
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.
- ricree 17y ago
  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.
- lincolnq 17y ago
  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.
- rtomayko 17y ago
  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.
davidu 17y ago
So obvious but very neatly done. POD is like this for perlish folks.
imd 17y ago
FWIW, pandoc is a Markdown-based tool that does all this very nicely: http://johnmacfarlane.net/pandoc/ http://johnmacfarlane.net/pandoc/

18 points by r11t 17y ago

boris 17y ago

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

josephruscio 17y ago

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 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 17y ago
I write books in it (well, PseudoPOD...).

haberman 17y ago

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.

ricree 17y ago
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.
lincolnq 17y ago
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.
rtomayko 17y ago
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.

davidu 17y ago

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

imd 17y ago

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