From: Brian Wisti <brian@...>
Date: 2002-11-10T16:55:34+09:00
Subject: Re: [ANN] www.ruby-doc.org

Hi James,

This is a great resource.  Thanks for setting it up!  Just one 
question:  Is it possible to browse (almost) randomly through the Standard 
Library API?

-Brian W
At 02:34 PM 11/10/2002 +0900, JamesBritt wrote:
>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/