Doc polish

* Little improvements on docs, from typos to minor style tweak
* Made docbook script work locally (in order to be able to check my changes)
* Made README.md render correctly on GH as well as made it more "man"-like