From: JamesBritt <james@...>
Date: 2002-11-10T14:34:17+09:00
Subject: [ANN] www.ruby-doc.org

Jim Freeze's presentation at RubyConf 2002 mentioned, among other things, the
need for a ruby-docs project and/or general docs web site.  I've taken the
initiative and created a site at www.ruby-doc.org, so that we now have:

* A place to track developments concerning the ruby-doc documentation project.
We have a ruby-doc mailing list, and a list archive [0], but not a web home.

* A place to store assorted documents, both by and for the ruby-doc group, and
for Ruby documentation in general

* A central reference site for tutorials, API and syntax refs, online books,
Ruby articles, and the like, whether hosted directly or online elsewhere

* Yet Another Example of eating one's own dog food; the entire site is built
using pure Ruby.  It's mostly Blogtari [1], with some wrappers around ri (munged
using Rimport[2]).  REXML [3] is used for some intra-site RSS transformations,
too.

* Something similar to the www.php.net URL shortcuts
(http://www.php.net/urlhowto.php) for grabbing reference info.

For example, you can do this:

   http://www.ruby-doc.org/find/ri/Array

and get back the ri info for the Array class.  This URL

  http://www.ruby-doc.org/find/ri/Array/sort

tells you about the sort method for the Array class.

The code just runs ri on the server and adds some elementary markup.
The transformation includes modding the method list so that the results contain
hyperlinks to other queries.  For example, if you pull back the general info
about the Array class, each of the listed methods is a link for a subsequent
query on that specific method.

Now, what's in ri by default is what�s in the pickaxe book, but the URLs for
various pickaxe pages aren't so clean.  To get the page about the Array class,
for example, you need to know how to mangle the file name (i.e.,
ref_c_array.html).  To get to the page anchor for a given method, you need to
know that format, too (e.g. ref_c_array.html#Array.sort).

So, I wrote some URL rewriting code to handle that automatically.

Pickaxe URL searches work basically the same way as for ri, resolving path info
into URL matching class, module, or tutorial HTML files.

For example,

   http://www.ruby-doc.org/find/pickaxe/array

gives you the Programming Ruby page for Arrays:

   http://www.ruby-doc.org/docs/ProgrammingRuby/html/ref_c_array.html

The URL

   http://www.ruby-doc.org/find/pickaxe/array/sort

gives you the Array page, jumping to the page anchor marking the 'sort' method:

   http://www.ruby-doc.org/docs/ProgrammingRuby/html/ref_c_array.html#Array.sort

If the code cannot make a reasonable guess it gives you (I hope) the index page.
If the derived page anchor is working, you should at least get the top of the
related page.  For example,

   http://www.ruby-doc.org/find/pickaxe/array/foo

maps to

   http://www.ruby-doc.org/docs/ProgrammingRuby/html/ref_c_array.html#Array.foo

which is a bogus anchor, but a real page.


There's more work to be done on the site, but comments are invited.  I want to
add more data to the site's ri so that things currently missing from ri (and the
pickaxe) are retrievable via the munged version online.  Right now, for example,
you can get Matrix info online, something not available from the standard ri,
though the code was sparsely commented.  Likewise, WeakRef, Pstore, and a few
others are in there via rimport.

I also need to sort out additional pages for more details on things like doc
tools, project documents, syntax help, and so on.


James Britt

[0] http://www.moonwolf.com/~arcml/cgi-bin/arcml/?rm=threadlist&list_id=2
[1] http://www.jamesbritt.com/articles/blogatari.html
[2] http://www.ruby-lang.org/en/raa-list.rhtml?id=413
[3] http://www.germane-software.com/software/rexml/