1.1 --- a/en/preface.tex	Mon Apr 16 17:37:27 2007 -0700
     1.2 +++ b/en/preface.tex	Wed Apr 18 11:55:39 2007 -0700
     1.3 @@ -18,6 +18,39 @@
     1.4  it will prove useful to others.  I also hope that readers will
     1.5  contribute as they see fit.
     1.6  
     1.7 +\section{About the examples in this book}
     1.8 +
     1.9 +This book takes an unusual approach to code samples.  Every example is
    1.10 +``live''---each one is actually the result of a shell script that
    1.11 +executes the Mercurial commands you see.  Every time an image of the
    1.12 +book is built from its sources, all the example scripts are
    1.13 +automatically run, and their current results compared against their
    1.14 +expected results.
    1.15 +
    1.16 +The advantage of this approach is that the examples are always
    1.17 +accurate; they describe \emph{exactly} the behaviour of the version of
    1.18 +Mercurial that's mentioned at the front of the book.  If I update the
    1.19 +version of Mercurial that I'm documenting, and the output of some
    1.20 +command changes, the build fails.
    1.21 +
    1.22 +There is a small disadvantage to this approach, which is that the
    1.23 +dates and times you'll see in examples tend to be ``squashed''
    1.24 +together in a way that they wouldn't be if the same commands were
    1.25 +being typed by a human.  Where a human can issue no more than one
    1.26 +command every few seconds, with any resulting timestamps
    1.27 +correspondingly spread out, my automated example scripts run many
    1.28 +commands in one second.
    1.29 +
    1.30 +As an instance of this, several consecutive commits in an example can
    1.31 +show up as having occurred during the same second.  You can see this
    1.32 +occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect},
    1.33 +for instance.
    1.34 +
    1.35 +So when you're reading examples, don't place too much weight on the
    1.36 +dates or times you see in the output of commands.  But \emph{do} be
    1.37 +confident that the behaviour you're seeing is consistent and
    1.38 +reproducible.
    1.39 +
    1.40  \section{Colophon---this book is Free}
    1.41  
    1.42  This book is licensed under the Open Publication License, and is

     2.1 --- a/en/undo.tex	Mon Apr 16 17:37:27 2007 -0700
     2.2 +++ b/en/undo.tex	Wed Apr 18 11:55:39 2007 -0700
     2.3 @@ -26,7 +26,9 @@
     2.4  each modification of a repository as a \emph{transaction}.  Every time
     2.5  you commit a changeset or pull changes from another repository,
     2.6  Mercurial remembers what you did.  You can undo, or \emph{roll back},
     2.7 -exactly one of these actions using the \hgcmd{rollback} command.
     2.8 +exactly one of these actions using the \hgcmd{rollback} command.  (See
     2.9 +section~\ref{sec:undo:rollback-after-push} for an important caveat
    2.10 +about the use of this command.)
    2.11  
    2.12  Here's a mistake that I often find myself making: committing a change
    2.13  in which I've created a new file, but forgotten to \hgcmd{add} it.
    2.14 @@ -77,6 +79,7 @@
    2.15  all you need to undo this mistake.
    2.16  
    2.17  \subsection{Rolling back is useless once you've pushed}
    2.18 +\label{sec:undo:rollback-after-push}
    2.19  
    2.20  The value of the \hgcmd{rollback} command drops to zero once you've
    2.21  pushed your changes to another repository.  Rolling back a change
    2.22 @@ -455,6 +458,7 @@
    2.23  changesets.  Kind of an important omission.
    2.24  
    2.25  \section{Finding the source of a bug}
    2.26 +\label{sec:undo:bisect}
    2.27  
    2.28  While it's all very well to be able to back out a changeset that
    2.29  introduced a bug, this requires that you know which changeset to back