1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch00-preface.xml	Thu Mar 12 15:35:19 2009 +0800
     1.3 @@ -0,0 +1,80 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<preface id="chap:preface">
     1.7 +  <title>Preface</title>
     1.8 +
     1.9 +  <para>Distributed revision control is a relatively new territory,
    1.10 +    and has thus far grown due to people's willingness to strike out
    1.11 +    into ill-charted territory.</para>
    1.12 +
    1.13 +  <para>I am writing a book about distributed revision control because
    1.14 +    I believe that it is an important subject that deserves a field
    1.15 +    guide. I chose to write about Mercurial because it is the easiest
    1.16 +    tool to learn the terrain with, and yet it scales to the demands
    1.17 +    of real, challenging environments where many other revision
    1.18 +    control tools fail.</para>
    1.19 +
    1.20 +  <sect1>
    1.21 +    <title>This book is a work in progress</title>
    1.22 +
    1.23 +    <para>I am releasing this book while I am still writing it, in the
    1.24 +      hope that it will prove useful to others.  I also hope that
    1.25 +      readers will contribute as they see fit.</para>
    1.26 +
    1.27 +  </sect1>
    1.28 +  <sect1>
    1.29 +    <title>About the examples in this book</title>
    1.30 +
    1.31 +    <para>This book takes an unusual approach to code samples.  Every
    1.32 +      example is <quote>live</quote>---each one is actually the result
    1.33 +      of a shell script that executes the Mercurial commands you see.
    1.34 +      Every time an image of the book is built from its sources, all
    1.35 +      the example scripts are automatically run, and their current
    1.36 +      results compared against their expected results.</para>
    1.37 +
    1.38 +    <para>The advantage of this approach is that the examples are
    1.39 +      always accurate; they describe <emphasis>exactly</emphasis> the
    1.40 +      behaviour of the version of Mercurial that's mentioned at the
    1.41 +      front of the book.  If I update the version of Mercurial that
    1.42 +      I'm documenting, and the output of some command changes, the
    1.43 +      build fails.</para>
    1.44 +
    1.45 +    <para>There is a small disadvantage to this approach, which is
    1.46 +      that the dates and times you'll see in examples tend to be
    1.47 +      <quote>squashed</quote> together in a way that they wouldn't be
    1.48 +      if the same commands were being typed by a human.  Where a human
    1.49 +      can issue no more than one command every few seconds, with any
    1.50 +      resulting timestamps correspondingly spread out, my automated
    1.51 +      example scripts run many commands in one second.</para>
    1.52 +
    1.53 +    <para>As an instance of this, several consecutive commits in an
    1.54 +      example can show up as having occurred during the same second.
    1.55 +      You can see this occur in the <literal
    1.56 +	role="hg-ext">bisect</literal> example in section <xref
    1.57 +	id="sec:undo:bisect"/>, for instance.</para>
    1.58 +
    1.59 +    <para>So when you're reading examples, don't place too much weight
    1.60 +      on the dates or times you see in the output of commands.  But
    1.61 +      <emphasis>do</emphasis> be confident that the behaviour you're
    1.62 +      seeing is consistent and reproducible.</para>
    1.63 +
    1.64 +  </sect1>
    1.65 +  <sect1>
    1.66 +    <title>Colophon---this book is Free</title>
    1.67 +
    1.68 +    <para>This book is licensed under the Open Publication License,
    1.69 +      and is produced entirely using Free Software tools.  It is
    1.70 +      typeset with \LaTeX{}; illustrations are drawn and rendered with
    1.71 +      <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
    1.72 +
    1.73 +    <para>The complete source code for this book is published as a
    1.74 +      Mercurial repository, at <ulink
    1.75 +	url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
    1.76 +
    1.77 +  </sect1>
    1.78 +</preface>
    1.79 +<!--
    1.80 +local variables: 
    1.81 +sgml-parent-document: ("00book.xml" "book" "preface")
    1.82 +end:
    1.83 +-->