From: Robert Dober Date: 2009-06-24T15:56:19+09:00 Subject: Re: ruby suggestion: officially sanctioned tutorials/howto's On Wed, Jun 24, 2009 at 7:40 AM, Robert Klemme wrote: > On 24.06.2009 00:00, Roger Pack wrote: >>>> >>>> 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. > > For me that is not an advantage.  For me a tutorial is something that has > been written with the reader's learning curve in focus and not with the > structure of software.  That is completely logical because when reading a > tutorial I might not know what classes will implement particular > functionality.  I'm all for tutorials but please don't mix them with > 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. BTW Thank you Tom Christiansen for making me discover the wonderful world of closures (yes he does read this ML but would probably never admit it ;). That said I agree with you on that rdoc is not that nice a format. > >> The concern is that the tutorials would clutter the code, is that correct? > > 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. No, the tutorials will not go into the code, they would live their lives Even if RDoc was chosen and there would be a lib/tutorials/string.rb nobody would ever require that file. > >> 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. I agree with you on this, but it would be better than nothing. > >> Another benefit is the tutorials will likely show up in the rdoc's too. > > We would be able to achieve that witch external links as well, don't we? > >> Another question is how to preserve a wiki-like feel to the tutorials. > > Well, you can do that only with a Wiki not with something distributed with > the source code. > >> 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? > > 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 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. Cheers Robert -- 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]