Few tweaks to readme

Took the challenge and this is the result of the first step of generating readme (and more verbose docs) from single specification.

Table of contents is auto-generated and the input file looks like: https://gist.github.com/phadej/8173545, next step would be to introduce more primitives to this documentation DSL.