From: Gavin Sinclair <gsinclair@...>
Date: 2002-09-06T01:02:08+09:00
Subject: Re: suggestions to the Ruby community


----- Original Message ----- 
From: " JamesBritt" <james@jamesbritt.com>


> 
> 
> > -----Original Message-----
> > From: Berger, Daniel [mailto:djberge@qwest.com]
> > Sent: Thursday, September 05, 2002 5:52 AM
> > To: ruby-talk ML
> > 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.
> 
> 
> Not a bad idea.  But I imagine the ability to grab a Ruby distribution,
> install it, and being able to start viewing/extracting/whatever the docs
> right away.  I'd rather not have to go and install Perl (which isn't
> installed by default on Windows boxen).
> 
> James

The reasons for using POD are good, but here are the cons:
 - relying on Perl installation is not good (as above)
 - porting to Ruby is questionable - need to keep up-to-date
 - we already have doc formats in Ruby; let's evolve them and
   "almost port" POD if necessary (I don't even know what in
   particular is so great about it).

I think it's time we started a new thread; even better, a new ML!

Gavin