1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->

2

3 <preface id="chap.preface">

4 <title>Preface</title>

5

6 <para>Distributed revision control is a relatively new territory,

7 and has thus far grown due to people's willingness to strike out

8 into ill-charted territory.</para>

9

10 <para>I am writing a book about distributed revision control because

11 I believe that it is an important subject that deserves a field

12 guide. I chose to write about Mercurial because it is the easiest

13 tool to learn the terrain with, and yet it scales to the demands

14 of real, challenging environments where many other revision

15 control tools fail.</para>

16

17 <sect1>

18 <title>This book is a work in progress</title>

19

20 <para>I am releasing this book while I am still writing it, in the

21 hope that it will prove useful to others. I also hope that

22 readers will contribute as they see fit.</para>

23

24 </sect1>

25 <sect1>

26 <title>About the examples in this book</title>

27

28 <para>This book takes an unusual approach to code samples. Every

29 example is <quote>live</quote>---each one is actually the result

30 of a shell script that executes the Mercurial commands you see.

31 Every time an image of the book is built from its sources, all

32 the example scripts are automatically run, and their current

33 results compared against their expected results.</para>

34

35 <para>The advantage of this approach is that the examples are

36 always accurate; they describe <emphasis>exactly</emphasis> the

37 behaviour of the version of Mercurial that's mentioned at the

38 front of the book. If I update the version of Mercurial that

39 I'm documenting, and the output of some command changes, the

40 build fails.</para>

41

42 <para>There is a small disadvantage to this approach, which is

43 that the dates and times you'll see in examples tend to be

44 <quote>squashed</quote> together in a way that they wouldn't be

45 if the same commands were being typed by a human. Where a human

46 can issue no more than one command every few seconds, with any

47 resulting timestamps correspondingly spread out, my automated

48 example scripts run many commands in one second.</para>

49

50 <para>As an instance of this, several consecutive commits in an

51 example can show up as having occurred during the same second.

52 You can see this occur in the <literal

53 role="hg-ext">bisect</literal> example in section <xref

54 id="sec.undo.bisect"/>, for instance.</para>

55

56 <para>So when you're reading examples, don't place too much weight

57 on the dates or times you see in the output of commands. But

58 <emphasis>do</emphasis> be confident that the behaviour you're

59 seeing is consistent and reproducible.</para>

60

61 </sect1>

62 <sect1>

63 <title>Colophon---this book is Free</title>

64

65 <para>This book is licensed under the Open Publication License,

66 and is produced entirely using Free Software tools. It is

67 typeset with \LaTeX{}; illustrations are drawn and rendered with

68 <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>

69

70 <para>The complete source code for this book is published as a

71 Mercurial repository, at <ulink

72 url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>

73

74 </sect1>

75 </preface>

76 <!--

77 local variables:

78 sgml-parent-document: ("00book.xml" "book" "preface")

79 end:

80 -->