many enhancements in docs - fixes #38, fixes #51, fixes #52