readme in markdown format plus various changes to details