readme update#4
major readme update plus a few minor changes
doc fixes