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


 

Forums >

comp.lang.ruby

[RCR] Include CONFIG::Config['rubydocdir'] in rbconfig.rb

Gavin Sinclair

10/1/2003 12:38:00 PM

Hi folks,

I apologise if people have read this RCR and are not interested, but
this is what I consider to be an important RCR, not a merely
convenient one, and I may have done it a disservice by burying its
mention in a previous thread.

At any rate, it has not attracted many votes, and no comments, so I'd
like to point you to http://www.rubygarden.org/article.p... if
you are interested in registering an opinion on this.

Summary: if Ruby had a standard documentation directory, then
installers could install documentation there. A typical Ruby
installation does contain documentation in a sensible place, but this
location is not retrievable through the normal Config['xyz']
mechanism.

Thanks,
Gavin
7 Answers

matz

10/1/2003 3:18:00 PM

0

Hi,

In message "[RCR] Include CONFIG::Config['rubydocdir'] in rbconfig.rb"
on 03/10/01, Gavin Sinclair <gsinclair@soyabean.com.au> writes:

|Summary: if Ruby had a standard documentation directory, then
|installers could install documentation there. A typical Ruby
|installation does contain documentation in a sensible place, but this
|location is not retrievable through the normal Config['xyz']
|mechanism.

Currently it does not have one. Where do you think it should be, if
Ruby should have a standard documentation directory. And how far
should it cover? Libraries? Applications?

matz.

Eric Hodel

10/1/2003 3:58:00 PM

0

Yukihiro Matsumoto (matz@ruby-lang.org) wrote:

> In message "[RCR] Include CONFIG::Config['rubydocdir'] in rbconfig.rb"
> on 03/10/01, Gavin Sinclair <gsinclair@soyabean.com.au> writes:
>
> |Summary: if Ruby had a standard documentation directory, then
> |installers could install documentation there. A typical Ruby
> |installation does contain documentation in a sensible place, but this
> |location is not retrievable through the normal Config['xyz']
> |mechanism.
>
> Currently it does not have one. Where do you think it should be, if
> Ruby should have a standard documentation directory. And how far
> should it cover? Libraries? Applications?

On FreeBSD Ruby documentation is stored in /usr/local/share/doc/ruby,
so if I install ruby, ruby libs, or ruby apps on FreeBSD, that's
where I expect documentation to end up.

FWIW, install.rb puts things in the correct place if you have a data/doc
directory (data maps to /usr/local/share).

--
Eric Hodel - drbrain@segment7.net - http://se...
All messages signed with fingerprint:
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

ahoward

10/1/2003 5:07:00 PM

0

Berger, Daniel

10/1/2003 7:25:00 PM

0

"Ara.T.Howard" wrote:
>
> On Thu, 2 Oct 2003, Yukihiro Matsumoto wrote:
>
> > Hi,
> >
> > In message "[RCR] Include CONFIG::Config['rubydocdir'] in rbconfig.rb"
> > on 03/10/01, Gavin Sinclair <gsinclair@soyabean.com.au> writes:
> >
> > |Summary: if Ruby had a standard documentation directory, then
> > |installers could install documentation there. A typical Ruby
> > |installation does contain documentation in a sensible place, but this
> > |location is not retrievable through the normal Config['xyz']
> > |mechanism.
> >
> > Currently it does not have one. Where do you think it should be, if
> > Ruby should have a standard documentation directory. And how far
> > should it cover? Libraries? Applications?
>
> first of all, this idea is fantastic. however, i think it would be made
> better if a standard doccumentation format was also agreed upon.

Given that the Ruby source contains all of its docs in RD format, and
that you can generate html, man or rdoc pages (I think) from rd docs,
why should we settle on html?

Now, if someone wants to include a massive rdoc index for all the
builtin stuff, that's fine with me. In any case, let's just settle on
the directory first. And yes, I already voted on the RCR. :)

Regards,

Dan

Zachary P. Landau

10/1/2003 7:40:00 PM

0

> |Summary: if Ruby had a standard documentation directory, then
> |installers could install documentation there. A typical Ruby
> |installation does contain documentation in a sensible place, but this
> |location is not retrievable through the normal Config['xyz']
> |mechanism.
>
> Currently it does not have one. Where do you think it should be, if
> Ruby should have a standard documentation directory. And how far
> should it cover? Libraries? Applications?

The documentation dir should probably only handle libraries. With
applications, it shouldn't matter what language they are written in, so
the documentation should go in the same place as any other program
documentation. You wouldn't have /usr/share/doc/c/gawk/README or
something like that.

Libraries are used when people are writing something in the same
programming language, so it should make sense to put those in something
like /usr/share/doc/ruby/ruby-gtk2/README.

So maybe we want Config['libdocs'] or something that shows it is for
ruby libraries and applications.

--
Zachary P. Landau <kapheine@hypa.net>
GPG: gpg --recv-key 0x24E5AD99 | http://kapheine.hypa.net/ka...

Eric Hodel

10/1/2003 9:31:00 PM

0

Ara.T.Howard (ahoward@fsl.noaa.gov) wrote:

> IMHO, it would be very, very, very, cool if, for example, each
> package had it's own rdoc directory which lived _along_side_ the
> package in site_ruby

This mixes libs and doc, which I feel is very, very bad.

If you want to save space, you have to do extra tedious work to snip out
the rdoc directories, which is not a problem if you have them sitting
with the rest of the system docs. Furthermore, it violates principles
of good design. Nothing else is storing documentation in your lib
directories, so why should Ruby? lib is for libraries, let's keep it
that way.

--
Eric Hodel - drbrain@segment7.net - http://se...
All messages signed with fingerprint:
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

Gavin Sinclair

10/1/2003 10:25:00 PM

0

On Thursday, October 2, 2003, 1:17:35 AM, Yukihiro wrote:

> Hi,

> In message "[RCR] Include CONFIG::Config['rubydocdir'] in rbconfig.rb"
> on 03/10/01, Gavin Sinclair <gsinclair@soyabean.com.au> writes:

> |Summary: if Ruby had a standard documentation directory, then
> |installers could install documentation there. A typical Ruby
> |installation does contain documentation in a sensible place, but this
> |location is not retrievable through the normal Config['xyz']
> |mechanism.

> Currently it does not have one. Where do you think it should be, if
> Ruby should have a standard documentation directory. And how far
> should it cover? Libraries? Applications?

My Cygwin setup has these directories:

/usr/local/doc/ruby/ri-1.8b
/usr/local/doc/ruby/ruby-1.8.0

So that covers an application and the language. Other applications
would be welcome there, e.g.

/usr/local/doc/ruby/rdict-x.y
/usr/local/doc/ruby/rcalc-m.n

And libraries would be a good fit as well:

/usr/local/doc/ruby/amrita-1.0.1
/usr/local/doc/ruby/amrita-1.0.1/README etc
/usr/local/doc/ruby/amrita-1.0.1/rdoc/index.html etc

As for the standard library, that could perhaps be documented in

/usr/local/doc/ruby/ruby-1.8.0/lib/...

Although http://stdlib-doc.rub... will be the best place to get
standard library documentation before too long.

Gavin