From: Robert Dober Date: 2009-06-25T06:04:46+09:00 Subject: Re: ruby suggestion: officially sanctioned tutorials/howto's On Wed, Jun 24, 2009 at 4:05 PM, Roger Pack wrote: >>>>> What'u think? >>> reference documentation.  If at all, have tutorials link reference >>> documentation. >> >> True, but I do not see why integrating it into ri/rdoc and the >> distribution would need that, there might be >> Tutorial::Network, Tutorial::HowToCookEggs and Tutorial::Array. This >> is very much inspired by Perl's way to do these things, but they did >> this quite well. I was able to get real work done with the perl pods >> and perl tutorials which were perfectly integrated. > > Perhaps you could help me by explaining how perl did it so nicely and > how the integration worked? Interesting thought, I admit that this might have been a jumped conclusion, maybe it was hard work behind the scenes. But my thought was that they just created .pl files full of POD? > For my own $0.02 I would imagine having the Tutorials in with the normal > rdoc would be an advantage--you could browse them while browsing the > rdoc.  Feels more accessible somehow. > > One option to avoid clutter would be to force everything into the > Tutorial root module [kind of like the Tutorial namespace], then it > would be close to the code but not integrated. I > > >>> Partly.  The other half is that I have certain expectations about how a >>> tutorial is written (see above) and placing them in code reference >>> documentation makes it harder to find for the novice. > > Well rdoc does give us somewhat of a layout in terms of class names.  I > had thought we could just use module names for sections, like > > Tutorial::Arrays::Chapter_1 > Tutorial::Arrays::Chapter_2 > > etc. > > someone could link to Tutorial::Arrays if they wanted to see the whole > thing.  I assumed it would be about as easy to navigate/find as any > indexed layout. Thoughts? > > >>>> 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." >>> >>> I doubt that ri the proper tool for the job.  We'd rather need something >>> which can present a table of contents and is capable of doing full text >>> search on it. > > Good point.  For me the nicety would be in rdoc integration, not ri > integration [I never use ri]. > > >>> A tutorial wiki on ruby-lang.org or a related place sounds good to me. >>> Usually Wiki engines nowadays have versioning so that shouldn't be a >>> problem. >> >> To me too, I am not saying that the Tutorial::OMG::RubyIsSoCool is the >> only solution, I just feel that you >> reject it for reasons that do not really exist. >> What is great is that it integrates nicely with the distribution, I >> imagine "sudo gem install ruby-tutorials" or >> "sudo gem install ruby-tutorials-ruby-is-cool" and nobody would need >> to learn yet another URL. It was a real > > Would gemifying stuff be helpful or are you just pointing out that > integration with existing tools takes out the need for another tool? > Just wondering. > >> speed up factor for me to learn Perl when I found all I needed at the >> same place. Again if we put a wiki to ruby-doc that will probably >> serve the same purpose. > > There is somewhat of a wiki: > http://en.wikibooks.org/wiki/Ruby_Programming [it's even linked to from > deep within the nether-reaches of the ruby-lang.org website].  Another > option might be to just flesh that out and call that the tutorial.  Many > of the things it has are things that could belong in a Ruby > tutorial--ex: basics of an Array.  Of course it's missing things that > might be quite useful, like "how to use -rdebug", "how to use openssl", > "how to use -rtracer" etc, so obviously it's far from complete > currently.  The kicker is that it seems like if we put tutorials there, > [ex: openssl] we'd end up explaining the methods we use as we use them, > duplicating the existing rdoc, so a tutorial closer to [and > supplementing] the rdoc might be easier to write. > > I did notice from http://webri.tigerops.org/ that many classes [ex: > BigDecimal] already have tutorial like information in the class > description.  For some reason that information isn't in the rdocs I'm > not sure why [1].  I suppose that means that an option is to put all > tutorial information into the class' rdocs... > > Anyway the wiki and the ri are "related projects" to a tutorial system > thought I'd point them out. > > Thoughts? > =r I am a little bit confused about some of the quoting, my fault my post really was too long, but I like what you propse. I also like what Robert proposes, I just want to defend the Tutorial namespace thing he refuses. Correct Robert? Cheers R -- Toutes les grandes personnes ont d’abord été des enfants, mais peu d’entre elles s’en souviennent. All adults have been children first, but not many remember. [Antoine de Saint-Exupéry]