Make the API documentation into more of a proper specification.

specification.markdown describes fairly precisely and in reasonable
detail what all the parsers and combinators should do. It describes
error messages, thus fixing #4.