hgbook

annotate en/preface.tex @ 339:adb677612c39

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