more improvements to documentation and man pages