I’ve been following the documentation discussion with some interest. Some
of this has focused on rd2.
At the risk of being branded a heretic by the Ruby Community, I believe
there’s an alternative that we haven’t considered.
That’s right - POD. POD as in Perl’s “Plain Old Data”. POD and rd2 are
markup languages. They have nothing to do with the language (i.e. Perl or
Ruby) itself. I can put rd2 documentation in a Perl module just as easily
as I can use POD to document my Ruby modules.
“But, but, but…the parsers are written in Perl!” - So what? A healthy
chunk of your gnu utilities are written in Perl. Many others are bash or
korn shell scripts. I’ll bet that doesn’t stop you from using those
“RDoc and POD aren’t the same, though” - You’re right. They create
different documents. But then, rd2 and RDoc are just as different. If you
prefer the documentation that RDoc generates, stick with RDoc.
“Why not stick with rd2?” - POD’s been around longer and the output looks
nicer. As a result of more years of development, there are several pod
tools for generating more output types, including man pages, latex, html and
plain text. That’s right, I said MAN pages. There are also tools for
reading nroff-like formatting (in addition to the man stuff) and even
colorizing. I haven’t even mentioned the parsing utilities that exist.
“But it’s not written in Ruby!” - So friggin’ what? Get over it.
Seriously, if you refuse to use a tool because of the language it’s written
in, you can put yourself in the “religious zealot” category right now.
Hell, even I use Eclipse, and I hate Java - but I like Eclipse.
“Won’t this create confusion?” - If you’re really worried about it, you can
stick the POD in a separate file altogether. There’s no rule that says the
documentation has to be included in the source file. Just as long as there
/me is now prepared for the kindling and matches.