ruby suggestion: officially sanctioned tutorials/howto's

[Roger Pack]

Current situation:

I remember way back when using the official python tutorial, there was
a section explaining the proper use of select with sockets, etc [1].
This was quite helpful to me getting started with the language, having
a more "tutorial" feel place to explain how socket IO should work
[i.e. larger snippets than the current rdoc has, place to explain
nuances, etc.]

The current rdocs [2] are useful and contain a lot of very helpful
information, but for me I currently have to already know the name of
the method I want to learn about for them to be useful [there is no
guide, little hierarchy [class based only], no "officially sanctioned"
place for things like longer tutorials, etc.]


I would like to suggest a more "officially sanctioned" Ruby
tutorial/howto to try to help fill that void. Whatever that might
mean [official editable wiki page for it, a folder in svn that has
tutorials only, whatever]. I would be quite happy to help--set it up,
maintain it, or even write it myself, should such an idea be accepted.

Another option might be to add very long, tutorial style rdoc comments
to classes.

Thoughts?
Thanks.

=roger

[1] http://docs.python.org/tutorial/ specifically
http://docs.python.org/dev/howto/sockets.html
[2] http://ruby-doc.faithpromotingstories.org/doc/ruby-1.9.1-p129 or
http://ruby-doc.org/core-1.9/index.html

 

[James Gray]

I would like to suggest a more "officially sanctioned" Ruby
tutorial/howto to try to help fill that void.

I think this is a very good idea.

I was just thinking the other day about how I really like that perldoc
can do more than just look up method definitions. For example, it can
search Perl's FAQ for you. I realize that's not exactly what you are
suggesting here, but I found it useful in a similar way during my time
in their camp.

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.

James Edward Gray II

 

[Joel VanderWerf]

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?

 

[Robert Dober]

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

=A0`ri Tutorial` =3D=3D> list of tutorials(*)

=A0`ri Socket::Tutorial` =3D=3D> the socket tutorial

=A0`ri Socket::Tutorial.open` =3D=3D> tutorial on Socket.open.

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

Honestly that sounds brilliant. I am just a little bit confused about
the x::Tutorial, should that not be Tutorial::X
for X in { Array, Module, Class, Exception, Enumerator, You::Name::It } ?

And Tutorial would be a module in the standard lib?
Cheers
Robert


--=20
Toutes les grandes personnes ont d=92abord =E9t=E9 des enfants, mais peu
d=92entre elles s=92en souviennent.

All adults have been children first, but not many remember.

[Antoine de Saint-Exup=E9ry]

 

[Tom Cloyd]

I think this is a very good idea.

I was just thinking the other day about how I really like that perldoc
can do more than just look up method definitions. For example, it can
search Perl's FAQ for you. I realize that's not exactly what you are
suggesting here, but I found it useful in a similar way during my time
in their camp.


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.

James Edward Gray II

I'm liking this thread a LOT. However, as a perpetual Ruby amateur (in
both senses - non-professional, and lover), I would like to see the wiki
notion preserved.

If the only author for this material is the programmer(s), that's
needlessly limiting. Some never have time to write up such tutorials,
AND community people have some very good ideas which they would do well
to contribute to the tutorial, over and above the thoughts of the
code-originator. I'd want both sources of input, for the benefit of
people like me (who need all the help they can find).

I sure hope this fine idea sees the light of day.

Tom

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Joel VanderWerf]

I am just a little bit confused about
the x::Tutorial, should that not be Tutorial::X
for X in { Array, Module, Class, Exception, Enumerator, You::Name::It } ?

And Tutorial would be a module in the standard lib?

I had it the other way (Socket::Tutorial etc.) because that would keep
the tutorial in the namespace of the subject. You could structure a
library like this:

module M
# Give the overall M tutorial here.
module Tutorial
# Tutorial for feature x
def self.feature_x
end
end

def self.feature_x
end

# API overview for C
class C
# Tutorial for C
module Tutorial
end
end
end

Or maybe it should all be in one global Tutorial space. Dunno...

 

[Eric Hodel]

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?

Why can't the tutorial go on Socket, or Socket.open? Net::HTTP has
it's tutorials on Net::HTTP...

 

[Robert Dober]

I had it the other way (Socket::Tutorial etc.) because that would keep th= e
tutorial in the namespace of the subject. You could structure a library l= ike
this:

module M
=A0# Give the overall M tutorial here.
=A0module Tutorial
=A0 =A0# Tutorial for feature x
=A0 =A0def self.feature_x
=A0 =A0end
=A0end

