From: Seth Kurtzberg <seth@...>
Date: 2003-02-24T02:18:49+09:00
Subject: Re: embedded docs

I agree that this is very important.

Another note:  for some key modules there is documentation only in Japanese.

On Sunday 23 February 2003 09:55 am, Piers Harding wrote:
> It's funny how these conversations all seem to lead back to the same
> things:
>
> The Perl community has -
>
>  (1) documentation standards (pod + perldoc)
>  (2) distribution standards (h2xs stub builder and the like, and the
>      whole Makefile.PL dance)
>  (3) development standards (pause and the whole smokehouse concept)
>  (4) a decent archive (CPAN - note: I'm not saying that ruby doesnt have
>     an archive - just that what CPAN offers that the Ruby community doesnt
>     is constantly under estimated IMHO)
>  (5) bug tracking (rt.cpan.org)
>
> These are all things that add up in lots of subtle, and not so subtle
> ways to be a very effective Langauge support infrastructure.
>
> The way Perl does all these things may not be the best way, but it all
> adds up to being arguably the most successful Community Language of all
> time (so far).
> Forinstance Makefile.PL's  reliance on make is a problem for some - but
> because you at least have a build, test, and install phase that is enforced
> to some degree, and the automatic creation, and installation of
> documentation, still makes light years ahead of extconf.rb approach.
>
> The absence of these things that Perl programmers take for granted, is
> quite possibly the stumbling block that may stop Ruby from stepping up
> to the mark in the long run if there is no will to take what is good
> from those that have been before.
>
> I propose that all those that are going to OSCON (if there is still
> going to be a Ruby contingent) get togther (maybe at a BOF), and have a
> go at mapping this stuff out - I'll certainly be there for it.
>
> (sorry for the rant Simon - just taking the lead in from the thread, and
> certainly not a criticism of you).
>
> Cheers.
>
> On Sun, Feb 23, 2003 at 11:47:08PM +0900, Simon Cozens wrote:
> > Brian Wisti <brian@coolnamehere.com> writes:
> > > Will ri (or some other doc browser) be available as part of the
> > > standard distribution?  I really miss perldoc and was looking for a
> > > similar utility for Ruby.
> >
> > Perhaps the best thing about perldoc is that I can install a new Perl
> > module and then read its documentation and work out how to use it. In
> > the Ruby world, I often install a module and then think "Now
> > what?". If I'm very lucky, there's some documentation buried away in the
> > module's source tarball somewhere. If I'm only ordinarily lucky, there
> > might be an example script. Usually, there's neither.
> >
> > I don't know a good way of fixing this that *doesn't* presuppose a
> > documentation browser which can go and find documentation about a
> > specific module in a known, standard place.
> >
> > --
> > <yrlnry> I think the real problem here is that he is a university CS
> > professor and therefore knows very little about programming in the real
> > world, in any languge.

-- 
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth@cql.com