thebuzzmedia/universal-binary-json — pull request #1 by kxepal (2012-08-05 00:42:08+00:00)
Title: Draft 8 specification.

Add Draft-8 specification written by using sphinx-docs[1].

Why sphinx-docs?

Firstly, to track specification changes easily: now we could make references
in our issues to specific lines or sections.

Secondly, rst is human friendly format that easy to read and modify with very
base text editor, but it much more powerful than markdown.

Thirdly, it could be easily converted to any other format: html, pdf, man,
latex and more.

Similar solution was accepted by CouchDB team[2], so mostly this commit inspired
by their results and discussion.

Why not GitHub wiki?

It's awkward: it requires more clicks to access, more clicks to track changes,
it doesn't support pull requests and lives within separate repository.

How to work than?

master branch: Should contains latest develop specification version.
version branches (e.g. 0.8): Should contains release specification version. Only allowed changes there is typo/format fixes, notes, examples and things explanations, but **nothing** that changes any behavior. Hope that we would never develop on two or more versions at one time.

For each version we should provide test suite for positive and negative cases like JSON does[3].

If nobody stand against such solution, I'll merge this commit and open 0.8 branch to track Draft-8 changes.

P.S. You could browse result at ReadTheDoc[4] site.

[1] http://sphinx.pocoo.org/
[2] http://thread.gmane.org/gmane.comp.db.couchdb.devel/21796
[3] http://json.org/JSON_checker/
[4] http://universal-binary-json.readthedocs.org/en/latest/