anchor.diff:      on the reflection system to extrapolate serialization rules for
       each type (resulting in runtime errors if this is not possible).
   
  -  * There is confusion as to which is the prefered design pattern for serialization.
  +  * There is confusion as to which is the prefered methodology for when
  +    defining serialization semantics for new types.
       The BCL comes with a multitude of dated, unsafe, mutually exclusive
  -    and naturally inefficient patterns.
  +    and naturally inefficient approaches.
   
  -### BCL Serialization patterns
  +### BCL Serialization methods
   
   The BCL comes with the following patterns for defining serializable types:
   
     * Field-based serialization: objects are pickled by serializing the contents 
       of their fields. This behaviour is tuned by applying an assortment of attributes
  -    such as `Serialized`, `NonSerialized`, `OnSerializing`, `OnDeserialized`, etc and
  -    implementing the `IDeserializationCallback` interface. This is arguably the most
  -    loathed serialization pattern, since it is extremely sensitive to internal implementation details.
  -    Incidentally, this is the pattern of choice for most F# generated types.
  +    such as `Serialized`, `NonSerialized`, `OnSerializing`, `OnDeserialized` and
  +    the `IDeserializationCallback` interface. This is arguably the most
  +    problematic approach, since it is sensitive to internal implementation details.
  +    Incidentally, this is the pattern of choice for most F# types.
   
     * Property-based or [DataContract](http://msdn.microsoft.com/en-us/library/ms733127.aspx) 
       serialization: objects are pickled by serializing the contents
       of specially flagged properties. Properties should be settable and are usually required to be
       public. In most cases, a parameterless constructor is also necessary. Property-based serialization
  -    is probably the most popular pattern.
  +    is probably the most popular approach.
   
     * [ISerializable](http://msdn.microsoft.com/en-us/library/system.runtime.serialization.iserializable.aspx) 
       types: possibly intended as a type-safe replacement of field-based serialization.
       It fails to live up to this role, mostly due to the nature of interfaces; it still requires a
       special constructor for deserialization which, if missing, would result in a runtime error.
  -    It is a particularly verbose pattern, resulting in a lot of boilerplate code.
  +    It requires separate implementations for serialization and deserialization, often leading to bugs
  +    and introducing lots of boilerplate code.
       Its dynamic nature also makes it impossible to reason about the components it serializes a priori.
  -    It is however an indispensible pattern, since it is used by many BCL types, most important being
  -    exception types, whose metadata is impossible to replicate without `ISerializable`.
  +    It is however an indispensible pattern since it is used by many BCL types, most important being
  +    exceptions, whose metadata is impossible to serialize otherwise.
   
   ### Serialization Libraries
   
  -The BCL ships with a couple of general-purpose serializer libraries but these either suffer
  +The BCL ships with a couple of general-purpose serializer libraries but these suffer either
   from obsolescence (e.g. [BinaryFormatter](http://msdn.microsoft.com/en-us/library/system.runtime.serialization.formatters.binary.binaryformatter.aspx)) 
  -or are painfully slow ([NetDataContractSerializer](http://msdn.microsoft.com/en-us/library/system.runtime.serialization.netdatacontractserializer.aspx)).
  +or performance ([NetDataContractSerializer](http://msdn.microsoft.com/en-us/library/system.runtime.serialization.netdatacontractserializer.aspx)).
   
   Many third-party libraries have emerged attempting to address the issue of performance, some with success.
   However, experience shows that such libraries hardly achieve the level of generalization
  
positive.code: In that sense, it was designed with a goal to embrace the imperfect world that is
  the .NET framework in its totality, albeit with an eye for correctness.
  
  At this point, I should acknowledge Anton Tayanovskyy and his great little F#
  snippet [Union-Friendly Generic Binary Serializer](http://www.fssnip.net/6u)
  which served as the initial inspiration for this library.
  
  ## Picklers and Pickler Combinators
  
  FsPickler is founded on the functional programming notion of picklers and
  pickler combinators. A *pickler* is essentially the type:
  
  *)
  
  
negative.code:     }
  
  (***hide***)
  // mask the dummy pickler implementation
  open Nessos.FsPickler
  
  (**
  
  Given a sufficient range of primitive picklers and pickler combinators,
  it is possible to define pickling rules for most essentially serializable .NET types. 
  However, these would still need to be declared manually by their implementor.
  
  FsPickler attempts to solve this by providing an automated pickler generation framework: 
  picklers are generated at runtime and on demand using a combination of reflection and 
  dynamic IL generation. Picklers are cached for future use, hence the cost of generation 
  has a constant price.
  
  Moreover, it extends the concept of picklers so that features particular to the
  .NET framework are accommodated: object orientation and subtype polymorphism, 
  null references and cyclic objects.
  
  It should be mentioned for the sake of completeness that a 
  [similar effort](http://lampwww.epfl.ch/~hmiller/files/pickling.pdf) 
  has been undertaken by the Scala community. There are differences of approach however, 
  since this mostly relies on the metaprogramming facility offered by scala.
  
  ## Serializable Types
  
  So what qualifies as a serializable type in FsPickler?
  The short answer would be any type `'T` for which we present an instance of `Pickler<'T>`.
  To make the question more meaningful: for what types does the library auto-generate picklers? 
  This is something that can only be answered at runtime, typically by calling
  
  *)
  
  FsPickler.IsSerializableType<SomeType> ()
  
  (**
  
  Primitive types and `string` are serializable but pointers, COM objects and MarshalByRef types are not.
  A managed class or struct is serializable if and only if it carries the `Serializable` attribute
  and moreover satisfies either of the following:
  
    * is abstract or a delegate.
  