From: "Ara.T.Howard" <ahoward@...>
Date: 2003-10-02T04:02:08+09:00
Subject: Re: [RCR] Include CONFIG::Config['rubydocdir'] in rbconfig.rb

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.  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: ara.t.howard@noaa.gov
  | 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'
  ====================================