Better README

README

@@ -1,3 +1,16 @@
-The GAP 4 package `json'
-==============================
+The GAP 4 package 'json'
+========================
 
+This package defines a mapping between the JSON markup language and GAP.
+The built-in datatypes of GAP provide an easy mapping to and from JSON.
+This package uses the following mapping between GAP and JSON.
+
+* JSON lists are mapped to GAP lists
+* JSON dictionaries are mapped to GAP records
+* JSON strings are mapped to GAP strings
+* Integers are mapped to GAP integers, non-integer numbers are mapped to Floats
+* true, false and null are mapped to true, false and fail respectively
+
+Note that this library will not map any other GAP types, such as groups,
+permutatations, to or from JSON. If you wish to map between more complex
+types, look at the openmath package, or IO_Pickle in the IO package.