more doc editing
improved error reporting