From: Gavin Sinclair <gsinclair@...>
Date: 2003-11-28T06:25:06+09:00
Subject: Installing Docs (Was Re: Library directory structure on windows)

On Friday, November 28, 2003, 2:11:34 AM, Gavri wrote:

>> As above, you don't place it in the lib area manually.  Let the
>> installer do the work.  It will decide where to put the files (almost
>> certainly under lib/ruby/site_ruby/1.8/iowa/).
>> 
>> The things you download should be versioned so you can have them
>> sitting side by side.  The runtime files aren't versioned as you can
>> only have one version installed at a time.
>> 

> thanks gavin. there *is* an installer.

> however i noticed that the installer didn't automatically copy any
> docs. this is also the case for a few other packages i installed.
> why don't installers do that? do ruby application installers never
> copy docs to the ruby/docs folder. should i always do it manually?
> if so, why?

Thanks for opening a can of worms.  If the next Ruby Conference is in
Australia, I will give a presentation on this :)

Documentation is not routinely installed as part of a Ruby package
installation.  The commonly-used install.rb/setup.rb doesn't do it.  I
think I emailed the author about it and he replied that there's no
standard place to install the documentation.  I raised an RCR to
define a standard documentation directory.  It was popular, but RCRs
need time, and Matz would like to see more detail.  When the new RCR
process is in place, or perhaps before, I will write a more detailed
one.

To prove the concept, my 'extensions' package installs documentation
with a seperate 'install-doc.rb' command.  Anyone can use that for
their own project.  It works great.

Rake has an RDoc task, so people using Rakefiles - probably more
common as time goes on as it is good technology - can provide their
users with a command to build documentation from RDoc.  If and when we
are blessed with an agreed place to install documentation, then it
will be easily done with Rake.

RubyGems, as far as I know, makes no provision for installing
documentation.  I was going to offer my services to the owners of this
project once it settled down a bit.

http://ruby-doc.org/stdlib (CSS problems beware, but looks good in IE)
will soon provide a download with an installer.  Using this, you will
install standard library documentation to that central directory I've
spoken of.  Therefore one bookmark in your browser will survive all
version updates.  That will be another proof of concept.

What is this central directory I've been talking about?  The RCR
explains it (http://www.rubygarden.org/article.php?sid=319), but here
we are in brief:

  Assuming /usr/local/bin/ruby        - executable
           /usr/local/lib/ruby/1.8/   - libraries

  then     /usr/local/doc/ruby/       - documentation

On my machine:

  $ ls -1F /usr/local/doc/ruby/
      extensions-0.2.12/     (contains full API via RDoc)
      ri-1.8b/               (contains README, ChangeLog, COPYING)
      ruby-1.8.0/            (same as above, but a few more scraps)
      stdlib/                (contains full API via RDoc)

OK, 'stdlib' is not there yet, but it will be.  'ri-1.8b' and
'ruby-1.8.0' were installed there without any particular direction
from me.

Every documentation directory is versioned except for 'stdlib', which
doesn't need it because it's pure documentation, not software, and
because it only makes sense to have the latest copy.

Here is the code in extensions/install-doc.rb that determines where to
put documentation:

  require "rbconfig"

  prefix = Config::CONFIG['prefix']
  rubydocdir = File.join(prefix, "doc", "ruby")

On Windows, 'prefix' would typically be "C:\Ruby", so 'rubydocdir'
would be "C:\Ruby\doc\ruby".  This seems repetitive, but no more so
than the existing "C:\Ruby\lib\ruby\1.8".

A few people on various Unix systems have reported in the past that
their directory structure doesn't look like everyone else's.  Maybe
the above code is good for them, maybe not.

OK, so that wasn't so brief, but it's an important issue.

Gavin