--- a/hgext/obsolete.py
+++ b/hgext/obsolete.py
@@ -19,61 +19,59 @@
 changeset history. Standard changeset history versions files. The *obsolete*
 relation versions changesets.
 
-:obsolete:     a changeset that have been replace by another one.
-:unstable:     a non-obsolet changeset based on another one.
+:obsolete:     a changeset that has been replaced by another one.
+:unstable:     a changeset that is not obsolete but has an obsolete ancestor.
 :suspended:    an obsolete changeset with unstable descendant.
-:extinct:      an obsolete changeset without unstable descendant
+:extinct:      an obsolete changeset without unstable descendant.
                (subject to garbage collection)
 
 Another name for unstable could be out of sync.
 
 
-
 Usage and Feature
 =================
 
-
 Display and Exchange
-....................
+--------------------
 
 obsolete changesets are hidden. (except if they have non obsolete changeset)
 
-obsolete changesets are currently not exchange. This will probably change later
-but it was the simpler solution for now.
+obsolete changesets are not exchanged. This will probably change later but it
+was the simpler solution for now.
 
 New commands
-............
+------------
 
-a ``debugobsolete`` command has been added.
-
-It add an obsolete relation between too relation.
+A ``debugobsolete`` command was added. It adds an obsolete relation between two
+nodes.
 
 Context object
-..............
+--------------
 
-Context gain a ``obsolete`` method that return True if a changeset is obsolete
-False otherwise.
+Context gains a ``obsolete`` method that will return True if a changeset is
+obsolete False otherwise.
 
 revset
-......
+------
 
 Add an ``obsolete()`` entry.
 
 repo extension
-..............
+--------------
 
 To Do
------
+~~~~~
 
-* refuse to obsolete published changesets
+- refuse to obsolete published changesets
 
-* handle split
+- handle split
 
-* handle conflict
+- handle conflict
 
-* handle unstable // out of sync
+- handle unstable // out of sync
 
 """
+
 import os
 try:
     from cStringIO import StringIO
@@ -815,7 +813,7 @@
                     journalpath = self.sjoin(journalname)
                     util.copyfile(filepath, journalpath)
 
-        else: # XXX remove this bloc while breaking support to Hg 2.1
+        else: # XXX removing this bloc will break Hg 2.1 support
             def _writejournal(self, desc):
                 """wrapped version of _writejournal that save obsolete data"""
                 entries = list(o_writejournal(desc))
@@ -845,7 +843,7 @@
 
         @storecache('00changelog.i')
         def changelog(self):
-            # << copy pasted from mercurila source
+            # << copy pasted from mercurial source
             c = changelog.changelog(self.sopener)
             if 'HG_PENDING' in os.environ:
                 p = os.environ['HG_PENDING']
@@ -882,5 +880,3 @@
                 phases.retractboundary(repo, 2, expobs)
             finally:
                 lock.release()
-
-