diff -r ef6113f3d38e -r 8f8a52cd0b9f docs/index.rst
--- a/docs/index.rst	Mon Mar 26 18:24:39 2012 +0200
+++ b/docs/index.rst	Tue Mar 27 16:50:14 2012 +0200
@@ -4,48 +4,48 @@
 
 
 Here are various Materials on planned improvement to mercurial regarding
-rewriting mutable history.
+rewriting history.
 
-The effort  split in two part:
+The effort  splits in two parts:
 
- * The **obsolete marker** concept aiming to provide and alternative to strip to
-   get ride of changesets.
+ * The **obsolete marker** concept aims to provide and alternative to ``strip``
+   to get ride of changesets.
 
- * A mercurial extension: **evolve** that rewrite using *obsolete marker*
+ * The **evolve** mercurial extension to rewrite history using *obsolete marker*
    under the hood.
 
 
-regarding mercurial internals, the first and most important step is the
-**obsolete marker**. However most user will never be directly exposed to the
-concept. For this reason document about changeset evolution are put first.
+The first and most important step is by far the **obsolete marker**. However
+most user will never be directly exposed to the concept. For this reason
+document about changeset evolution are put first.
 
 
 Evolve: A robust alternative to MQ
 ====================================
 
-Evolve is an experimental history rewriting extensions that use the obsolete
-marker. It is inspired from MQ and pbranch but have multiple advantage over
-them.
+Evolve is an experimental history rewriting extensions that use obsolete
+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)
 
-* Handle any kind history. Even history with branch and merge.
+* Handle **non-linear history with branches and merges**
 
-* Use robust mercurial's merge mechanism 
+* Use **robust merge** mechanism of mercurial.
 
   simple conflict are handled by real merge tools using appropriate ancestor.
   Conflict are much rarer and much more user friendly.
 
-* All mutable history available at the same time
+*  Mutable history **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. Evole create and exchange real changeset only. 
   Mutable history can be used in all usual operation 'pull, push, log, diff …)
 
-* Allow sharing and collaborating mutable history without fear of duplicate.
+* Allow **sharing and collaboration** mutable history without fear of duplicate.
   (thanks to obsolete marker).
 
 * Cover all mq usage but guard.
@@ -62,9 +62,19 @@
     $ 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)
+
+    $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/hgview/
+    $ cd hgview
+    $ python setup.py install --user
+
+
+ ---
+
+For more information see documents below
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    tutorial
    evolve-faq
@@ -73,14 +83,32 @@
 Smart changeset deletion: Obselete Marker
 ==========================================
 
-for dev and advanced user
+Obsolete marker is a powerful concept that allow mercurial to safely handle
+history rewriting operations. It is a new type of relation between Mercurial
+changesets that track the result of history rewriting operations.
+
+This concept is simple to define and provides a very solid base to:
+
+- Very fast history rewriting operations,
+
+- auditable and reversible history rewritting process,
 
+- clean final history,
+
+- share and collaborate on mutable part of the history,
+
+- gracefully handle history rewriting conflict,
+
+- allows various history rewriting UI to collaborate with a underlying common API.
+
+ ---
+
+For more information see documents below
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    obs-concept
-   glossary
    obs-implementation
 
 
@@ -91,4 +119,25 @@
 Know canveas
 =================================
 
-Big flashy warning on current remaining issue
+Here is a list of know issue that will be fixed later:
+
+* Unstable changeset turns secret.
+
+* ``hg stabilize`` does not handle conflict.
+
+* 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.
+
+* ``hg update`` can move an obsolete parent
+
+* you need to provideto graft --continue -O if you started you graft using -O.
+
+
+
+
+
+Anexe
+=================================
+
+.. toctree::
+   glossary