Merge pull request open-source-parsers#282 from keithkml/patch-1

Clarify which parts of README for users vs devs

Author: cdunn2001

README.md

@@ -19,12 +19,14 @@ format to store user input files.
 * `0.y.z` can be used with older compilers.
 * Major versions maintain binary-compatibility.
 
-Using JsonCpp in your project
+# Using JsonCpp in your project
 -----------------------------
-The recommended approach to integrating JsonCpp in your project is to build
-the amalgamated source (a single `.cpp` file) with your own build system. This
-ensures consistency of compilation flags and ABI compatibility. See the section
-"Generating amalgamated source and header" for instructions.
+The recommended approach to integrating JsonCpp in your project is to include
+the [amalgamated source](#generating-amalgamated-source-and-header) (a single 
+`.cpp` file and two `.h` files) in your project, and compile and build as you 
+would any other source file. This ensures consistency of compilation flags and
+ABI compatibility, issues which arise when building shared or static 
+libraries. See the next section for instructions.
 
 The `include/` should be added to your compiler include path. Jsoncpp headers
 should be included as follow:
@@ -34,6 +36,31 @@ should be included as follow:
 If JsonCpp was built as a dynamic library on Windows, then your project needs to
 define the macro `JSON_DLL`.
 
+Generating amalgamated source and header
+----------------------------------------
+JsonCpp is provided with a script to generate a single header and a single
+source file to ease inclusion into an existing project. The amalgamated source
+can be generated at any time by running the following command from the
+top-directory (this requires Python 2.6):
+
+    python amalgamate.py
+
+It is possible to specify header name. See the `-h` option for detail.
+
+By default, the following files are generated:
+* `dist/jsoncpp.cpp`: source file that needs to be added to your project.
+* `dist/json/json.h`: corresponding header file for use in your project. It is
+  equivalent to including `json/json.h` in non-amalgamated source. This header
+  only depends on standard headers.
+* `dist/json/json-forwards.h`: header that provides forward declaration of all
+  JsonCpp types.
+
+The amalgamated sources are generated by concatenating JsonCpp source in the
+correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion
+of other headers.
+
+# Contributing to JsonCpp
+
 Building and testing with CMake
 -------------------------------
 [CMake][] is a C++ Makefiles/Solution generator. It is usually available on most
@@ -106,7 +133,7 @@ If you are building with Microsoft Visual Studio 2008, you need to set up the
 environment by running `vcvars32.bat` (e.g. MSVC 2008 command prompt) before
 running SCons.
 
-# Running the tests manually
+## Running the tests manually
 You need to run tests manually only if you are troubleshooting an issue.
 
 In the instructions below, replace `path/to/jsontest` with the path of the
@@ -142,29 +169,6 @@ Run the Python script `doxybuild.py` from the top directory:
 
 See `doxybuild.py --help` for options.
 
-Generating amalgamated source and header
-----------------------------------------
-JsonCpp is provided with a script to generate a single header and a single
-source file to ease inclusion into an existing project. The amalgamated source
-can be generated at any time by running the following command from the
-top-directory (this requires Python 2.6):
-
-    python amalgamate.py
-
-It is possible to specify header name. See the `-h` option for detail.
-
-By default, the following files are generated:
-* `dist/jsoncpp.cpp`: source file that needs to be added to your project.
-* `dist/json/json.h`: corresponding header file for use in your project. It is
-  equivalent to including `json/json.h` in non-amalgamated source. This header
-  only depends on standard headers.
-* `dist/json/json-forwards.h`: header that provides forward declaration of all
-  JsonCpp types.
-
-The amalgamated sources are generated by concatenating JsonCpp source in the
-correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion
-of other headers.
-
 Adding a reader/writer test
 ---------------------------
 To add a test, you need to create two files in test/data: