clean up doc formatting and comments

just a bunch of formatting, wording and comment cleanups, mostly to the
README file
Merge pull request #1 from sventech/master

clean up doc formatting and comments