reference documentation. If at all, have tutorials link reference
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
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
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?
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 . 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.
 might be related to this:
Posted via http://www.ruby-forum.com/.