From: Gavin Sinclair Date: 2004-04-23T00:22:41+09:00 Subject: 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