>> 'site_ruby' implies libraries, not documentation.

[Dave:]
> I think I disagree, but I'll bow to Matz.
>
> To me, site_ruby is stuff that's global to a site (things that have
> been installed locally, but that are available to all local users). The
> standard lib/1.8 stuff are files that are global, but that are managed
> as part of the base Ruby install. This way, the stuff in site_ruby is
> protected against change when new minor releases of Ruby are installed.

Good point.

> Because of this, I want to support three directories in the standard
> search path for ri:
>
> 1. The system one, where documentation distributed with Ruby is stored
> 2. The site one, where admins store documentation on stuff that''s
>    available site-wide, and
> 3. The user one, which is under a user's home directory, and which
>    doesn't require root access to write to.

This is certainly a good idea.  So I propose the following, assuming
$prefix == "/usr":

  /usr/lib/ruby/doc/1.8/             <system documentation directory>
  /usr/lib/ruby/site_ruby/doc/1.8/   <site-wide documentation dir>
  ~/.ruby/doc/1.8/                   <user's installed documentation>

This is a neat and consistent trio.  The user's directory looks too
verbose for some tastes, but consider this:

 * The user's documentation directory needs to take account of the
   Ruby version, just like the system and site-wide ones.

 * ~/.rdoc is not accurate: RDoc output forms part of a package's
   installed documentation, but not all of it.  Other files include
   README, TODO, ChangeLog, etc.  "~/.ruby_doc" is better.

 * Taking the above two points together, we need "~/.ruby_doc/1.8/".
   Given that, we might as well change one character and make it
   look like the system and site-wide directories: ~/.ruby/doc/1.8/


>> Also, the "dbi-0.0.20" documentation is independent of the *Ruby*
>> version, so it shouldn't be buried in 'site-ruby/1.8' somewhere.
>
> Actually, not true (typically). When you install a package under (say)
> Ruby 1.6, it won't be available under 1.8 unless you reinstall it. I
> want the documentation to have the same behavior.

Another good point.  I built that into my suggestions above.

> Thanks for the discussion: it's helping clarify my thinking.

Me too.

Cheers,
Gavin