>
> On Dec 16, 2003, at 0:08, Gavin Sinclair wrote:
>
>>  * ~/.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.
>
> The stuff in .rdoc is just RDoc documentation. The random other stuff
> can go where it will, but I'd strongly suggest not putting it anywhere:
> there's really no reason to pollute someone's filesystem by copying a
> Changelog or TODO file out of a project structure and into the
> mainstream.

I quite disagree.  With that reasoning, why not simply generate the RDoc
stuff into the project structure?  Answer: we want centralisation of
documentation.  That goes for non-generated stuff as well as generated
stuff.  We shouldn't have an RDoc-prejudice.  ChangeLog may not sound all
that exciting, but what about UsersGuide.pdf?

If you copy it out of the project structure, then the project structure
can be deleted afterwards, or installed directly from the internet, etc. 
You shouldn't assume that people want to keep "project structure"
directories around on their machine.  You can reasonably assume that
people want comprehensive documentation "installed" on their machine.


>>   /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.

Gavin