From: Joel VanderWerf <vjoel@...>
Date: 2009-06-23T01:50:34+09:00
Subject: Re: ruby suggestion: officially sanctioned tutorials/howto's

James Gray wrote:
> On Jun 22, 2009, at 7:10 AM, Roger Pack wrote:
>> Another option might be to add very long, tutorial style rdoc comments
>> to classes.
> 
> We could create a tutorials folder in the main distribution, write RDoc 
> marked-up tutorials in there, and add those files to the documentation 
> build.  I'm not sure that's the best possible strategy, but it is one idea.

To expand on James's proposal a bit... what about defining a module 
called, for example, Socket::Tutorial, and putting the material in the 
comment block of that module, for rdoc to find? Then:

  `ri Tutorial` ==> list of tutorials(*)

  `ri Socket::Tutorial` ==> the socket tutorial

  `ri Socket::Tutorial.open` ==> tutorial on Socket.open.

(*) actually, I'm not sure current ri performs a search for x::Tutorial, 
but why shouldn't it?

-- 
       vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407