diff en/preface.tex @ 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