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

[Gavin Sinclair]

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.php?sid=319 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

 

[Yukihiro Matsumoto]

Hi,

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

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

--NPWyolIJAVLYbHY6
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

In message "[RCR] Include CONFIG::Config['rubydocdir'] in rbconfig.rb"
=20
|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.
=20
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).

--=20
Eric Hodel - (e-mail address removed) - http://segment7.net
All messages signed with fingerprint:
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04


--NPWyolIJAVLYbHY6
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (FreeBSD)

iD8DBQE/evl/MypVHHlsnwQRAtvXAKDmApGhpfj53q4yRDDKkK3A/Wkx0ACgk2dl
1ngg2gga5hdUoRWiKwUNfw4=
=SI1w
-----END PGP SIGNATURE-----

--NPWyolIJAVLYbHY6--

 

[Ara.T.Howard]

Hi,

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

|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. to me, this
choice is very simple: html is the only doc format that will easily work on
mac, windows, and *nix. rdoc is the best of the html doc generators. ergo,
rdoc wins my vote. personally, i prefer man pages but...

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 would allow, for example, one to do this:

netscape file:/usr/lib/ruby/site_ruby/1.8/package/rdoc/index.html

to see the docs for 'package'

furthermore, rdoc could be generated for docs for ALL of a site_ruby dir,
allowing one to

netscape file:/usr/lib/ruby/site_ruby/1.8/rdoc

to see the rdocs for EVERY INSTALLED COMPONENT on your system. this could be
super cool.

for all you java developers out there you will see where i am going with this,
if rubyists could agree on a place and format for docs pages could be
generated to doccument

a) all the ruby internal classes
b) all the installed classes on your system (combined)
c) all the installed classes on your system (individually)

if you use the pickaxe html page 'Built-in Classes and Methods', as i do, as
java programmers use the javadoc api pages - you will appreciate where i'm
going with this. imaging that there was also a 'Site-Ruby Classes and
Methods' page, and how that would help prgrammers jump into the ruby language.

my two cents.

-a
====================================
| Ara Howard
| NOAA Forecast Systems Laboratory
| Information and Technology Services
| Data Systems Group
| R/FST 325 Broadway
| Boulder, CO 80305-3328
| Email: (e-mail address removed)
| Phone: 303-497-7238
| Fax: 303-497-7259
| The difference between art and science is that science is what we understand
| well enough to explain to a computer. Art is everything else.
| -- Donald Knuth, "Discover"
| ~ > /bin/sh -c 'for lang in ruby perl; do $lang -e "print \"\x3a\x2d\x29\x0a\""; done'
====================================

 

[Daniel Berger]

Hi,

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

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

--mYCpIKhGyMATD0i+
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

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

--=20
Zachary P. Landau <[email protected]>
GPG: gpg --recv-key 0x24E5AD99 | http://kapheine.hypa.net/kapheine.asc

--mYCpIKhGyMATD0i+
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)

iD8DBQE/ey2XCwWyMCTlrZkRAsJfAJwJpjCi12VmdXWorVifIhQYqQZFEACeKK4r
Nbzexo0+KesMTcCfVCfITI8=
=czgX
-----END PGP SIGNATURE-----

--mYCpIKhGyMATD0i+--

 

[Eric Hodel]

--c8UbHMnQwI7BF+TB
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

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.

--=20
Eric Hodel - (e-mail address removed) - http://segment7.net
All messages signed with fingerprint:
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04


--c8UbHMnQwI7BF+TB
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (FreeBSD)

iD8DBQE/e0eOMypVHHlsnwQRArBXAKCDcfQq4phYVWIQdL+gpHVpd4PnNACfb6aA
HtwxVJdhfbDMhLSCFMPN2Zs=
=mung
-----END PGP SIGNATURE-----

--c8UbHMnQwI7BF+TB--

 

[Gavin Sinclair]

Hi,

In message "[RCR] Include CONFIG::Config['rubydocdir'] in rbconfig.rb"
on 03/10/01, Gavin Sinclair <[email protected]> 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.rubyforge.org will be the best place to get
standard library documentation before too long.

Gavin