copy changes and typo fixes for docs

I did a pass through the docs, running example commands and comparing command line args with help, then updating the corresponding files.

I found some of the targets referenced in the text had changed, so I updated the commands associated. Where the contents of the files had changed, I updated the text to reflect the new code.
Sync of https://github.com/pantsbuild/pants/commit/b8582d7c77f8f950fc603c388a2878593eee9d94