Mercurial > hgbook
diff en/ch00-preface.xml @ 658:b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed, 18 Feb 2009 00:22:09 -0800 |
parents | en/ch00-preface.tex@5cd47f721686 |
children | 8366882f67f2 cfdb601a3c8b |
line wrap: on
line diff
--- /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: +-->