[PATCH 2 of 9 V2] obsolete: add example of marker usage in the documentation

[pierre-yves.david at logilab.fr]

# HG changeset patch
# User Pierre-Yves David <pierre-yves.david at ens-lyon.org>
# Date 1350250390 -7200
# Node ID 599401a6fe6f44d33656f4c69f98de2f5ecec70c
# Parent  d5311633f0fc23b2fa7a1d9189fe082cb1cf2df9
obsolete: add example of marker usage in the documentation

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

diff --git a/mercurial/obsolete.py b/mercurial/obsolete.py
--- a/mercurial/obsolete.py
+++ b/mercurial/obsolete.py
@@ -18,10 +18,35 @@ transformations performed by history rew
 building new tools to reconciliate conflicting rewriting actions. To
 facilitate conflicts resolution, markers include various annotations
 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
 ------
 
 Markers are stored in an append-only file stored in