From: Piers Harding Date: 2003-02-24T01:55:47+09:00 Subject: Re: embedded docs 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 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. > > -- > 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.