1.1 --- a/en/ch08-undo.xml	Thu Mar 19 20:54:12 2009 -0700
     1.2 +++ b/en/ch08-undo.xml	Thu Mar 19 21:18:52 2009 -0700
     1.3 @@ -4,7 +4,7 @@
     1.4    <?dbhtml filename="finding-and-fixing-mistakes.html"?>
     1.5    <title>Finding and fixing mistakes</title>
     1.6  
     1.7 -  <para>To err might be human, but to really handle the consequences
     1.8 +  <para id="x_d2">To err might be human, but to really handle the consequences
     1.9      well takes a top-notch revision control system.  In this chapter,
    1.10      we'll discuss some of the techniques you can use when you find
    1.11      that a problem has crept into your project.  Mercurial has some
    1.12 @@ -17,7 +17,7 @@
    1.13      <sect2>
    1.14        <title>The accidental commit</title>
    1.15  
    1.16 -      <para>I have the occasional but persistent problem of typing
    1.17 +      <para id="x_d3">I have the occasional but persistent problem of typing
    1.18  	rather more quickly than I can think, which sometimes results
    1.19  	in me committing a changeset that is either incomplete or
    1.20  	plain wrong.  In my case, the usual kind of incomplete
    1.21 @@ -30,7 +30,7 @@
    1.22      <sect2 id="sec:undo:rollback">
    1.23        <title>Rolling back a transaction</title>
    1.24  
    1.25 -      <para>In section <xref linkend="sec:concepts:txn"/>, I mentioned
    1.26 +      <para id="x_d4">In section <xref linkend="sec:concepts:txn"/>, I mentioned
    1.27  	that Mercurial treats each modification of a repository as a
    1.28  	<emphasis>transaction</emphasis>.  Every time you commit a
    1.29  	changeset or pull changes from another repository, Mercurial
    1.30 @@ -40,20 +40,20 @@
    1.31  	section <xref linkend="sec:undo:rollback-after-push"/> for an
    1.32  	important caveat about the use of this command.)</para>
    1.33  
    1.34 -      <para>Here's a mistake that I often find myself making:
    1.35 +      <para id="x_d5">Here's a mistake that I often find myself making:
    1.36  	committing a change in which I've created a new file, but
    1.37  	forgotten to <command role="hg-cmd">hg add</command>
    1.38  	it.</para>
    1.39  
    1.40        &interaction.rollback.commit;
    1.41  
    1.42 -      <para>Looking at the output of <command role="hg-cmd">hg
    1.43 +      <para id="x_d6">Looking at the output of <command role="hg-cmd">hg
    1.44  	  status</command> after the commit immediately confirms the
    1.45  	error.</para>
    1.46  
    1.47        &interaction.rollback.status;
    1.48  
    1.49 -      <para>The commit captured the changes to the file
    1.50 +      <para id="x_d7">The commit captured the changes to the file
    1.51  	<filename>a</filename>, but not the new file
    1.52  	<filename>b</filename>.  If I were to push this changeset to a
    1.53  	repository that I shared with a colleague, the chances are
    1.54 @@ -62,14 +62,14 @@
    1.55  	repository when they pulled my changes.  I would thus become
    1.56  	the object of some indignation.</para>
    1.57  
    1.58 -      <para>However, luck is with me&emdash;I've caught my error
    1.59 +      <para id="x_d8">However, luck is with me&emdash;I've caught my error
    1.60  	before I pushed the changeset.  I use the <command
    1.61  	  role="hg-cmd">hg rollback</command> command, and Mercurial
    1.62  	makes that last changeset vanish.</para>
    1.63  
    1.64        &interaction.rollback.rollback;
    1.65  
    1.66 -      <para>Notice that the changeset is no longer present in the
    1.67 +      <para id="x_d9">Notice that the changeset is no longer present in the
    1.68  	repository's history, and the working directory once again
    1.69  	thinks that the file <filename>a</filename> is modified.  The
    1.70  	commit and rollback have left the working directory exactly as
    1.71 @@ -84,14 +84,14 @@
    1.72      <sect2>
    1.73        <title>The erroneous pull</title>
    1.74  
    1.75 -      <para>It's common practice with Mercurial to maintain separate
    1.76 +      <para id="x_da">It's common practice with Mercurial to maintain separate
    1.77  	development branches of a project in different repositories.
    1.78  	Your development team might have one shared repository for
    1.79  	your project's <quote>0.9</quote> release, and another,
    1.80  	containing different changes, for the <quote>1.0</quote>
    1.81  	release.</para>
    1.82  
    1.83 -      <para>Given this, you can imagine that the consequences could be
    1.84 +      <para id="x_db">Given this, you can imagine that the consequences could be
    1.85  	messy if you had a local <quote>0.9</quote> repository, and
    1.86  	accidentally pulled changes from the shared <quote>1.0</quote>
    1.87  	repository into it.  At worst, you could be paying
    1.88 @@ -103,7 +103,7 @@
    1.89  	see it pull a suspiciously large number of changes into the
    1.90  	repository.</para>
    1.91  
    1.92 -      <para>The <command role="hg-cmd">hg rollback</command> command
    1.93 +      <para id="x_dc">The <command role="hg-cmd">hg rollback</command> command
    1.94  	will work nicely to expunge all of the changesets that you
    1.95  	just pulled.  Mercurial groups all changes from one <command
    1.96  	  role="hg-cmd">hg pull</command> into a single transaction,
    1.97 @@ -114,7 +114,7 @@
    1.98      <sect2 id="sec:undo:rollback-after-push">
    1.99        <title>Rolling back is useless once you've pushed</title>
   1.100  
   1.101 -      <para>The value of the <command role="hg-cmd">hg
   1.102 +      <para id="x_dd">The value of the <command role="hg-cmd">hg
   1.103  	  rollback</command> command drops to zero once you've pushed
   1.104  	your changes to another repository.  Rolling back a change
   1.105  	makes it disappear entirely, but <emphasis>only</emphasis> in
   1.106 @@ -123,7 +123,7 @@
   1.107  	eliminates history, there's no way for the disappearance of a
   1.108  	change to propagate between repositories.</para>
   1.109  
   1.110 -      <para>If you've pushed a change to another
   1.111 +      <para id="x_de">If you've pushed a change to another
   1.112  	repository&emdash;particularly if it's a shared
   1.113  	repository&emdash;it has essentially <quote>escaped into the
   1.114  	  wild,</quote> and you'll have to recover from your mistake
   1.115 @@ -132,7 +132,7 @@
   1.116  	you pushed to, is that the changeset will reappear in your
   1.117  	repository.</para>
   1.118  
   1.119 -      <para>(If you absolutely know for sure that the change you want
   1.120 +      <para id="x_df">(If you absolutely know for sure that the change you want
   1.121  	to roll back is the most recent change in the repository that
   1.122  	you pushed to, <emphasis>and</emphasis> you know that nobody
   1.123  	else could have pulled it from that repository, you can roll
   1.124 @@ -146,7 +146,7 @@
   1.125      <sect2>
   1.126        <title>You can only roll back once</title>
   1.127  
   1.128 -      <para>Mercurial stores exactly one transaction in its
   1.129 +      <para id="x_e0">Mercurial stores exactly one transaction in its
   1.130  	transaction log; that transaction is the most recent one that
   1.131  	occurred in the repository. This means that you can only roll
   1.132  	back one transaction.  If you expect to be able to roll back
   1.133 @@ -155,7 +155,7 @@
   1.134  
   1.135        &interaction.rollback.twice;
   1.136  
   1.137 -      <para>Once you've rolled back one transaction in a repository,
   1.138 +      <para id="x_e1">Once you've rolled back one transaction in a repository,
   1.139  	you can't roll back again in that repository until you perform
   1.140  	another commit or pull.</para>
   1.141  
   1.142 @@ -164,7 +164,7 @@
   1.143    <sect1>
   1.144      <title>Reverting the mistaken change</title>
   1.145  
   1.146 -    <para>If you make a modification to a file, and decide that you
   1.147 +    <para id="x_e2">If you make a modification to a file, and decide that you
   1.148        really didn't want to change the file at all, and you haven't
   1.149        yet committed your changes, the <command role="hg-cmd">hg
   1.150  	revert</command> command is the one you'll need.  It looks at
   1.151 @@ -173,42 +173,42 @@
   1.152        changeset. (That's a long-winded way of saying that, in the
   1.153        normal case, it undoes your modifications.)</para>
   1.154  
   1.155 -    <para>Let's illustrate how the <command role="hg-cmd">hg
   1.156 +    <para id="x_e3">Let's illustrate how the <command role="hg-cmd">hg
   1.157  	revert</command> command works with yet another small example.
   1.158        We'll begin by modifying a file that Mercurial is already
   1.159        tracking.</para>
   1.160  
   1.161      &interaction.daily.revert.modify;
   1.162  
   1.163 -    <para>If we don't
   1.164 +    <para id="x_e4">If we don't
   1.165        want that change, we can simply <command role="hg-cmd">hg
   1.166  	revert</command> the file.</para>
   1.167  
   1.168        &interaction.daily.revert.unmodify;
   1.169  
   1.170 -    <para>The <command role="hg-cmd">hg revert</command> command
   1.171 +    <para id="x_e5">The <command role="hg-cmd">hg revert</command> command
   1.172        provides us with an extra degree of safety by saving our
   1.173        modified file with a <filename>.orig</filename>
   1.174        extension.</para>
   1.175  
   1.176      &interaction.daily.revert.status;
   1.177  
   1.178 -    <para>Here is a summary of the cases that the <command
   1.179 +    <para id="x_e6">Here is a summary of the cases that the <command
   1.180  	role="hg-cmd">hg revert</command> command can deal with.  We
   1.181        will describe each of these in more detail in the section that
   1.182        follows.</para>
   1.183      <itemizedlist>
   1.184 -      <listitem><para>If you modify a file, it will restore the file
   1.185 +      <listitem><para id="x_e7">If you modify a file, it will restore the file
   1.186  	  to its unmodified state.</para>
   1.187        </listitem>
   1.188 -      <listitem><para>If you <command role="hg-cmd">hg add</command> a
   1.189 +      <listitem><para id="x_e8">If you <command role="hg-cmd">hg add</command> a
   1.190  	  file, it will undo the <quote>added</quote> state of the
   1.191  	  file, but leave the file itself untouched.</para>
   1.192        </listitem>
   1.193 -      <listitem><para>If you delete a file without telling Mercurial,
   1.194 +      <listitem><para id="x_e9">If you delete a file without telling Mercurial,
   1.195  	  it will restore the file to its unmodified contents.</para>
   1.196        </listitem>
   1.197 -      <listitem><para>If you use the <command role="hg-cmd">hg
   1.198 +      <listitem><para id="x_ea">If you use the <command role="hg-cmd">hg
   1.199  	    remove</command> command to remove a file, it will undo
   1.200  	  the <quote>removed</quote> state of the file, and restore
   1.201  	  the file to its unmodified contents.</para>
   1.202 @@ -217,13 +217,13 @@
   1.203      <sect2 id="sec:undo:mgmt">
   1.204        <title>File management errors</title>
   1.205  
   1.206 -      <para>The <command role="hg-cmd">hg revert</command> command is
   1.207 +      <para id="x_eb">The <command role="hg-cmd">hg revert</command> command is
   1.208  	useful for more than just modified files.  It lets you reverse
   1.209  	the results of all of Mercurial's file management
   1.210  	commands&emdash;<command role="hg-cmd">hg add</command>,
   1.211  	<command role="hg-cmd">hg remove</command>, and so on.</para>
   1.212  
   1.213 -      <para>If you <command role="hg-cmd">hg add</command> a file,
   1.214 +      <para id="x_ec">If you <command role="hg-cmd">hg add</command> a file,
   1.215  	then decide that in fact you don't want Mercurial to track it,
   1.216  	use <command role="hg-cmd">hg revert</command> to undo the
   1.217  	add.  Don't worry; Mercurial will not modify the file in any
   1.218 @@ -231,7 +231,7 @@
   1.219  
   1.220        &interaction.daily.revert.add;
   1.221  
   1.222 -      <para>Similarly, if you ask Mercurial to <command
   1.223 +      <para id="x_ed">Similarly, if you ask Mercurial to <command
   1.224  	  role="hg-cmd">hg remove</command> a file, you can use
   1.225  	<command role="hg-cmd">hg revert</command> to restore it to
   1.226  	the contents it had as of the parent of the working directory.
   1.227 @@ -242,7 +242,7 @@
   1.228  
   1.229        &interaction.daily.revert.missing;
   1.230  
   1.231 -      <para>If you revert a <command role="hg-cmd">hg copy</command>,
   1.232 +      <para id="x_ee">If you revert a <command role="hg-cmd">hg copy</command>,
   1.233  	the copied-to file remains in your working directory
   1.234  	afterwards, untracked.  Since a copy doesn't affect the
   1.235  	copied-from file in any way, Mercurial doesn't do anything
   1.236 @@ -253,7 +253,7 @@
   1.237        <sect3>
   1.238  	<title>A slightly special case: reverting a rename</title>
   1.239  
   1.240 -	<para>If you <command role="hg-cmd">hg rename</command> a
   1.241 +	<para id="x_ef">If you <command role="hg-cmd">hg rename</command> a
   1.242  	  file, there is one small detail that you should remember.
   1.243  	  When you <command role="hg-cmd">hg revert</command> a
   1.244  	  rename, it's not enough to provide the name of the
   1.245 @@ -261,7 +261,7 @@
   1.246  
   1.247  	&interaction.daily.revert.rename;
   1.248  
   1.249 -	<para>As you can see from the output of <command
   1.250 +	<para id="x_f0">As you can see from the output of <command
   1.251  	    role="hg-cmd">hg status</command>, the renamed-to file is
   1.252  	  no longer identified as added, but the
   1.253  	  renamed-<emphasis>from</emphasis> file is still removed!
   1.254 @@ -270,22 +270,22 @@
   1.255  
   1.256  	&interaction.daily.revert.rename-orig;
   1.257  
   1.258 -	<para>So remember, to revert a <command role="hg-cmd">hg
   1.259 +	<para id="x_f1">So remember, to revert a <command role="hg-cmd">hg
   1.260  	    rename</command>, you must provide
   1.261  	  <emphasis>both</emphasis> the source and destination
   1.262  	  names.</para>
   1.263  
   1.264 -	<para>% TODO: the output doesn't look like it will be
   1.265 +	<para id="x_f2">% TODO: the output doesn't look like it will be
   1.266  	  removed!</para>
   1.267  
   1.268 -	<para>(By the way, if you rename a file, then modify the
   1.269 +	<para id="x_f3">(By the way, if you rename a file, then modify the
   1.270  	  renamed-to file, then revert both components of the rename,
   1.271  	  when Mercurial restores the file that was removed as part of
   1.272  	  the rename, it will be unmodified. If you need the
   1.273  	  modifications in the renamed-to file to show up in the
   1.274  	  renamed-from file, don't forget to copy them over.)</para>
   1.275  
   1.276 -	<para>These fiddly aspects of reverting a rename arguably
   1.277 +	<para id="x_f4">These fiddly aspects of reverting a rename arguably
   1.278  	  constitute a small bug in Mercurial.</para>
   1.279  
   1.280        </sect3>
   1.281 @@ -294,13 +294,13 @@
   1.282    <sect1>
   1.283      <title>Dealing with committed changes</title>
   1.284  
   1.285 -    <para>Consider a case where you have committed a change $a$, and
   1.286 +    <para id="x_f5">Consider a case where you have committed a change $a$, and
   1.287        another change $b$ on top of it; you then realise that change
   1.288        $a$ was incorrect.  Mercurial lets you <quote>back out</quote>
   1.289        an entire changeset automatically, and building blocks that let
   1.290        you reverse part of a changeset by hand.</para>
   1.291  
   1.292 -    <para>Before you read this section, here's something to keep in
   1.293 +    <para id="x_f6">Before you read this section, here's something to keep in
   1.294        mind: the <command role="hg-cmd">hg backout</command> command
   1.295        undoes changes by <emphasis>adding</emphasis> history, not by
   1.296        modifying or erasing it.  It's the right tool to use if you're
   1.297 @@ -311,7 +311,7 @@
   1.298      <sect2>
   1.299        <title>Backing out a changeset</title>
   1.300  
   1.301 -      <para>The <command role="hg-cmd">hg backout</command> command
   1.302 +      <para id="x_f7">The <command role="hg-cmd">hg backout</command> command
   1.303  	lets you <quote>undo</quote> the effects of an entire
   1.304  	changeset in an automated fashion.  Because Mercurial's
   1.305  	history is immutable, this command <emphasis>does
   1.306 @@ -320,14 +320,14 @@
   1.307  	<emphasis>reverses</emphasis> the effect of the to-be-undone
   1.308  	changeset.</para>
   1.309  
   1.310 -      <para>The operation of the <command role="hg-cmd">hg
   1.311 +      <para id="x_f8">The operation of the <command role="hg-cmd">hg
   1.312  	  backout</command> command is a little intricate, so let's
   1.313  	illustrate it with some examples.  First, we'll create a
   1.314  	repository with some simple changes.</para>
   1.315  
   1.316        &interaction.backout.init;
   1.317  
   1.318 -      <para>The <command role="hg-cmd">hg backout</command> command
   1.319 +      <para id="x_f9">The <command role="hg-cmd">hg backout</command> command
   1.320  	takes a single changeset ID as its argument; this is the
   1.321  	changeset to back out.  Normally, <command role="hg-cmd">hg
   1.322  	  backout</command> will drop you into a text editor to write
   1.323 @@ -340,12 +340,12 @@
   1.324      <sect2>
   1.325        <title>Backing out the tip changeset</title>
   1.326  
   1.327 -      <para>We're going to start by backing out the last changeset we
   1.328 +      <para id="x_fa">We're going to start by backing out the last changeset we
   1.329  	committed.</para>
   1.330  
   1.331        &interaction.backout.simple;
   1.332  
   1.333 -      <para>You can see that the second line from
   1.334 +      <para id="x_fb">You can see that the second line from
   1.335  	<filename>myfile</filename> is no longer present.  Taking a
   1.336  	look at the output of <command role="hg-cmd">hg log</command>
   1.337  	gives us an idea of what the <command role="hg-cmd">hg
   1.338 @@ -361,7 +361,7 @@
   1.339        <informalfigure id="fig:undo:backout">
   1.340  	<mediaobject><imageobject><imagedata
   1.341  				    fileref="undo-simple"/></imageobject><textobject><phrase>XXX 
   1.342 -	      add text</phrase></textobject><caption><para>Backing out
   1.343 +	      add text</phrase></textobject><caption><para id="x_fc">Backing out
   1.344  	      a change using the <command role="hg-cmd">hg
   1.345  		backout</command>
   1.346  	      command</para></caption></mediaobject>
   1.347 @@ -372,27 +372,27 @@
   1.348      <sect2>
   1.349        <title>Backing out a non-tip change</title>
   1.350  
   1.351 -      <para>If you want to back out a change other than the last one
   1.352 +      <para id="x_fd">If you want to back out a change other than the last one
   1.353  	you committed, pass the <option
   1.354  	  role="hg-opt-backout">--merge</option> option to the
   1.355  	<command role="hg-cmd">hg backout</command> command.</para>
   1.356  
   1.357        &interaction.backout.non-tip.clone;
   1.358  
   1.359 -      <para>This makes backing out any changeset a
   1.360 +      <para id="x_fe">This makes backing out any changeset a
   1.361  	<quote>one-shot</quote> operation that's usually simple and
   1.362  	fast.</para>
   1.363  
   1.364        &interaction.backout.non-tip.backout;
   1.365  
   1.366 -      <para>If you take a look at the contents of
   1.367 +      <para id="x_ff">If you take a look at the contents of
   1.368  	<filename>myfile</filename> after the backout finishes, you'll
   1.369  	see that the first and third changes are present, but not the
   1.370  	second.</para>
   1.371  
   1.372        &interaction.backout.non-tip.cat;
   1.373  
   1.374 -      <para>As the graphical history in figure <xref
   1.375 +      <para id="x_100">As the graphical history in figure <xref
   1.376  	  linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial
   1.377  	actually commits <emphasis>two</emphasis> changes in this kind
   1.378  	of situation (the box-shaped nodes are the ones that Mercurial
   1.379 @@ -403,19 +403,19 @@
   1.380  	the previous parent of the working directory, and commits the
   1.381  	result of the merge.</para>
   1.382  
   1.383 -      <para>% TODO: to me it looks like mercurial doesn't commit the
   1.384 +      <para id="x_101">% TODO: to me it looks like mercurial doesn't commit the
   1.385  	second merge automatically!</para>
   1.386  
   1.387        <informalfigure id="fig:undo:backout-non-tip">
   1.388  	<mediaobject><imageobject><imagedata
   1.389  				    fileref="undo-non-tip"/></imageobject><textobject><phrase>XXX 
   1.390 -	      add text</phrase></textobject><caption><para>Automated
   1.391 +	      add text</phrase></textobject><caption><para id="x_102">Automated
   1.392  	      backout of a non-tip change using the <command
   1.393  		role="hg-cmd">hg backout</command>
   1.394  	      command</para></caption></mediaobject>
   1.395        </informalfigure>
   1.396  
   1.397 -      <para>The result is that you end up <quote>back where you
   1.398 +      <para id="x_103">The result is that you end up <quote>back where you
   1.399  	  were</quote>, only with some extra history that undoes the
   1.400  	effect of the changeset you wanted to back out.</para>
   1.401  
   1.402 @@ -423,7 +423,7 @@
   1.403  	<title>Always use the <option
   1.404  	    role="hg-opt-backout">--merge</option> option</title>
   1.405  
   1.406 -	<para>In fact, since the <option
   1.407 +	<para id="x_104">In fact, since the <option
   1.408  	    role="hg-opt-backout">--merge</option> option will do the
   1.409  	  <quote>right thing</quote> whether or not the changeset
   1.410  	  you're backing out is the tip (i.e. it won't try to merge if
   1.411 @@ -436,7 +436,7 @@
   1.412      <sect2>
   1.413        <title>Gaining more control of the backout process</title>
   1.414  
   1.415 -      <para>While I've recommended that you always use the <option
   1.416 +      <para id="x_105">While I've recommended that you always use the <option
   1.417  	  role="hg-opt-backout">--merge</option> option when backing
   1.418  	out a change, the <command role="hg-cmd">hg backout</command>
   1.419  	command lets you decide how to merge a backout changeset.
   1.420 @@ -449,13 +449,13 @@
   1.421  
   1.422        &interaction.backout.manual.clone;
   1.423  
   1.424 -      <para>As with our
   1.425 +      <para id="x_106">As with our
   1.426  	earlier example, We'll commit a third changeset, then back out
   1.427  	its parent, and see what happens.</para>
   1.428  
   1.429        &interaction.backout.manual.backout;
   1.430  
   1.431 -      <para>Our new changeset is again a descendant of the changeset
   1.432 +      <para id="x_107">Our new changeset is again a descendant of the changeset
   1.433  	we backout out; it's thus a new head, <emphasis>not</emphasis>
   1.434  	a descendant of the changeset that was the tip.  The <command
   1.435  	  role="hg-cmd">hg backout</command> command was quite
   1.436 @@ -463,7 +463,7 @@
   1.437  
   1.438        &interaction.backout.manual.log;
   1.439  
   1.440 -      <para>Again, it's easier to see what has happened by looking at
   1.441 +      <para id="x_108">Again, it's easier to see what has happened by looking at
   1.442  	a graph of the revision history, in figure <xref
   1.443  	  linkend="fig:undo:backout-manual"/>.  This makes it clear
   1.444  	that when we use <command role="hg-cmd">hg backout</command>
   1.445 @@ -474,25 +474,25 @@
   1.446        <informalfigure id="fig:undo:backout-manual">
   1.447  	<mediaobject><imageobject><imagedata
   1.448  				    fileref="undo-manual"/></imageobject><textobject><phrase>XXX 
   1.449 -	      add text</phrase></textobject><caption><para>Backing out
   1.450 +	      add text</phrase></textobject><caption><para id="x_109">Backing out
   1.451  	      a change using the <command role="hg-cmd">hg
   1.452  		backout</command>
   1.453  	      command</para></caption></mediaobject>
   1.454  	
   1.455        </informalfigure>
   1.456  
   1.457 -      <para>After the <command role="hg-cmd">hg backout</command>
   1.458 +      <para id="x_10a">After the <command role="hg-cmd">hg backout</command>
   1.459  	command has completed, it leaves the new
   1.460  	<quote>backout</quote> changeset as the parent of the working
   1.461  	directory.</para>
   1.462  
   1.463        &interaction.backout.manual.parents;
   1.464  
   1.465 -      <para>Now we have two isolated sets of changes.</para>
   1.466 +      <para id="x_10b">Now we have two isolated sets of changes.</para>
   1.467  
   1.468        &interaction.backout.manual.heads;
   1.469  
   1.470 -      <para>Let's think about what we expect to see as the contents of
   1.471 +      <para id="x_10c">Let's think about what we expect to see as the contents of
   1.472  	<filename>myfile</filename> now.  The first change should be
   1.473  	present, because we've never backed it out.  The second change
   1.474  	should be missing, as that's the change we backed out.  Since
   1.475 @@ -502,19 +502,19 @@
   1.476  
   1.477        &interaction.backout.manual.cat;
   1.478  
   1.479 -      <para>To get the third change back into the file, we just do a
   1.480 +      <para id="x_10d">To get the third change back into the file, we just do a
   1.481  	normal merge of our two heads.</para>
   1.482  
   1.483        &interaction.backout.manual.merge;
   1.484  
   1.485 -      <para>Afterwards, the graphical history of our repository looks
   1.486 +      <para id="x_10e">Afterwards, the graphical history of our repository looks
   1.487  	like figure
   1.488  	<xref linkend="fig:undo:backout-manual-merge"/>.</para>
   1.489  
   1.490        <informalfigure id="fig:undo:backout-manual-merge">
   1.491  	<mediaobject><imageobject><imagedata
   1.492  				    fileref="undo-manual-merge"/></imageobject><textobject><phrase>XXX 
   1.493 -	      add text</phrase></textobject><caption><para>Manually
   1.494 +	      add text</phrase></textobject><caption><para id="x_10f">Manually
   1.495  	      merging a backout change</para></caption></mediaobject>
   1.496  	
   1.497        </informalfigure>
   1.498 @@ -524,43 +524,43 @@
   1.499        <title>Why <command role="hg-cmd">hg backout</command> works as
   1.500  	it does</title>
   1.501  
   1.502 -      <para>Here's a brief description of how the <command
   1.503 +      <para id="x_110">Here's a brief description of how the <command
   1.504  	  role="hg-cmd">hg backout</command> command works.</para>
   1.505        <orderedlist>
   1.506 -	<listitem><para>It ensures that the working directory is
   1.507 +	<listitem><para id="x_111">It ensures that the working directory is
   1.508  	    <quote>clean</quote>, i.e. that the output of <command
   1.509  	      role="hg-cmd">hg status</command> would be empty.</para>
   1.510  	</listitem>
   1.511 -	<listitem><para>It remembers the current parent of the working
   1.512 +	<listitem><para id="x_112">It remembers the current parent of the working
   1.513  	    directory.  Let's call this changeset
   1.514  	    <literal>orig</literal></para>
   1.515  	</listitem>
   1.516 -	<listitem><para>It does the equivalent of a <command
   1.517 +	<listitem><para id="x_113">It does the equivalent of a <command
   1.518  	      role="hg-cmd">hg update</command> to sync the working
   1.519  	    directory to the changeset you want to back out.  Let's
   1.520  	    call this changeset <literal>backout</literal></para>
   1.521  	</listitem>
   1.522 -	<listitem><para>It finds the parent of that changeset.  Let's
   1.523 +	<listitem><para id="x_114">It finds the parent of that changeset.  Let's
   1.524  	    call that changeset <literal>parent</literal>.</para>
   1.525  	</listitem>
   1.526 -	<listitem><para>For each file that the
   1.527 +	<listitem><para id="x_115">For each file that the
   1.528  	    <literal>backout</literal> changeset affected, it does the
   1.529  	    equivalent of a <command role="hg-cmd">hg revert -r
   1.530  	      parent</command> on that file, to restore it to the
   1.531  	    contents it had before that changeset was
   1.532  	    committed.</para>
   1.533  	</listitem>
   1.534 -	<listitem><para>It commits the result as a new changeset.
   1.535 +	<listitem><para id="x_116">It commits the result as a new changeset.
   1.536  	    This changeset has <literal>backout</literal> as its
   1.537  	    parent.</para>
   1.538  	</listitem>
   1.539 -	<listitem><para>If you specify <option
   1.540 +	<listitem><para id="x_117">If you specify <option
   1.541  	      role="hg-opt-backout">--merge</option> on the command
   1.542  	    line, it merges with <literal>orig</literal>, and commits
   1.543  	    the result of the merge.</para>
   1.544  	</listitem></orderedlist>
   1.545  
   1.546 -      <para>An alternative way to implement the <command
   1.547 +      <para id="x_118">An alternative way to implement the <command
   1.548  	  role="hg-cmd">hg backout</command> command would be to
   1.549  	<command role="hg-cmd">hg export</command> the
   1.550  	to-be-backed-out changeset as a diff, then use the <option
   1.551 @@ -570,14 +570,14 @@
   1.552  	sounds much simpler, but it would not work nearly as
   1.553  	well.</para>
   1.554  
   1.555 -      <para>The reason that <command role="hg-cmd">hg
   1.556 +      <para id="x_119">The reason that <command role="hg-cmd">hg
   1.557  	  backout</command> does an update, a commit, a merge, and
   1.558  	another commit is to give the merge machinery the best chance
   1.559  	to do a good job when dealing with all the changes
   1.560  	<emphasis>between</emphasis> the change you're backing out and
   1.561  	the current tip.</para>
   1.562  
   1.563 -      <para>If you're backing out a changeset that's 100 revisions
   1.564 +      <para id="x_11a">If you're backing out a changeset that's 100 revisions
   1.565  	back in your project's history, the chances that the
   1.566  	<command>patch</command> command will be able to apply a
   1.567  	reverse diff cleanly are not good, because intervening changes
   1.568 @@ -596,13 +596,13 @@
   1.569    <sect1 id="sec:undo:aaaiiieee">
   1.570      <title>Changes that should never have been</title>
   1.571  
   1.572 -    <para>Most of the time, the <command role="hg-cmd">hg
   1.573 +    <para id="x_11b">Most of the time, the <command role="hg-cmd">hg
   1.574  	backout</command> command is exactly what you need if you want
   1.575        to undo the effects of a change.  It leaves a permanent record
   1.576        of exactly what you did, both when committing the original
   1.577        changeset and when you cleaned up after it.</para>
   1.578  
   1.579 -    <para>On rare occasions, though, you may find that you've
   1.580 +    <para id="x_11c">On rare occasions, though, you may find that you've
   1.581        committed a change that really should not be present in the
   1.582        repository at all.  For example, it would be very unusual, and
   1.583        usually considered a mistake, to commit a software project's
   1.584 @@ -611,12 +611,12 @@
   1.585        so they increase the size of the repository and the amount of
   1.586        time it takes to clone or pull changes.</para>
   1.587  
   1.588 -    <para>Before I discuss the options that you have if you commit a
   1.589 +    <para id="x_11d">Before I discuss the options that you have if you commit a
   1.590        <quote>brown paper bag</quote> change (the kind that's so bad
   1.591        that you want to pull a brown paper bag over your head), let me
   1.592        first discuss some approaches that probably won't work.</para>
   1.593  
   1.594 -    <para>Since Mercurial treats history as accumulative&emdash;every
   1.595 +    <para id="x_11e">Since Mercurial treats history as accumulative&emdash;every
   1.596        change builds on top of all changes that preceded it&emdash;you
   1.597        generally can't just make disastrous changes disappear.  The one
   1.598        exception is when you've just committed a change, and it hasn't
   1.599 @@ -625,7 +625,7 @@
   1.600        command, as I detailed in section <xref
   1.601  	linkend="sec:undo:rollback"/>.</para>
   1.602  
   1.603 -    <para>After you've pushed a bad change to another repository, you
   1.604 +    <para id="x_11f">After you've pushed a bad change to another repository, you
   1.605        <emphasis>could</emphasis> still use <command role="hg-cmd">hg
   1.606  	rollback</command> to make your local copy of the change
   1.607        disappear, but it won't have the consequences you want.  The
   1.608 @@ -633,7 +633,7 @@
   1.609        will reappear in your local repository the next time you
   1.610        pull.</para>
   1.611  
   1.612 -    <para>If a situation like this arises, and you know which
   1.613 +    <para id="x_120">If a situation like this arises, and you know which
   1.614        repositories your bad change has propagated into, you can
   1.615        <emphasis>try</emphasis> to get rid of the changeefrom
   1.616        <emphasis>every</emphasis> one of those repositories.  This is,
   1.617 @@ -641,13 +641,13 @@
   1.618        single repository while you're expunging, the change is still
   1.619        <quote>in the wild</quote>, and could propagate further.</para>
   1.620  
   1.621 -    <para>If you've committed one or more changes
   1.622 +    <para id="x_121">If you've committed one or more changes
   1.623        <emphasis>after</emphasis> the change that you'd like to see
   1.624        disappear, your options are further reduced. Mercurial doesn't
   1.625        provide a way to <quote>punch a hole</quote> in history, leaving
   1.626        changesets intact.</para>
   1.627  
   1.628 -    <para>XXX This needs filling out.  The
   1.629 +    <para id="x_122">XXX This needs filling out.  The
   1.630        <literal>hg-replay</literal> script in the
   1.631        <literal>examples</literal> directory works, but doesn't handle
   1.632        merge changesets.  Kind of an important omission.</para>
   1.633 @@ -656,14 +656,14 @@
   1.634        <title>Protect yourself from <quote>escaped</quote>
   1.635  	changes</title>
   1.636  
   1.637 -      <para>If you've committed some changes to your local repository
   1.638 +      <para id="x_123">If you've committed some changes to your local repository
   1.639  	and they've been pushed or pulled somewhere else, this isn't
   1.640  	necessarily a disaster.  You can protect yourself ahead of
   1.641  	time against some classes of bad changeset.  This is
   1.642  	particularly easy if your team usually pulls changes from a
   1.643  	central repository.</para>
   1.644  
   1.645 -      <para>By configuring some hooks on that repository to validate
   1.646 +      <para id="x_124">By configuring some hooks on that repository to validate
   1.647  	incoming changesets (see chapter <xref linkend="chap:hook"/>),
   1.648  	you can
   1.649  	automatically prevent some kinds of bad changeset from being
   1.650 @@ -673,7 +673,7 @@
   1.651  	propagate into the central repository.  Better yet, this
   1.652  	happens without any need for explicit intervention.</para>
   1.653  
   1.654 -      <para>For instance, an incoming change hook that verifies that a
   1.655 +      <para id="x_125">For instance, an incoming change hook that verifies that a
   1.656  	changeset will actually compile can prevent people from
   1.657  	inadvertantly <quote>breaking the build</quote>.</para>
   1.658  
   1.659 @@ -682,14 +682,14 @@
   1.660    <sect1 id="sec:undo:bisect">
   1.661      <title>Finding the source of a bug</title>
   1.662  
   1.663 -    <para>While it's all very well to be able to back out a changeset
   1.664 +    <para id="x_126">While it's all very well to be able to back out a changeset
   1.665        that introduced a bug, this requires that you know which
   1.666        changeset to back out.  Mercurial provides an invaluable
   1.667        command, called <command role="hg-cmd">hg bisect</command>, that
   1.668        helps you to automate this process and accomplish it very
   1.669        efficiently.</para>
   1.670  
   1.671 -    <para>The idea behind the <command role="hg-cmd">hg
   1.672 +    <para id="x_127">The idea behind the <command role="hg-cmd">hg
   1.673  	bisect</command> command is that a changeset has introduced
   1.674        some change of behaviour that you can identify with a simple
   1.675        binary test.  You don't know which piece of code introduced the
   1.676 @@ -698,41 +698,41 @@
   1.677        test to direct its search for the changeset that introduced the
   1.678        code that caused the bug.</para>
   1.679  
   1.680 -    <para>Here are a few scenarios to help you understand how you
   1.681 +    <para id="x_128">Here are a few scenarios to help you understand how you
   1.682        might apply this command.</para>
   1.683      <itemizedlist>
   1.684 -      <listitem><para>The most recent version of your software has a
   1.685 +      <listitem><para id="x_129">The most recent version of your software has a
   1.686  	  bug that you remember wasn't present a few weeks ago, but
   1.687  	  you don't know when it was introduced.  Here, your binary
   1.688  	  test checks for the presence of that bug.</para>
   1.689        </listitem>
   1.690 -      <listitem><para>You fixed a bug in a rush, and now it's time to
   1.691 +      <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to
   1.692  	  close the entry in your team's bug database.  The bug
   1.693  	  database requires a changeset ID when you close an entry,
   1.694  	  but you don't remember which changeset you fixed the bug in.
   1.695  	  Once again, your binary test checks for the presence of the
   1.696  	  bug.</para>
   1.697        </listitem>
   1.698 -      <listitem><para>Your software works correctly, but runs 15%
   1.699 +      <listitem><para id="x_12b">Your software works correctly, but runs 15%
   1.700  	  slower than the last time you measured it.  You want to know
   1.701  	  which changeset introduced the performance regression.  In
   1.702  	  this case, your binary test measures the performance of your
   1.703  	  software, to see whether it's <quote>fast</quote> or
   1.704  	  <quote>slow</quote>.</para>
   1.705        </listitem>
   1.706 -      <listitem><para>The sizes of the components of your project that
   1.707 +      <listitem><para id="x_12c">The sizes of the components of your project that
   1.708  	  you ship exploded recently, and you suspect that something
   1.709  	  changed in the way you build your project.</para>
   1.710        </listitem></itemizedlist>
   1.711  
   1.712 -    <para>From these examples, it should be clear that the <command
   1.713 +    <para id="x_12d">From these examples, it should be clear that the <command
   1.714  	role="hg-cmd">hg bisect</command> command is not useful only
   1.715        for finding the sources of bugs.  You can use it to find any
   1.716        <quote>emergent property</quote> of a repository (anything that
   1.717        you can't find from a simple text search of the files in the
   1.718        tree) for which you can write a binary test.</para>
   1.719  
   1.720 -    <para>We'll introduce a little bit of terminology here, just to
   1.721 +    <para id="x_12e">We'll introduce a little bit of terminology here, just to
   1.722        make it clear which parts of the search process are your
   1.723        responsibility, and which are Mercurial's.  A
   1.724        <emphasis>test</emphasis> is something that
   1.725 @@ -745,7 +745,7 @@
   1.726  	the <command role="hg-cmd">hg bisect</command>
   1.727  	command</quote>.</para>
   1.728  
   1.729 -    <para>One simple way to automate the searching process would be
   1.730 +    <para id="x_12f">One simple way to automate the searching process would be
   1.731        simply to probe every changeset.  However, this scales poorly.
   1.732        If it took ten minutes to test a single changeset, and you had
   1.733        10,000 changesets in your repository, the exhaustive approach
   1.734 @@ -755,7 +755,7 @@
   1.735        your search to those, you'd still be looking at over 40 hours to
   1.736        find the changeset that introduced your bug.</para>
   1.737  
   1.738 -    <para>What the <command role="hg-cmd">hg bisect</command> command
   1.739 +    <para id="x_130">What the <command role="hg-cmd">hg bisect</command> command
   1.740        does is use its knowledge of the <quote>shape</quote> of your
   1.741        project's revision history to perform a search in time
   1.742        proportional to the <emphasis>logarithm</emphasis> of the number
   1.743 @@ -766,7 +766,7 @@
   1.744        Limit your search to the last hundred changesets, and it will
   1.745        take only about an hour (roughly seven tests).</para>
   1.746  
   1.747 -    <para>The <command role="hg-cmd">hg bisect</command> command is
   1.748 +    <para id="x_131">The <command role="hg-cmd">hg bisect</command> command is
   1.749        aware of the <quote>branchy</quote> nature of a Mercurial
   1.750        project's revision history, so it has no problems dealing with
   1.751        branches, merges, or multiple heads in a repository.  It can
   1.752 @@ -777,24 +777,24 @@
   1.753        <title>Using the <command role="hg-cmd">hg bisect</command>
   1.754  	command</title>
   1.755  
   1.756 -      <para>Here's an example of <command role="hg-cmd">hg
   1.757 +      <para id="x_132">Here's an example of <command role="hg-cmd">hg
   1.758  	  bisect</command> in action.</para>
   1.759  
   1.760        <note>
   1.761 -	<para>  In versions 0.9.5 and earlier of Mercurial, <command
   1.762 +	<para id="x_133">  In versions 0.9.5 and earlier of Mercurial, <command
   1.763  	    role="hg-cmd">hg bisect</command> was not a core command:
   1.764  	  it was distributed with Mercurial as an extension. This
   1.765  	  section describes the built-in command, not the old
   1.766  	  extension.</para>
   1.767        </note>
   1.768  
   1.769 -      <para>Now let's create a repository, so that we can try out the
   1.770 +      <para id="x_134">Now let's create a repository, so that we can try out the
   1.771  	<command role="hg-cmd">hg bisect</command> command in
   1.772  	isolation.</para>
   1.773  
   1.774        &interaction.bisect.init;
   1.775  
   1.776 -      <para>We'll simulate a project that has a bug in it in a
   1.777 +      <para id="x_135">We'll simulate a project that has a bug in it in a
   1.778  	simple-minded way: create trivial changes in a loop, and
   1.779  	nominate one specific change that will have the
   1.780  	<quote>bug</quote>.  This loop creates 35 changesets, each
   1.781 @@ -804,44 +804,44 @@
   1.782  
   1.783        &interaction.bisect.commits;
   1.784  
   1.785 -      <para>The next thing that we'd like to do is figure out how to
   1.786 +      <para id="x_136">The next thing that we'd like to do is figure out how to
   1.787  	use the <command role="hg-cmd">hg bisect</command> command.
   1.788  	We can use Mercurial's normal built-in help mechanism for
   1.789  	this.</para>
   1.790  
   1.791        &interaction.bisect.help;
   1.792  
   1.793 -      <para>The <command role="hg-cmd">hg bisect</command> command
   1.794 +      <para id="x_137">The <command role="hg-cmd">hg bisect</command> command
   1.795  	works in steps.  Each step proceeds as follows.</para>
   1.796        <orderedlist>
   1.797 -	<listitem><para>You run your binary test.</para>
   1.798 +	<listitem><para id="x_138">You run your binary test.</para>
   1.799  	  <itemizedlist>
   1.800 -	    <listitem><para>If the test succeeded, you tell <command
   1.801 +	    <listitem><para id="x_139">If the test succeeded, you tell <command
   1.802  		  role="hg-cmd">hg bisect</command> by running the
   1.803  		<command role="hg-cmd">hg bisect good</command>
   1.804  		command.</para>
   1.805  	    </listitem>
   1.806 -	    <listitem><para>If it failed, run the <command
   1.807 +	    <listitem><para id="x_13a">If it failed, run the <command
   1.808  		  role="hg-cmd">hg bisect bad</command>
   1.809  		command.</para></listitem></itemizedlist>
   1.810  	</listitem>
   1.811 -	<listitem><para>The command uses your information to decide
   1.812 +	<listitem><para id="x_13b">The command uses your information to decide
   1.813  	    which changeset to test next.</para>
   1.814  	</listitem>
   1.815 -	<listitem><para>It updates the working directory to that
   1.816 +	<listitem><para id="x_13c">It updates the working directory to that
   1.817  	    changeset, and the process begins again.</para>
   1.818  	</listitem></orderedlist>
   1.819 -      <para>The process ends when <command role="hg-cmd">hg
   1.820 +      <para id="x_13d">The process ends when <command role="hg-cmd">hg
   1.821  	  bisect</command> identifies a unique changeset that marks
   1.822  	the point where your test transitioned from
   1.823  	<quote>succeeding</quote> to <quote>failing</quote>.</para>
   1.824  
   1.825 -      <para>To start the search, we must run the <command
   1.826 +      <para id="x_13e">To start the search, we must run the <command
   1.827  	  role="hg-cmd">hg bisect --reset</command> command.</para>
   1.828  
   1.829        &interaction.bisect.search.init;
   1.830  
   1.831 -      <para>In our case, the binary test we use is simple: we check to
   1.832 +      <para id="x_13f">In our case, the binary test we use is simple: we check to
   1.833  	see if any file in the repository contains the string <quote>i
   1.834  	  have a gub</quote>.  If it does, this changeset contains the
   1.835  	change that <quote>caused the bug</quote>.  By convention, a
   1.836 @@ -849,14 +849,14 @@
   1.837  	<quote>bad</quote>, while one that doesn't is
   1.838  	<quote>good</quote>.</para>
   1.839  
   1.840 -      <para>Most of the time, the revision to which the working
   1.841 +      <para id="x_140">Most of the time, the revision to which the working
   1.842  	directory is synced (usually the tip) already exhibits the
   1.843  	problem introduced by the buggy change, so we'll mark it as
   1.844  	<quote>bad</quote>.</para>
   1.845  
   1.846        &interaction.bisect.search.bad-init;
   1.847  
   1.848 -      <para>Our next task is to nominate a changeset that we know
   1.849 +      <para id="x_141">Our next task is to nominate a changeset that we know
   1.850  	<emphasis>doesn't</emphasis> have the bug; the <command
   1.851  	  role="hg-cmd">hg bisect</command> command will
   1.852  	<quote>bracket</quote> its search between the first pair of
   1.853 @@ -866,38 +866,38 @@
   1.854  
   1.855        &interaction.bisect.search.good-init;
   1.856  
   1.857 -      <para>Notice that this command printed some output.</para>
   1.858 +      <para id="x_142">Notice that this command printed some output.</para>
   1.859        <itemizedlist>
   1.860 -	<listitem><para>It told us how many changesets it must
   1.861 +	<listitem><para id="x_143">It told us how many changesets it must
   1.862  	    consider before it can identify the one that introduced
   1.863  	    the bug, and how many tests that will require.</para>
   1.864  	</listitem>
   1.865 -	<listitem><para>It updated the working directory to the next
   1.866 +	<listitem><para id="x_144">It updated the working directory to the next
   1.867  	    changeset to test, and told us which changeset it's
   1.868  	    testing.</para>
   1.869  	</listitem></itemizedlist>
   1.870  
   1.871 -      <para>We now run our test in the working directory.  We use the
   1.872 +      <para id="x_145">We now run our test in the working directory.  We use the
   1.873  	<command>grep</command> command to see if our
   1.874  	<quote>bad</quote> file is present in the working directory.
   1.875  	If it is, this revision is bad; if not, this revision is good.
   1.876  	&interaction.bisect.search.step1;</para>
   1.877  
   1.878 -      <para>This test looks like a perfect candidate for automation,
   1.879 +      <para id="x_146">This test looks like a perfect candidate for automation,
   1.880  	so let's turn it into a shell function.</para>
   1.881        &interaction.bisect.search.mytest;
   1.882  
   1.883 -      <para>We can now run an entire test step with a single command,
   1.884 +      <para id="x_147">We can now run an entire test step with a single command,
   1.885  	<literal>mytest</literal>.</para>
   1.886  
   1.887        &interaction.bisect.search.step2;
   1.888  
   1.889 -      <para>A few more invocations of our canned test step command,
   1.890 +      <para id="x_148">A few more invocations of our canned test step command,
   1.891  	and we're done.</para>
   1.892  
   1.893        &interaction.bisect.search.rest;
   1.894  
   1.895 -      <para>Even though we had 40 changesets to search through, the
   1.896 +      <para id="x_149">Even though we had 40 changesets to search through, the
   1.897  	<command role="hg-cmd">hg bisect</command> command let us find
   1.898  	the changeset that introduced our <quote>bug</quote> with only
   1.899  	five tests.  Because the number of tests that the <command
   1.900 @@ -910,7 +910,7 @@
   1.901      <sect2>
   1.902        <title>Cleaning up after your search</title>
   1.903  
   1.904 -      <para>When you're finished using the <command role="hg-cmd">hg
   1.905 +      <para id="x_14a">When you're finished using the <command role="hg-cmd">hg
   1.906  	  bisect</command> command in a repository, you can use the
   1.907  	<command role="hg-cmd">hg bisect reset</command> command to
   1.908  	drop the information it was using to drive your search.  The
   1.909 @@ -930,7 +930,7 @@
   1.910      <sect2>
   1.911        <title>Give consistent input</title>
   1.912  
   1.913 -      <para>The <command role="hg-cmd">hg bisect</command> command
   1.914 +      <para id="x_14b">The <command role="hg-cmd">hg bisect</command> command
   1.915  	requires that you correctly report the result of every test
   1.916  	you perform.  If you tell it that a test failed when it really
   1.917  	succeeded, it <emphasis>might</emphasis> be able to detect the
   1.918 @@ -944,7 +944,7 @@
   1.919      <sect2>
   1.920        <title>Automate as much as possible</title>
   1.921  
   1.922 -      <para>When I started using the <command role="hg-cmd">hg
   1.923 +      <para id="x_14c">When I started using the <command role="hg-cmd">hg
   1.924  	  bisect</command> command, I tried a few times to run my
   1.925  	tests by hand, on the command line.  This is an approach that
   1.926  	I, at least, am not suited to.  After a few tries, I found
   1.927 @@ -952,7 +952,7 @@
   1.928  	my searches several times before finally getting correct
   1.929  	results.</para>
   1.930  
   1.931 -      <para>My initial problems with driving the <command
   1.932 +      <para id="x_14d">My initial problems with driving the <command
   1.933  	  role="hg-cmd">hg bisect</command> command by hand occurred
   1.934  	even with simple searches on small repositories; if the
   1.935  	problem you're looking for is more subtle, or the number of
   1.936 @@ -961,14 +961,14 @@
   1.937  	the search is much higher.  Once I started automating my
   1.938  	tests, I had much better results.</para>
   1.939  
   1.940 -      <para>The key to automated testing is twofold:</para>
   1.941 +      <para id="x_14e">The key to automated testing is twofold:</para>
   1.942        <itemizedlist>
   1.943 -	<listitem><para>always test for the same symptom, and</para>
   1.944 -	</listitem>
   1.945 -	<listitem><para>always feed consistent input to the <command
   1.946 +	<listitem><para id="x_14f">always test for the same symptom, and</para>
   1.947 +	</listitem>
   1.948 +	<listitem><para id="x_150">always feed consistent input to the <command
   1.949  	      role="hg-cmd">hg bisect</command> command.</para>
   1.950  	</listitem></itemizedlist>
   1.951 -      <para>In my tutorial example above, the <command>grep</command>
   1.952 +      <para id="x_151">In my tutorial example above, the <command>grep</command>
   1.953  	command tests for the symptom, and the <literal>if</literal>
   1.954  	statement takes the result of this check and ensures that we
   1.955  	always feed the same input to the <command role="hg-cmd">hg
   1.956 @@ -980,21 +980,21 @@
   1.957      <sect2>
   1.958        <title>Check your results</title>
   1.959  
   1.960 -      <para>Because the output of a <command role="hg-cmd">hg
   1.961 +      <para id="x_152">Because the output of a <command role="hg-cmd">hg
   1.962  	  bisect</command> search is only as good as the input you
   1.963  	give it, don't take the changeset it reports as the absolute
   1.964  	truth.  A simple way to cross-check its report is to manually
   1.965  	run your test at each of the following changesets:</para>
   1.966        <itemizedlist>
   1.967 -	<listitem><para>The changeset that it reports as the first bad
   1.968 +	<listitem><para id="x_153">The changeset that it reports as the first bad
   1.969  	    revision.  Your test should still report this as
   1.970  	    bad.</para>
   1.971  	</listitem>
   1.972 -	<listitem><para>The parent of that changeset (either parent,
   1.973 +	<listitem><para id="x_154">The parent of that changeset (either parent,
   1.974  	    if it's a merge). Your test should report this changeset
   1.975  	    as good.</para>
   1.976  	</listitem>
   1.977 -	<listitem><para>A child of that changeset.  Your test should
   1.978 +	<listitem><para id="x_155">A child of that changeset.  Your test should
   1.979  	    report this changeset as bad.</para>
   1.980  	</listitem></itemizedlist>
   1.981  
   1.982 @@ -1002,7 +1002,7 @@
   1.983      <sect2>
   1.984        <title>Beware interference between bugs</title>
   1.985  
   1.986 -      <para>It's possible that your search for one bug could be
   1.987 +      <para id="x_156">It's possible that your search for one bug could be
   1.988  	disrupted by the presence of another.  For example, let's say
   1.989  	your software crashes at revision 100, and worked correctly at
   1.990  	revision 50.  Unknown to you, someone else introduced a
   1.991 @@ -1010,7 +1010,7 @@
   1.992  	revision 80.  This could distort your results in one of
   1.993  	several ways.</para>
   1.994  
   1.995 -      <para>It is possible that this other bug completely
   1.996 +      <para id="x_157">It is possible that this other bug completely
   1.997  	<quote>masks</quote> yours, which is to say that it occurs
   1.998  	before your bug has a chance to manifest itself.  If you can't
   1.999  	avoid that other bug (for example, it prevents your project
  1.1000 @@ -1020,14 +1020,14 @@
  1.1001  	you can mark a changeset as untested by running <command
  1.1002  	  role="hg-cmd">hg bisect --skip</command>.</para>
  1.1003  
  1.1004 -      <para>A different problem could arise if your test for a bug's
  1.1005 +      <para id="x_158">A different problem could arise if your test for a bug's
  1.1006  	presence is not specific enough.  If you check for <quote>my
  1.1007  	  program crashes</quote>, then both your crashing bug and an
  1.1008  	unrelated crashing bug that masks it will look like the same
  1.1009  	thing, and mislead <command role="hg-cmd">hg
  1.1010  	  bisect</command>.</para>
  1.1011  
  1.1012 -      <para>Another useful situation in which to use <command
  1.1013 +      <para id="x_159">Another useful situation in which to use <command
  1.1014  	  role="hg-cmd">hg bisect --skip</command> is if you can't
  1.1015  	test a revision because your project was in a broken and hence
  1.1016  	untestable state at that revision, perhaps because someone
  1.1017 @@ -1038,7 +1038,7 @@
  1.1018      <sect2>
  1.1019        <title>Bracket your search lazily</title>
  1.1020  
  1.1021 -      <para>Choosing the first <quote>good</quote> and
  1.1022 +      <para id="x_15a">Choosing the first <quote>good</quote> and
  1.1023  	<quote>bad</quote> changesets that will mark the end points of
  1.1024  	your search is often easy, but it bears a little discussion
  1.1025  	nevertheless.  From the perspective of <command
  1.1026 @@ -1046,7 +1046,7 @@
  1.1027  	changeset is conventionally <quote>bad</quote>, and the older
  1.1028  	changeset is <quote>good</quote>.</para>
  1.1029  
  1.1030 -      <para>If you're having trouble remembering when a suitable
  1.1031 +      <para id="x_15b">If you're having trouble remembering when a suitable
  1.1032  	<quote>good</quote> change was, so that you can tell <command
  1.1033  	  role="hg-cmd">hg bisect</command>, you could do worse than
  1.1034  	testing changesets at random.  Just remember to eliminate
  1.1035 @@ -1055,7 +1055,7 @@
  1.1036  	where another problem masks the bug (as I discussed
  1.1037  	above).</para>
  1.1038  
  1.1039 -      <para>Even if you end up <quote>early</quote> by thousands of
  1.1040 +      <para id="x_15c">Even if you end up <quote>early</quote> by thousands of
  1.1041  	changesets or months of history, you will only add a handful
  1.1042  	of tests to the total number that <command role="hg-cmd">hg
  1.1043  	  bisect</command> must perform, thanks to its logarithmic