diff docs/user-guide.rst @ 1268:ba3ff8c00304 stable

docs: explain --hidden option

Also move the discussion of revision numbers up, and splice the
explanation of --hidden into it.

--- a/docs/user-guide.rst	Mon Apr 13 15:42:42 2015 -0400
+++ b/docs/user-guide.rst	Mon Apr 13 15:09:55 2015 -0400
@@ -248,10 +248,38 @@
 history modification work is not yet done. We'll see examples of that
 later, when we cover advanced usage.
 
-Seeing hidden changesets
-========================
+
+Understanding revision numbers and hidden changesets
+====================================================
+
+As the name implies, hidden changesets are normally not visible. If
+you run ``hg log`` on the repository from Figure 2, Mercurial will
+show revisions 0 and 3, but not 1 and 2. That's something you don't
+see with plain vanilla Mercurial—normally, revision *N* is always
+followed by revision *N* + 1.
+
+This is just the visible manifestation of hidden changesets. If
+revision 0 is followed by revision 3, that means there are two hidden
+changesets, 1 and 2, in between.
+
+To see those hidden changesets, use the ``--hidden`` option::
 
-TODO
+  $ hg --hidden log --graph --template '{rev}:{node|short}  {desc|firstline}\n'
+  @  3:934359450037  implement feature Y
+  |
+  | x  2:6c5f78d5d467  temporary amend commit for fe0ecd3bd2a4
+  | |
+  | x  1:fe0ecd3bd2a4  implement feature Y
+  |/
+  o  0:08c4b6f4efc8  init
+
+Note that changeset IDs are still the permanent, immutable identifier
+for changesets. Revision numbers are, as ever, a handy shorthand that
+work in your local repository, but cannot be used across repositories.
+They also have the useful property of showing when there are hidden
+changesets lurking under the covers, which is why this document uses
+revision numbers.
+
 
 Under the hood: Prune an unwanted changeset
 ===========================================
@@ -309,27 +337,6 @@
 TODO
 
 
-Understanding revision numbers
-==============================
-
-If you're trying these examples on your own, especially using ``hg
-log`` without ``--hidden``, you have probably noticed some funny
-business going on with revision numbers: there are now gaps in the
-sequence. That's something you don't see with plain vanilla Mercurial;
-normally, revision N is always followed by revision N+1.
-
-This is just the visible manifestation of hidden changesets. If
-revision 95 is followed by revision 98, that means there are two
-hidden changesets, 96 and 97, in between.
-
-Note that changeset IDs are still the permanent, immutable identifier
-for changesets. Revision numbers are, as ever, a handy shorthand that
-work in your local repository, but cannot be used across repositories.
-They also have the useful property of showing when there are hidden
-changesets lurking under the covers, which is why this document uses
-revision numbers.
-
-
 Life with ``evolve`` (advanced usage)
 -------------------------------------