From: Gavin Sinclair <gsinclair@...>
Date: 2003-12-16T22:45:30+09:00
Subject: Re: Where to install documentation

On Tuesday, December 16, 2003, 6:05:40 PM, Gavin wrote:

>>> /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>
>>
>> Except the version number should come before /doc, because it has a
>> higher precedence, I think (remember the part about documentation being
>> version specific).

> Documentation is version specific, and whether we use doc/1.8 or 1.8/doc,
> that fact is honored.  I advocate doc/1.8 because I want to think "ah,
> this is where the documentation is stored" not "this is where everything
> to do with 1.8 is stored".

> I know you want to be able to "rm -rf 1.6", but I can handle one or two
> extra "rm -rf" steps in the uncommon activity of uninstalling Ruby.

> 'doc' should go higher in the directory structure than '1.8' because it is
> more general.

As a followup point, consider this.

  $ ls -1 /usr/local/lib/ruby/site_ruby/1.8
  amrita
  dict.rb
  doc
  dot
  extensions
  install-pkg.rb
  markup
  rake
  rake.rb
  ...
  
You are proposing to put 'doc' in the 'site_ruby/1.8' directory, and I
have simulated that in the above listing.

But 'doc' is clearly not a sibling of 'dict.rb' or 'amrita' or 'rake'.
Therefore this directory is clearly a wrong place for it.
Furthermore, what if I created a package called 'doc', which
installed, as is custom, into the 'site_ruby/1.8/doc' directory?  Big
trouble.

Now the alternative.

  $ ls --expand-interesting-directories /usr/local/lib/ruby/site_ruby/
  1.6
  1.8
  doc/1.6
  doc/1.8

We could argue all day about whether 'doc' is a sensible sibling for
'1.6' and '1.8', and I couldn't argue strongly in favour.  However, at
least it's not clearly wrong.  And, given all the other locations
we've considered (especially that site-wide docs should be contained
within 'site_ruby'), this is the only arrangement I consider
reasonable.

More sensible would be

  $ ls --expand-interesting-directories /usr/local/lib/ruby/site_ruby/
  lib/1.6
  lib/1.8
  doc/1.6
  doc/1.8

(Or even the other way around: {1.6,1.8}/{lib,doc})  But it's too late
for that.

Cheers,
Gavin