diff -r abe52cf492ee -r 5a17c0d41a00 docs/index.rst
--- a/docs/index.rst	Wed May 09 13:08:46 2012 +0200
+++ b/docs/index.rst	Wed May 09 14:24:56 2012 +0200
@@ -6,7 +6,8 @@
 Here are various Materials on planned improvement to mercurial regarding
 rewriting history.
 
-First read about what challenge arise while rewriting history and how we plan to solve them once and for all.
+First read about what challenge arise while rewriting history and how we plan to
+solve them once and for all.
 
 .. toctree::
    :maxdepth: 2
@@ -16,22 +17,20 @@
 The effort is splits in two parts:
 
  * The **obsolete marker** concept aims to provide and alternative to ``strip``
-   to get ride of changesets.
+   to get rid of changesets.
 
  * The **evolve** mercurial extension to rewrite history using *obsolete marker*
    under the hood.
 
-
 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.
-
+most users will never be directly exposed to the concept. For this reason
+this manual starts with changeset evolution.
 
 Evolve: A robust alternative to MQ
 ====================================
 
-Evolve is an experimental history rewriting extensions that use obsolete
-markers. It is inspired from MQ and pbranch but have multiple advantage over
+Evolve is an experimental history rewriting extension that uses obsolete
+markers. It is inspired from MQ and pbranch but have multiple advantages over
 them:
 
 * Focus on your current work.
@@ -46,25 +45,25 @@
   Simple conflict are handled by real merge tools using appropriate ancestor.
   Conflict are much rarer and much more user friendly.
 
-*  Mutable history are **fully available all the 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.
+  always use 'hg update' and forget about (un)applying patches to access the
+  mutable part of your history.
+
 
-* Use **plain changeset** only.
+* Use only **plain changeset** and forget about patches. Evole will create and
+  exchange real changesets. Mutable history can be used in all usual operations:
+  pull, push, log, diff, etc.
 
-  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.
+* Allow **sharing and collaboration** mutable history without fear of duplicate
   (thanks to obsolete marker).
 
 * Cover all mq usage but guard.
 
 .. warning:: The evolve extention and the obsolete marker are at an experimental
-            stage. While using obsolet you'll likely be exposed to complexe
+            stage. While using obsolete you'll likely be exposed to complex
             implication of the **obsolete marker** concept. I do not recommend
-            non power user to test this at this stage.
+            non-power user to test this at this stage.
 
             XXX make sure to read the XXX section before using it.
 
@@ -108,15 +107,15 @@
 
 - Very fast history rewriting operations,
 
-- auditable and reversible history rewritting process,
+- auditable and reversible history rewriting process,
 
 - clean final history,
 
-- share and collaborate on mutable part of the history,
+- share and collaborate on mutable parts of the history,
 
-- gracefully handle history rewriting conflict,
+- gracefully handle history rewriting conflicts,
 
-- allows various history rewriting UI to collaborate with a underlying common API.
+- allow various history rewriting UI to collaborate with a underlying common API.
 
  ---
 
@@ -129,9 +128,14 @@
    obs-implementation
 
 
-
+Known caveats
+=============
 
+Here is a list of known issues that will be fixed later:
 
+* Unstable changeset turn secret.
+
+* ``hg stabilize`` does not handle conflicts.
 
 Known limitation and bug
 =================================
@@ -144,16 +148,16 @@
 
     You must fallback to graft or rebase when that happen.
 
-* rewritinf conflict are not detected yet``hg stabilize`` does not handle them.
+* rewriting conflict are not detected yet``hg stabilize`` does not handle them.
 
 * ``hg update`` can move an obsolete parent
 
 * 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.
+* ``hg merge`` considers an extinct head to be a valid target, hence requiring
+  you to manually specify target all the time.
 
-* obsolete relation exchange crash (as in traceback) on static http repo.
+* trying to exchange obsolete relations with a static http repo will crash.
 
 * Extinct changeset are turned secret by various commands.
 
@@ -170,14 +174,18 @@
 * 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.
-
+  obsolete another one. You have to use hg push -f more often than necessary.
 
 
+* ``hg heads`` shows extinct changeset
 
+* ``hg merge`` considers an extinct head to be a valid target, hence requiring
+  you to manually specify target all the time.
+
+* trying to exchange obsolete relations with a static http repo will crash.
 
 Annexe
-=================================
+======
 
 .. toctree::
    :maxdepth: 1