[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

Installing Docs (Was Re: Library directory structure on windows

Gavin Sinclair

11/27/2003 9:25:00 PM

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.... (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.p...), 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
3 Answers

Jim Weirich

11/28/2003 4:36:00 AM

0

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://onest...
-----------------------------------------------------------------
"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)

Hugh Sasse

11/28/2003 10:44:00 AM

0

Gavin Sinclair

11/28/2003 12:11:00 PM

0

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.

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