--- JSON-XS/README	2007/04/04 00:01:44	1.10
+++ JSON-XS/README	2007/05/09 16:35:21	1.11
@@ -114,15 +114,47 @@
         generate characters outside the code range 0..127 (which is ASCII).
         Any unicode characters outside that range will be escaped using
         either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL
-        escape sequence, as per RFC4627.
+        escape sequence, as per RFC4627. The resulting encoded JSON text can
+        be treated as a native unicode string, an ascii-encoded,
+        latin1-encoded or UTF-8 encoded string, or any other superset of
+        ASCII.
 
         If $enable is false, then the "encode" method will not escape
-        Unicode characters unless required by the JSON syntax. This results
-        in a faster and more compact format.
+        Unicode characters unless required by the JSON syntax or other
+        flags. This results in a faster and more compact format.
+
+        The main use for this flag is to produce JSON texts that can be
+        transmitted over a 7-bit channel, as the encoded JSON texts will not
+        contain any 8 bit characters.
 
           JSON::XS->new->ascii (1)->encode ([chr 0x10401])
           => ["\ud801\udc01"]
 
+    $json = $json->latin1 ([$enable])
+        If $enable is true (or missing), then the "encode" method will
+        encode the resulting JSON text as latin1 (or iso-8859-1), escaping
+        any characters outside the code range 0..255. The resulting string
+        can be treated as a latin1-encoded JSON text or a native unicode
+        string. The "decode" method will not be affected in any way by this
+        flag, as "decode" by default expects unicode, which is a strict
+        superset of latin1.
+
+        If $enable is false, then the "encode" method will not escape
+        Unicode characters unless required by the JSON syntax or other
+        flags.
+
+        The main use for this flag is efficiently encoding binary data as
+        JSON text, as most octets will not be escaped, resulting in a
+        smaller encoded size. The disadvantage is that the resulting JSON
+        text is encoded in latin1 (and must correctly be treated as such
+        when storing and transfering), a rare encoding for JSON. It is
+        therefore most useful when you want to store data structures known
+        to contain binary data efficiently in files or databases, not when
+        talking to other JSON encoders/decoders.
+
+          JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
+          => ["\x{89}\\u0abc"]    # (perl syntax, U+abc escaped, U+89 not)
+
     $json = $json->utf8 ([$enable])
         If $enable is true (or missing), then the "encode" method will
         encode the JSON result into UTF-8, as required by many protocols,
@@ -303,6 +335,19 @@
         become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
         becomes 1, "false" becomes 0 and "null" becomes "undef".
 
+    ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
+        This works like the "decode" method, but instead of raising an
+        exception when there is trailing garbage after the first JSON
+        object, it will silently stop parsing there and return the number of
+        characters consumed so far.
+
+        This is useful if your JSON texts are not delimited by an outer
+        protocol (which is not the brightest thing to do in the first place)
+        and you need to know where the JSON text ends.
+
+           JSON::XS->new->decode_prefix ("[1] the tail")
+           => ([], 3)
+
 MAPPING
     This section describes how JSON::XS maps Perl values to JSON values and
     vice versa. These mappings are designed to "do the right thing" in most
@@ -567,7 +612,7 @@
     with the "max_depth" method.
 
     And last but least, something else could bomb you that I forgot to think
-    of. In that case, you get to keep the pieces. I am alway sopen for
+    of. In that case, you get to keep the pieces. I am always open for
     hints, though...
 
 BUGS