Update the README to better explain this, and make a few other tweaks.

Signed-off-by: Jakov Smolic <jakov.smolic@sartura.hr>

Example:
mkdir build && cd build
cmake -DOVERRIDE_GET_RANDOM_SEED='do { extern uint32_t getMsTicks(void); int ms = getMsTicks() * 433494437; return ms; } while(0)' ..

json-c has symbol collisions with other popular C JSON libraries.
To prevent random crashes in downstream applications that may use a
library which depends on json-c, the solution is to statically link
libjson-c.a into those libraries.

`-fPIC`/`-fPIE` is required when building a `.a` so it can be linked
into a `.so`.

This patch provides a CMakeLists.txt file to build JSON-C library without relying on auto-tools support. This makes the build a bit more portable and cleaner.

It can detect headers and symbols and generate config.h header file based on those detections. It cannot yet handle ctest(1) as the testing itself depends on comparing the output against files. Testing would need some creative abuse of CMake :) This will be provided a few patches later and may possibly involve refactoring test cases.

The patch has been tested on GCC 4.8.5 (Linux), GCC 7.2.0 (MinGW) and Microsoft Visual C++ 16.0 (2010?) locally. Also, compiles correctly on Travis CI and AppVeyor without errors.

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