The section about Tcl in ADP's and HTML in Tcl code; how about some examples or alternatives here? How should people achieve this? Probably need something about when and why to register ADP tags, for example instead of calling a proc in an ADP; and when to use registered tags or included templates, instead of embedding HTML in Tcl.
The thing about return_url comes under the more general heading of naming. For instance should it be mentioned that boolean variables have a _p affix?
When deleting queries from Tcl files perhaps we could replace the query with the literal string *SQL* rather than "" or {}. If you make a mistake and the correct query can not be found from the .xql file, the blank error message can be a little confusing, but with *SQL* it's more obvious what has happened.
Why must plpgsql function parameters be prefixed with p_? I don't remember seeing this used already in the toolkit, and we don't prefix Tcl parameter names with p_. Variable names are prefixed with v_ because you can't assign a new value to a function parameter (right?) and so must use a new but simillarly named variable.
I know this is just a draft, but ultimately there probably needs to be a complete document describing how to create upgrade scripts, with a simple link to it explaining that it must be followed. I think Jon Griffin's your man here...
