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