--- Types-Serialiser/README	2013/10/27 20:17:16	1.2
+++ Types-Serialiser/README	2013/10/28 15:29:28	1.3
@@ -78,6 +78,62 @@
     While it is possible to use an isa test, directly comparing stash
     pointers is faster and guaranteed to work.
 
+    For historical reasons, the "Types::Serialiser::Boolean" stash is just
+    an alias for "JSON::PP::Boolean". When printed, the classname withh
+    usually be "JSON::PP::Boolean", but isa tests and stash pointer
+    comparison will normally work correctly (i.e. Types::Serialiser::true
+    ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
+
+A GENERIC OBJECT SERIALIATION PROTOCOL
+    This section explains the object serialisation protocol used by
+    CBOR::XS. It is meant to be generic enough to support any kind of
+    generic object serialiser.
+
+    This protocol is called "the Types::Serialiser object serialisation
+    protocol".
+
+  ENCODING
+    When the encoder encounters an object that it cannot otherwise encode
+    (for example, CBOR::XS can encode a few special types itself, and will
+    first attempt to use the special "TO_CBOR" serialisation protocol), it
+    will look up the "FREEZE" method on the object.
+
+    If it exists, it will call it with two arguments: the object to
+    serialise, and a constant string that indicates the name of the
+    serialisationformat. For example CBOR::XS uses "CBOR", and JSON and
+    JSON::XS (or any other JSON serialiser), would use "JSON" as second
+    argument.
+
+    The "FREEZE" method can then return zero or more values to identify the
+    object instance. The serialiser is then supposed to encode the class
+    name and all of these return values (which must be encodable in the
+    format) using the relevant form for perl objects. In CBOR for example,
+    there is a registered tag number for encoded perl objects.
+
+  DECODING
+    When the decoder then encounters such an encoded perl object, it should
+    look up the "THAW" method on the stored classname, and invoke it with
+    the classname, the constant string to identify the format, and all the
+    return values returned by "FREEZE".
+
+  EXAMPLES
+    See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
+    details, an example implementation, and code examples.
+
+    Here is an example "FREEZE"/"THAW" method pair:
+
+       sub My::Object::FREEZE {
+          my ($self, $serialiser) = @_;
+
+          ($self->{type}, $self->{id}, $self->{variant})
+       }
+
+       sub My::Object::THAW {
+          my ($class, $serialiser, $type, $id, $variant) = @_;
+
+          $class-<new (type => $type, id => $id, variant => $variant)
+       }
+
 BUGS
     The use of overload makes this module much heavier than it should be (on
     my system, this module: 4kB RSS, overload: 260kB RSS).