--- CBOR-XS/XS.pm	2013/10/30 10:11:04	1.17
+++ CBOR-XS/XS.pm	2013/11/20 16:29:02	1.21
@@ -28,12 +28,12 @@
 
 =head1 DESCRIPTION
 
-WARNING! This module is very new, and not very well tested (that's up to
-you to do). Furthermore, details of the implementation might change freely
-before version 1.0. And lastly, the object serialisation protocol depends
-on a pending IANA assignment, and until that assignment is official, this
-implementation is not interoperable with other implementations (even
-future versions of this module) until the assignment is done.
+WARNING! This module is very new, and not very well tested (that's up
+to you to do). Furthermore, details of the implementation might change
+freely before version 1.0. And lastly, most extensions depend on an IANA
+assignment, and until that assignment is official, this implementation is
+not interoperable with other implementations (even future versions of this
+module) until the assignment is done.
 
 You are still invited to try out CBOR, and this module.
 
@@ -56,6 +56,11 @@
 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>.
 
+In addition to the core CBOR data format, this module implements a number
+of extensions, to support cyclic and self-referencing data structures
+(see C<allow_sharing>), string deduplication (see C<allow_stringref>) and
+scalar references (always enabled).
+
 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.
 
@@ -159,6 +164,74 @@
 
 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.
+
+It is recommended to leave it off unless you know your
+communication partner supports the value sharing extensions to CBOR
+(http://cbor.schmorp.de/value-sharing).
+
+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.
+
+=item $cbor = $cbor->allow_stringref ([$enable])
+
+=item $enabled = $cbor->get_allow_stringref
+
+If C<$enable> is true (or missing), then C<encode> will try not to encode
+the same string twice, but will instead encode a reference to the string
+instead. Depending on your data format. this can save a lot of space, but
+also results in a very large runtime overhead (expect encoding times to be
+2-4 times as high as without).
+
+It is recommended to leave it off unless you know your
+communications partner supports the stringref extension to CBOR
+(http://cbor.schmorp.de/stringref).
+
+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 - string references will
+always be decoded properly if present.
+
 =item $cbor_data = $cbor->encode ($perl_scalar)
 
 Converts the given Perl data structure (a scalar value) to its CBOR
@@ -457,10 +530,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 +627,49 @@
       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 <unassigned>, <unassigned> (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
+
+These tags are automatically decoded when encountered. They are only
+encoded, however, when C<allow_stringref> 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,