1.1 --- a/en/preface.tex	Tue Jul 11 23:48:25 2006 -0700
     1.2 +++ b/en/preface.tex	Wed Jan 07 22:27:30 2009 -0500
     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