1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch00-preface.tex	Thu Jan 29 22:56:27 2009 -0800
     1.3 @@ -0,0 +1,67 @@
     1.4 +\chapter*{Preface}
     1.5 +\addcontentsline{toc}{chapter}{Preface}
     1.6 +\label{chap:preface}
     1.7 +
     1.8 +Distributed revision control is a relatively new territory, and has
     1.9 +thus far grown due to people's willingness to strike out into
    1.10 +ill-charted territory.
    1.11 +
    1.12 +I am writing a book about distributed revision control because I
    1.13 +believe that it is an important subject that deserves a field guide.
    1.14 +I chose to write about Mercurial because it is the easiest tool to
    1.15 +learn the terrain with, and yet it scales to the demands of real,
    1.16 +challenging environments where many other revision control tools fail.
    1.17 +
    1.18 +\section{This book is a work in progress}
    1.19 +
    1.20 +I am releasing this book while I am still writing it, in the hope that
    1.21 +it will prove useful to others.  I also hope that readers will
    1.22 +contribute as they see fit.
    1.23 +
    1.24 +\section{About the examples in this book}
    1.25 +
    1.26 +This book takes an unusual approach to code samples.  Every example is
    1.27 +``live''---each one is actually the result of a shell script that
    1.28 +executes the Mercurial commands you see.  Every time an image of the
    1.29 +book is built from its sources, all the example scripts are
    1.30 +automatically run, and their current results compared against their
    1.31 +expected results.
    1.32 +
    1.33 +The advantage of this approach is that the examples are always
    1.34 +accurate; they describe \emph{exactly} the behaviour of the version of
    1.35 +Mercurial that's mentioned at the front of the book.  If I update the
    1.36 +version of Mercurial that I'm documenting, and the output of some
    1.37 +command changes, the build fails.
    1.38 +
    1.39 +There is a small disadvantage to this approach, which is that the
    1.40 +dates and times you'll see in examples tend to be ``squashed''
    1.41 +together in a way that they wouldn't be if the same commands were
    1.42 +being typed by a human.  Where a human can issue no more than one
    1.43 +command every few seconds, with any resulting timestamps
    1.44 +correspondingly spread out, my automated example scripts run many
    1.45 +commands in one second.
    1.46 +
    1.47 +As an instance of this, several consecutive commits in an example can
    1.48 +show up as having occurred during the same second.  You can see this
    1.49 +occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect},
    1.50 +for instance.
    1.51 +
    1.52 +So when you're reading examples, don't place too much weight on the
    1.53 +dates or times you see in the output of commands.  But \emph{do} be
    1.54 +confident that the behaviour you're seeing is consistent and
    1.55 +reproducible.
    1.56 +
    1.57 +\section{Colophon---this book is Free}
    1.58 +
    1.59 +This book is licensed under the Open Publication License, and is
    1.60 +produced entirely using Free Software tools.  It is typeset with
    1.61 +\LaTeX{}; illustrations are drawn and rendered with
    1.62 +\href{http://www.inkscape.org/}{Inkscape}.
    1.63 +
    1.64 +The complete source code for this book is published as a Mercurial
    1.65 +repository, at \url{http://hg.serpentine.com/mercurial/book}.
    1.66 +
    1.67 +%%% Local Variables: 
    1.68 +%%% mode: latex
    1.69 +%%% TeX-master: "00book"
    1.70 +%%% End: