--- JSON-XS/README	2008/03/27 06:37:35	1.24
+++ JSON-XS/README	2008/04/16 18:38:38	1.25
@@ -400,6 +400,21 @@
            JSON::XS->new->allow_nonref->encode ("Hello, World!")
            => "Hello, World!"
 
+    $json = $json->allow_unknown ([$enable])
+    $enabled = $json->get_allow_unknown
+        If $enable is true (or missing), then "encode" will *not* throw an
+        exception when it encounters values it cannot represent in JSON (for
+        example, filehandles) but instead will encode a JSON "null" value.
+        Note that blessed objects are not included here and are handled
+        separately by c<allow_nonref>.
+
+        If $enable is false (the default), then "encode" will throw an
+        exception when it encounters anything it cannot encode as JSON.
+
+        This option does not affect "decode" in any way, and it is
+        recommended to leave it off unless you know your communications
+        partner.
+
     $json = $json->allow_blessed ([$enable])
     $enabled = $json->get_allow_blessed
         If $enable is true (or missing), then the "encode" method will not
@@ -543,9 +558,9 @@
     $json = $json->max_depth ([$maximum_nesting_depth])
     $max_depth = $json->get_max_depth
         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.
+        or decoding. If a higher nesting level is detected in JSON text or a
+        Perl data structure, 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
@@ -555,9 +570,12 @@
         Setting the maximum depth to one disallows any nesting, so that
         ensures that the object is only a single hash/object or array.
 
-        The argument to "max_depth" will be rounded up to the next highest
-        power of two. If no argument is given, the highest possible setting
-        will be used, which is rarely useful.
+        If no argument is given, the highest possible setting will be used,
+        which is rarely useful.
+
+        Note that nesting is implemented by recursion in C. The default
+        value has been chosen to be as large as typical operating systems
+        allow without crashing.
 
         See SECURITY CONSIDERATIONS, below, for more info on why this is
         useful.
@@ -566,14 +584,12 @@
     $max_size = $json->get_max_size
         Set the maximum length a JSON text may have (in bytes) where
         decoding is being attempted. The default is 0, meaning no limit.
-        When "decode" is called on a string longer then this number of
-        characters it will not attempt to decode the string but throw an
+        When "decode" is called on a string that is longer then this many
+        bytes, it will not attempt to decode the string but throw an
         exception. This setting has no effect on "encode" (yet).
 
-        The argument to "max_size" will be rounded up to the next highest
-        power of two (so may be more than requested). If no argument is
-        given, the limit check will be deactivated (same as when 0 is
-        specified).
+        If no argument is given, the limit check will be deactivated (same
+        as when 0 is specified).
 
         See SECURITY CONSIDERATIONS, below, for more info on why this is
         useful.
@@ -1099,8 +1115,9 @@
     single-line JSON string (also available at
     <http://dist.schmorp.de/misc/json/short.json>).
 
-       {"method": "handleMessage", "params": ["user1", "we were just talking"], \
-       "id": null, "array":[1,11,234,-5,1e5,1e7, true,  false]}
+       {"method": "handleMessage", "params": ["user1",
+       "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
+       true,  false]}
 
     It shows the number of encodes/decodes per second (JSON::XS uses the
     functional interface, while JSON::XS/2 uses the OO interface with