--- JSON-XS/README	2007/03/25 22:11:06	1.8
+++ JSON-XS/README	2007/04/04 00:01:44	1.10
@@ -247,7 +247,12 @@
         many short strings. It will also try to downgrade any strings to
         octet-form if possible: perl stores strings internally either in an
         encoding called UTF-X or in octet-form. The latter cannot store
-        everything but uses less space in general.
+        everything but uses less space in general (and some buggy Perl or C
+        code might even rely on that internal representation being used).
+
+        The actual definition of what shrink does might change in future
+        versions, but it will always try to save space at the expense of
+        time.
 
         If $enable is true (or missing), the string returned by "encode"
         will be shrunk-to-fit, while all strings generated by "decode" will
@@ -262,10 +267,10 @@
         saving space.
 
     $json = $json->max_depth ([$maximum_nesting_depth])
-        Sets the maximum nesting level (default 8192) accepted while
-        encoding or decoding. If the JSON text or Perl data structure has an
-        equal or higher nesting level then this limit, then the encoder and
-        decoder will stop and croak at that point.
+        Sets the maximum nesting level (default 512) accepted while encoding
+        or decoding. If the JSON text or Perl data structure has an equal or
+        higher nesting level then this limit, then the encoder and decoder
+        will stop and croak at that point.
 
         Nesting level is defined by number of hash- or arrayrefs that the
         encoder needs to traverse to reach a given point or the number of
@@ -346,17 +351,28 @@
 
     hash references
         Perl hash references become JSON objects. As there is no inherent
-        ordering in hash keys, they will usually be encoded in a
-        pseudo-random order that can change between runs of the same program
-        but stays generally the same within a single run of a program.
-        JSON::XS can optionally sort the hash keys (determined by the
-        *canonical* flag), so the same datastructure will serialise to the
-        same JSON text (given same settings and version of JSON::XS), but
-        this incurs a runtime overhead.
+        ordering in hash keys (or JSON objects), they will usually be
+        encoded in a pseudo-random order that can change between runs of the
+        same program but stays generally the same within a single run of a
+        program. JSON::XS can optionally sort the hash keys (determined by
+        the *canonical* flag), so the same datastructure will serialise to
+        the same JSON text (given same settings and version of JSON::XS),
+        but this incurs a runtime overhead and is only rarely useful, e.g.
+        when you want to compare some JSON text against another for
+        equality.
 
     array references
         Perl array references become JSON arrays.
 
+    other references
+        Other unblessed references are generally not allowed and will cause
+        an exception to be thrown, except for references to the integers 0
+        and 1, which get turned into "false" and "true" atoms in JSON. You
+        can also use "JSON::XS::false" and "JSON::XS::true" to improve
+        readability.
+
+           to_json [\0,JSON::XS::true]      # yields [false,true]
+
     blessed objects
         Blessed objects are not allowed. JSON::XS currently tries to encode
         their underlying representation (hash- or arrayref), but this
@@ -397,9 +413,6 @@
         You can not currently output JSON booleans or force the type in
         other, less obscure, ways. Tell me if you need this capability.
 
-    circular data structures
-        Those will be encoded until memory or stackspace runs out.
-
 COMPARISON
     As already mentioned, this module was created because none of the
     existing JSON modules could be made to work correctly. First I will
@@ -547,8 +560,9 @@
     Third, JSON::XS recurses using the C stack when decoding objects and
     arrays. The C stack is a limited resource: for instance, on my amd64
     machine with 8MB of stack size I can decode around 180k nested arrays
-    but only 14k nested JSON objects. If that is exceeded, the program
-    crashes. Thats why the default nesting limit is set to 8192. If your
+    but only 14k nested JSON objects (due to perl itself recursing deeply on
+    croak to free the temporary). If that is exceeded, the program crashes.
+    to be conservative, the default nesting limit is set to 512. If your
     process has a smaller stack, you should adjust this setting accordingly
     with the "max_depth" method.