--- a/docs/sharing.rst	Mon Apr 20 13:52:43 2015 +0200
+++ b/docs/sharing.rst	Tue Apr 14 12:43:37 2015 -0400
@@ -5,12 +5,15 @@
 ------------------------------
 
 Once you have mastered the art of mutable history in a single
-repository, you might want to move up to the next level: *shared*
-mutable history. ``evolve`` lets you push and pull draft changesets
-between repositories along with their obsolescence markers. This opens
-up a number of interesting possibilities.
+repository (see the `user guide`_), you might want to move up to the
+next level: *shared* mutable history. ``evolve`` lets you push and
+pull draft changesets between repositories along with their
+obsolescence markers. This opens up a number of interesting
+possibilities.
 
-The most common scenario is a single developer working across two
+.. _`user guide`: user-guide.html
+
+The simplest scenario is a single developer working across two
 computers. Say you're working on code that must be tested on a remote
 test server, probably in a rack somewhere, only accessible by SSH, and
 running an “enterprise-grade” (out-of-date) OS. But you probably
@@ -40,9 +43,9 @@
 those half-baked changesets between repositories to try things out on
 your test server before anything is carved in stone.
 
-A less common scenario is multiple developers sharing mutable history.
-(This is in fact how Mercurial itself is developed.) We'll cover this
-scenario later. But first, single-user sharing.
+A less common scenario is multiple developers sharing mutable history,
+typically for code review. We'll cover this scenario later. But first,
+single-user sharing.
 
 Publishing and non-publishing repositories
 ------------------------------------------
@@ -60,15 +63,20 @@
 
 We'll work an example with three local repositories, although in the
 real world they'd most likely be on three different computers. First,
-the public repository is where tested, polished changesets live, and
-it is where you push/pull changesets to/from the rest of your team. ::
+the ``public`` repository is where tested, polished changesets live,
+and it is where you synchronize changesets with the rest of your team.
+::
 
   $ hg init public
 
 We'll need two clones where work gets done::
 
-  $ hg clone -q public test-repo
-  $ hg clone -q test-repo dev-repo
+  $ hg clone public test-repo
+  updating to branch default
+  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg clone test-repo dev-repo
+  updating to branch default
+  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
 ``dev-repo`` is your local machine, with GUI merge tools and IDEs and
 everything configured just the way you like it. ``test-repo`` is the
@@ -76,25 +84,29 @@
 we'll develop in ``dev-repo``, push to ``test-repo``, test and polish
 there, and push to ``public``.
 
-The key to making this whole thing work is to make ``test-repo``
-non-publishing::
+The key to shared mutable history is to make the target repository,
+``test-repo`` in this case, non-publishing. And, of course, we have to enable ``evolve`` in both ``test-repo`` and ``dev-repo``.
+
+First, edit the configuration for ``test-repo``::
 
-  $ cat >> test-repo/.hg/hgrc <<EOF
+  $ hg -R test-repo config --edit --local
+
+and add ::
+
   [phases]
   publish = false
-  EOF
 
-We also have to configure ``evolve`` in both ``test-repo`` and
-``dev-repo``, so that we can amend and evolve in both of them. ::
-
-  $ cat >> test-repo/.hg/hgrc <<EOF
   [extensions]
   evolve = /path/to/mutable-history/hgext/evolve.py
-  EOF
-  $ cat >> dev-repo/.hg/hgrc <<EOF
+
+Then edit the configuration for ``dev-repo``::
+
+  $ hg -R dev-repo config --edit --local
+
+and add ::
+
   [extensions]
   evolve = /path/to/mutable-history/hgext/evolve.py
-  EOF
 
 Keep in mind that in real life, these repositories would probably be
 on separate computers, so you'd have to login to each one to configure
@@ -106,15 +118,20 @@
   $ echo 'my new project' > file1
   $ hg add file1
   $ hg commit -m 'create new project'
-  $ hg push -q
+  $ hg push
+  [...]
+  added 1 changesets with 1 changes to 1 files
 
 and pull that into the development repository::
 
   $ cd ../dev-repo
   $ hg pull -u
+  [...]
+  added 1 changesets with 1 changes to 1 files
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
-Amending a shared changeset
----------------------------
+Example 1: Amend a shared changeset
+-----------------------------------
 
 Everything you learned in the `user guide`_ applies to work done in
 ``dev-repo``. You can commit, amend, uncommit, evolve, and so forth
@@ -187,8 +204,8 @@
 numbers in ``test-repo`` and ``dev-repo`` are no longer consistent. We
 *must* use changeset IDs.
 
-Amend again, locally
---------------------
+Example 2: Amend again, locally
+-------------------------------
 
 This process can repeat. Perhaps you figure out a more elegant fix to
 the bug, and want to mutate history so nobody ever knows you had a
@@ -209,7 +226,8 @@
 Let's hop over to ``test-repo`` to test the more elegant fix::
 
   $ cd ../test-repo
-  $ hg update -q
+  $ hg update
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
 This time, all the tests pass, so no further amendment is required.
 This bug fix is finished, so we push it to the public repository::
@@ -264,8 +282,12 @@
 it in the last example, with two immutable changesets (figure 5
 above). Two developers, Alice and Bob, start working from this point::
 
-  $ hg clone -q public alice
-  $ hg clone -q public bob
+  $ hg clone public alice
+  updating to branch default
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg clone public bob
+  updating to branch default
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
 We need to configure Alice's and Bob's working repositories similar to
 ``test-repo``, i.e. make them non-publishing and enable ``evolve``::
@@ -298,15 +320,19 @@
 
   $ cd alice
   $ echo 'fix' > file2
-  $ hg commit -q -A -m 'fix bug 15'
+  $ hg commit -A -m 'fix bug 15'
+  adding file2
 
 Now Bob has a bad idea: he decides to pull whatever Alice is working
 on and tweak her bug fix to his taste::
 
   $ cd ../bob
-  $ hg pull -q -u ../alice
+  $ hg pull -u ../alice
+  [...]
+  added 1 changesets with 1 changes to 1 files
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
   $ echo 'Fix.' > file2
-  $ hg amend -q -A -m 'fix bug 15 (amended)'
+  $ hg amend -A -m 'fix bug 15 (amended)'
 
 (Note the lack of communication between Alice and Bob. Failing to
 communicate with your colleagues is a good way to get into trouble.
@@ -319,7 +345,9 @@
 publish. ::
 
   $ cd ../alice
-  $ hg push  -q
+  $ hg push
+  [...]
+  added 1 changesets with 1 changes to 1 files
 
 This introduces a contradiction: in Bob's repository, changeset 2:e011
 (his copy of Alice's fix) is obsolete, since Bob amended it. But in
@@ -382,7 +410,9 @@
 idea)::
 
   $ cd ../alice
-  $ hg pull -q -u ../bob
+  $ hg pull -u ../bob
+  [...]
+  added 1 changesets with 1 changes to 1 files
   $ echo 'better (alice)' >> file1
   $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'