--- JSON-XS/XS.pm	2007/12/30 21:24:57	1.82
+++ JSON-XS/XS.pm	2008/01/20 19:19:07	1.83
@@ -776,16 +776,18 @@
 
 =item blessed objects
 
-Blessed objects are not allowed. JSON::XS currently tries to encode their
-underlying representation (hash- or arrayref), but this behaviour might
-change in future versions.
+Blessed objects are not directly representable in JSON. See the
+C<allow_blessed> and C<convert_blessed> methods on various options on
+how to deal with this: basically, you can choose between throwing an
+exception, encoding the reference as if it weren't blessed, or provide
+your own serialiser method.
 
 =item simple scalars
 
 Simple Perl scalars (any scalar that is not a reference) are the most
 difficult objects to encode: JSON::XS will encode undefined scalars as
-JSON null value, scalars that have last been used in a string context
-before encoding as JSON strings and anything else as number value:
+JSON C<null> values, scalars that have last been used in a string context
+before encoding as JSON strings, and anything else as number value:
 
    # dump as number
    encode_json [2]                      # yields [2]
@@ -813,7 +815,8 @@
    $x *= 1;     # same thing, the choice is yours.
 
 You can not currently force the type in other, less obscure, ways. Tell me
-if you need this capability.
+if you need this capability (but don't forget to explain why its needed
+:).
 
 =back
 
@@ -918,7 +921,7 @@
    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
+This will I<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 and also has different and incompatible
 unicode handling, so you should make sure that your hash keys are
@@ -927,11 +930,12 @@
 multilingual page). YAML also does not allow C<\/> sequences in strings
 (which JSON::XS does not I<currently> generate).
 
-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 when you least
-expect it.
+There might be other incompatibilities that I am not aware of (or the YAML
+specification has been changed yet again - it does so quite often). 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 when you
+least expect it.
 
 =over 4
 
@@ -945,14 +949,14 @@
 from "your documentation contains inaccurate and negative statements about
 YAML" (the only negative comment is this footnote, and it didn't exist
 back then; the question on which claims were inaccurate was never answered
-etc.) to "the YAML spec is not up-to-date" (the *real* and suppsedly
+etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly
 JSON-compatible spec is apparently not currently publicly available)
 to actual requests to replace this section by *incorrect* information,
 suppressing information about the real problem).
 
 So whenever you are told that YAML was a superset of JSON, first check
-wether it is really true (it might be when you check it, but it cetrainly
-is not true when this was written). I would much prefer if the YAML team
+wether it is really true (it might be when you check it, but it certainly
+was not true when this was written). I would much prefer if the YAML team
 would spent their time on actually making JSON compatibility a truth
 (JSON, after all, has a very small and simple specification) instead of
 trying to lobby/force people into reporting untruths.