1.1 --- a/en/ch00-preface.xml	Thu Mar 19 20:54:12 2009 -0700
     1.2 +++ b/en/ch00-preface.xml	Thu Mar 19 22:42:14 2009 -0700
     1.3 @@ -6,13 +6,13 @@
     1.4    <sect1>
     1.5      <title>Why revision control? Why Mercurial?</title>
     1.6  
     1.7 -    <para>Revision control is the process of managing multiple
     1.8 +    <para id="x_6d">Revision control is the process of managing multiple
     1.9        versions of a piece of information.  In its simplest form, this
    1.10        is something that many people do by hand: every time you modify
    1.11        a file, save it under a new name that contains a number, each
    1.12        one higher than the number of the preceding version.</para>
    1.13  
    1.14 -    <para>Manually managing multiple versions of even a single file is
    1.15 +    <para id="x_6e">Manually managing multiple versions of even a single file is
    1.16        an error-prone task, though, so software tools to help automate
    1.17        this process have long been available.  The earliest automated
    1.18        revision control tools were intended to help a single user to
    1.19 @@ -23,11 +23,11 @@
    1.20        problem coping with thousands of people working together on
    1.21        projects that consist of hundreds of thousands of files.</para>
    1.22  
    1.23 -    <para>The arrival of distributed revision control is relatively
    1.24 +    <para id="x_6f">The arrival of distributed revision control is relatively
    1.25        recent, and so far this new field has grown due to people's
    1.26        willingness to explore ill-charted territory.</para>
    1.27  
    1.28 -    <para>I am writing a book about distributed revision control
    1.29 +    <para id="x_70">I am writing a book about distributed revision control
    1.30        because I believe that it is an important subject that deserves
    1.31        a field guide. I chose to write about Mercurial because it is
    1.32        the easiest tool to learn the terrain with, and yet it scales to
    1.33 @@ -37,41 +37,41 @@
    1.34      <sect2>
    1.35        <title>Why use revision control?</title>
    1.36  
    1.37 -      <para>There are a number of reasons why you or your team might
    1.38 +      <para id="x_71">There are a number of reasons why you or your team might
    1.39  	want to use an automated revision control tool for a
    1.40  	project.</para>
    1.41  
    1.42        <itemizedlist>
    1.43 -	<listitem><para>It will track the history and evolution of
    1.44 +	<listitem><para id="x_72">It will track the history and evolution of
    1.45  	    your project, so you don't have to.  For every change,
    1.46  	    you'll have a log of <emphasis>who</emphasis> made it;
    1.47  	    <emphasis>why</emphasis> they made it;
    1.48  	    <emphasis>when</emphasis> they made it; and
    1.49  	    <emphasis>what</emphasis> the change
    1.50  	    was.</para></listitem>
    1.51 -	<listitem><para>When you're working with other people,
    1.52 +	<listitem><para id="x_73">When you're working with other people,
    1.53  	    revision control software makes it easier for you to
    1.54  	    collaborate.  For example, when people more or less
    1.55  	    simultaneously make potentially incompatible changes, the
    1.56  	    software will help you to identify and resolve those
    1.57  	    conflicts.</para></listitem>
    1.58 -	<listitem><para>It can help you to recover from mistakes.  If
    1.59 +	<listitem><para id="x_74">It can help you to recover from mistakes.  If
    1.60  	    you make a change that later turns out to be in error, you
    1.61  	    can revert to an earlier version of one or more files.  In
    1.62  	    fact, a <emphasis>really</emphasis> good revision control
    1.63  	    tool will even help you to efficiently figure out exactly
    1.64  	    when a problem was introduced (see section <xref
    1.65  	      linkend="sec:undo:bisect"/> for details).</para></listitem>
    1.66 -	<listitem><para>It will help you to work simultaneously on,
    1.67 +	<listitem><para id="x_75">It will help you to work simultaneously on,
    1.68  	    and manage the drift between, multiple versions of your
    1.69  	    project.</para></listitem>
    1.70        </itemizedlist>
    1.71  
    1.72 -      <para>Most of these reasons are equally valid---at least in
    1.73 +      <para id="x_76">Most of these reasons are equally valid---at least in
    1.74  	theory---whether you're working on a project by yourself, or
    1.75  	with a hundred other people.</para>
    1.76  
    1.77 -      <para>A key question about the practicality of revision control
    1.78 +      <para id="x_77">A key question about the practicality of revision control
    1.79  	at these two different scales (<quote>lone hacker</quote> and
    1.80  	<quote>huge team</quote>) is how its
    1.81  	<emphasis>benefits</emphasis> compare to its
    1.82 @@ -79,19 +79,19 @@
    1.83  	difficult to understand or use is going to impose a high
    1.84  	cost.</para>
    1.85  
    1.86 -      <para>A five-hundred-person project is likely to collapse under
    1.87 +      <para id="x_78">A five-hundred-person project is likely to collapse under
    1.88  	its own weight almost immediately without a revision control
    1.89  	tool and process. In this case, the cost of using revision
    1.90  	control might hardly seem worth considering, since
    1.91  	<emphasis>without</emphasis> it, failure is almost
    1.92  	guaranteed.</para>
    1.93  
    1.94 -      <para>On the other hand, a one-person <quote>quick hack</quote>
    1.95 +      <para id="x_79">On the other hand, a one-person <quote>quick hack</quote>
    1.96  	might seem like a poor place to use a revision control tool,
    1.97  	because surely the cost of using one must be close to the
    1.98  	overall cost of the project.  Right?</para>
    1.99  
   1.100 -      <para>Mercurial uniquely supports <emphasis>both</emphasis> of
   1.101 +      <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of
   1.102  	these scales of development.  You can learn the basics in just
   1.103  	a few minutes, and due to its low overhead, you can apply
   1.104  	revision control to the smallest of projects with ease.  Its
   1.105 @@ -101,7 +101,7 @@
   1.106  	time, Mercurial's high performance and peer-to-peer nature let
   1.107  	you scale painlessly to handle large projects.</para>
   1.108  
   1.109 -      <para>No revision control tool can rescue a poorly run project,
   1.110 +      <para id="x_7b">No revision control tool can rescue a poorly run project,
   1.111  	but a good choice of tools can make a huge difference to the
   1.112  	fluidity with which you can work on a project.</para>
   1.113  
   1.114 @@ -110,19 +110,19 @@
   1.115      <sect2>
   1.116        <title>The many names of revision control</title>
   1.117  
   1.118 -      <para>Revision control is a diverse field, so much so that it is
   1.119 +      <para id="x_7c">Revision control is a diverse field, so much so that it is
   1.120  	referred to by many names and acronyms.  Here are a few of the
   1.121  	more common variations you'll encounter:</para>
   1.122        <itemizedlist>
   1.123 -	<listitem><para>Revision control (RCS)</para></listitem>
   1.124 -	<listitem><para>Software configuration management (SCM), or
   1.125 +	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
   1.126 +	<listitem><para id="x_7e">Software configuration management (SCM), or
   1.127  	    configuration management</para></listitem>
   1.128 -	<listitem><para>Source code management</para></listitem>
   1.129 -	<listitem><para>Source code control, or source
   1.130 +	<listitem><para id="x_7f">Source code management</para></listitem>
   1.131 +	<listitem><para id="x_80">Source code control, or source
   1.132  	    control</para></listitem>
   1.133 -	<listitem><para>Version control
   1.134 +	<listitem><para id="x_81">Version control
   1.135  	    (VCS)</para></listitem></itemizedlist>
   1.136 -      <para>Some people claim that these terms actually have different
   1.137 +      <para id="x_82">Some people claim that these terms actually have different
   1.138  	meanings, but in practice they overlap so much that there's no
   1.139  	agreed or even useful way to tease them apart.</para>
   1.140  
   1.141 @@ -132,7 +132,7 @@
   1.142    <sect1>
   1.143      <title>This book is a work in progress</title>
   1.144  
   1.145 -    <para>I am releasing this book while I am still writing it, in the
   1.146 +    <para id="x_83">I am releasing this book while I am still writing it, in the
   1.147        hope that it will prove useful to others.  I am writing under an
   1.148        open license in the hope that you, my readers, will contribute
   1.149        feedback and perhaps content of your own.</para>
   1.150 @@ -141,21 +141,21 @@
   1.151    <sect1>
   1.152      <title>About the examples in this book</title>
   1.153  
   1.154 -    <para>This book takes an unusual approach to code samples.  Every
   1.155 +    <para id="x_84">This book takes an unusual approach to code samples.  Every
   1.156        example is <quote>live</quote>---each one is actually the result
   1.157        of a shell script that executes the Mercurial commands you see.
   1.158        Every time an image of the book is built from its sources, all
   1.159        the example scripts are automatically run, and their current
   1.160        results compared against their expected results.</para>
   1.161  
   1.162 -    <para>The advantage of this approach is that the examples are
   1.163 +    <para id="x_85">The advantage of this approach is that the examples are
   1.164        always accurate; they describe <emphasis>exactly</emphasis> the
   1.165        behaviour of the version of Mercurial that's mentioned at the
   1.166        front of the book.  If I update the version of Mercurial that
   1.167        I'm documenting, and the output of some command changes, the
   1.168        build fails.</para>
   1.169  
   1.170 -    <para>There is a small disadvantage to this approach, which is
   1.171 +    <para id="x_86">There is a small disadvantage to this approach, which is
   1.172        that the dates and times you'll see in examples tend to be
   1.173        <quote>squashed</quote> together in a way that they wouldn't be
   1.174        if the same commands were being typed by a human.  Where a human
   1.175 @@ -163,13 +163,13 @@
   1.176        resulting timestamps correspondingly spread out, my automated
   1.177        example scripts run many commands in one second.</para>
   1.178  
   1.179 -    <para>As an instance of this, several consecutive commits in an
   1.180 +    <para id="x_87">As an instance of this, several consecutive commits in an
   1.181        example can show up as having occurred during the same second.
   1.182        You can see this occur in the <literal
   1.183  	role="hg-ext">bisect</literal> example in section <xref
   1.184  	id="sec:undo:bisect"/>, for instance.</para>
   1.185  
   1.186 -    <para>So when you're reading examples, don't place too much weight
   1.187 +    <para id="x_88">So when you're reading examples, don't place too much weight
   1.188        on the dates or times you see in the output of commands.  But
   1.189        <emphasis>do</emphasis> be confident that the behaviour you're
   1.190        seeing is consistent and reproducible.</para>
   1.191 @@ -179,18 +179,18 @@
   1.192    <sect1>
   1.193      <title>Trends in the field</title>
   1.194  
   1.195 -    <para>There has been an unmistakable trend in the development and
   1.196 +    <para id="x_89">There has been an unmistakable trend in the development and
   1.197        use of revision control tools over the past four decades, as
   1.198        people have become familiar with the capabilities of their tools
   1.199        and constrained by their limitations.</para>
   1.200  
   1.201 -    <para>The first generation began by managing single files on
   1.202 +    <para id="x_8a">The first generation began by managing single files on
   1.203        individual computers.  Although these tools represented a huge
   1.204        advance over ad-hoc manual revision control, their locking model
   1.205        and reliance on a single computer limited them to small,
   1.206        tightly-knit teams.</para>
   1.207  
   1.208 -    <para>The second generation loosened these constraints by moving
   1.209 +    <para id="x_8b">The second generation loosened these constraints by moving
   1.210        to network-centered architectures, and managing entire projects
   1.211        at a time.  As projects grew larger, they ran into new problems.
   1.212        With clients needing to talk to servers very frequently, server
   1.213 @@ -202,7 +202,7 @@
   1.214        tools to interact with a project in a natural way, as they could
   1.215        not record their changes.</para>
   1.216  
   1.217 -    <para>The current generation of revision control tools is
   1.218 +    <para id="x_8c">The current generation of revision control tools is
   1.219        peer-to-peer in nature.  All of these systems have dropped the
   1.220        dependency on a single central server, and allow people to
   1.221        distribute their revision control data to where it's actually
   1.222 @@ -217,14 +217,14 @@
   1.223      <title>A few of the advantages of distributed revision
   1.224        control</title>
   1.225  
   1.226 -    <para>Even though distributed revision control tools have for
   1.227 +    <para id="x_8d">Even though distributed revision control tools have for
   1.228        several years been as robust and usable as their
   1.229        previous-generation counterparts, people using older tools have
   1.230        not yet necessarily woken up to their advantages.  There are a
   1.231        number of ways in which distributed tools shine relative to
   1.232        centralised ones.</para>
   1.233  
   1.234 -    <para>For an individual developer, distributed tools are almost
   1.235 +    <para id="x_8e">For an individual developer, distributed tools are almost
   1.236        always much faster than centralised tools.  This is for a simple
   1.237        reason: a centralised tool needs to talk over the network for
   1.238        many common operations, because most metadata is stored in a
   1.239 @@ -235,7 +235,7 @@
   1.240        going to spend a lot of time interacting with your revision
   1.241        control software.</para>
   1.242  
   1.243 -    <para>Distributed tools are indifferent to the vagaries of your
   1.244 +    <para id="x_8f">Distributed tools are indifferent to the vagaries of your
   1.245        server infrastructure, again because they replicate metadata to
   1.246        so many locations.  If you use a centralised system and your
   1.247        server catches fire, you'd better hope that your backup media
   1.248 @@ -243,7 +243,7 @@
   1.249        worked.  With a distributed tool, you have many backups
   1.250        available on every contributor's computer.</para>
   1.251  
   1.252 -    <para>The reliability of your network will affect distributed
   1.253 +    <para id="x_90">The reliability of your network will affect distributed
   1.254        tools far less than it will centralised tools.  You can't even
   1.255        use a centralised tool without a network connection, except for
   1.256        a few highly constrained commands.  With a distributed tool, if
   1.257 @@ -256,7 +256,7 @@
   1.258      <sect2>
   1.259        <title>Advantages for open source projects</title>
   1.260  
   1.261 -      <para>If you take a shine to an open source project and decide
   1.262 +      <para id="x_91">If you take a shine to an open source project and decide
   1.263  	that you would like to start hacking on it, and that project
   1.264  	uses a distributed revision control tool, you are at once a
   1.265  	peer with the people who consider themselves the
   1.266 @@ -274,7 +274,7 @@
   1.267        <sect3>
   1.268  	<title>The forking non-problem</title>
   1.269  
   1.270 -	<para>It has been suggested that distributed revision control
   1.271 +	<para id="x_92">It has been suggested that distributed revision control
   1.272  	  tools pose some sort of risk to open source projects because
   1.273  	  they make it easy to <quote>fork</quote> the development of
   1.274  	  a project.  A fork happens when there are differences in
   1.275 @@ -284,7 +284,7 @@
   1.276  	  project's source code, and goes off in its own
   1.277  	  direction.</para>
   1.278  
   1.279 -	<para>Sometimes the camps in a fork decide to reconcile their
   1.280 +	<para id="x_93">Sometimes the camps in a fork decide to reconcile their
   1.281  	  differences. With a centralised revision control system, the
   1.282  	  <emphasis>technical</emphasis> process of reconciliation is
   1.283  	  painful, and has to be performed largely by hand.  You have
   1.284 @@ -293,7 +293,7 @@
   1.285  	  the tree somehow. This usually loses some or all of one
   1.286  	  side's revision history.</para>
   1.287  
   1.288 -	<para>What distributed tools do with respect to forking is
   1.289 +	<para id="x_94">What distributed tools do with respect to forking is
   1.290  	  they make forking the <emphasis>only</emphasis> way to
   1.291  	  develop a project.  Every single change that you make is
   1.292  	  potentially a fork point.  The great strength of this
   1.293 @@ -302,23 +302,23 @@
   1.294  	  because forks are absolutely fundamental: they happen all
   1.295  	  the time.</para>
   1.296  
   1.297 -	<para>If every piece of work that everybody does, all the
   1.298 +	<para id="x_95">If every piece of work that everybody does, all the
   1.299  	  time, is framed in terms of forking and merging, then what
   1.300  	  the open source world refers to as a <quote>fork</quote>
   1.301  	  becomes <emphasis>purely</emphasis> a social issue.  If
   1.302  	  anything, distributed tools <emphasis>lower</emphasis> the
   1.303  	  likelihood of a fork:</para>
   1.304  	<itemizedlist>
   1.305 -	  <listitem><para>They eliminate the social distinction that
   1.306 +	  <listitem><para id="x_96">They eliminate the social distinction that
   1.307  	      centralised tools impose: that between insiders (people
   1.308  	      with commit access) and outsiders (people
   1.309  	      without).</para></listitem>
   1.310 -	  <listitem><para>They make it easier to reconcile after a
   1.311 +	  <listitem><para id="x_97">They make it easier to reconcile after a
   1.312  	      social fork, because all that's involved from the
   1.313  	      perspective of the revision control software is just
   1.314  	      another merge.</para></listitem></itemizedlist>
   1.315  
   1.316 -	<para>Some people resist distributed tools because they want
   1.317 +	<para id="x_98">Some people resist distributed tools because they want
   1.318  	  to retain tight control over their projects, and they
   1.319  	  believe that centralised tools give them this control.
   1.320  	  However, if you're of this belief, and you publish your CVS
   1.321 @@ -335,7 +335,7 @@
   1.322      <sect2>
   1.323        <title>Advantages for commercial projects</title>
   1.324  
   1.325 -      <para>Many commercial projects are undertaken by teams that are
   1.326 +      <para id="x_99">Many commercial projects are undertaken by teams that are
   1.327  	scattered across the globe.  Contributors who are far from a
   1.328  	central server will see slower command execution and perhaps
   1.329  	less reliability.  Commercial revision control systems attempt
   1.330 @@ -347,7 +347,7 @@
   1.331  	there's no redundant communication between repositories over
   1.332  	expensive long-haul network links.</para>
   1.333  
   1.334 -      <para>Centralised revision control systems tend to have
   1.335 +      <para id="x_9a">Centralised revision control systems tend to have
   1.336  	relatively low scalability.  It's not unusual for an expensive
   1.337  	centralised system to fall over under the combined load of
   1.338  	just a few dozen concurrent users.  Once again, the typical
   1.339 @@ -359,7 +359,7 @@
   1.340  	replication to balance load becomes a simple matter of
   1.341  	scripting.</para>
   1.342  
   1.343 -      <para>If you have an employee in the field, troubleshooting a
   1.344 +      <para id="x_9b">If you have an employee in the field, troubleshooting a
   1.345  	problem at a customer's site, they'll benefit from distributed
   1.346  	revision control. The tool will let them generate custom
   1.347  	builds, try different fixes in isolation from each other, and
   1.348 @@ -372,35 +372,35 @@
   1.349    <sect1>
   1.350      <title>Why choose Mercurial?</title>
   1.351  
   1.352 -    <para>Mercurial has a unique set of properties that make it a
   1.353 +    <para id="x_9c">Mercurial has a unique set of properties that make it a
   1.354        particularly good choice as a revision control system.</para>
   1.355      <itemizedlist>
   1.356 -      <listitem><para>It is easy to learn and use.</para></listitem>
   1.357 -      <listitem><para>It is lightweight.</para></listitem>
   1.358 -      <listitem><para>It scales excellently.</para></listitem>
   1.359 -      <listitem><para>It is easy to
   1.360 +      <listitem><para id="x_9d">It is easy to learn and use.</para></listitem>
   1.361 +      <listitem><para id="x_9e">It is lightweight.</para></listitem>
   1.362 +      <listitem><para id="x_9f">It scales excellently.</para></listitem>
   1.363 +      <listitem><para id="x_a0">It is easy to
   1.364  	  customise.</para></listitem></itemizedlist>
   1.365  
   1.366 -    <para>If you are at all familiar with revision control systems,
   1.367 +    <para id="x_a1">If you are at all familiar with revision control systems,
   1.368        you should be able to get up and running with Mercurial in less
   1.369        than five minutes.  Even if not, it will take no more than a few
   1.370        minutes longer.  Mercurial's command and feature sets are
   1.371        generally uniform and consistent, so you can keep track of a few
   1.372        general rules instead of a host of exceptions.</para>
   1.373  
   1.374 -    <para>On a small project, you can start working with Mercurial in
   1.375 +    <para id="x_a2">On a small project, you can start working with Mercurial in
   1.376        moments. Creating new changes and branches; transferring changes
   1.377        around (whether locally or over a network); and history and
   1.378        status operations are all fast.  Mercurial attempts to stay
   1.379        nimble and largely out of your way by combining low cognitive
   1.380        overhead with blazingly fast operations.</para>
   1.381  
   1.382 -    <para>The usefulness of Mercurial is not limited to small
   1.383 +    <para id="x_a3">The usefulness of Mercurial is not limited to small
   1.384        projects: it is used by projects with hundreds to thousands of
   1.385        contributors, each containing tens of thousands of files and
   1.386        hundreds of megabytes of source code.</para>
   1.387  
   1.388 -    <para>If the core functionality of Mercurial is not enough for
   1.389 +    <para id="x_a4">If the core functionality of Mercurial is not enough for
   1.390        you, it's easy to build on.  Mercurial is well suited to
   1.391        scripting tasks, and its clean internals and implementation in
   1.392        Python make it easy to add features in the form of extensions.
   1.393 @@ -412,7 +412,7 @@
   1.394    <sect1>
   1.395      <title>Mercurial compared with other tools</title>
   1.396  
   1.397 -    <para>Before you read on, please understand that this section
   1.398 +    <para id="x_a5">Before you read on, please understand that this section
   1.399        necessarily reflects my own experiences, interests, and (dare I
   1.400        say it) biases.  I have used every one of the revision control
   1.401        tools listed below, in most cases for several years at a
   1.402 @@ -422,22 +422,22 @@
   1.403      <sect2>
   1.404        <title>Subversion</title>
   1.405  
   1.406 -      <para>Subversion is a popular revision control tool, developed
   1.407 +      <para id="x_a6">Subversion is a popular revision control tool, developed
   1.408  	to replace CVS.  It has a centralised client/server
   1.409  	architecture.</para>
   1.410  
   1.411 -      <para>Subversion and Mercurial have similarly named commands for
   1.412 +      <para id="x_a7">Subversion and Mercurial have similarly named commands for
   1.413  	performing the same operations, so if you're familiar with
   1.414  	one, it is easy to learn to use the other.  Both tools are
   1.415  	portable to all popular operating systems.</para>
   1.416  
   1.417 -      <para>Prior to version 1.5, Subversion had no useful support for
   1.418 +      <para id="x_a8">Prior to version 1.5, Subversion had no useful support for
   1.419  	merges. At the time of writing, its merge tracking capability
   1.420  	is new, and known to be <ulink
   1.421  	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
   1.422  	  and buggy</ulink>.</para>
   1.423  
   1.424 -      <para>Mercurial has a substantial performance advantage over
   1.425 +      <para id="x_a9">Mercurial has a substantial performance advantage over
   1.426  	Subversion on every revision control operation I have
   1.427  	benchmarked.  I have measured its advantage as ranging from a
   1.428  	factor of two to a factor of six when compared with Subversion
   1.429 @@ -450,7 +450,7 @@
   1.430  	and network bandwidth become bottlenecks for modestly large
   1.431  	projects.</para>
   1.432  
   1.433 -      <para>Additionally, Subversion incurs substantial storage
   1.434 +      <para id="x_aa">Additionally, Subversion incurs substantial storage
   1.435  	overhead to avoid network transactions for a few common
   1.436  	operations, such as finding modified files
   1.437  	(<literal>status</literal>) and displaying modifications
   1.438 @@ -460,13 +460,13 @@
   1.439  	even though the Mercurial repository contains a complete
   1.440  	history of the project.</para>
   1.441  
   1.442 -      <para>Subversion is widely supported by third party tools.
   1.443 +      <para id="x_ab">Subversion is widely supported by third party tools.
   1.444  	Mercurial currently lags considerably in this area.  This gap
   1.445  	is closing, however, and indeed some of Mercurial's GUI tools
   1.446  	now outshine their Subversion equivalents.  Like Mercurial,
   1.447  	Subversion has an excellent user manual.</para>
   1.448  
   1.449 -      <para>Because Subversion doesn't store revision history on the
   1.450 +      <para id="x_ac">Because Subversion doesn't store revision history on the
   1.451  	client, it is well suited to managing projects that deal with
   1.452  	lots of large, opaque binary files.  If you check in fifty
   1.453  	revisions to an incompressible 10MB file, Subversion's
   1.454 @@ -475,14 +475,14 @@
   1.455  	of revisions, because the differences between each revision
   1.456  	are large.</para>
   1.457  
   1.458 -      <para>In addition, it's often difficult or, more usually,
   1.459 +      <para id="x_ad">In addition, it's often difficult or, more usually,
   1.460  	impossible to merge different versions of a binary file.
   1.461  	Subversion's ability to let a user lock a file, so that they
   1.462  	temporarily have the exclusive right to commit changes to it,
   1.463  	can be a significant advantage to a project where binary files
   1.464  	are widely used.</para>
   1.465  
   1.466 -      <para>Mercurial can import revision history from a Subversion
   1.467 +      <para id="x_ae">Mercurial can import revision history from a Subversion
   1.468  	repository. It can also export revision history to a
   1.469  	Subversion repository.  This makes it easy to <quote>test the
   1.470  	  waters</quote> and use Mercurial and Subversion in parallel
   1.471 @@ -496,24 +496,24 @@
   1.472      <sect2>
   1.473        <title>Git</title>
   1.474  
   1.475 -      <para>Git is a distributed revision control tool that was
   1.476 +      <para id="x_af">Git is a distributed revision control tool that was
   1.477  	developed for managing the Linux kernel source tree.  Like
   1.478  	Mercurial, its early design was somewhat influenced by
   1.479  	Monotone.</para>
   1.480  
   1.481 -      <para>Git has a very large command set, with version 1.5.0
   1.482 +      <para id="x_b0">Git has a very large command set, with version 1.5.0
   1.483  	providing 139 individual commands.  It has something of a
   1.484  	reputation for being difficult to learn.  Compared to Git,
   1.485  	Mercurial has a strong focus on simplicity.</para>
   1.486  
   1.487 -      <para>In terms of performance, Git is extremely fast.  In
   1.488 +      <para id="x_b1">In terms of performance, Git is extremely fast.  In
   1.489  	several cases, it is faster than Mercurial, at least on Linux,
   1.490  	while Mercurial performs better on other operations.  However,
   1.491  	on Windows, the performance and general level of support that
   1.492  	Git provides is, at the time of writing, far behind that of
   1.493  	Mercurial.</para>
   1.494  
   1.495 -      <para>While a Mercurial repository needs no maintenance, a Git
   1.496 +      <para id="x_b2">While a Mercurial repository needs no maintenance, a Git
   1.497  	repository requires frequent manual <quote>repacks</quote> of
   1.498  	its metadata.  Without these, performance degrades, while
   1.499  	space usage grows rapidly.  A server that contains many Git
   1.500 @@ -524,13 +524,13 @@
   1.501  	slightly smaller than a Mercurial repository, but an unpacked
   1.502  	repository is several orders of magnitude larger.</para>
   1.503  
   1.504 -      <para>The core of Git is written in C.  Many Git commands are
   1.505 +      <para id="x_b3">The core of Git is written in C.  Many Git commands are
   1.506  	implemented as shell or Perl scripts, and the quality of these
   1.507  	scripts varies widely. I have encountered several instances
   1.508  	where scripts charged along blindly in the presence of errors
   1.509  	that should have been fatal.</para>
   1.510  
   1.511 -      <para>Mercurial can import revision history from a Git
   1.512 +      <para id="x_b4">Mercurial can import revision history from a Git
   1.513  	repository.</para>
   1.514  
   1.515  
   1.516 @@ -538,11 +538,11 @@
   1.517      <sect2>
   1.518        <title>CVS</title>
   1.519  
   1.520 -      <para>CVS is probably the most widely used revision control tool
   1.521 +      <para id="x_b5">CVS is probably the most widely used revision control tool
   1.522  	in the world.  Due to its age and internal untidiness, it has
   1.523  	been only lightly maintained for many years.</para>
   1.524  
   1.525 -      <para>It has a centralised client/server architecture.  It does
   1.526 +      <para id="x_b6">It has a centralised client/server architecture.  It does
   1.527  	not group related file changes into atomic commits, making it
   1.528  	easy for people to <quote>break the build</quote>: one person
   1.529  	can successfully commit part of a change and then be blocked
   1.530 @@ -554,7 +554,7 @@
   1.531  	the changes made to each file involved (if you even know what
   1.532  	those files were).</para>
   1.533  
   1.534 -      <para>CVS has a muddled notion of tags and branches that I will
   1.535 +      <para id="x_b7">CVS has a muddled notion of tags and branches that I will
   1.536  	not attempt to even describe.  It does not support renaming of
   1.537  	files or directories well, making it easy to corrupt a
   1.538  	repository.  It has almost no internal consistency checking
   1.539 @@ -562,7 +562,7 @@
   1.540  	whether or how a repository is corrupt.  I would not recommend
   1.541  	CVS for any project, existing or new.</para>
   1.542  
   1.543 -      <para>Mercurial can import CVS revision history.  However, there
   1.544 +      <para id="x_b8">Mercurial can import CVS revision history.  However, there
   1.545  	are a few caveats that apply; these are true of every other
   1.546  	revision control tool's CVS importer, too.  Due to CVS's lack
   1.547  	of atomic changes and unversioned filesystem hierarchy, it is
   1.548 @@ -576,7 +576,7 @@
   1.549  	the less interesting problems I can recall from personal
   1.550  	experience).</para>
   1.551  
   1.552 -      <para>Mercurial can import revision history from a CVS
   1.553 +      <para id="x_b9">Mercurial can import revision history from a CVS
   1.554  	repository.</para>
   1.555  
   1.556  
   1.557 @@ -584,13 +584,13 @@
   1.558      <sect2>
   1.559        <title>Commercial tools</title>
   1.560  
   1.561 -      <para>Perforce has a centralised client/server architecture,
   1.562 +      <para id="x_ba">Perforce has a centralised client/server architecture,
   1.563  	with no client-side caching of any data.  Unlike modern
   1.564  	revision control tools, Perforce requires that a user run a
   1.565  	command to inform the server about every file they intend to
   1.566  	edit.</para>
   1.567  
   1.568 -      <para>The performance of Perforce is quite good for small teams,
   1.569 +      <para id="x_bb">The performance of Perforce is quite good for small teams,
   1.570  	but it falls off rapidly as the number of users grows beyond a
   1.571  	few dozen. Modestly large Perforce installations require the
   1.572  	deployment of proxies to cope with the load their users
   1.573 @@ -601,16 +601,16 @@
   1.574      <sect2>
   1.575        <title>Choosing a revision control tool</title>
   1.576  
   1.577 -      <para>With the exception of CVS, all of the tools listed above
   1.578 +      <para id="x_bc">With the exception of CVS, all of the tools listed above
   1.579  	have unique strengths that suit them to particular styles of
   1.580  	work.  There is no single revision control tool that is best
   1.581  	in all situations.</para>
   1.582  
   1.583 -      <para>As an example, Subversion is a good choice for working
   1.584 +      <para id="x_bd">As an example, Subversion is a good choice for working
   1.585  	with frequently edited binary files, due to its centralised
   1.586  	nature and support for file locking.</para>
   1.587  
   1.588 -      <para>I personally find Mercurial's properties of simplicity,
   1.589 +      <para id="x_be">I personally find Mercurial's properties of simplicity,
   1.590  	performance, and good merge support to be a compelling
   1.591  	combination that has served me well for several years.</para>
   1.592  
   1.593 @@ -620,7 +620,7 @@
   1.594    <sect1>
   1.595      <title>Switching from another tool to Mercurial</title>
   1.596  
   1.597 -    <para>Mercurial is bundled with an extension named <literal
   1.598 +    <para id="x_bf">Mercurial is bundled with an extension named <literal
   1.599  	role="hg-ext">convert</literal>, which can incrementally
   1.600        import revision history from several other revision control
   1.601        tools.  By <quote>incremental</quote>, I mean that you can
   1.602 @@ -628,21 +628,21 @@
   1.603        the conversion later to obtain new changes that happened after
   1.604        the initial conversion.</para>
   1.605  
   1.606 -    <para>The revision control tools supported by <literal
   1.607 +    <para id="x_c0">The revision control tools supported by <literal
   1.608  	role="hg-ext">convert</literal> are as follows:</para>
   1.609      <itemizedlist>
   1.610 -      <listitem><para>Subversion</para></listitem>
   1.611 -      <listitem><para>CVS</para></listitem>
   1.612 -      <listitem><para>Git</para></listitem>
   1.613 -      <listitem><para>Darcs</para></listitem></itemizedlist>
   1.614 -
   1.615 -    <para>In addition, <literal role="hg-ext">convert</literal> can
   1.616 +      <listitem><para id="x_c1">Subversion</para></listitem>
   1.617 +      <listitem><para id="x_c2">CVS</para></listitem>
   1.618 +      <listitem><para id="x_c3">Git</para></listitem>
   1.619 +      <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist>
   1.620 +
   1.621 +    <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can
   1.622        export changes from Mercurial to Subversion.  This makes it
   1.623        possible to try Subversion and Mercurial in parallel before
   1.624        committing to a switchover, without risking the loss of any
   1.625        work.</para>
   1.626  
   1.627 -    <para>The <command role="hg-ext-convert">convert</command> command
   1.628 +    <para id="x_c6">The <command role="hg-ext-convert">convert</command> command
   1.629        is easy to use.  Simply point it at the path or URL of the
   1.630        source repository, optionally give it the name of the
   1.631        destination repository, and it will start working.  After the
   1.632 @@ -653,7 +653,7 @@
   1.633    <sect1>
   1.634      <title>A short history of revision control</title>
   1.635  
   1.636 -    <para>The best known of the old-time revision control tools is
   1.637 +    <para id="x_c7">The best known of the old-time revision control tools is
   1.638        SCCS (Source Code Control System), which Marc Rochkind wrote at
   1.639        Bell Labs, in the early 1970s.  SCCS operated on individual
   1.640        files, and required every person working on a project to have
   1.641 @@ -664,13 +664,13 @@
   1.642        modifying those files without the help of an
   1.643        administrator.</para>
   1.644  
   1.645 -    <para>Walter Tichy developed a free alternative to SCCS in the
   1.646 +    <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the
   1.647        early 1980s; he called his program RCS (Revision Control System).
   1.648        Like SCCS, RCS required developers to work in a single shared
   1.649        workspace, and to lock files to prevent multiple people from
   1.650        modifying them simultaneously.</para>
   1.651  
   1.652 -    <para>Later in the 1980s, Dick Grune used RCS as a building block
   1.653 +    <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block
   1.654        for a set of shell scripts he initially called cmt, but then
   1.655        renamed to CVS (Concurrent Versions System).  The big innovation
   1.656        of CVS was that it let developers work simultaneously and
   1.657 @@ -681,7 +681,7 @@
   1.658        their copies independently.  They had to merge their edits prior
   1.659        to committing changes to the central repository.</para>
   1.660  
   1.661 -    <para>Brian Berliner took Grune's original scripts and rewrote
   1.662 +    <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote
   1.663        them in C, releasing in 1989 the code that has since developed
   1.664        into the modern version of CVS.  CVS subsequently acquired the
   1.665        ability to operate over a network connection, giving it a
   1.666 @@ -692,14 +692,14 @@
   1.667        server is.  CVS has been enormously successful; it is probably
   1.668        the world's most widely used revision control system.</para>
   1.669  
   1.670 -    <para>In the early 1990s, Sun Microsystems developed an early
   1.671 +    <para id="x_cb">In the early 1990s, Sun Microsystems developed an early
   1.672        distributed revision control system, called TeamWare.  A
   1.673        TeamWare workspace contains a complete copy of the project's
   1.674        history.  TeamWare has no notion of a central repository.  (CVS
   1.675        relied upon RCS for its history storage; TeamWare used
   1.676        SCCS.)</para>
   1.677  
   1.678 -    <para>As the 1990s progressed, awareness grew of a number of
   1.679 +    <para id="x_cc">As the 1990s progressed, awareness grew of a number of
   1.680        problems with CVS.  It records simultaneous changes to multiple
   1.681        files individually, instead of grouping them together as a
   1.682        single logically atomic operation.  It does not manage its file
   1.683 @@ -709,7 +709,7 @@
   1.684  	level</quote> of fixing these architectural problems
   1.685        prohibitive.</para>
   1.686  
   1.687 -    <para>In 2001, Jim Blandy and Karl Fogel, two developers who had
   1.688 +    <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had
   1.689        worked on CVS, started a project to replace it with a tool that
   1.690        would have a better architecture and cleaner code.  The result,
   1.691        Subversion, does not stray from CVS's centralised client/server
   1.692 @@ -718,7 +718,7 @@
   1.693        generally better tool than CVS. Since its initial release, it
   1.694        has rapidly grown in popularity.</para>
   1.695  
   1.696 -    <para>More or less simultaneously, Graydon Hoare began working on
   1.697 +    <para id="x_ce">More or less simultaneously, Graydon Hoare began working on
   1.698        an ambitious distributed revision control system that he named
   1.699        Monotone. While Monotone addresses many of CVS's design flaws
   1.700        and has a peer-to-peer architecture, it goes beyond earlier (and
   1.701 @@ -727,7 +727,7 @@
   1.702        integral notion of <quote>trust</quote> for code from different
   1.703        sources.</para>
   1.704  
   1.705 -    <para>Mercurial began life in 2005.  While a few aspects of its
   1.706 +    <para id="x_cf">Mercurial began life in 2005.  While a few aspects of its
   1.707        design are influenced by Monotone, Mercurial focuses on ease of
   1.708        use, high performance, and scalability to very large
   1.709        projects.</para>
   1.710 @@ -737,12 +737,12 @@
   1.711    <sect1>
   1.712      <title>Colophon&emdash;this book is Free</title>
   1.713  
   1.714 -    <para>This book is licensed under the Open Publication License,
   1.715 +    <para id="x_d0">This book is licensed under the Open Publication License,
   1.716        and is produced entirely using Free Software tools.  It is
   1.717        typeset with DocBook XML.  Illustrations are drawn and rendered with
   1.718        <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
   1.719  
   1.720 -    <para>The complete source code for this book is published as a
   1.721 +    <para id="x_d1">The complete source code for this book is published as a
   1.722        Mercurial repository, at <ulink
   1.723  	url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
   1.724