add changes that were made in #319

For some reason, the spec changes and readme changes introduced in #319 were deleted in my pull request #316. Adding them back...