annotate en/ch00-preface.xml @ 746:d0160b0b1a9e

Merge with http://hg.serpentine.com/mercurial/book

<!-- 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 DocBook XML.  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:
-->