bos@26: \chapter*{Preface}
bos@26: \addcontentsline{toc}{chapter}{Preface}
bos@26: \label{chap:preface}
bos@26: 
bos@26: Distributed revision control is a relatively new territory, and has
bos@26: thus far grown due to people's willingness to strike out into
bos@26: ill-charted territory.
bos@26: 
bos@26: I am writing a book about distributed revision control because I
bos@26: believe that it is an important subject that deserves a field guide.
bos@26: I chose to write about Mercurial because it is the easiest tool to
bos@26: learn the terrain with, and yet it scales to the demands of real,
bos@26: challenging environments where many other revision control tools fail.
bos@26: 
bos@26: \section{This book is a work in progress}
bos@26: 
bos@26: I am releasing this book while I am still writing it, in the hope that
bos@26: it will prove useful to others.  I also hope that readers will
bos@26: contribute as they see fit.
bos@26: 
bos@200: \section{About the examples in this book}
bos@200: 
bos@200: This book takes an unusual approach to code samples.  Every example is
bos@200: ``live''---each one is actually the result of a shell script that
bos@200: executes the Mercurial commands you see.  Every time an image of the
bos@200: book is built from its sources, all the example scripts are
bos@200: automatically run, and their current results compared against their
bos@200: expected results.
bos@200: 
bos@200: The advantage of this approach is that the examples are always
bos@200: accurate; they describe \emph{exactly} the behaviour of the version of
bos@200: Mercurial that's mentioned at the front of the book.  If I update the
bos@200: version of Mercurial that I'm documenting, and the output of some
bos@200: command changes, the build fails.
bos@200: 
bos@200: There is a small disadvantage to this approach, which is that the
bos@200: dates and times you'll see in examples tend to be ``squashed''
bos@200: together in a way that they wouldn't be if the same commands were
bos@200: being typed by a human.  Where a human can issue no more than one
bos@200: command every few seconds, with any resulting timestamps
bos@200: correspondingly spread out, my automated example scripts run many
bos@200: commands in one second.
bos@200: 
bos@200: As an instance of this, several consecutive commits in an example can
bos@200: show up as having occurred during the same second.  You can see this
bos@200: occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect},
bos@200: for instance.
bos@200: 
bos@200: So when you're reading examples, don't place too much weight on the
bos@200: dates or times you see in the output of commands.  But \emph{do} be
bos@200: confident that the behaviour you're seeing is consistent and
bos@200: reproducible.
bos@200: 
bos@26: \section{Colophon---this book is Free}
bos@26: 
bos@26: This book is licensed under the Open Publication License, and is
bos@26: produced entirely using Free Software tools.  It is typeset with
bos@26: \LaTeX{}; illustrations are drawn and rendered with
bos@26: \href{http://www.inkscape.org/}{Inkscape}.
bos@26: 
bos@26: The complete source code for this book is published as a Mercurial
bos@26: repository, at \url{http://hg.serpentine.com/mercurial/book}.
bos@26: 
bos@26: %%% Local Variables: 
bos@26: %%% mode: latex
bos@26: %%% TeX-master: "00book"
bos@26: %%% End: