general documentation review/cleanup

The main documentation has been reviewed and
all the examples checked.  Many minor wording
changes and typos were fixed.