Re: how to get ri/rdoc working for [user-installed libraries]

On Thursday, April 22, 2004, 11:22:14 PM, Dave wrote:


> On Apr 22, 2004, at 3:03, Gavin Sinclair wrote:

>> That's definitely in our TODO.  We haven't fleshed it out, but I 
>> believe a
>> 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.

There's only one existing documentation context where I think it's helpful
to look through 1000 entries: an index.  ri has a good index, but not
a table of contents.  It has no current way to show you what packages
you can browse.  I think that's an important thing to address as the
documentation base gets bigger, and I don't see a good way to do that
except for integrating somewhat with gems.  Not in such a way as to
alienate non-gems users; far from it.

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.

>> So a more sensible use case (IMO) is:
>>
>>   ri --gem log4r          # Shows all relevant classes
>>   ri --gem log4r Log4r    # Searches class/method within log4r space
>>
>>   ri --search to_i        # Global search
>>

> I'm afraid I disagree 100% with this. gems are ways of getting code 
> into the box, but in their users' minds that's it. The approach you're
> suggesting is equivalent to

>    man -k --installed-via-rpm  xxx
>    man -k --installed-manually xxx
> etc

Would you think differently if gems were the one and only way people
installed Ruby libs and apps?  Of course that's not true now, but I
think it will be in a few years.  I may be wrong and/or unconvincing,
but at least you know where I'm coming from.

Even before gems are ubiquitous, I expect RubyGems will be a standard
Ruby component, as is ri.  In that scenario, it's not unreasonable for
them to share some knowledge for the benefit of the user.

And as my hasty use case above didn't make clear, I had no intention
of deprecating current ri functionality.  It's just an optimisation,
and the user need never type --gem if they don't want to.

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.

>> Consider this also.  When you uninstall a gem, it should remove the ri
>> data.  Basically, the ri data for a gem should be installed in that
>> gem's
>> directory, like:
>>
>>   gems/log4r/doc/rdoc         # exists
>>   gems/log4r/doc/ri           # doesn't exist
>>

> Why? Don't gems keep track of the files they've altered during 
> installation, and remove those that were altered but not already there
> on uninstall? I don't see why anything needs to know about gems apart
> from gems?

No it doesn't.  It knows that everything it's installed is in certain
directories, and wipes those directories.  There are one or two small
exceptions.  The approach I outlined above (gem has its own ri
directory) is wholly consistent with the gems approach.

>> All of this is definitely doable, but it needs your input, Dave.

> I'd be happy to make any reasonable changes (I'll look at the 
> reentrancy issue batsman raised, for example). But I'm not convinced at
> all that ri (or any other utility) should be gems aware. It they need
> to be, then I'm currently thinking that that means the gems system 
> could be more transparent.

For better or for worse, gems will never be very transparent.  It's
impossible to support multiple versions of the same library installed
simulataneously without taking a different approach to the traditional
Unix and Ruby "shotgun over the filesystem" approach.

"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?  If
so, how can ri support this without grokking gems?  If not, which
version gets used for documentation?  (Answer, I expect: the one
installed most recently.)

Clarification: my proposed target dir for a gem's ri data was
inaccurate.  The example above should be more like this:

  $ruby/gems/1.8/gems/copland-0.2/rdoc
  $ruby/gems/1.8/gems/copland-0.2/ri
  $ruby/gems/1.8/gems/copland-0.3/rdoc
  $ruby/gems/1.8/gems/copland-0.3/ri

  ($ruby == /usr/local/lib/ruby, for instance)
  
Cheers,
Gavin