--- JSON-XS/XS.pm	2007/06/06 18:16:52	1.38
+++ JSON-XS/XS.pm	2007/06/11 02:58:10	1.39
@@ -404,6 +404,7 @@
 lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
 refers to the abstract Perl language itself.
 
+
 =head2 JSON -> PERL
 
 =over 4
@@ -444,6 +445,7 @@
 
 =back
 
+
 =head2 PERL -> JSON
 
 The mapping from Perl to JSON is slightly more difficult, as Perl is a
@@ -607,6 +609,29 @@
 
 =back
 
+
+=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.
+
+If you really must use JSON::XS to generate YAML, you should this
+algorithm (subject to change in future versions):
+
+   my $to_yaml = JSON::XS->new->utf8->space_after (1);
+   my $yaml = $to_yaml->encode ($ref) . "\n";
+
+This will usually generate JSON texts that also parse as valid
+YAML. Please note that YAML has hardcoded limits on object key lengths
+that JSON doesn't have, so you should make sure that your hash keys are
+noticably shorter than 1024 characters.
+
+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.
+
+
 =head2 SPEED
 
 It seems that JSON::XS is surprisingly fast, as shown in the following
@@ -620,9 +645,10 @@
    {"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
-pretty-printing and hashkey sorting enabled). Higher is better:
+It shows the number of encodes/decodes per second (JSON::XS uses
+the functional interface, while JSON::XS/2 uses the OO interface
+with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
+shrink). Higher is better:
 
    module     |     encode |     decode |
    -----------|------------|------------|