Robert Abitol There has been a lot of talk on this wiki about writing tutorials for beginners.
I am sure these could help certain people.
But not everyone. I for one am the type of person who can learn well through examples. For example, I find reading the law itself very boring but on the contrary I love to read legal cases. We always find surprising stuff, psychology, interpretations, logic, etc. And even humour at times!
I am not the only one. A lot of people are like me. There was a saying about learning through examples which I forgot: It said something like when I am told I understand; when I am given an example I understand better.
The same thing goes for programming.
With this in mind, I believe the best way to show by examples would be to write comments for each line of code for certain programs. Put yourself in the place of an absolute beginner who wants to learn Tcl and write comments accordingly.
These comments could be the best tutorial!
It's quite a challenge but it can be done.
For example, Richard Suchenwirth has written an excellent search and replace function. See Simple search and replace. If anyone would be interested in commenting every line of his code, a lot of beginners could learn a lot of stuff out of it very very quickly. And surely there is no better teacher than RS!
George Peter Staplin also writes excellent code; it is very concise, very organized.
So does Mike Griffiths (MG).
I am sure others write excellent stuff too.
I am sure we could learn a lot of stuff from their code if only it was commented in simple terms with the absolute beginner in mind.
LV The trickiest part of this sort of thing is to find a program which has been written using only things that you would want to teach a beginner. There are many things in Tcl which are likely not conducive to a beginner's view on things. Just because things can be done within Tcl, does not imply that those things should be done .
So, if you have a specific program whose content is appropriate for a beginner (whatever that term means to you), then mention it and perhaps people can try to figure out a way to go through and explain it.
aa I've found that while "commenting every line" can make excruciatingly clear just what a program is doing, it tends to be a poor way of documenting why a program does what it does. It's usually better to give a brief description before each functional block of code, making sure to call attention to any clever but nonobvious usage.
Appending comments to each "line" of Tcl code often cannot be done in the first place, as Tcl comments are permitted only when a command is expected by the parser.
LV: I took the request for line by line commenting not as to literally sprinkle code with line by line # comment lines, but to take a piece of code and to write up what each line is doing. However, like aa, I'd say what was probably really desired was a discussion of the why, since one can simply read the lines of code to see what each line of tcl is literally doing.
Robert Abitol Taking a chunk of code and explaining how this is done is also an excellent way to teach the language. As good as the line-by-line approach in certain cases.
In fact, what is hard in programming is learning the tricks to be used so that the computer does something. I remember seing in my translator a strange line of code. It was something like a=1. It was an indication to the computer to do such and such thing if it went beyond a certain spot; the spot being the line of code. Beyond that line, a was equal to 1; before that line it was equal to 0.
Well I believe those things could be learned through examples.
As for the best program to comment, I believe the one mentioned above RS's could be a good start. Remember however: you are talking to an absolute beginner.