diff en/ch00-preface.xml @ 658:b90b024729f1

WIP DocBook snapshot that all compiles. Mirabile dictu!

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