--- a/docs/user-guide.rst	Wed Sep 13 21:41:57 2017 +0200
+++ b/docs/user-guide.rst	Wed Aug 30 17:32:32 2017 +0200
@@ -26,17 +26,17 @@
 (``rebase``, ``histedit``, etc.), and also by the ``evolve``
 extension. Specifically, ``evolve`` adds a number of commands that can
 be used to modify history: ``amend``, ``uncommit``, ``prune``,
-``fold``, and ``evolve``. Generally speaking, changesets remain in
-*draft* phase until they are pushed to another repository, at which
-point they enter *public* phase. ::
+``fold``, and ``evolve``. ::
 
   $ hg commit -m 'implement feature X'
   $ hg phase -r .
   1: draft
 
-(Strictly speaking, changesets only become public when they are pushed
-to a *publishing* repository. But all repositories are publishing by
-default; you have to explicitly configure repositories to be
+Generally speaking, changesets remain in *draft* phase until they are
+pushed to another repository, at which point they enter the *public*
+phase. (Strictly speaking, changesets only become public when they are
+pushed to a *publishing* repository. But all repositories are publishing
+by default; you have to explicitly configure repositories to be
 *non-publishing*. Non-publishing repositories are an advanced topic
 which we'll see when we get to `sharing mutable history`_.)
 
@@ -60,7 +60,8 @@
 to create a new, amended changeset. The drawback of doing this with
 vanilla Mercurial is that your original, flawed, changeset is removed
 from the repository. This is *unsafe* history editing. It's probably
-not too serious if all you did was fix a syntax error, but still.
+not too serious if all you did was fix a syntax error, but for deeper
+changes there can be more serious consequences to unsafe history editing.
 
 .. figure:: figures/figure-ug01.svg
 
@@ -70,8 +71,9 @@
 (Incidentally, Mercurial's traditional history modification mechanism
 isn't *really* unsafe: any changeset(s) removed from the repository
 are kept in a backup directory, so you can manually restore them later
-if you change your mind. But it's awkward and inconvenient compared to
-the features provided by ``evolve`` and changeset obsolescence.)
+if you change your mind. However, this mechanism is very awkward and
+inconvenient compared to the features provided by ``evolve`` and
+changeset obsolescence.)
 
 Life with ``evolve`` (basic usage)
 ----------------------------------
@@ -99,7 +101,7 @@
 pass ``-m`` or ``-l``.)
 
 Under the hood, though, things are quite different. Mercurial has
-simply marked the old changeset *obsolete*, replacing it with a new
+simply marked the old changeset as *obsolete*, replacing it with a new
 one. We'll explore what this means in detail later, after working
 through a few more examples.
 
@@ -192,7 +194,7 @@
 
 and fold them::
 
-  $ hg fold -m 'fix bug 64' -r 7::
+  $ hg fold -m 'fix bug 64' -r 7:: --exact
   3 changesets folded
   1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
@@ -214,7 +216,7 @@
 When you have the ``evolve`` extension enabled, all history
 modification uses the same underlying mechanism: the original
 changesets are marked *obsolete* and replaced by zero or more
-*successors*. The obsolete changesets are the *precursors* of their
+*successors*. The obsolete changesets are the *predecessors* of their
 successors. This applies equally to built-in commands (``commit
 --amend``), commands added by ``evolve`` (``amend``, ``prune``,
 ``uncommit``, ``fold``), and commands provided by other extensions
@@ -232,7 +234,7 @@
 Consider Example 2, amending a changeset with ``evolve``. We saw above
 that you can do this using the exact same command-line syntax as core
 Mercurial, namely ``hg commit --amend``. But the implementation is
-quite different, and Figure 2 shows how.
+quite different, as Figure 2 shows.
 
 .. figure:: figures/figure-ug02.svg
 
@@ -243,8 +245,8 @@
    versions of Mercurial will not create them.)
 
 In this case, the obsolete changesets are also *hidden*. That is the
-usual end state for obsolete changesets. But many scenarios result in
-obsolete changesets that are still visible, which indicates your
+usual end state for obsolete changesets. However, many scenarios result
+in obsolete changesets that are still visible, which indicates your
 history modification work is not yet done. We'll see examples of that
 later, when we cover advanced usage.
 
@@ -287,7 +289,7 @@
 ``prune`` (example 4 above) is the simplest history modification
 command provided by ``evolve``. All it does is mark the specified
 changeset(s) obsolete, with no successor/precursor relationships
-involved. (If the working directory parent was one of the obsolete
+involved. (If the working directory parent was one of the obsoleted
 changesets, ``prune`` updates back to a suitable ancestor.)
 
 .. figure:: figures/figure-ug03.svg
@@ -299,11 +301,8 @@
 
 In one sense, ``uncommit`` is a simplified version of ``amend``. Like
 ``amend``, it obsoletes one changeset and leaves it with a single
-successor. Unlike ``amend``, there is no ugly "temporary amend commit"
-cluttering up the repository.
-
-In another sense, ``uncommit`` is the inverse of ``amend``: ``amend``
-takes any uncommitted changes in the working dir and “adds”
+successor. In another sense, ``uncommit`` is the inverse of ``amend``:
+``amend`` takes any uncommitted changes in the working dir and “adds”
 them to the working directory's parent changeset. (In reality, of
 course, it creates a successor changeset, marking the original
 obsolete.) In contrast, ``uncommit`` takes some changes in the working
