--- JSON-XS/README	2011/07/27 15:53:40	1.36
+++ JSON-XS/README	2013/05/23 09:32:02	1.37
@@ -371,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
@@ -1322,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