From: Daniel Bretoi <lists@...>
Date: 2002-11-12T15:12:57+09:00
Subject: Re: [ANN] www.ruby-doc.org

awesome :) I'd love to see something in the style of PHP's php.net.
I've found theirs to be the most helpful document project ever. 
Thoughts?

db

On Sun, Nov 10, 2002 at 02:34:17PM +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/
> 

-- 
A.D. 1844: Samuel Morse invents Morse code. Cryptography export
restrictions prevent the telegraph's use outside the U.S. and Canada.