--- CBOR-XS/XS.pm	2013/10/29 22:04:52	1.16
+++ CBOR-XS/XS.pm	2013/11/20 01:09:46	1.19
@@ -68,7 +68,7 @@
 
 use common::sense;
 
-our $VERSION = 0.07;
+our $VERSION = 0.08;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_cbor decode_cbor);
@@ -159,6 +159,53 @@
 
 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_sharable ([$enable])
+
+=item $enabled = $cbor->get_allow_sharable
+
+If C<$enable> is true (or missing), then C<encode> will not double-encode
+values that have been seen 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, all shared values will be detected, even weird and unusual
+cases, such as an array with multiple "copies" of the I<same> scalar,
+which are hard but not impossible to create in Perl (L<Storable> for
+example doesn't handle these cases). If this turns out ot be a performance
+issue then future versions might limit the shared value detection to
+references only.
+
+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
@@ -457,10 +504,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.
 
@@ -554,6 +601,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,