changeset 17775:13744acc4ad7

obsolete: add example of marker usage in the documentation

Recent discussion with Augie Fackler pointed the lack of such example in the
documentation.

--- a/mercurial/obsolete.py	Mon Oct 15 00:12:06 2012 +0200
+++ b/mercurial/obsolete.py	Sun Oct 14 23:33:10 2012 +0200
@@ -20,6 +20,31 @@
 besides old and news changeset identifiers, such as creation date or
 author name.
 
+Examples:
+
+- When changeset A is replacement by a changeset A', one marker is stored:
+
+    (A, (A'))
+
+- When changesets A and B are folded into a new changeset C two markers are
+  stored:
+
+    (A, (C,)) and (B, (C,))
+
+- When changeset A is simply "pruned" from the graph, a marker in create:
+
+    (A, ())
+
+- When changeset A is split into B and C, a single marker are used:
+
+    (A, (C, C))
+
+  We use a single marker to distinct the "split" case from the "divergence"
+  case. If two independants operation rewrite the same changeset A in to A' and
+  A'' when have an error case: divergent rewriting. We can detect it because
+  two markers will be created independently:
+
+  (A, (B,)) and (A, (C,))
 
 Format
 ------