--- JSON-XS/XS.pm	2007/12/19 11:42:52	1.79
+++ JSON-XS/XS.pm	2007/12/29 17:22:39	1.80
@@ -907,9 +907,10 @@
 
 =head2 JSON and YAML
 
-You often hear that JSON is a subset (or a close subset) of YAML. This is,
-however, a mass hysteria and very far from the truth. In general, there is
-no way to configure JSON::XS to output a data structure as valid YAML.
+You often hear that JSON is a subset of YAML. This is, however, a mass
+hysteria and very far from the truth. In general, there is no way to
+configure JSON::XS to output a data structure as valid YAML that works for
+all cases.
 
 If you really must use JSON::XS to generate YAML, you should use this
 algorithm (subject to change in future versions):
@@ -919,13 +920,17 @@
 
 This will usually generate JSON texts that also parse as valid
 YAML. Please note that YAML has hardcoded limits on (simple) object key
-lengths that JSON doesn't have, so you should make sure that your hash
-keys are noticeably shorter than the 1024 characters YAML allows.
+lengths that JSON doesn't have and also has different and incompatible
+unicode handling, so you should make sure that your hash keys are
+noticeably shorter than the 1024 "stream characters" YAML allows and that
+you do not have codepoints with values outside the Unicode BMP (basic
+multilingual page).
 
 There might be other incompatibilities that I am not aware of. In general
 you should not try to generate YAML with a JSON generator or vice versa,
 or try to parse JSON with a YAML parser or vice versa: chances are high
-that you will run into severe interoperability problems.
+that you will run into severe interoperability problems when you least
+expect it.
 
 
 =head2 SPEED