clarified pickle version requirements (fixes #186)

Author: wjakob

docs/advanced.rst

@@ -1340,13 +1340,15 @@ An instance can now be pickled as follows:
 
     p = Pickleable("test_value")
     p.setExtra(15)
-    data = pickle.dumps(p, -1)
-
-Note that only the cPickle module is supported on Python 2.7. It is also
-important to request usage of the highest protocol version using the ``-1``
-argument to ``dumps``. Failure to follow these two steps will lead to important
-pybind11 memory allocation routines to be skipped during unpickling, which will
-likely cause memory corruption and/or segmentation faults.
+    data = pickle.dumps(p, 2)
+
+Note that only the cPickle module is supported on Python 2.7. The second
+argument to ``dumps`` is also crucial: it selects the pickle protocol version
+2, since the older version 1 is not supported. Newer versions are also fine—for
+instance, specify ``-1`` to always use the latest available version. Beware:
+failure to follow these instructions will cause important pybind11 memory
+allocation routines to be skipped during unpickling, which will likely lead to
+memory corruption and/or segmentation faults.
 
 .. seealso::
 

example/example15.py

@@ -14,7 +14,7 @@
 p.setExtra1(15)
 p.setExtra2(48)
 
-data = pickle.dumps(p, -1)  # -1 is important (use highest protocol version)
+data = pickle.dumps(p, 2)  # Must use pickle protocol >= 2
 print("%s %i %i" % (p.value(), p.extra1(), p.extra2()))
 
 p2 = pickle.loads(data)