changeset 200:9bba958be4c6

Mention automatic example generation.

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

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