diff -r 0892b91947ef -r abe52cf492ee docs/index.rst
--- a/docs/index.rst	Wed May 09 12:43:45 2012 +0200
+++ b/docs/index.rst	Wed May 09 13:08:46 2012 +0200
@@ -6,7 +6,14 @@
 Here are various Materials on planned improvement to mercurial regarding
 rewriting history.
 
-The effort  splits in two parts:
+First read about what challenge arise while rewriting history and how we plan to solve them once and for all.
+
+.. toctree::
+   :maxdepth: 2
+
+   unstability
+
+The effort is splits in two parts:
 
  * The **obsolete marker** concept aims to provide and alternative to ``strip``
    to get ride of changesets.
@@ -27,22 +34,26 @@
 markers. It is inspired from MQ and pbranch but have multiple advantage over
 them:
 
-* sticks to "Work where you are" philosophy (I'll need better wording
-  for that)
+* Focus on your current work.
+
+    You can focus your work on a single changeset and take care of adapting
+    descendent changeset later.
 
 * Handle **non-linear history with branches and merges**
 
-* Use **robust merge** mechanism of mercurial.
+* Rely internally on **robust merge** mechanism of mercurial.
 
-  simple conflict are handled by real merge tools using appropriate ancestor.
+  Simple conflict are handled by real merge tools using appropriate ancestor.
   Conflict are much rarer and much more user friendly.
 
-*  Mutable history **fully available all the time**.
+*  Mutable history are **fully available all the time**.
 
   You are do not need to unapply and apply patche to access various part of you
   history.
 
-* Use **plain changeset** only. Evole create and exchange real changeset only. 
+* Use **plain changeset** only.
+
+  Evolve create and exchange real changeset only, not patches.
   Mutable history can be used in all usual operation 'pull, push, log, diff …)
 
 * Allow **sharing and collaboration** mutable history without fear of duplicate.
@@ -55,6 +66,8 @@
             implication of the **obsolete marker** concept. I do not recommend
             non power user to test this at this stage.
 
+            XXX make sure to read the XXX section before using it.
+
             Production ready version should hide such details to normal user.
 
 To enable the evolve extension use::
@@ -62,17 +75,18 @@
     $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/mutable-history/
     $ mutable-history/enable.sh >> ~/.hgrc
 
-You will probably want to use the associated version of hgview (QT viewer
-only). ::
+You will probably want to use the associated version of hgview (qt viewer
+recommended). ::
 
     $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/hgview/
     $ cd hgview
     $ python setup.py install --user
 
+works with mercurial 2.1 and 2.2 (recommended)
 
  ---
 
-For more information see documents below
+For more information see documents below:
 
 .. toctree::
    :maxdepth: 2
@@ -119,31 +133,45 @@
 
 
 
-Know canveas
+Known limitation and bug
 =================================
 
 Here is a list of know issue that will be fixed later:
 
-* Unstable changeset turns secret.
+
+
+* ``hg stabilize`` does not handle merge conflict.
 
-* ``hg stabilize`` does not handle conflict.
+    You must fallback to graft or rebase when that happen.
 
-* Mercurial think you are pushing additional heads even when the new head
-  obsolete another one. You have to use hg push -f more than necessary.
+* rewritinf conflict are not detected yet``hg stabilize`` does not handle them.
 
 * ``hg update`` can move an obsolete parent
 
-* you need to provideto graft --continue -O if you started you graft using -O.
-
-* hg graphlog show extinct changeset
-
-* hg heads show extinct changeset
+* you need to provide to `graft --continue -O` if you started you graft using `-O`.
 
 * hg merge considered extinct head as valid target. requiring you to manually
   specify target all the time.
 
 * obsolete relation exchange crash (as in traceback) on static http repo.
 
+* Extinct changeset are turned secret by various commands.
+
+* Extinct changesets are hidden using the *hidden* feature of mercurial only
+  supported by a few commands.
+
+  Only ``hg log``, ``hgview`` and `hg glog` (2.2 only) support it. ``hg head`` or other visual viewer don't.
+
+* hg heads show extinct changeset
+
+Fixed in 2.2
+---------------------------------
+
+* hg graphlog show extinct changeset
+
+* Mercurial 2.1 think you are pushing additional heads even when the new head
+  obsolete another one. You have to use hg push -f more than necessary.
+