From: Jostein Berntsen <jostein.berntsen@...>
Date: 2002-11-10T21:39:02+09:00
Subject: Re: [ANN] www.ruby-doc.org

Hi,

A fine site and a good resource! I believe good, structured documentation like 
this on the web can be a booster for language promotion.

- Default look: In my Mozilla browser the fonts are very small in the right 
frame. Maybe Default should somewhere in between Default and Big type? Ugly 
might deserve it's name.
- A note on the front saying that the entire site was written in Ruby?
- Are there any documentation for using eRuby?
- A "How to use the site"-doc could be cool.
- A search tool made in Ruby. :)

I will keep digging...

Regards,

Jostein

On Sunday 10 November 2002 06:34,  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.so
>rt
>
> 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.fo
>o
>
> 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/