hgbook
diff en/ch00-preface.tex @ 559:b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Feb 18 00:22:09 2009 -0800 (2009-02-18) |
parents | 9bba958be4c6 |
children |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/en/ch00-preface.tex Wed Feb 18 00:22:09 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: