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