[Grok-dev] "Transient Objects" tutorial

[Brandon Craig Rhodes]

I have submitted my first tutorial for consideration for the web site!
Thanks for everyone who helped me learn enough to write it. :-) Its
name is "transient-objects.txt" and it lives in the "minitutorials"
directory alongside the other submissions.  Some notes:

 - It uses many Unicode characters, and will probably cause your
   grok2html to explode, so I have not presumed to add it to the
   official "doc/grok2html.py" until we figure out how to make Unicode
   possible in our documentation.

 - I can't wait until the fix for the Zope bug I filed makes it into a
   production version (thanks to PvW for shepherding the issue!)
   because that will make the tutorial much simpler - whole sections
   of explanation and code near the bottom can disappear!  The issue
   about which I speak is:

     https://bugs.launchpad.net/zope3/+bug/139044

   On what kind of schedule do these sorts of fixes turn up in the
   code which the average tutorial reader gets when they run
   "grokproject"?

 - The tutorial needs to link to a generic how-to-run-grokproject-and-
   set-up-an-app page.

 - The tutorial seems to do far too many things for a single tutorial.
   Do you remember those folks a few weeks ago who were suggesting
   that our site should have "recipes" instead of just "tutorials"?
   And do you remember me disagreeing with them?  Well, I am
   reconsidering!  I feel that this tutorial should really a small
   "Guide to Transient Objects" that links to four different
   "Recipes", one for each of the four basic methods.  It makes the
   document so long to have all of the examples in-line!

 - I feel sorry for the people who actually try out the code in this
   tutorial rather than just reading it.  Think of all the cutting and
   pasting, and creating and deleting files, and then getting down
   near the bottom of the tutorial and finding something is broken
   because they missed an insertion or deletion they were supposed to
   do!  And then they might have to start the whole tutorial again
   from the top to figure out what their example app should look like
   by the time they're done.

   So I wish that ReST gave me some way of marking a series of quoted
   Python code so that the user could click on a little icon and get a
   .tar.gz of that particular example, ready to run inside of a Grok
   instance.  If this tutorial were broken into four shorter and more
   reasonable "recipes", then maybe each could have a single button to
   download the whole example app?

 - It would be neat if they could skip having to "create the app"
   through the Grok interface.  Everyone who I show Grok too finds
   that terribly weird anyway.

 - It would be neat if there were also a way to mark up the tutorial
   so that a sort of "tutorial doctest" could be run that created the
   app the way the tutorial describes, and sees if it really runs and
   returns the output the tutorial claims.

 - I was not sure, when writing, when to say "Grok" and when to say
   "Zope".  There are several possible schemes we could adopt; I am
   sure that I have not been consistent with any of them. :-)

-- 
Brandon Craig Rhodes   brandon at rhodesmill.org   http://rhodesmill.org/brandon