--- JSON-XS/README	2010/03/11 17:36:09	1.34
+++ JSON-XS/README	2013/05/23 09:32:02	1.37
@@ -58,10 +58,11 @@
     *   round-trip integrity
 
         When you serialise a perl data structure using only data types
-        supported by JSON, the deserialised data structure is identical on
-        the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"
-        just because it looks like a number). There minor *are* exceptions
-        to this, read the MAPPING section below to learn about those.
+        supported by JSON and Perl, the deserialised data structure is
+        identical on the Perl level. (e.g. the string "2.0" doesn't suddenly
+        become "2" just because it looks like a number). There *are* minor
+        exceptions to this, read the MAPPING section below to learn about
+        those.
 
     *   strict checking of JSON correctness
 
@@ -370,7 +371,8 @@
 
         If $enable is false, then the "encode" method will output key-value
         pairs in the order Perl stores them (which will likely change
-        between runs of the same script).
+        between runs of the same script, and can change even within the same
+        run from 5.18 onwards).
 
         This option is useful if you want the same data structure to be
         encoded as the same JSON text (given the same overall settings). If
@@ -637,7 +639,7 @@
     JSON::XS will only attempt to parse the JSON text once it is sure it has
     enough text to get a decisive result, using a very simple but truly
     incremental parser. This means that it sometimes won't stop as early as
-    the full parser, for example, it doesn't detect parenthese mismatches.
+    the full parser, for example, it doesn't detect mismatched parentheses.
     The only thing it guarantees is that it starts decoding as soon as a
     syntactically valid JSON text has been seen. This means you need to set
     resource limits (e.g. "max_size") to ensure the parser will stop parsing
@@ -672,6 +674,11 @@
         the scalar context case. Note that in this case, any
         previously-parsed JSON texts will be lost.
 
+        Example: Parse some JSON arrays/objects in a given string and return
+        them.
+
+           my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
+
     $lvalue_string = $json->incr_text
         This method returns the currently stored JSON fragment as an lvalue,
         that is, you can manipulate it. This *only* works when a preceding
@@ -896,6 +903,11 @@
         ability, but the JSON number will still be re-encoded as a JSON
         number).
 
+        Note that precision is not accuracy - binary floating point values
+        cannot represent most decimal fractions exactly, and when converting
+        from and to floating point, JSON::XS only guarantees precision up to
+        but not including the leats significant bit.
+
     true, false
         These JSON atoms become "JSON::XS::true" and "JSON::XS::false",
         respectively. They are overloaded to act almost exactly like the
@@ -981,6 +993,13 @@
         Tell me if you need this capability (but don't forget to explain why
         it's needed :).
 
+        Note that numerical precision has the same meaning as under Perl (so
+        binary to decimal conversion follows the same rules as in Perl,
+        which can differ to other languages). Also, your perl interpreter
+        might expose extensions to the floating point numbers of your
+        platform, such as infinities or NaN's - these cannot be represented
+        in JSON, and it is an error to pass those in.
+
 ENCODING/CODESET FLAG NOTES
     The interested reader might have seen a number of flags that signify
     encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
@@ -1127,7 +1146,7 @@
     Another problem is that some javascript implementations reserve some
     property names for their own purposes (which probably makes them
     non-ECMAscript-compliant). For example, Iceweasel reserves the
-    "__proto__" property name for it's own purposes.
+    "__proto__" property name for its own purposes.
 
     If that is a problem, you could parse try to filter the resulting JSON
     output for these property strings, e.g.:
@@ -1185,11 +1204,12 @@
         spreading lies about the real compatibility for many *years* and
         trying to silence people who point out that it isn't true.
 
-        Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON,
+        Addendum/2009: the YAML 1.2 spec is still incompatible with JSON,
         even though the incompatibilities have been documented (and are
         known to Brian) for many years and the spec makes explicit claims
         that YAML is a superset of JSON. It would be so easy to fix, but
-        apparently, bullying and corrupting userdata is so much easier.
+        apparently, bullying people and corrupting userdata is so much
+        easier.
 
   SPEED
     It seems that JSON::XS is surprisingly fast, as shown in the following
@@ -1303,6 +1323,22 @@
 
     (It might actually work, but you have been warned).
 
+THE PERILS OF SETLOCALE
+    Sometimes people avoid the Perl locale support and directly call the
+    system's setlocale function with "LC_ALL".
+
+    This breaks both perl and modules such as JSON::XS, as stringification
+    of numbers no longer works correcly (e.g. "$x = 0.1; print "$x"+1" might
+    print 1, and JSON::XS might output illegal JSON as JSON::XS relies on
+    perl to stringify numbers).
+
+    The solution is simple: don't call "setlocale", or use it for only those
+    categories you need, such as "LC_MESSAGES" or "LC_CTYPE".
+
+    If you need "LC_NUMERIC", you should enable it only around the code that
+    actually needs it (avoiding stringification of numbers), and restore it
+    afterwards.
+
 BUGS
     While the goal of this module is to be correct, that unfortunately does
     not mean it's bug-free, only that I think its design is bug-free. If you