From: "Berger, Daniel" <djberge@...>
Date: 2002-09-05T21:52:25+09:00
Subject: RE: suggestions to the Ruby community

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.

POD. <ducking vegetables>

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*
tools.

"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
*is* documentation. :)

/me is now prepared for the kindling and matches.

Regards,

Dan