1.1 --- a/en/ch01-tour-basic.xml	Fri Mar 20 16:43:35 2009 +0800
     1.2 +++ b/en/ch01-tour-basic.xml	Mon Mar 30 16:23:33 2009 +0800
     1.3 @@ -1,27 +1,27 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter id="chap.tour-basic">
     1.7 +<chapter id="chap:tour-basic">
     1.8    <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
     1.9    <title>A tour of Mercurial: the basics</title>
    1.10  
    1.11 -  <sect1 id="sec.tour.install">
    1.12 +  <sect1 id="sec:tour:install">
    1.13      <title>Installing Mercurial on your system</title>
    1.14  
    1.15 -    <para>Prebuilt binary packages of Mercurial are available for
    1.16 +    <para id="x_1">Prebuilt binary packages of Mercurial are available for
    1.17        every popular operating system.  These make it easy to start
    1.18        using Mercurial on your computer immediately.</para>
    1.19  
    1.20      <sect2>
    1.21        <title>Linux</title>
    1.22  
    1.23 -      <para>Because each Linux distribution has its own packaging
    1.24 +      <para id="x_2">Because each Linux distribution has its own packaging
    1.25  	tools, policies, and rate of development, it's difficult to
    1.26  	give a comprehensive set of instructions on how to install
    1.27  	Mercurial binaries.  The version of Mercurial that you will
    1.28  	end up with can vary depending on how active the person is who
    1.29  	maintains the package for your distribution.</para>
    1.30  
    1.31 -      <para>To keep things simple, I will focus on installing
    1.32 +      <para id="x_3">To keep things simple, I will focus on installing
    1.33  	Mercurial from the command line under the most popular Linux
    1.34  	distributions.  Most of these distributions provide graphical
    1.35  	package managers that will let you install Mercurial with a
    1.36 @@ -29,15 +29,15 @@
    1.37  	<literal>mercurial</literal>.</para>
    1.38  
    1.39        <itemizedlist>
    1.40 -	<listitem><para>Debian:</para>
    1.41 +	<listitem><para id="x_4">Debian:</para>
    1.42  	  <programlisting>apt-get install mercurial</programlisting></listitem>
    1.43 -	<listitem><para>Fedora Core:</para>
    1.44 +	<listitem><para id="x_5">Fedora Core:</para>
    1.45  	  <programlisting>yum install mercurial</programlisting></listitem>
    1.46 -	<listitem><para>Gentoo:</para>
    1.47 +	<listitem><para id="x_6">Gentoo:</para>
    1.48  	  <programlisting>emerge mercurial</programlisting></listitem>
    1.49 -	<listitem><para>OpenSUSE:</para>
    1.50 +	<listitem><para id="x_7">OpenSUSE:</para>
    1.51  	  <programlisting>yum install mercurial</programlisting></listitem>
    1.52 -	<listitem><para>Ubuntu: Ubuntu's Mercurial package is based on
    1.53 +	<listitem><para id="x_8">Ubuntu: Ubuntu's Mercurial package is based on
    1.54  	    Debian's.  To install it, run the following
    1.55  	    command.</para>
    1.56  	  <programlisting>apt-get install mercurial</programlisting></listitem>
    1.57 @@ -47,7 +47,7 @@
    1.58      <sect2>
    1.59        <title>Solaris</title>
    1.60  
    1.61 -      <para>SunFreeWare, at <ulink
    1.62 +      <para id="x_9">SunFreeWare, at <ulink
    1.63  	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
    1.64  	is a good source for a large number of pre-built Solaris
    1.65  	packages for 32 and 64 bit Intel and Sparc architectures,
    1.66 @@ -57,7 +57,7 @@
    1.67      <sect2>
    1.68        <title>Mac OS X</title>
    1.69  
    1.70 -      <para>Lee Cantey publishes an installer of Mercurial for Mac OS
    1.71 +      <para id="x_a">Lee Cantey publishes an installer of Mercurial for Mac OS
    1.72  	X at <ulink
    1.73  	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    1.74  	This package works on both Intel- and Power-based Macs. Before
    1.75 @@ -66,7 +66,7 @@
    1.76  	is easy to do; simply follow the instructions on Lee's
    1.77  	site.</para>
    1.78  
    1.79 -      <para>It's also possible to install Mercurial using Fink or
    1.80 +      <para id="x_b">It's also possible to install Mercurial using Fink or
    1.81  	MacPorts, two popular free package managers for Mac OS X.  If
    1.82  	you have Fink, use <command>sudo apt-get install
    1.83  	  mercurial-py25</command>.  If MacPorts, <command>sudo port
    1.84 @@ -76,14 +76,14 @@
    1.85      <sect2>
    1.86        <title>Windows</title>
    1.87  
    1.88 -      <para>Lee Cantey publishes an installer of Mercurial for Windows
    1.89 +      <para id="x_c">Lee Cantey publishes an installer of Mercurial for Windows
    1.90  	at <ulink
    1.91  	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    1.92  	This package has no external dependencies; it <quote>just
    1.93  	  works</quote>.</para>
    1.94  
    1.95        <note>
    1.96 -	<para>  The Windows version of Mercurial does not
    1.97 +	<para id="x_d">  The Windows version of Mercurial does not
    1.98  	  automatically convert line endings between Windows and Unix
    1.99  	  styles.  If you want to share work with Unix users, you must
   1.100  	  do a little additional configuration work. XXX Flesh this
   1.101 @@ -95,7 +95,7 @@
   1.102    <sect1>
   1.103      <title>Getting started</title>
   1.104  
   1.105 -    <para>To begin, we'll use the <command role="hg-cmd">hg
   1.106 +    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
   1.107  	version</command> command to find out whether Mercurial is
   1.108        actually installed properly.  The actual version information
   1.109        that it prints isn't so important; it's whether it prints
   1.110 @@ -106,7 +106,7 @@
   1.111      <sect2>
   1.112        <title>Built-in help</title>
   1.113  
   1.114 -      <para>Mercurial provides a built-in help system.  This is
   1.115 +      <para id="x_f">Mercurial provides a built-in help system.  This is
   1.116  	  invaluable for those times when you find yourself stuck
   1.117  	  trying to remember how to run a command.  If you are
   1.118  	  completely stuck, simply run <command role="hg-cmd">hg
   1.119 @@ -117,7 +117,7 @@
   1.120  
   1.121  	&interaction.tour.help;
   1.122  
   1.123 -	<para>For a more impressive level of detail (which you won't
   1.124 +	<para id="x_10">For a more impressive level of detail (which you won't
   1.125  	  usually need) run <command role="hg-cmd">hg help <option
   1.126  	      role="hg-opt-global">-v</option></command>.  The <option
   1.127  	    role="hg-opt-global">-v</option> option is short for
   1.128 @@ -130,13 +130,13 @@
   1.129    <sect1>
   1.130      <title>Working with a repository</title>
   1.131  
   1.132 -    <para>In Mercurial, everything happens inside a
   1.133 +    <para id="x_11">In Mercurial, everything happens inside a
   1.134        <emphasis>repository</emphasis>.  The repository for a project
   1.135        contains all of the files that <quote>belong to</quote> that
   1.136        project, along with a historical record of the project's
   1.137        files.</para>
   1.138  
   1.139 -    <para>There's nothing particularly magical about a repository; it
   1.140 +    <para id="x_12">There's nothing particularly magical about a repository; it
   1.141        is simply a directory tree in your filesystem that Mercurial
   1.142        treats as special. You can rename or delete a repository any
   1.143        time you like, using either the command line or your file
   1.144 @@ -145,7 +145,7 @@
   1.145      <sect2>
   1.146        <title>Making a local copy of a repository</title>
   1.147  
   1.148 -      <para><emphasis>Copying</emphasis> a repository is just a little
   1.149 +      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
   1.150  	bit special.  While you could use a normal file copying
   1.151  	command to make a copy of a repository, it's best to use a
   1.152  	built-in command that Mercurial provides.  This command is
   1.153 @@ -154,23 +154,23 @@
   1.154  
   1.155        &interaction.tour.clone;
   1.156  
   1.157 -      <para>If our clone succeeded, we should now have a local
   1.158 +      <para id="x_14">If our clone succeeded, we should now have a local
   1.159  	directory called <filename class="directory">hello</filename>.
   1.160  	This directory will contain some files.</para>
   1.161  
   1.162        &interaction.tour.ls;
   1.163  
   1.164 -      <para>These files have the same contents and history in our
   1.165 +      <para id="x_15">These files have the same contents and history in our
   1.166  	repository as they do in the repository we cloned.</para>
   1.167  
   1.168 -      <para>Every Mercurial repository is complete, self-contained,
   1.169 +      <para id="x_16">Every Mercurial repository is complete, self-contained,
   1.170  	and independent.  It contains its own private copy of a
   1.171  	project's files and history.  A cloned repository remembers
   1.172  	the location of the repository it was cloned from, but it does
   1.173  	not communicate with that repository, or any other, unless you
   1.174  	tell it to.</para>
   1.175  
   1.176 -      <para>What this means for now is that we're free to experiment
   1.177 +      <para id="x_17">What this means for now is that we're free to experiment
   1.178  	with our repository, safe in the knowledge that it's a private
   1.179  	<quote>sandbox</quote> that won't affect anyone else.</para>
   1.180  
   1.181 @@ -178,20 +178,20 @@
   1.182      <sect2>
   1.183        <title>What's in a repository?</title>
   1.184  
   1.185 -      <para>When we take a more detailed look inside a repository, we
   1.186 +      <para id="x_18">When we take a more detailed look inside a repository, we
   1.187  	can see that it contains a directory named <filename
   1.188  	  class="directory">.hg</filename>.  This is where Mercurial
   1.189  	keeps all of its metadata for the repository.</para>
   1.190  
   1.191        &interaction.tour.ls-a;
   1.192  
   1.193 -      <para>The contents of the <filename
   1.194 +      <para id="x_19">The contents of the <filename
   1.195  	  class="directory">.hg</filename> directory and its
   1.196  	subdirectories are private to Mercurial.  Every other file and
   1.197  	directory in the repository is yours to do with as you
   1.198  	please.</para>
   1.199  
   1.200 -      <para>To introduce a little terminology, the <filename
   1.201 +      <para id="x_1a">To introduce a little terminology, the <filename
   1.202  	  class="directory">.hg</filename> directory is the
   1.203  	<quote>real</quote> repository, and all of the files and
   1.204  	directories that coexist with it are said to live in the
   1.205 @@ -208,68 +208,66 @@
   1.206    <sect1>
   1.207      <title>A tour through history</title>
   1.208  
   1.209 -    <para>One of the first things we might want to do with a new,
   1.210 +    <para id="x_1b">One of the first things we might want to do with a new,
   1.211        unfamiliar repository is understand its history.  The <command
   1.212  	role="hg-cmd">hg log</command> command gives us a view of
   1.213        history.</para>
   1.214  
   1.215      &interaction.tour.log;
   1.216  
   1.217 -    <para>By default, this command prints a brief paragraph of output
   1.218 +    <para id="x_1c">By default, this command prints a brief paragraph of output
   1.219        for each change to the project that was recorded.  In Mercurial
   1.220        terminology, we call each of these recorded events a
   1.221        <emphasis>changeset</emphasis>, because it can contain a record
   1.222        of changes to several files.</para>
   1.223  
   1.224 -    <para>The fields in a record of output from <command
   1.225 +    <para id="x_1d">The fields in a record of output from <command
   1.226  	role="hg-cmd">hg log</command> are as follows.</para>
   1.227      <itemizedlist>
   1.228 -      <listitem><para><literal>changeset</literal>: This field has the
   1.229 +      <listitem><para id="x_1e"><literal>changeset</literal>: This field has the
   1.230  	  format of a number, followed by a colon, followed by a
   1.231  	  hexadecimal string.  These are
   1.232  	  <emphasis>identifiers</emphasis> for the changeset.  There
   1.233  	  are two identifiers because the number is shorter and easier
   1.234  	  to type than the hex string.</para></listitem>
   1.235 -      <listitem><para><literal>user</literal>: The identity of the
   1.236 +      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
   1.237  	  person who created the changeset.  This is a free-form
   1.238  	  field, but it most often contains a person's name and email
   1.239  	  address.</para></listitem>
   1.240 -      <listitem><para><literal>date</literal>: The date and time on
   1.241 +      <listitem><para id="x_20"><literal>date</literal>: The date and time on
   1.242  	  which the changeset was created, and the timezone in which
   1.243  	  it was created.  (The date and time are local to that
   1.244  	  timezone; they display what time and date it was for the
   1.245  	  person who created the changeset.)</para></listitem>
   1.246 -      <listitem><para><literal>summary</literal>: The first line of
   1.247 +      <listitem><para id="x_21"><literal>summary</literal>: The first line of
   1.248  	  the text message that the creator of the changeset entered
   1.249  	  to describe the changeset.</para></listitem></itemizedlist>
   1.250 -    <para>The default output printed by <command role="hg-cmd">hg
   1.251 +    <para id="x_22">The default output printed by <command role="hg-cmd">hg
   1.252  	log</command> is purely a summary; it is missing a lot of
   1.253        detail.</para>
   1.254  
   1.255 -    <para>Figure <xref endterm="fig.tour-basic.history.caption"
   1.256 -        linkend="fig.tour-basic.history"/> provides a
   1.257 -      graphical representation of the history of the <filename
   1.258 +    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
   1.259 +      a graphical representation of the history of the <filename
   1.260  	class="directory">hello</filename> repository, to make it a
   1.261        little easier to see which direction history is
   1.262        <quote>flowing</quote> in.  We'll be returning to this figure
   1.263        several times in this chapter and the chapter that
   1.264        follows.</para>
   1.265  
   1.266 -    <informalfigure id="fig.tour-basic.history">
   1.267 +    <figure id="fig:tour-basic:history">
   1.268 +      <title>Graphical history of the <filename
   1.269 +	  class="directory">hello</filename> repository</title>
   1.270        <mediaobject>
   1.271 -	<imageobject><imagedata fileref="images/tour-history.png"/></imageobject>
   1.272 +	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
   1.273  	<textobject><phrase>XXX add text</phrase></textobject>
   1.274 -	<caption><para id="fig.tour-basic.history.caption">Graphical history of
   1.275 -	    the <filename class="directory">hello</filename> repository</para>
   1.276 -	</caption>
   1.277        </mediaobject>
   1.278 -    </informalfigure>
   1.279 +    </figure>
   1.280  
   1.281      <sect2>
   1.282        <title>Changesets, revisions, and talking to other
   1.283  	people</title>
   1.284  
   1.285 -      <para>As English is a notoriously sloppy language, and computer
   1.286 +      <para id="x_25">As English is a notoriously sloppy language, and computer
   1.287  	science has a hallowed history of terminological confusion
   1.288  	(why use one term when four will do?), revision control has a
   1.289  	variety of words and phrases that mean the same thing.  If you
   1.290 @@ -279,7 +277,7 @@
   1.291  	<quote>cset</quote>, and sometimes a changeset is referred to
   1.292  	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   1.293  
   1.294 -      <para>While it doesn't matter what <emphasis>word</emphasis> you
   1.295 +      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
   1.296  	use to refer to the concept of <quote>a changeset</quote>, the
   1.297  	<emphasis>identifier</emphasis> that you use to refer to
   1.298  	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   1.299 @@ -288,14 +286,14 @@
   1.300  	  log</command> identifies a changeset using both a number and
   1.301  	a hexadecimal string.</para>
   1.302        <itemizedlist>
   1.303 -	<listitem><para>The revision number is <emphasis>only valid in
   1.304 +	<listitem><para id="x_27">The revision number is <emphasis>only valid in
   1.305  	      that repository</emphasis>,</para></listitem>
   1.306 -	<listitem><para>while the hex string is the
   1.307 +	<listitem><para id="x_28">while the hex string is the
   1.308  	    <emphasis>permanent, unchanging identifier</emphasis> that
   1.309  	    will always identify that exact changeset in
   1.310  	    <emphasis>every</emphasis> copy of the
   1.311  	    repository.</para></listitem></itemizedlist>
   1.312 -      <para>This distinction is important.  If you send someone an
   1.313 +      <para id="x_29">This distinction is important.  If you send someone an
   1.314  	email talking about <quote>revision 33</quote>, there's a high
   1.315  	likelihood that their revision 33 will <emphasis>not be the
   1.316  	  same</emphasis> as yours.  The reason for this is that a
   1.317 @@ -305,7 +303,7 @@
   1.318  	repositories. Three changes $a,b,c$ can easily appear in one
   1.319  	repository as $0,1,2$, while in another as $1,0,2$.</para>
   1.320  
   1.321 -      <para>Mercurial uses revision numbers purely as a convenient
   1.322 +      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
   1.323  	shorthand.  If you need to discuss a changeset with someone,
   1.324  	or make a record of a changeset for some other reason (for
   1.325  	example, in a bug report), use the hexadecimal
   1.326 @@ -315,7 +313,7 @@
   1.327      <sect2>
   1.328        <title>Viewing specific revisions</title>
   1.329  
   1.330 -      <para>To narrow the output of <command role="hg-cmd">hg
   1.331 +      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
   1.332  	  log</command> down to a single revision, use the <option
   1.333  	  role="hg-opt-log">-r</option> (or <option
   1.334  	  role="hg-opt-log">--rev</option>) option.  You can use
   1.335 @@ -324,7 +322,7 @@
   1.336  
   1.337        &interaction.tour.log-r;
   1.338  
   1.339 -      <para>If you want to see the history of several revisions
   1.340 +      <para id="x_2c">If you want to see the history of several revisions
   1.341  	without having to list each one, you can use <emphasis>range
   1.342  	  notation</emphasis>; this lets you express the idea <quote>I
   1.343  	  want all revisions between <literal>abc</literal> and
   1.344 @@ -332,7 +330,7 @@
   1.345        
   1.346  	&interaction.tour.log.range;
   1.347  
   1.348 -      <para>Mercurial also honours the order in which you specify
   1.349 +      <para id="x_2d">Mercurial also honours the order in which you specify
   1.350  	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   1.351  	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   1.352  	  4:2</command> prints 4, 3, and 2.</para>
   1.353 @@ -341,7 +339,7 @@
   1.354      <sect2>
   1.355        <title>More detailed information</title>
   1.356  
   1.357 -      <para>While the summary information printed by <command
   1.358 +      <para id="x_2e">While the summary information printed by <command
   1.359  	  role="hg-cmd">hg log</command> is useful if you already know
   1.360  	what you're looking for, you may need to see a complete
   1.361  	description of the change, or a list of the files changed, if
   1.362 @@ -353,13 +351,13 @@
   1.363  
   1.364        &interaction.tour.log-v;
   1.365  
   1.366 -      <para>If you want to see both the description and content of a
   1.367 -	change, add the <option role="hg-opt-log">-p</option> (or
   1.368 -	<option role="hg-opt-log">--patch</option>) option.  This
   1.369 -	displays the content of a change as a <emphasis>unified
   1.370 -	  diff</emphasis> (if you've never seen a unified diff before,
   1.371 -	see section <xref linkend="sec.mq.patch"/> for an
   1.372 -	overview).</para>
   1.373 +      <para id="x_2f">If you want to see both the description and
   1.374 +	content of a change, add the <option
   1.375 +	  role="hg-opt-log">-p</option> (or <option
   1.376 +	  role="hg-opt-log">--patch</option>) option.  This displays
   1.377 +	the content of a change as a <emphasis>unified diff</emphasis>
   1.378 +	(if you've never seen a unified diff before, see <xref
   1.379 +	  linkend="sec:mq:patch"/> for an overview).</para>
   1.380  
   1.381        &interaction.tour.log-vp;
   1.382  
   1.383 @@ -368,39 +366,39 @@
   1.384    <sect1>
   1.385      <title>All about command options</title>
   1.386  
   1.387 -    <para>Let's take a brief break from exploring Mercurial commands
   1.388 +    <para id="x_30">Let's take a brief break from exploring Mercurial commands
   1.389        to discuss a pattern in the way that they work; you may find
   1.390        this useful to keep in mind as we continue our tour.</para>
   1.391  
   1.392 -    <para>Mercurial has a consistent and straightforward approach to
   1.393 +    <para id="x_31">Mercurial has a consistent and straightforward approach to
   1.394        dealing with the options that you can pass to commands.  It
   1.395        follows the conventions for options that are common to modern
   1.396        Linux and Unix systems.</para>
   1.397      <itemizedlist>
   1.398 -      <listitem><para>Every option has a long name.  For example, as
   1.399 +      <listitem><para id="x_32">Every option has a long name.  For example, as
   1.400  	  we've already seen, the <command role="hg-cmd">hg
   1.401  	    log</command> command accepts a <option
   1.402  	    role="hg-opt-log">--rev</option> option.</para></listitem>
   1.403 -      <listitem><para>Most options have short names, too.  Instead of
   1.404 +      <listitem><para id="x_33">Most options have short names, too.  Instead of
   1.405  	  <option role="hg-opt-log">--rev</option>, we can use <option
   1.406  	    role="hg-opt-log">-r</option>.  (The reason that some
   1.407  	  options don't have short names is that the options in
   1.408  	  question are rarely used.)</para></listitem>
   1.409 -      <listitem><para>Long options start with two dashes (e.g. <option
   1.410 +      <listitem><para id="x_34">Long options start with two dashes (e.g. <option
   1.411  	    role="hg-opt-log">--rev</option>), while short options
   1.412  	  start with one (e.g. <option
   1.413  	    role="hg-opt-log">-r</option>).</para></listitem>
   1.414 -      <listitem><para>Option naming and usage is consistent across
   1.415 +      <listitem><para id="x_35">Option naming and usage is consistent across
   1.416  	  commands.  For example, every command that lets you specify
   1.417  	  a changeset ID or revision number accepts both <option
   1.418  	    role="hg-opt-log">-r</option> and <option
   1.419  	    role="hg-opt-log">--rev</option>
   1.420  	  arguments.</para></listitem></itemizedlist>
   1.421 -    <para>In the examples throughout this book, I use short options
   1.422 +    <para id="x_36">In the examples throughout this book, I use short options
   1.423        instead of long.  This just reflects my own preference, so don't
   1.424        read anything significant into it.</para>
   1.425  
   1.426 -    <para>Most commands that print output of some kind will print more
   1.427 +    <para id="x_37">Most commands that print output of some kind will print more
   1.428        output when passed a <option role="hg-opt-global">-v</option>
   1.429        (or <option role="hg-opt-global">--verbose</option>) option, and
   1.430        less when passed <option role="hg-opt-global">-q</option> (or
   1.431 @@ -410,11 +408,11 @@
   1.432    <sect1>
   1.433      <title>Making and reviewing changes</title>
   1.434  
   1.435 -    <para>Now that we have a grasp of viewing history in Mercurial,
   1.436 +    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
   1.437        let's take a look at making some changes and examining
   1.438        them.</para>
   1.439  
   1.440 -    <para>The first thing we'll do is isolate our experiment in a
   1.441 +    <para id="x_39">The first thing we'll do is isolate our experiment in a
   1.442        repository of its own.  We use the <command role="hg-cmd">hg
   1.443  	clone</command> command, but we don't need to clone a copy of
   1.444        the remote repository.  Since we already have a copy of it
   1.445 @@ -424,7 +422,7 @@
   1.446  
   1.447      &interaction.tour.reclone;
   1.448  
   1.449 -    <para>As an aside, it's often good practice to keep a
   1.450 +    <para id="x_3a">As an aside, it's often good practice to keep a
   1.451        <quote>pristine</quote> copy of a remote repository around,
   1.452        which you can then make temporary clones of to create sandboxes
   1.453        for each task you want to work on.  This lets you work on
   1.454 @@ -433,7 +431,7 @@
   1.455        local clones are so cheap, there's almost no overhead to cloning
   1.456        and destroying repositories whenever you want.</para>
   1.457  
   1.458 -    <para>In our <filename class="directory">my-hello</filename>
   1.459 +    <para id="x_3b">In our <filename class="directory">my-hello</filename>
   1.460        repository, we have a file <filename>hello.c</filename> that
   1.461        contains the classic <quote>hello, world</quote> program. Let's
   1.462        use the ancient and venerable <command>sed</command> command to
   1.463 @@ -446,20 +444,20 @@
   1.464  
   1.465      &interaction.tour.sed;
   1.466  
   1.467 -    <para>Mercurial's <command role="hg-cmd">hg status</command>
   1.468 +    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
   1.469        command will tell us what Mercurial knows about the files in the
   1.470        repository.</para>
   1.471  
   1.472      &interaction.tour.status;
   1.473  
   1.474 -    <para>The <command role="hg-cmd">hg status</command> command
   1.475 +    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
   1.476        prints no output for some files, but a line starting with
   1.477        <quote><literal>M</literal></quote> for
   1.478        <filename>hello.c</filename>.  Unless you tell it to, <command
   1.479  	role="hg-cmd">hg status</command> will not print any output
   1.480        for files that have not been modified.</para>
   1.481  
   1.482 -    <para>The <quote><literal>M</literal></quote> indicates that
   1.483 +    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
   1.484        Mercurial has noticed that we modified
   1.485        <filename>hello.c</filename>.  We didn't need to
   1.486        <emphasis>inform</emphasis> Mercurial that we were going to
   1.487 @@ -467,7 +465,7 @@
   1.488        file after we were done; it was able to figure this out
   1.489        itself.</para>
   1.490  
   1.491 -    <para>It's a little bit helpful to know that we've modified
   1.492 +    <para id="x_3f">It's a little bit helpful to know that we've modified
   1.493        <filename>hello.c</filename>, but we might prefer to know
   1.494        exactly <emphasis>what</emphasis> changes we've made to it.  To
   1.495        do this, we use the <command role="hg-cmd">hg diff</command>
   1.496 @@ -479,14 +477,14 @@
   1.497    <sect1>
   1.498      <title>Recording changes in a new changeset</title>
   1.499  
   1.500 -    <para>We can modify files, build and test our changes, and use
   1.501 +    <para id="x_40">We can modify files, build and test our changes, and use
   1.502        <command role="hg-cmd">hg status</command> and <command
   1.503  	role="hg-cmd">hg diff</command> to review our changes, until
   1.504        we're satisfied with what we've done and arrive at a natural
   1.505        stopping point where we want to record our work in a new
   1.506        changeset.</para>
   1.507  
   1.508 -    <para>The <command role="hg-cmd">hg commit</command> command lets
   1.509 +    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
   1.510        us create a new changeset; we'll usually refer to this as
   1.511        <quote>making a commit</quote> or
   1.512        <quote>committing</quote>.</para>
   1.513 @@ -494,7 +492,7 @@
   1.514      <sect2>
   1.515        <title>Setting up a username</title>
   1.516  
   1.517 -      <para>When you try to run <command role="hg-cmd">hg
   1.518 +      <para id="x_42">When you try to run <command role="hg-cmd">hg
   1.519  	  commit</command> for the first time, it is not guaranteed to
   1.520  	succeed.  Mercurial records your name and address with each
   1.521  	change that you commit, so that you and others will later be
   1.522 @@ -503,36 +501,37 @@
   1.523  	change with.  It will attempt each of the following methods,
   1.524  	in order:</para>
   1.525        <orderedlist>
   1.526 -	<listitem><para>If you specify a <option
   1.527 +	<listitem><para id="x_43">If you specify a <option
   1.528  	      role="hg-opt-commit">-u</option> option to the <command
   1.529  	      role="hg-cmd">hg commit</command> command on the command
   1.530  	    line, followed by a username, this is always given the
   1.531  	    highest precedence.</para></listitem>
   1.532 -	<listitem><para>If you have set the <envar>HGUSER</envar>
   1.533 +	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
   1.534  	    environment variable, this is checked
   1.535  	    next.</para></listitem>
   1.536 -	<listitem><para>If you create a file in your home directory
   1.537 -	    called <filename role="special">.hgrc</filename>, with a
   1.538 -	    <envar role="rc-item-ui">username</envar> entry, that will
   1.539 -	    be used next.  To see what the contents of this file
   1.540 -	    should look like, refer to section <xref
   1.541 -	      linkend="sec.tour-basic.username"/>
   1.542 +	<listitem><para id="x_45">If you create a file in your home
   1.543 +	    directory called <filename
   1.544 +	      role="special">.hgrc</filename>, with a <envar
   1.545 +	      role="rc-item-ui">username</envar> entry, that will be
   1.546 +	    used next.  To see what the contents of this file should
   1.547 +	    look like, refer to <xref
   1.548 +	      linkend="sec:tour-basic:username"/>
   1.549  	    below.</para></listitem>
   1.550 -	<listitem><para>If you have set the <envar>EMAIL</envar>
   1.551 +	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
   1.552  	    environment variable, this will be used
   1.553  	    next.</para></listitem>
   1.554 -	<listitem><para>Mercurial will query your system to find out
   1.555 +	<listitem><para id="x_47">Mercurial will query your system to find out
   1.556  	    your local user name and host name, and construct a
   1.557  	    username from these components. Since this often results
   1.558  	    in a username that is not very useful, it will print a
   1.559  	    warning if it has to do
   1.560  	    this.</para></listitem>
   1.561        </orderedlist>
   1.562 -      <para>If all of these mechanisms fail, Mercurial will
   1.563 +      <para id="x_48">If all of these mechanisms fail, Mercurial will
   1.564  	  fail, printing an error message.  In this case, it will not
   1.565  	  let you commit until you set up a
   1.566  	  username.</para>
   1.567 -      <para>You should think of the <envar>HGUSER</envar> environment
   1.568 +      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
   1.569  	variable and the <option role="hg-opt-commit">-u</option>
   1.570  	option to the <command role="hg-cmd">hg commit</command>
   1.571  	command as ways to <emphasis>override</emphasis> Mercurial's
   1.572 @@ -540,10 +539,10 @@
   1.573  	and most robust way to set a username for yourself is by
   1.574  	creating a <filename role="special">.hgrc</filename> file; see
   1.575  	below for details.</para>
   1.576 -      <sect3 id="sec.tour-basic.username">
   1.577 +      <sect3 id="sec:tour-basic:username">
   1.578  	<title>Creating a Mercurial configuration file</title>
   1.579  
   1.580 -	<para>To set a user name, use your favourite editor
   1.581 +	<para id="x_4a">To set a user name, use your favourite editor
   1.582  	    to create a file called <filename
   1.583  	      role="special">.hgrc</filename> in your home directory.
   1.584  	    Mercurial will use this file to look up your personalised
   1.585 @@ -555,7 +554,7 @@
   1.586  username = Firstname Lastname
   1.587  &lt;email.address@domain.net&gt;</programlisting>
   1.588  
   1.589 -	<para>The <quote><literal>[ui]</literal></quote> line begins a
   1.590 +	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
   1.591  	  <emphasis>section</emphasis> of the config file, so you can
   1.592  	  read the <quote><literal>username = ...</literal></quote>
   1.593  	  line as meaning <quote>set the value of the
   1.594 @@ -570,14 +569,14 @@
   1.595        <sect3>
   1.596  	<title>Choosing a user name</title>
   1.597  
   1.598 -	<para>You can use any text you like as the value of
   1.599 +	<para id="x_4c">You can use any text you like as the value of
   1.600  	    the <literal>username</literal> config item, since this
   1.601  	    information is for reading by other people, but for
   1.602  	    interpreting by Mercurial.  The convention that most
   1.603  	    people follow is to use their name and email address, as
   1.604  	    in the example above.</para>
   1.605  	<note>
   1.606 -	  <para>Mercurial's built-in web server obfuscates
   1.607 +	  <para id="x_4d">Mercurial's built-in web server obfuscates
   1.608  	      email addresses, to make it more difficult for the email
   1.609  	      harvesting tools that spammers use. This reduces the
   1.610  	      likelihood that you'll start receiving more junk email
   1.611 @@ -589,7 +588,7 @@
   1.612      <sect2>
   1.613        <title>Writing a commit message</title>
   1.614  
   1.615 -      <para>When we commit a change, Mercurial drops us into
   1.616 +      <para id="x_4e">When we commit a change, Mercurial drops us into
   1.617  	  a text editor, to enter a message that will describe the
   1.618  	  modifications we've made in this changeset.  This is called
   1.619  	  the <emphasis>commit message</emphasis>.  It will be a
   1.620 @@ -599,14 +598,14 @@
   1.621  
   1.622         &interaction.tour.commit;
   1.623  
   1.624 -      <para>The editor that the <command role="hg-cmd">hg
   1.625 +      <para id="x_4f">The editor that the <command role="hg-cmd">hg
   1.626  	    commit</command> command drops us into will contain an
   1.627  	  empty line, followed by a number of lines starting with
   1.628  	  <quote><literal>HG:</literal></quote>.</para>
   1.629  
   1.630      <programlisting>XXX fix this XXX</programlisting>
   1.631  
   1.632 -      <para>Mercurial ignores the lines that start with
   1.633 +      <para id="x_50">Mercurial ignores the lines that start with
   1.634  	  <quote><literal>HG:</literal></quote>; it uses them only to
   1.635  	  tell us which files it's recording changes to.  Modifying or
   1.636  	  deleting these lines has no effect.</para>
   1.637 @@ -614,7 +613,7 @@
   1.638      <sect2>
   1.639        <title>Writing a good commit message</title>
   1.640  
   1.641 -      <para>Since <command role="hg-cmd">hg log</command>
   1.642 +      <para id="x_51">Since <command role="hg-cmd">hg log</command>
   1.643  	  only prints the first line of a commit message by default,
   1.644  	  it's best to write a commit message whose first line stands
   1.645  	  alone.  Here's a real example of a commit message that
   1.646 @@ -628,13 +627,13 @@
   1.647  date:        Tue Sep 26 21:37:07 2006 -0700
   1.648  summary:     include buildmeister/commondefs. Add exports.</programlisting>
   1.649  
   1.650 -      <para>As far as the remainder of the contents of the
   1.651 +      <para id="x_52">As far as the remainder of the contents of the
   1.652  	  commit message are concerned, there are no hard-and-fast
   1.653  	  rules.  Mercurial itself doesn't interpret or care about the
   1.654  	  contents of the commit message, though your project may have
   1.655  	  policies that dictate a certain kind of
   1.656  	  formatting.</para>
   1.657 -      <para>My personal preference is for short, but
   1.658 +      <para id="x_53">My personal preference is for short, but
   1.659  	  informative, commit messages that tell me something that I
   1.660  	  can't figure out with a quick glance at the output of
   1.661  	  <command role="hg-cmd">hg log
   1.662 @@ -643,12 +642,12 @@
   1.663      <sect2>
   1.664        <title>Aborting a commit</title>
   1.665  
   1.666 -      <para>If you decide that you don't want to commit
   1.667 +      <para id="x_54">If you decide that you don't want to commit
   1.668  	  while in the middle of editing a commit message, simply exit
   1.669  	  from your editor without saving the file that it's editing.
   1.670  	  This will cause nothing to happen to either the repository
   1.671  	  or the working directory.</para>
   1.672 -      <para>If we run the <command role="hg-cmd">hg
   1.673 +      <para id="x_55">If we run the <command role="hg-cmd">hg
   1.674  	    commit</command> command without any arguments, it records
   1.675  	  all of the changes we've made, as reported by <command
   1.676  	    role="hg-cmd">hg status</command> and <command
   1.677 @@ -657,7 +656,7 @@
   1.678      <sect2>
   1.679        <title>Admiring our new handiwork</title>
   1.680  
   1.681 -      <para>Once we've finished the commit, we can use the
   1.682 +      <para id="x_56">Once we've finished the commit, we can use the
   1.683  	  <command role="hg-cmd">hg tip</command> command to display
   1.684  	  the changeset we just created.  This command produces output
   1.685  	  that is identical to <command role="hg-cmd">hg
   1.686 @@ -666,7 +665,7 @@
   1.687  
   1.688        &interaction.tour.tip;
   1.689  
   1.690 -      <para>We refer to
   1.691 +      <para id="x_57">We refer to
   1.692  	  the newest revision in the repository as the tip revision,
   1.693  	  or simply the tip.</para>
   1.694      </sect2>
   1.695 @@ -675,16 +674,16 @@
   1.696    <sect1>
   1.697      <title>Sharing changes</title>
   1.698  
   1.699 -    <para>We mentioned earlier that repositories in
   1.700 +    <para id="x_58">We mentioned earlier that repositories in
   1.701  	Mercurial are self-contained.  This means that the changeset
   1.702  	we just created exists only in our <filename
   1.703  	  class="directory">my-hello</filename> repository.  Let's
   1.704  	look at a few ways that we can propagate this change into
   1.705  	other repositories.</para>
   1.706  
   1.707 -    <sect2 id="sec.tour.pull">
   1.708 +    <sect2 id="sec:tour:pull">
   1.709        <title>Pulling changes from another repository</title>
   1.710 -      <para>To get started, let's clone our original
   1.711 +      <para id="x_59">To get started, let's clone our original
   1.712  	  <filename class="directory">hello</filename> repository,
   1.713  	  which does not contain the change we just committed.  We'll
   1.714  	  call our temporary repository <filename
   1.715 @@ -692,7 +691,7 @@
   1.716  
   1.717        &interaction.tour.clone-pull;
   1.718  
   1.719 -      <para>We'll use the <command role="hg-cmd">hg
   1.720 +      <para id="x_5a">We'll use the <command role="hg-cmd">hg
   1.721  	    pull</command> command to bring changes from <filename
   1.722  	    class="directory">my-hello</filename> into <filename
   1.723  	    class="directory">hello-pull</filename>.  However, blindly
   1.724 @@ -705,21 +704,21 @@
   1.725  
   1.726        &interaction.tour.incoming;
   1.727  
   1.728 -      <para>(Of course, someone could
   1.729 +      <para id="x_5b">(Of course, someone could
   1.730  	  cause more changesets to appear in the repository that we
   1.731  	  ran <command role="hg-cmd">hg incoming</command> in, before
   1.732  	  we get a chance to <command role="hg-cmd">hg pull</command>
   1.733  	  the changes, so that we could end up pulling changes that we
   1.734  	  didn't expect.)</para>
   1.735  
   1.736 -      <para>Bringing changes into a repository is a simple
   1.737 +      <para id="x_5c">Bringing changes into a repository is a simple
   1.738  	  matter of running the <command role="hg-cmd">hg
   1.739  	    pull</command> command, and telling it which repository to
   1.740  	  pull from.</para>
   1.741  
   1.742        &interaction.tour.pull;
   1.743  
   1.744 -      <para>As you can see
   1.745 +      <para id="x_5d">As you can see
   1.746  	  from the before-and-after output of <command
   1.747  	    role="hg-cmd">hg tip</command>, we have successfully
   1.748  	  pulled changes into our repository.  There remains one step
   1.749 @@ -729,19 +728,19 @@
   1.750      <sect2>
   1.751        <title>Updating the working directory</title>
   1.752  
   1.753 -      <para>We have so far glossed over the relationship between a
   1.754 -	repository and its working directory.  The <command
   1.755 +      <para id="x_5e">We have so far glossed over the relationship
   1.756 +	between a repository and its working directory.  The <command
   1.757  	  role="hg-cmd">hg pull</command> command that we ran in
   1.758 -	section <xref linkend="sec.tour.pull"/> brought changes
   1.759 -	into the repository, but if we check, there's no sign of those
   1.760 -	changes in the working directory.  This is because <command
   1.761 +	<xref linkend="sec:tour:pull"/> brought changes into the
   1.762 +	repository, but if we check, there's no sign of those changes
   1.763 +	in the working directory.  This is because <command
   1.764  	  role="hg-cmd">hg pull</command> does not (by default) touch
   1.765  	the working directory.  Instead, we use the <command
   1.766  	  role="hg-cmd">hg update</command> command to do this.</para>
   1.767  
   1.768        &interaction.tour.update;
   1.769  
   1.770 -      <para>It might seem a bit strange that <command role="hg-cmd">hg
   1.771 +      <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg
   1.772  	  pull</command> doesn't update the working directory
   1.773  	automatically.  There's actually a good reason for this: you
   1.774  	can use <command role="hg-cmd">hg update</command> to update
   1.775 @@ -752,29 +751,28 @@
   1.776  	  role="hg-cmd">hg pull</command> which automatically updated
   1.777  	the working directory to a new revision, you might not be
   1.778  	terribly happy.</para>
   1.779 -      <para>However, since pull-then-update is such a common thing to
   1.780 +      <para id="x_60">However, since pull-then-update is such a common thing to
   1.781  	do, Mercurial lets you combine the two by passing the <option
   1.782  	  role="hg-opt-pull">-u</option> option to <command
   1.783  	  role="hg-cmd">hg pull</command>.</para>
   1.784  
   1.785 -      <para>If you look back at the output of <command
   1.786 -	  role="hg-cmd">hg pull</command> in section <xref
   1.787 -	    linkend="sec.tour.pull"/> when we ran it without <option
   1.788 +      <para id="x_61">If you look back at the output of <command
   1.789 +	  role="hg-cmd">hg pull</command> in <xref
   1.790 +	    linkend="sec:tour:pull"/> when we ran it without <option
   1.791  	  role="hg-opt-pull">-u</option>, you can see that it printed
   1.792  	a helpful reminder that we'd have to take an explicit step to
   1.793  	update the working directory:</para>
   1.794  
   1.795        <!-- &interaction.xxx.fixme; -->
   1.796  
   1.797 -      <para>To find out what revision the working directory is at, use
   1.798 +      <para id="x_62">To find out what revision the working directory is at, use
   1.799  	the <command role="hg-cmd">hg parents</command>
   1.800  	command.</para>
   1.801  
   1.802        &interaction.tour.parents;
   1.803  
   1.804 -      <para>If you look back at figure <xref
   1.805 -	   endterm="fig.tour-basic.history.caption" 
   1.806 -	   linkend="fig.tour-basic.history"/>,
   1.807 +      <para id="x_63">If you look back at <xref
   1.808 +	  linkend="fig:tour-basic:history"/>,
   1.809  	you'll see arrows connecting each changeset.  The node that
   1.810  	the arrow leads <emphasis>from</emphasis> in each case is a
   1.811  	parent, and the node that the arrow leads
   1.812 @@ -782,14 +780,14 @@
   1.813  	has a parent in just the same way; this is the changeset that
   1.814  	the working directory currently contains.</para>
   1.815  
   1.816 -      <para>To update the working directory to a particular revision,
   1.817 +      <para id="x_64">To update the working directory to a particular revision,
   1.818  
   1.819  	give a revision number or changeset ID to the <command
   1.820  	  role="hg-cmd">hg update</command> command.</para>
   1.821  
   1.822        &interaction.tour.older;
   1.823  
   1.824 -      <para>If you omit an explicit revision, <command
   1.825 +      <para id="x_65">If you omit an explicit revision, <command
   1.826  	  role="hg-cmd">hg update</command> will update to the tip
   1.827  	revision, as shown by the second call to <command
   1.828  	  role="hg-cmd">hg update</command> in the example
   1.829 @@ -799,7 +797,7 @@
   1.830      <sect2>
   1.831        <title>Pushing changes to another repository</title>
   1.832  
   1.833 -      <para>Mercurial lets us push changes to another
   1.834 +      <para id="x_66">Mercurial lets us push changes to another
   1.835  	  repository, from the repository we're currently visiting.
   1.836  	  As with the example of <command role="hg-cmd">hg
   1.837  	    pull</command> above, we'll create a temporary repository
   1.838 @@ -807,19 +805,19 @@
   1.839  
   1.840        &interaction.tour.clone-push;
   1.841  
   1.842 -      <para>The <command role="hg-cmd">hg outgoing</command> command
   1.843 +      <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command
   1.844  	  tells us what changes would be pushed into another
   1.845  	  repository.</para>
   1.846  
   1.847        &interaction.tour.outgoing;
   1.848  
   1.849 -      <para>And the
   1.850 +      <para id="x_68">And the
   1.851  	  <command role="hg-cmd">hg push</command> command does the
   1.852  	  actual push.</para>
   1.853  
   1.854        &interaction.tour.push;
   1.855  
   1.856 -      <para>As with
   1.857 +      <para id="x_69">As with
   1.858  	  <command role="hg-cmd">hg pull</command>, the <command
   1.859  	    role="hg-cmd">hg push</command> command does not update
   1.860  	  the working directory in the repository that it's pushing
   1.861 @@ -828,7 +826,7 @@
   1.862  	  does not provide a <literal>-u</literal> option that updates
   1.863  	  the other repository's working directory.)</para>
   1.864  
   1.865 -      <para>What happens if we try to pull or push changes
   1.866 +      <para id="x_6a">What happens if we try to pull or push changes
   1.867  	  and the receiving repository already has those changes?
   1.868  	  Nothing too exciting.</para>
   1.869  
   1.870 @@ -837,7 +835,7 @@
   1.871      <sect2>
   1.872        <title>Sharing changes over a network</title>
   1.873  
   1.874 -      <para>The commands we have covered in the previous few
   1.875 +      <para id="x_6b">The commands we have covered in the previous few
   1.876  	  sections are not limited to working with local repositories.
   1.877  	  Each works in exactly the same fashion over a network
   1.878  	  connection; simply pass in a URL instead of a local
   1.879 @@ -845,7 +843,7 @@
   1.880  	
   1.881        &interaction.tour.outgoing.net;
   1.882  
   1.883 -      <para>In this example, we
   1.884 +      <para id="x_6c">In this example, we
   1.885  	  can see what changes we could push to the remote repository,
   1.886  	  but the repository is understandably not set up to let
   1.887  	  anonymous users push to it.</para>