--- CBOR-XS/XS.pm	2013/10/29 20:59:16	1.14
+++ CBOR-XS/XS.pm	2013/11/20 02:03:08	1.20
@@ -48,10 +48,13 @@
 often compresses better than CBOR though, so if you plan to compress the
 data later you might want to compare both formats first).
 
-To give you a general idea, with texts in the megabyte range, C<CBOR::XS>
-usually encodes roughly twice as fast as L<Storable> or L<JSON::XS> and
-decodes about 15%-30% faster than those. The shorter the data, the worse
-L<Storable> performs in comparison.
+To give you a general idea about speed, with texts in the megabyte range,
+C<CBOR::XS> usually encodes roughly twice as fast as L<Storable> or
+L<JSON::XS> and decodes about 15%-30% faster than those. The shorter the
+data, the worse L<Storable> performs in comparison.
+
+As for compactness, C<CBOR::XS> encoded data structures are usually about
+20% smaller than the same data encoded as (compact) JSON or L<Storable>.
 
 The primary goal of this module is to be I<correct> and the secondary goal
 is to be I<fast>. To reach the latter goal it was written in C.
@@ -65,7 +68,7 @@
 
 use common::sense;
 
-our $VERSION = 0.06;
+our $VERSION = 0.08;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_cbor decode_cbor);
@@ -156,6 +159,52 @@
 
 See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
 
+=item $cbor = $cbor->allow_unknown ([$enable])
+
+=item $enabled = $cbor->get_allow_unknown
+
+If C<$enable> is true (or missing), then C<encode> will I<not> throw an
+exception when it encounters values it cannot represent in CBOR (for
+example, filehandles) but instead will encode a CBOR C<error> value.
+
+If C<$enable> is false (the default), then C<encode> will throw an
+exception when it encounters anything it cannot encode as CBOR.
+
+This option does not affect C<decode> in any way, and it is recommended to
+leave it off unless you know your communications partner.
+
+=item $cbor = $cbor->allow_sharing ([$enable])
+
+=item $enabled = $cbor->get_allow_sharing
+
+If C<$enable> is true (or missing), then C<encode> will not double-encode
+values that have been referenced before (e.g. when the same object, such
+as an array, is referenced multiple times), but instead will emit a
+reference to the earlier value.
+
+This means that such values will only be encoded once, and will not result
+in a deep cloning of the value on decode, in decoders supporting the value
+sharing extension.
+
+Detecting shared values incurs a runtime overhead when values are encoded
+that have a reference counter large than one, and might unnecessarily
+increase the encoded size, as potentially shared values are encode as
+sharable whether or not they are actually shared.
+
+At the moment, only targets of references can be shared (e.g. scalars,
+arrays or hashes pointed to by a reference). Weirder constructs, such as
+an array with multiple "copies" of the I<same> string, which are hard but
+not impossible to create in Perl, are not supported (this is the same as
+for L<Storable>).
+
+If C<$enable> is false (the default), then C<encode> will encode
+exception when it encounters anything it cannot encode as CBOR.
+
+This option does not affect C<decode> in any way - shared values and
+references will always be decoded properly if present. It is recommended
+to leave it off unless you know your communications partner supports the
+value sharing extensions to CBOR (http://cbor.schmorp.de/value-sharing).
+
 =item $cbor_data = $cbor->encode ($perl_scalar)
 
 Converts the given Perl data structure (a scalar value) to its CBOR
@@ -454,10 +503,10 @@
 There is no way to distinguish CBOR from other formats
 programmatically. To make it easier to distinguish CBOR from other
 formats, the CBOR specification has a special "magic string" that can be
-prepended to any CBOR string without changing it's meaning.
+prepended to any CBOR string without changing its meaning.
 
 This string is available as C<$CBOR::XS::MAGIC>. This module does not
-prepend this string tot he CBOR data it generates, but it will ignroe it
+prepend this string to the CBOR data it generates, but it will ignore it
 if present, so users can prepend this string as a "file type" indicator as
 required.
 
@@ -551,6 +600,44 @@
       CBOR::XS::tag 24,
          encode_cbor [1, 2, 3];
 
+=head1 TAG HANDLING AND EXTENSIONS
+
+This section describes how this module handles specific tagged values and
+extensions. If a tag is not mentioned here, then the default handling
+applies (creating a CBOR::XS::Tagged object on decoding, and only encoding
+the tag when explicitly requested).
+
+Future versions of this module reserve the right to special case
+additional tags (such as bigfloat or base64url).
+
+=over 4
+
+=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>)
+
+These tags are automatically created for serialisable objects using the
+C<FREEZE/THAW> methods (the L<Types::Serialier> object serialisation
+protocol).
+
+=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
+
+These tags are automatically decoded when encountered, resulting in
+shared values in the decoded object. They are only encoded, however, when
+C<allow_sharable> is enabled.
+
+=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
+
+This tag is automatically generated when a reference are encountered (with
+the exception of hash and array refernces). It is converted to a reference
+when decoding.
+
+=item 55799 (self-describe CBOR, RFC 7049)
+
+This value is not generated on encoding (unless explicitly requested by
+the user), and is simply ignored when decoding.
+
+=back
+
+
 =head1 CBOR and JSON
 
 CBOR is supposed to implement a superset of the JSON data model, and is,