Previously a special tag was added to README.md to make this the
main page in Doxygen generated docs. When viewing the README on the
GitHub page this tag was not hidden.

After upgrading to Doxygen 1.8.8 (and above) in changeset
219025727d a new Doxygen feature can be
used to specify the main page: Since release 1.8.3 Doxygen has a special
option to set a markdown file as main page. When using this option we
can drop the tag, making the README rendered by GitHub nice to look at.

Fixes: ae66b24369

Also, add a table of contents, and a brief section on using json-c with links to
the header files most likely to be useful.

Looks nice to see a `Build Passing` tag when you
scroll to the README.

Signed-off-by: Alexandru Ardelean <ardeleanalex@gmail.com>

Cause README.md to show up in Doxygen output as the main page.

svn.metaparadigm.com no longer exists so it is not possible to use source from there.

- code blocks
 - slight text changes (rewording)
 - pretty printing

Markdownify + fix a few errors here and there