improving the Manual

It seems like a fine introduction to the problem to me. I might quibble with the emphasis a bit (a lot of times, troublesome Python routines can be improved simply by writing the Python code better), but it gets the point across. Thanks!