Various modifications, in response to my own criticism

Following Pete's suggestion, I worked hard to meet my own criticism.
One open question is in bold (about the API, p. 5).