[Urwid] docgen_tutorial.py that also creates scripts

[Derek Peschel]

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.

> > Why is the example in section 3.1 so short?  It looks like an editing
> > mistake to me.
> 
> WRT main loops in 5 and 3.1, maybe some kind of standard main loop 
> should be introduced earlier and used through the rest of the examples.. 
> I'm not sure. It's hard to write these things, and I probably know too 
> much about Urwid to do a good job of it!  :-)

The section 3.1 example, as given in the HTML, is missing more than
a main loop.  It isn't even close to being a runnable program.

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

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?

> The files could be numbered the same way that the numbers are generated 
> for the table of contents.

The one logistical problem, I believe, is that by the time the section
numbers are generated, the code blocks have already been edited into their
HTML form.  A careful redesign of the docgen program -- that separated
the script form from the HTML form -- would easily solve that problem, though.

Some sections have more than one example.  When creating the files by hand,
I've created file names like
  example1.1.py		only example in that section
  example5.2.py		first example in that section
  example5.2a.py	second example in that section
Is it still important to accommodate DOS users and their short filenames?

-- Derek