hgbook
view en/preface.tex @ 200:9bba958be4c6
Mention automatic example generation.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Wed Apr 18 11:55:39 2007 -0700 (2007-04-18) |
| parents | 1bc6c1f0192a |
| children |
line source
1 \chapter*{Preface}
2 \addcontentsline{toc}{chapter}{Preface}
3 \label{chap:preface}
5 Distributed revision control is a relatively new territory, and has
6 thus far grown due to people's willingness to strike out into
7 ill-charted territory.
9 I am writing a book about distributed revision control because I
10 believe that it is an important subject that deserves a field guide.
11 I chose to write about Mercurial because it is the easiest tool to
12 learn the terrain with, and yet it scales to the demands of real,
13 challenging environments where many other revision control tools fail.
15 \section{This book is a work in progress}
17 I am releasing this book while I am still writing it, in the hope that
18 it will prove useful to others. I also hope that readers will
19 contribute as they see fit.
21 \section{About the examples in this book}
23 This book takes an unusual approach to code samples. Every example is
24 ``live''---each one is actually the result of a shell script that
25 executes the Mercurial commands you see. Every time an image of the
26 book is built from its sources, all the example scripts are
27 automatically run, and their current results compared against their
28 expected results.
30 The advantage of this approach is that the examples are always
31 accurate; they describe \emph{exactly} the behaviour of the version of
32 Mercurial that's mentioned at the front of the book. If I update the
33 version of Mercurial that I'm documenting, and the output of some
34 command changes, the build fails.
36 There is a small disadvantage to this approach, which is that the
37 dates and times you'll see in examples tend to be ``squashed''
38 together in a way that they wouldn't be if the same commands were
39 being typed by a human. Where a human can issue no more than one
40 command every few seconds, with any resulting timestamps
41 correspondingly spread out, my automated example scripts run many
42 commands in one second.
44 As an instance of this, several consecutive commits in an example can
45 show up as having occurred during the same second. You can see this
46 occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect},
47 for instance.
49 So when you're reading examples, don't place too much weight on the
50 dates or times you see in the output of commands. But \emph{do} be
51 confident that the behaviour you're seeing is consistent and
52 reproducible.
54 \section{Colophon---this book is Free}
56 This book is licensed under the Open Publication License, and is
57 produced entirely using Free Software tools. It is typeset with
58 \LaTeX{}; illustrations are drawn and rendered with
59 \href{http://www.inkscape.org/}{Inkscape}.
61 The complete source code for this book is published as a Mercurial
62 repository, at \url{http://hg.serpentine.com/mercurial/book}.
64 %%% Local Variables:
65 %%% mode: latex
66 %%% TeX-master: "00book"
67 %%% End: