From: Gavin Sinclair <gsinclair@...>
Date: 2003-12-12T06:57:10+09:00
Subject: Re: Ruby Doc Vision (was Re: Docs for Socket, OpenSSL, etc)

On Friday, December 12, 2003, 4:50:15 AM, James wrote:

> On Fri, 12 Dec 2003 02:14:43 +0900
> Dave Thomas <dave@pragprog.com> wrote:

>> 
>> On Dec 11, 2003, at 9:15, James F. Hranicky wrote:
>> 
>> > KO...let me know when to start back up.
>> 
>> In the meantime, I assume you've looked at
>> 
>> http://www.rubycentral.com/book/lib_network.html

> Ack! I guess I haven't run through Pickaxe in a while ( I know, bad 
Jim...:->> ).

> Any chance the info there could be moved into the 1.6 reference? As good
> as the Pickaxe is, sometimes I just want a quick reference a la the 1.4.6
> ref. 

> I'm probably opening up a big/old can of worms, right now it seems that
> there are several sources of documentation for Ruby, all with different
> areas covered. What is the ultimate vision for ruby docs? rd? ri? rdoc?
> ruby-doc.org? pickaxe? The only thing php or perl have over Ruby IMO is
> their docs are standardized: perldoc blah (even man blah...yay!), 
> or http://www.php.net/manual/en . 

* rd is being used less and less.
* RDoc is being used more and more.  A good practice for library authors
  is to make the RDoc of their library viewable online, e.g.
  http://extensions.rubyforge.org
* ri does built-in classes only, but is great at what it does
  (http://rjay.roubyforge.org is an alpha attempt to add stdlib doc to
  it)
* ruby-doc.org has several evolving aims, and will always collect
  available Ruby documentation, as well as endeavouring to create it.
  The stdlib documentation is a good example.
* Pickaxe: I presume you're talking about updates.  We'll have to wait
  and see.

The ultimate vision, for me, is
 * RDoc being used everywhere
 * ri giving quick access to RDoc info
 * RubyGems simplifying access to the documentation for all your
   installed packages
 * ruby-doc.org completely documenting the standard library
 * ruby-doc.org collecting all other documentation and providing a
   breeding ground for original content

Although there are 5 points there, they don't overlap (too much).


> Whatever the ultimate vision, I'm more than happy to help out. 

Excellent.  I don't know why Dave's new work on RDoc means you
shouldn't continue with Socket and OpenSSL, but since it's in C it
could be a curly one.  If you have a favourite library (Ruby-lang)
that isn't currently documented, you could start there.  If you want
an easier job, there are some libraries done in RD that need
conversion to RDoc.

Cheers,
Gavin