--- JSON-XS/XS.pm	2013/10/29 15:55:49	1.151
+++ JSON-XS/XS.pm	2013/10/30 22:11:01	1.152
@@ -1563,6 +1563,67 @@
 such as L<JSON::PP> and L<CBOR::XS>.
 
 
+=head1 INTEROPERABILITY WITH OTHER JSON DECODERS
+
+As long as you only serialise data that can be directly expressed in JSON,
+C<JSON::XS> is incapable of generating invalid JSON output (modulo bugs,
+but C<JSON::XS> has found more bugs in the official JSON testsuite (1)
+than the official JSON testsuite has found in C<JSON::XS> (0)).
+
+When you have trouble decoding JSON generated by this module using other
+decoders, then it is very likely that you have an encoding mismatch or the
+other decoder is broken.
+
+When decoding, C<JSON::XS> is strict by default and will likely catch all
+errors. There are currently two settings that change this: C<relaxed>
+makes C<JSON::XS> accept (but not generate) some non-standard extensions,
+and C<allow_tags> will allow you to encode and decode Perl objects, at the
+cost of not outputting valid JSON anymore.
+
+=head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
+
+When you use C<allow_tags> to use the extended (and also nonstandard and
+invalid) JSON syntax for serialised objects, and you still want to decode
+the generated When you want to serialise objects, you can run a regex
+to replace the tagged syntax by standard JSON arrays (it only works for
+"normal" packagesnames without comma, newlines or single colons). First,
+the readable Perl version:
+
+   # if your FREEZE methods return no values, you need this replace first:
+   $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
+
+   # this works for non-empty constructor arg lists:
+   $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
+
+And here is a less readable version that is easy to adapt to other
+languages:
+
+   $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
+
+Here is an ECMAScript version (same regex):
+
+   json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
+
+Since this syntax converts to standard JSON arrays, it might be hard to
+distinguish serialised objects from normal arrays. You can prepend a
+"magic number" as first array element to reduce chances of a collision:
+
+   $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
+
+And after decoding the JSON text, you could walk the data
+structure looking for arrays with a first element of
+C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
+
+The same approach cna be used to create the tagged format with another
+encoder. First, you create an array with the magic string as first member,
+the classname as second, and constructor arguments last, encode it as part
+of your JSON structure, and then:
+
+   $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
+
+Again, this has some limitations - the magic string must not be encoded
+with character escapes, and the constructor arguments must be non-empty.
+
 =head1 THREADS
 
 This module is I<not> guaranteed to be thread safe and there are no