various fixes and improvements to the documentation