--- CBOR-XS/XS.pm	2013/11/17 05:26:14	1.18
+++ CBOR-XS/XS.pm	2013/11/20 02:03:08	1.20
@@ -159,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
@@ -554,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,