Ruby suggestion: officially sanctioned tutorials/howto's

Ruby
1

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] The Python Tutorial — Python 3.11.4 documentation specifically
Socket Programming HOWTO — Python 3.13.0a0 documentation
[2] http://ruby-doc.faithpromotingstories.org/doc/ruby-1.9.1-p129 or
http://ruby-doc.org/core-1.9/index.html

2

James G. wrote:

On Jun 22, 2009, at 7:10 AM, Roger P. wrote:

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.

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?

3

On Jun 22, 2009, at 7:10 AM, Roger P. wrote:

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

4

On Mon, Jun 22, 2009 at 6:50 PM, Joel
VanderWerf[email protected] wrote:

James G. wrote:

On Jun 22, 2009, at 7:10 AM, Roger P. wrote:

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

–
vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407
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

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

5

James G. wrote:

suggesting here, but I found it useful in a similar way during my time
James Edward G. 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 C., MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
6

On Jun 22, 2009, at 09:50, Joel VanderWerf wrote:

To expand on James’s proposal a bit… what about defining a module
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…

7

Robert D. wrote:

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…

8

On Tue, Jun 23, 2009 at 2:51 AM, Tom C.[email protected] wrote:

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

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

9

On Tue, Jun 23, 2009 at 5:00 AM, Joel
VanderWerf[email protected] wrote:

this:
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…
Why not Joël, 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

–
vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

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

10

Eric H. wrote:

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 :frowning:

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.

11

On Jun 23, 2009, at 12:11, Joel VanderWerf wrote:

Eric H. wrote:

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 :frowning:

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

12

On Tue, Jun 23, 2009 at 9:11 PM, Joel
VanderWerf[email protected] wrote:

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

13

On 23.06.2009 01:20, Robert D. wrote:

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?

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

14

On Tue, Jun 23, 2009 at 11:30 PM, Robert
Klemme[email protected] wrote:

called,
(*) actually, I’m not sure current ri performs a search for x::Tutorial,
of carrying documentation. The primary purpose of source code is to provide
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ël has
probably an idea about that.

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

R.

15

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.

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

16

On 24.06.2009 00:00, Roger P. wrote:

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

17

On Wed, Jun 24, 2009 at 7:40 AM, Robert
Klemme[email protected] 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. 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.

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]

18

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:
Ruby Programming - Wikibooks, open books for an open world [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

19

On Wed, Jun 24, 2009 at 4:05 PM, Roger P.[email protected]
wrote:

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
Tutorial::Arrays::Chapter_2

problem.
integration with existing tools takes out the need for another tool?
of the things it has are things that could belong in a Ruby
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]

20

There is somewhat of a wiki:
Ruby Programming - Wikibooks, open books for an open world [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