=A0def self.feature_x
=A0end

=A0# API overview for C
=A0class C
=A0 =A0# Tutorial for C
=A0 =A0module Tutorial
=A0 =A0end
=A0end
end

Or maybe it should all be in one global Tutorial space. Dunno...

Why not Jo=EBl, I did not really get it. But I guess it all depends on
the tools and implementors.
The only issue I see is with frozen classes, they could not be reopened in =
a
require 'tutorial/whatver'
right?
But I guess there are no frozen classes in core and stdlib. However it
would be great for third party developers to be able to adopt the
style.

Just my Doller/(42+8)
Cheers
Robert


--=20
Toutes les grandes personnes ont d=92abord =E9t=E9 des enfants, mais peu
d=92entre elles s=92en souviennent.

All adults have been children first, but not many remember.

[Antoine de Saint-Exup=E9ry]

 

[Robert Dober]

I'm liking this thread a LOT. However, as a perpetual Ruby amateur (in bo= th
senses - non-professional, and lover), I would like to see the wiki notio= n
preserved.

I would like both ideas preserved and if someone could come up with
more ideas, why not?
Maybe the wiki could take on where the Tutorial stops or be a place to
make the Tutorial evolve too.
Robert


--=20
Toutes les grandes personnes ont d=92abord =E9t=E9 des enfants, mais peu
d=92entre elles s=92en souviennent.

All adults have been children first, but not many remember.

[Antoine de Saint-Exup=E9ry]

 

[Joel VanderWerf]

Why can't the tutorial go on Socket, or Socket.open? Net::HTTP has it's
tutorials on Net::HTTP...

If every class were so well documented, the subject of this thread
probably wouldn't come up

Still, I can imagine wanting 'ri Net::HTTP' to output a short summary of
the api, rather than a full tutorial, which would be accessible by some
other command.

 

[Eric Hodel]

If every class were so well documented, the subject of this thread
probably wouldn't come up

Still, I can imagine wanting 'ri Net::HTTP' to output a short
summary of the api, rather than a full tutorial, which would be
accessible by some other command.

I love Net::HTTP for it's verboseness. 90% of what I want to do is
covered in that page and I can easily see how the whole thing fits
together from all the examples it presents. This also allow me to
figure out what method I want to look up for the remaining 10%.

 

[Robert Dober]

If every class were so well documented, the subject of this thread probab= ly
wouldn't come up

Still, I can imagine wanting 'ri Net::HTTP' to output a short summary of = the
api, rather than a full tutorial, which would be accessible by some other
command.

Exactly, the purpose of inline documentation is to give a reference
for quick checkup IMHO. I would not like to go through the whole
tutorial everytime. Now one could imagine to have rdoc generate both,
but I feel that this is better done in a different file.
Cheers
Rober
--=20
Toutes les grandes personnes ont d=92abord =E9t=E9 des enfants, mais peu
d=92entre elles s=92en souviennent.

All adults have been children first, but not many remember.

[Antoine de Saint-Exup=E9ry]

 

[Robert Klemme]

Honestly that sounds brilliant. I am just a little bit confused about
the x::Tutorial, should that not be Tutorial::X
for X in { Array, Module, Class, Exception, Enumerator, You::Name::It } ?

And Tutorial would be a module in the standard lib?

I do not like the idea. Here's why: you add code which has the sole
purpose of carrying documentation. The primary purpose of source code
is to provide functionality and not serve as a text skeleton.

The second reason is, that documentation derived from code typically has
a different structure than "hand crafted" tutorials. This documentation
is structured around source code artifacts such as classes and modules.
A written tutorial focuses on tasks and usually has a structure so
that you can more easily learn when reading from beginning to end.

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.

My 0.02 EUR

Kind regards

robert

 

[Robert Dober]

I do not like the idea. =A0Here's why: you add code which has the sole pu= rpose
of carrying documentation. =A0The primary purpose of source code is to pr= ovide
functionality and not serve as a text skeleton.

And what if documentation were the functionality of this code?
IMHO it is completely open if there would be code or only rdoc
documentation, but nicely included into the class hierarchy. Jo=EBl has
probably an idea about that.

The second reason is, that documentation derived from code typically has = a
different structure than "hand crafted" tutorials. =A0This documentation = is
structured around source code artifacts such as classes and modules. =A0A
written tutorial focuses on tasks and usually has a structure so that you
can more easily learn when reading from beginning to end.

