diff -r f46a41006136 -r 79aacd34bf1e hgext/obsolete.py
--- a/hgext/obsolete.py	Wed Aug 08 16:51:45 2012 +0200
+++ b/hgext/obsolete.py	Wed Aug 15 15:38:55 2012 +0200
@@ -10,19 +10,18 @@
 General concept
 ===============
 
-This extension introduces the *obsolete* concept. It adds a new *obsolete*
-relation between two changesets. A relation ``<changeset B> obsolete <changeset
-A>`` is set to denote that ``<changeset B>`` is new version of ``<changeset
-A>``.
+This extension introduces the *obsolete* concept. The relation
+``<changeset B> obsoletes <changeset A>`` denotes that ``<changeset B>``
+is a new version of ``<changeset A>``.
 
-The *obsolete* relation act as a **perpendicular history** to the standard
-changeset history. Standard changeset history versions files. The *obsolete*
-relation versions changesets.
+The *obsolete* relations act as an history **orthogonal** to the regular
+changesets history. Regular changesets history versions files. *Obsolete*
+relations version changesets.
 
 :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.
+:suspended:    an obsolete changeset with unstable descendants.
+:extinct:      an obsolete changeset without unstable descendants.
                (subject to garbage collection)
 
 Another name for unstable could be out of sync.