@@ -341,8 +340,9 @@
 changesets.
 
 Note that all hidden changesets are obsolete: hidden is a subset of
-obsolete.
+obsolete. This is explained in more depth in the `concepts`_ section.
 
+.. _`concepts`: concepts.html
 
 Life with ``evolve`` (advanced usage)
 -------------------------------------
@@ -353,12 +353,12 @@
 which is an unavoidable consequence of obsolescence. What really sets
 ``evolve`` apart from other history modification mechanisms is the
 fact that it recognizes troubles like unstable changesets and provides
-a consistent way for you to get out of trouble.
+a consistent way for you to get back to a stable repository.
 
-(Incidentally, there are two other types of trouble that changesets
-can get into with ``evolve``: they may be *divergent* or *bumped*.
-Both of those states are more likely to occur when `sharing mutable
-history`_, so we won't see them in this user guide.)
+(Incidentally, there are two other types of troubles that changesets
+can get into with ``evolve``: they may be *divergent* or
+*bumped*. Both of those states are more likely to occur when
+`sharing mutable history`_, so we won't cover them in this user guide.)
 
 .. _`sharing mutable history`: sharing.html
 
@@ -366,8 +366,8 @@
 Example 7: Amend an older changeset
 ===================================
 
-Sometimes you don't notice your mistakes until after you have
-committed new changesets on top of them. ::
+Sometimes you don't notice a mistake until after you have committed
+new changesets on top of the changeset with the mistake. ::
 
   $ hg commit -m 'fix bug 17'         # rev 11 (mistake here)
   $ hg commit -m 'cleanup'            # rev 12
@@ -402,10 +402,10 @@
    descendants are *unstable*. The temporary amend commit, revision
    14, is hidden because it has no non-obsolete descendants.
 
-All non-obsolete descendants of an obsolete changeset are unstable. An
-interesting consequence of this is that revision 11 is still visible,
-even though it is obsolete. Obsolete changesets with non-obsolete
-descendants are not hidden.
+All non-obsolete descendants of an obsolete changeset are considered
+unstable. An interesting consequence of this is that revision 11 is
+still visible, even though it is obsolete. Obsolete changesets with
+non-obsolete descendants are not hidden.
 
 The fix is to *evolve* history::
 
@@ -415,9 +415,8 @@
 because there might be conflicts. If your amended changeset modifies a
 file that one of its descendants also modified, Mercurial has to fire
 up your merge tool to resolve the conflict. More importantly, you have
-to switch contexts from "writing code" to "resolving conflicts". That
-can be an expensive context switch, so Mercurial lets you decide when
-to do it.
+to switch from "writing code" to "resolving conflicts". That can be an
+expensive context switch, so Mercurial lets you decide when to do it.
 
 The end state, after ``evolve`` finishes, is that the original
 revisions (11-13) are obsolete and hidden. Their successor revisions
@@ -491,7 +490,7 @@
   M file2.c
 
 Now your repository has unstable changesets, so you need to evolve it.
-But ``hg evolve`` requires a clean working directory to resolve merge
+However, ``hg evolve`` requires a clean working directory to resolve merge
 conflicts, so you need to decide what to do with ``file2.c``.
 
 In this case, the change to ``file2.c`` was a temporary debugging
@@ -525,12 +524,12 @@
   $ hg commit -u dan -d '12 0' -m 'new feature'   # rev 27 (fine)
 
 As before, we update back to the flawed changeset (this time,
-revision 26) and ``uncommit``, leaving uncommitted changes to
+revision 26) and use ``uncommit``, leaving uncommitted changes to
 ``file2.c`` in the working dir::
 
   $ hg update -q 26
   1 files updated, 0 files merged, 0 files removed, 0 files unresolved
-  $ hg uncommit -q file2.c                        # obsoletes rev 26, creates rev 28
+  $ hg uncommit -q file2.c  # obsoletes rev 26, creates rev 28
   1 new unstable changesets
   $ hg status
   M file2.c
@@ -541,8 +540,8 @@
 
 Figure 11 shows the story so far: ``uncommit`` obsoleted revision 26
 and created revision 28, the successor of 26. Then we committed
-revision 29, a child of 28. We still have to deal with the unstable
-revision 27.
+revision 29, a child of 28. We still have to deal with the revision 27,
+which is an unstable changeset.
 
 .. figure:: figures/figure-ug11.svg
 
@@ -594,7 +593,7 @@
 The current implementation of ``hg touch`` is not ideal, and is likely to
 change in the future. Consider the history in Figure 12, where revision 27
 is obsolete and the child of 26, also obsolete. If we ``hg touch 27``, that
-creates a new revision which is a non-obsolete child of 26—i.e., it is
+creates a new revision which is a non-obsolete child of 26—i.e., it is an
 unstable. It's also *divergent*, another type of trouble that we'll learn
 about in the `next section`_.