what used to be small documentation changes

The first 6 commits are small documentation and naming changes, which I originally wanted to submit as a pull request.

Apparently I don't understand github pull requests, though, since now quite a bit of refactoring slipped in. I think those are good, but they change the interface a bit. Let me know if I should bring this into some other shape.

I haven't tested the larger changes well since my diagrams code currently doesn't want to compile against diagrams from git.