annotate en/preface.tex @ 200:9bba958be4c6

Mention automatic example generation.

\chapter*{Preface}
\addcontentsline{toc}{chapter}{Preface}
\label{chap:preface}

Distributed revision control is a relatively new territory, and has
thus far grown due to people's willingness to strike out into
ill-charted territory.

I am writing a book about distributed revision control because I
believe that it is an important subject that deserves a field guide.
I chose to write about Mercurial because it is the easiest tool to
learn the terrain with, and yet it scales to the demands of real,
challenging environments where many other revision control tools fail.

\section{This book is a work in progress}

I am releasing this book while I am still writing it, in the hope that
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
produced entirely using Free Software tools.  It is typeset with
\LaTeX{}; illustrations are drawn and rendered with
\href{http://www.inkscape.org/}{Inkscape}.

The complete source code for this book is published as a Mercurial
repository, at \url{http://hg.serpentine.com/mercurial/book}.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "00book"
%%% End: