to my eternal shame (considering how proud I am of my documentation)
this was not mentioned anywhere! I'm getting old...
thanks to Pierre Habouzit for catching this
(also slipped in a few other minor doc changes. I wouldn't mix
unrelated stuff in a commit when doing code changes but it seems ok to
do this for docfixes, for some reason).