[Urwid] docgen_tutorial.py that also creates scripts

[Ian Ward]

Derek Peschel wrote:
> Take the example in section 1.1.  It defines a function and then calls it.
> So you can look at the order in which functions are defined, or the order
> in which they are executed.  The two are different.  I was too cryptic when
> I described that difference as "the idea of function definition".  (Yes,
> there's more to the idea than the difference, but let's not get into that.)
> 
> ui.run_wrapper calls the argument function (plus doing extra work before
> and after), but the novice may not know that the argument is called.
Yes, a comment there would be good in example 1.1. It is a tutorial and 
we can't expect that the user has read the reference beforehand.

> And finally, classes (with their own __init__ methods and main functions)
> create more differences between source-code order and execution order.
> Even with my years of programming experience it can be interesting to
> mentally trace some of the more complex programs, as I was trying to do
> while changing editor.py.  Perhaps tracing control flow is a waste of time
> and I should be learning UML?
UML's nice, but personally I've never been able to come up with the 
Right design for a program on a white board.. (but maybe that's just me)

> The question I was really thinking of but didn't ask is "Would urwid and a
> fleshed-out tutorial make a good way to introduce people to programming?"
> And I don't know the answer.  But part of fleshing out the tutorial might
> be to create a really short program before the current section 1.1, to
> help illustrate the concepts I just mentioned.  A full presentation of all
> the concepts would take several sections, though.
UI libraries are complex beasts (even little text-only ones like Urwid) 
I wouldn't want to be responsible for driving people away from Python if 
I can help it :-)

> I've been hacking away at docgen_tutorial.py.  Here is the latest version.
> It puts the section numbers in the filenames.  I made lots of other small
> changes, in an attempt to make the code maintainable and find my Python
> style "voice".  Getting a file full of small details right is _hard_
> (and I have even changed my own ideas along the way) so I'd welcome your
> reaction and criticism.

It's looking much improved.  I appreciate patches that include lots of 
good comments.  I'll try it out soon.

Ian