Format markdown docs, refactor examples, fix typos

[mwtoews]

This PR refactors a few of the examples and other parts of the markdown files.

Also fix a bunch of typos (found using codespell).

The minor fix to the Makefile replaces spaces with a tab.