hgbook
diff en/ch00-preface.xml @ 559:b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Feb 18 00:22:09 2009 -0800 (2009-02-18) |
parents | en/ch00-preface.tex@5cd47f721686 |
children | 8366882f67f2 cfdb601a3c8b |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/en/ch00-preface.xml Wed Feb 18 00:22:09 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 +-->