extensive rewrite of documentation