From: Roger Pack Date: 2009-06-24T23:05:45+09:00 Subject: Re: ruby suggestion: officially sanctioned tutorials/howto's >>>> 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? 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. >> 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 [1] might be related to this: http://rubyforge.org/tracker/index.php?func=detail&aid=26410&group_id=627&atid=2472 -- Posted via http://www.ruby-forum.com/.