Installing Docs (Was Re: Library directory structure on windows)

ruby-talk
1

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

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.

RDoc Documentation (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

¡¡¡

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?

2

Gavin Sinclair wrote:

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.

Yours services would be most welcome. There was a bit of conversation
about docs in RubyGems, but left for later once the basics are worked
out. Right now, I’m thinking that the documentation should be stored in
the directory where the gem is unpacked. Pre-generated docs could be
part of the gem, or some post installation formatting (e.g. rdoc) could
be done. Then all we have to do is make documentation tools
knowledgable about where gems are stored.

¡¡¡

–
– Jim Weirich jweirich@one.net http://onestepback.org

“Beware of bugs in the above code; I have only proved it correct,
not tried it.” – Donald Knuth (in a memo to Peter van Emde Boas)

3

[…]

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?
[…]
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

There is also the issue of M17N: which langauge the docs should be
in, how to support many languages, etc. I don’t really have any
good answers to that particular (sub)problem. I suspect Ruby 2’s
emphasis on multinationalization will interact with this problem
space.

I have this odd notion that accommodation of many human languages
fits in with the culture of mutual respect within the ruby
community, but what might be done to support this I don’t know.

    Hugh
¡¡¡

On Fri, 28 Nov 2003, Gavin Sinclair wrote:

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

4

Gavin Sinclair wrote:

¡¡¡

On Fri, 28 Nov 2003, Jim Weirich wrote:

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

Yours services would be most welcome. There was a bit of conversation

about docs in RubyGems, but left for later once the basics are worked

out. Right now, I’m thinking that the documentation should be stored in

the directory where the gem is unpacked. Pre-generated docs could be

part of the gem, or some post installation formatting (e.g. rdoc) could

be done. Then all we have to do is make documentation tools

knowledgable about where gems are stored.

To second what Jim said, documentation support was one of the first items
we discussed. It was saved until later partially because it’s not as
important as, say, installing code :slight_smile: and (I think) mostly because it’s a
fairly simple problem to solve.

The same goes for tests. A nice side-benefit of specifying this stuff in
metadata is that a tool such as a gem-friendly RAA can query which
libraries actually have docs and tests. I might, for example, like to
filter out libraries that don’t have a test suite configured.

Chad

5

Well, you can’t translate English language RDoc comments into other
languages, or vice versa. Some packages are distributed with
multi-lang README and other files. These would all be copied into the
central documentation area as part of installation.

Gavin

¡¡¡

On Friday, November 28, 2003, 9:43:47 PM, Hugh wrote:

On Fri, 28 Nov 2003, Gavin Sinclair wrote:

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

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?
[…]
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

There is also the issue of M17N: which langauge the docs should be
in, how to support many languages, etc. I don’t really have any
good answers to that particular (sub)problem. I suspect Ruby 2’s
emphasis on multinationalization will interact with this problem
space.

I have this odd notion that accommodation of many human languages
fits in with the culture of mutual respect within the ruby
community, but what might be done to support this I don’t know.