--- CBOR-XS/XS.pm	2013/10/29 15:13:50	1.12
+++ CBOR-XS/XS.pm	2013/11/20 02:03:08	1.20
@@ -48,6 +48,14 @@
 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 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.
 
@@ -60,7 +68,7 @@
 
 use common::sense;
 
-our $VERSION = 0.05;
+our $VERSION = 0.08;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_cbor decode_cbor);
@@ -151,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
@@ -285,8 +339,9 @@
 =item CBOR::XS::Tagged objects
 
 Objects of this type must be arrays consisting of a single C<[tag, value]>
-pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
-encoded as appropriate for the value.
+pair. The (numerical) tag will be encoded as a CBOR tag, the value will
+be encoded as appropriate for the value. You cna use C<CBOR::XS::tag> to
+create such objects.
 
 =item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
 
@@ -448,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.
 
@@ -518,6 +573,71 @@
    $_[0][1]
 }
 
+=head2 EXAMPLES
+
+Here are some examples of C<CBOR::XS::Tagged> uses to tag objects.
+
+You can look up CBOR tag value and emanings in the IANA registry at
+L<http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>.
+
+Prepend a magic header (C<$CBOR::XS::MAGIC>):
+
+   my $cbor = encode_cbor CBOR::XS::tag 55799, $value;
+   # same as:
+   my $cbor = $CBOR::XS::MAGIC . encode_cbor $value;
+
+Serialise some URIs and a regex in an array:
+
+   my $cbor = encode_cbor [
+      (CBOR::XS::tag 32, "http://www.nethype.de/"),
+      (CBOR::XS::tag 32, "http://software.schmorp.de/"),
+      (CBOR::XS::tag 35, "^[Pp][Ee][Rr][lL]\$"),
+   ];
+
+Wrap CBOR data in CBOR:
+
+   my $cbor_cbor = encode_cbor
+      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,