Organize documentation in README

This PR completely reorganizes the README file which had grown a bit out of control. There is now a TOC for easy navigation and similar topics have been grouped together. Additionally, all code examples were revised for accuracy and consistency.

@dcneiner: any comments on the changes? If not, I'll merge in Monday.