- Documentation generation is no longer handled by SCons. The script …

…doxybuild.py is used to generate the documentation on demand.

- Added file 'version' that contains jsoncpp version number. It is used by both SConstruct and doxybuild.py.
- Updated README.txt with documentation build instruction, and instructions to add a test case.

README.txt

@@ -1,18 +1,21 @@
 * Introduction:
+  =============
 
 JSON (JavaScript Object Notation) is a lightweight data-interchange format. 
 It can represent integer, real number, string, an ordered sequence of 
 value, and a collection of name/value pairs.
 
-JsonCpp is a simple API to manipulate JSON value, and handle serialization 
+JsonCpp is a simple API to manipulate JSON value, handle serialization 
 and unserialization to string.
 
 It can also preserve existing comment in unserialization/serialization steps,
 making it a convenient format to store user input files.
 
 Unserialization parsing is user friendly and provides precise error reports.
 
+
 * Building/Testing:
+  =================
 
 JsonCpp uses Scons (http://www.scons.org) as a build system. Scons requires
 python to be installed (http://www.python.org).
@@ -39,15 +42,76 @@ to do so.
 
 and TARGET may be:
 	check: build library and run unit tests.
-	doc: build documentation
-	doc-dist: build documentation tarball
 
-To run the test manually:
+
+* Running the test manually:
+  ==========================
+
 cd test
 # This will run the Reader/Writer tests
 python runjsontests.py "path to jsontest.exe"
+
+# This will run the Reader/Writer tests, using JSONChecker test suite
+# (http://www.json.org/JSON_checker/).
+# Notes: not all tests pass: JsonCpp is too lenient (for example,
+# it allows an integer to start with '0'). The goal is to improve
+# strict mode parsing to get all tests to pass.
+python runjsontests.py --with-json-checker "path to jsontest.exe"
+
 # This will run the unit tests (mostly Value)
 python rununittests.py "path to test_lib_json.exe"
 
-You can run the tests using valgrind using:
+You can run the tests using valgrind:
 python rununittests.py --valgrind "path to test_lib_json.exe"
+
+
+* Building the documentation:
+  ===========================
+
+Run the python script doxybuild.py from the top directory:
+
+python doxybuild.py --open --with-dot
+
+See doxybuild.py --help for options. 
+
+
+* Adding a reader/writer test:
+  ============================
+
+To add a test, you need to create two files in test/data:
+- a TESTNAME.json file, that contains the input document in JSON format.
+- a TESTNAME.expected file, that contains a flatened representation of 
+  the input document.
+
+TESTNAME.expected file format:
+- each line represents a JSON element of the element tree represented 
+  by the input document.
+- each line has two parts: the path to access the element separated from
+  the element value by '='. Array and object values are always empty 
+  (e.g. represented by either [] or {}).
+- element path: '.' represented the root element, and is used to separate 
+  object members. [N] is used to specify the value of an array element
+  at index N.
+See test_complex_01.json and test_complex_01.expected to better understand
+element path.
+
+
+* Understanding reader/writer test output:
+  ========================================
+
+When a test is run, output files are generated aside the input test files. 
+Below is a short description of the content of each file:
+
+- test_complex_01.json: input JSON document
+- test_complex_01.expected: flattened JSON element tree used to check if 
+    parsing was corrected.
+
+- test_complex_01.actual: flattened JSON element tree produced by 
+    jsontest.exe from reading test_complex_01.json
+- test_complex_01.rewrite: JSON document written by jsontest.exe using the
+    Json::Value parsed from test_complex_01.json and serialized using
+    Json::StyledWritter.
+- test_complex_01.actual-rewrite: flattened JSON element tree produced by 
+    jsontest.exe from reading test_complex_01.rewrite.
+test_complex_01.process-output: jsontest.exe output, typically useful to
+    understand parsing error.

SConstruct

@@ -1,79 +1,17 @@
 """
-Build system can be clean-up by sticking to a few core production factory, with automatic dependencies resolution.
-4 basic project productions:
-- library
-- binary
-- documentation
-- tests
+Notes: 
+- shared library support is buggy: it assumes that a static and dynamic library can be build from the same object files. This is not true on many platforms. For this reason it is only enabled on linux-gcc at the current time.
 
-* Library:
-  Input:
-    - dependencies (other libraries)
-    - headers: include path & files
-    - sources
-    - generated sources
-    - resources
-    - generated resources
-  Production:
-    - Static library
-    - Dynamic library
-    - Naming rule
-  Life-cycle:
-    - Library compilation
-    - Compilation as a dependencies
-    - Run-time
-    - Packaging
-  Identity:
-    - Name
-    - Version
-* Binary:
-  Input:
-    - dependencies (other libraries)
-    - headers: include path & files (usually empty)
-    - sources
-    - generated sources
-    - resources
-    - generated resources
-    - supported variant (optimized/debug, dll/static...)
-  Production:
-    - Binary executable
-    - Manifest [on some platforms]
-    - Debug symbol [on some platforms]
-  Life-cycle:
-    - Compilation
-    - Run-time
-    - Packaging
-  Identity:
-    - Name
-    - Version
-* Documentation:
-  Input:
-    - dependencies (libraries, binaries)
-    - additional sources
-    - generated sources
-    - resources
-    - generated resources
-    - supported variant (public/internal)
-  Production:
-    - HTML documentation
-    - PDF documentation
-    - CHM documentation
-  Life-cycle:
-    - Documentation
-    - Packaging
-    - Test
-  Identity:
-    - Name
-    - Version
+To add a platform:
+- add its name in options allowed_values below
+- add tool initialization for this platform. Search for "if platform == 'suncc'" as an example.
 """
 
-
-
 import os
 import os.path
 import sys
 
-JSONCPP_VERSION = '0.2'
+JSONCPP_VERSION = open(File('#version').abspath,'rt').read().strip()
 DIST_DIR = '#dist'
 
 options = Variables()
@@ -174,8 +112,6 @@ else:
     print "UNSUPPORTED PLATFORM."
     env.Exit(1)
 
-env.Tool('doxygen')
-env.Tool('substinfile')
 env.Tool('targz')
 env.Tool('srcdist')
 env.Tool('globtool')
@@ -295,6 +231,5 @@ env.Alias( 'src-dist', srcdist_cmd )
 buildProjectInDirectory( 'src/jsontestrunner' )
 buildProjectInDirectory( 'src/lib_json' )
 buildProjectInDirectory( 'src/test_lib_json' )
-buildProjectInDirectory( 'doc' )
 #print env.Dump()