From: Dave Thomas <dave@...>
Date: 2004-04-23T01:25:54+09:00
Subject: Re: how to get ri/rdoc working for [user-installed libraries]


On Apr 22, 2004, at 10:22, Gavin Sinclair wrote:

>>> sensible system would require a change to ri.  If you have 100 gems
>>> installed, and run 'ri --classes', I'm sure you don't want to see 
>>> 1000
>>> classes.
>
>> Why not?
>
> Because it's too much information to realistically browse.  And it
> would be too slow.  It takes about 2s for ri to show me all my classes
> now, and that's just core and (partial) stdlib.  That's already close
> to too much.  Doing any query takes at least as long.

Speeds a separate issue: ri and rdoc are implemented via a cache layer 
(ri_cache), but I haven't implemented it yet. Once that's done, you'll 
find that queries are a lot, lot faster.

You say it's too much information, but I dislike making policy decision 
on behalf of users. If they ask for a full class listing, then I'll 
give them one. If they want everything to do with X, then they can ask 
for that. The opposite, where they have to know where stuff comes from, 
seems to getr in the way.

> If you have an alternative idea for introducing categorisation to ri
> output, I'd like to hear it.  If you don't think it's important;
> that's OK too, since RDoc HTML combined with gem server fulfils the
> "table of contents" aspect.

Personally, I'd add a Catgegory: xxx markup to the files, and then 
build an index based on it.

Here's a stake in the ground. I like gems, and I support the idea. I'll 
be writing a gems appendix for the new pickaxe. At the same time, I am 
not going to tie RDoc/ri to gems: packaging scheme have proven to be 
ephemeral in the past.
>
> Would you think differently if gems were the one and only way people
> installed Ruby libs and apps?

I'd think differently if

1. gems were built in to Ruby. The test for this is that there'd be no 
more lib and ext directories, and the stuff needed to run gems was 
built-in. If that were the case, gems would be the universal mechanism, 
and Ruby would be distinguished as one of the few languages to 
integrate package management.

2. the gem directory structure, versioning, and naming conventions were 
universally adopted and understood

3. We understood better exactly how people use gems.

> I suppose it's possible to approach this the other way: one could write
> an ri clone that bridges the gap, using both the ri and rubygems
> libraries.  That's architecturally cleaner, I suppose.
>

I _think_ all you need is a simple wrapper that invokes ri with the 
appropriate options: there's no need to clone it.
>
> "More transparent"?  Possible, yes.  We're discussing some
> transparency aspects on the list now.  But here's a good litmus test
> question: do you think that ri should handle the fact that multiple
> versions of the same library are installed and have documentation?

No, I don't think this is a priority.  ri is a developer tool, not an 
end-user tool. Multiple versions of the libraries are (transparently) 
significant to end users, but developers are probably interested 
primarily in the current version's documentation.

Versioning is a good example of somewhere where gems has a solution, 
but I'm not sure of the problem. While it's good in theory to have 
multiple verions of every library, I'm not sure that in practice its a 
need I've ever had (and I'm a fairly active Ruby developer :)

Instead, I have versions ties to the version of the interpreter: on by 
current box, I have four interpreter trees, each with their 
then-current versions of libraries. If I run a different version of the 
interpreter, I get that interpreter's versions of the libraries.

Now I know that I'm probably just being curmudgeonly about this, but 
I'm one of those people who need to experience the need before 
expending a bunch of energy writing the code. In this case, I'm not 
sure about the versioning scheme in general, and then who the 
interaction between user categories, versions, and documentation takes 
place. I'd rather not code into that vacuum. Let's get some practice 
experience first, and then take a position.

Cheers

Dave