You are absolutely correct, but please see above, no code as far as I
am concerned.

Having said that it is probably a good idea to include tutorials in the
standard distribution. =A0But 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=EBl's
idea of linking it into the "right" place.
What'u think?

R.

 

[Roger Pack]

Having said that it is probably a good idea to include tutorials in the

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.

The concern is that the tutorials would clutter the code, is that
correct?

One thought [I think suggested previously?] might be something like

doc/socket_tutorial.rb # a separate file

class Socket
# a tutorial all about sockets
module Tutorial; end
end
end


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."

Another benefit is the tutorials will likely show up in the rdoc's too.

The question for me is still "if you do that, where do tutorials go that
don't fit [ex: a tutorial about blocks]?" and should it be
Socket::Tutorial or Tutorial::Socket. I suppose the former makes it
more inline and accessible?

Another question is how to preserve a wiki-like feel to the tutorials.
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?

-=r

 

[Robert Klemme]

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.

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.

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.

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.

Kind regards

robert

 

[Robert Dober]

For me that is not an advantage. =C2=A0For me a tutorial is something tha= t has
been written with the reader's learning curve in focus and not with the
structure of software. =C2=A0That is completely logical because when read= ing a
tutorial I might not know what classes will implement particular
functionality. =C2=A0I'm all for tutorials but please don't mix them with
reference documentation. =C2=A0If 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.

t?

Partly. =C2=A0The other half is that I have certain expectations about ho= w 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.

I doubt that ri the proper tool for the job. =C2=A0We'd rather need somet= hing
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.

We would be able to achieve that witch external links as well, don't we?


Well, you can do that only with a Wiki not with something distributed wit= h
the source code.


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
--=20
Toutes les grandes personnes ont d=E2=80=99abord =C3=A9t=C3=A9 des enfants,=
mais peu
d=E2=80=99entre elles s=E2=80=99en souviennent.

All adults have been children first, but not many remember.

[Antoine de Saint-Exup=C3=A9ry]

 

[Roger Pack]

What'u think?

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.


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?


Good point. For me the nicety would be in rdoc integration, not ri
integration [I never use ri].

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

 

[Robert Dober]

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. =A0Feels 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
Well rdoc does give us somewhat of a layout in terms of class names. =A0I
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. =A0I assumed it would be about as easy to navigate/find as any
indexed layout. Thoughts?


Good point. =A0For me the nicety would be in rdoc integration, not ri
integration [I never use ri].

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]. =A0Another
option might be to just flesh that out and call that the tutorial. =A0Man= y
of the things it has are things that could belong in a Ruby
tutorial--ex: basics of an Array. =A0Of 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. =A0The 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. =A0For some reason that information isn't in the rdocs I'm
not sure why [1]. =A0I 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?
=3Dr

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
--=20
Toutes les grandes personnes ont d=92abord =E9t=E9 des enfants, mais peu
d=92entre elles s=92en souviennent.

All adults have been children first, but not many remember.

[Antoine de Saint-Exup=E9ry]

 

[Roger Pack]

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].

I suppose one option would be to put tutorials into said wiki, then add
a link to them within the rdocs in core.

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...

Example if I go into trunk/ext/bigdecimal and run "rdoc" in that
directory, shouldn't the generated rdoc's have BigDecimal's description
somewhere? [they don't seem to, at least with 2.4.3] Is this expected?

[1] might be related to this:
http://rubyforge.org/tracker/index.php?func=detail&aid=26410&group_id=627&atid=2472

So assuming that those tutorials "are there" (and this is a temporary
bug) this means that some classes have tutorial info already so...to me
it would seem to make sense that, if you add more tutorial info, you
want to add it into the rdoc base somehow, so that it can be a sibling
to the existing tutorials and not split them up.

I think I finally understand Robert's original objection--it is that "if
it's a tutorial, shouldn't it be basically in some tutorial section
somehow, not mixed in ad hoc with the rdoc's?"


One way to attempt to not "mix them in together" might be to create the
tutorials are in a sub folder, i.e. trunk/doc/tutorials, then one can
generate "tutorial only" rdocs by running rdoc from within that
subfolder. It wouldn't (easily) contain backlinks to the class
description themselves, but it would give you all the tutorials in a
single rdoc. Would that help?


The other thought is "if it's not a wiki, it's not user editable".
I'm not sure of an easy way around that one...maybe have a "staging
wiki" for the tutorials that people can edit, that has a maintainer who
tracks changes and submits "good ones" to core?

Thoughts?
=r