[mod_python] gaps in the documentation

Hi,

I am trying to get PSP to work as a templating mechanism. I have had
problems getting it to do what I want, and this is mainly due to poor
documentation. While the concept is very nice (the alternative would be to
use PHP), it seriously needs to be better documented. This also applies to
other parts of mod_python:

1) The session management part needs to be fleshed out. Especially the
lock/unlock thing: when do I need it (it says, most often I do not, but I
have to be able to answer that myself), how do I use it and so on.
load/save should be explained in more detail (why is there a load()
function, anyway?)

2) PSP is (excuse my french) a pain in the ass at the moment. Why does it
have to rebind session and form without checking if they are already
bound, e.g. by the Publisher handler function? This totally screwed my
session handling and it really took some detective work to find out why.
And bigger still as the question of 'why does it behave like that' is the
question of 'why is it not documented'. Same applies to content type
handling, though I already posted a patch sugestion to mod-python-dev for
that one.

3) I brought up a while ago that PSP writing directly to the req object
when __str()__ is invoked (i.e., when you use PSP as a templating
mechanism like I do) is _very_ irritating. While I do not agree with the
reasons, I can live with it, however. What I cannot live with is that this
behaviour is (again) not documented at all.

In most of the cases I am only feeling my way here without complete
understanding, so I do not think I am suited for completing the
documentation. But someone really, really should get at it.

Regards,
Robert