From: Roger Pack <rogerpack2005@...>
Date: 2009-06-24T07:00:39+09:00
Subject: Re: ruby suggestion: officially sanctioned tutorials/howto's

>> Having said that it is probably a good idea to include tutorials in the
>> standard distribution. �But IMHO they should be written as tutorials,
>> probably using Textile markup or something similar.
> Not a bad idea at all. I would prefer to write it in textile rather
> than in rdoc.
> However I still feel it would be great if we could incorporate Jo�l's
> idea of linking it into the "right" place.
> What'u think?

Chiming in, I quite like the idea overall of having Tutorial's 
accessible via ri, since you could use ri to view it and then use ri to 
lookup methods--you'd only need one tool overall.

The concern is that the tutorials would clutter the code, is that 
correct?

One thought [I think suggested previously?] might be something like

doc/socket_tutorial.rb # a separate file

class Socket
 # a tutorial all about sockets
 module Tutorial; end
 end
end


The benefit of this not being "oooh we get to use rdoc syntax!" but more 
"we already have a command line browser for it, since we can use ri."

Another benefit is the tutorials will likely show up in the rdoc's too.

The question for me is still "if you do that, where do tutorials go that 
don't fit [ex: a tutorial about blocks]?" and should it be 
Socket::Tutorial or Tutorial::Socket.  I suppose the former makes it 
more inline and accessible?

Another question is how to preserve a wiki-like feel to the tutorials. 
I know google code projects commit wiki changes as svn commits but...I'm 
not sure how this could work for core.  Any thoughts there?  Just 
include instructions somewhere on how to update them maybe?

-=r
-- 
Posted via http://www.ruby-forum.com/.