Feedback for the Quixote Cookbook 0.1 at groups.yahoo.com, group "quixote-discuss", Files section.
This is a good structural overview of Quixote, complete with diagrams of how the parts interact. It's good that it focuses on structure rather than examples because there are other example-based tutorials ($QUIXOTE/doc/demo.txt, Titus's tutorial at http://darcs.idyll.org/~t/projects/quixote2-tutorial/). The document has no contact info for the author. An e-mail address would be nice. Some of my comments depend on the intended audience. There are two distinct newbie audiences: those coming from Quixote 1.3 or a transitional version, and those who are starting with 2.0. The latter critically need a tutorial; the former have already diminshed and will soon vanish. I would cut out all transitional information, move it to an appendix, or refer the user to $QUIXOTE/doc/upgrading.txt. Section 3.1 (page 4) says "write a program (CGI script)..." [to launch the publisher]. This is confusing because the CGI server is not how Quixote is usually deployed. I'd suggest writing this paragraph generically, referring to the simple server if any. Section 3.2 (page 5) says you don't need '' in _q_exports for _q_index, but you do. This was changed for Quixote 2. Section 3.3 (page 6) says "if no session manager is specified then a null session manager that effectively does nothing is used". But in fact, you do get memory-based sessions by default. These are incompatible with CGI, another reason not to recommend CGI at the outset. Section 4.2 (page 11) discusses the evolution of form and form1. This is rather verbose and not appropriate for the new generation of newbies. I would just say "form1 is for backward compatibility" and leave it at that. Section 4.2 (page 12) has a Form constructor with this argument: attrs=None actually it's: **attrs The "attr" explanation needs to be revised. Suggestion: "attrs: are keyword arguments which are converted to additional HTML attributes in the <form> tag. The paragraph then highlights the 'class' attribute. But you can't have a keyword argument 'class'; that's a syntax error. That's a bug in Form.__init__: it assumes you can specify 'class' but you can't, and there's no other way to set the CSS class. (Of course you can set form.attrs['class'] later, but that's too advanced for a tutorial.) Chapter 5 (pp. 15-16) on PTL is correct in a basic sense but glosses over some details. Simplification is good, but you don't want to plant false assumptions that will confuse the user later when they learn the contradictory details. (1) You don't have to use the import hook if you precompile the templates. (2) The recommended way to install the hooks has changed. (3) PTL only vaguely "applies str()" to bare expressions; this characterization may confuse the user when they learn more details. Better to add, "it actually does more than this, but we'll get to that later". (4) Escapable values aren't just those that come as function arguments, but also global variables, return values, etc -- anything that's not a literal. -- -- Mike Orr <[EMAIL PROTECTED]>To all:
To help Chris Hobbs out in finding a home for his Cookbook I have registered a Quixote Discussion Group at Yahoo Groups, since they allow uploading of files by members and downloading of files by the public.
My intention is not to challenge the quixote-users group in anyway, but just to allow the extra features that yahoo provides (file, rss, etc).
Thanks,
Anthony
_______________________________________________ Quixote-users mailing list [email protected] http://mail.mems-exchange.org/mailman/listinfo/quixote-users
