Major rewrite of the README

Also some changes to soothe the Scrutinizer.
may be a few other instances also. See above.