[Urwid] docgen_tutorial.py that also creates scripts

[Ian Ward]

Derek Peschel wrote:
> On Mon, Jul 24, 2006 at 11:39:23PM -0400, Ian Ward wrote:
>> That's a very good idea.  One comment: the creation of the files and 
>> generation of documentation should be  command line options if the 
>> script is going to have two purposes.
> 
> I was hinting (by posting the patch) that you should generate the examples
> and then distribute them.  But you're right, the two jobs should be
> separated.

Yes, it would be good to generate the examples along with the docs. It's 
on my list.

> The step-by-step design of the tutorial nicely matches my level of
> experience with Python and urwid (I can't speak for anyone else).
> BTW, would it be useful to put a dummy program before the current section
> 1.1, just to introduce the ideas of function definition and main-code
> executable statements and ui.run_wrapper?  

I'm not sure what you mean here. Would you elaborate?

> If you trace the flow of
> control through even a simple script, like the one in section 1.1, you
> end up with something surprisingly complicated.  I can see novices having
> trouble.  Would it also be useful to highlight the differences between
> each example and the next?

That is a good idea.  I'll have to think about a good way to do that.

> The only problem with the step-by-step idea is that the most bulletproof
> main loop is also the most complicated.  It has to handle mouse events,
> curses vs. Web displays, and other things.  Has it even been written? --
> can you point to any of the demo programs as having _the_ best possible
> main loop?  And how does a tutorial writer encourage people to write high-
> quality programs, without swamping them with details in the early chapters
> so they give up reading?

All very good questions.  I tried to write the new example program 
"graph.py" in a very sound-software-engineering kind of way.  It needs 
some better comments, but in that case I had a complicated enough 
program to merit adding sound-software-engineering (read: complexity) to 
the main loop.

> Is it still important to accommodate DOS users and their short filenames?

What's a DOS user? ;-)

Ian