1.1 --- a/en/appA-svn.xml	Sun Apr 26 23:22:04 2009 -0700
     1.2 +++ b/en/appA-svn.xml	Sun Apr 26 23:22:28 2009 -0700
     1.3 @@ -4,66 +4,66 @@
     1.4    <?dbhtml filename="migrating-to-mercurial.html"?>
     1.5  <title>Migrating to Mercurial</title>
     1.6  
     1.7 -  <para>A common way to test the waters with a new revision control
     1.8 +  <para id="x_6e0">A common way to test the waters with a new revision control
     1.9      tool is to experiment with switching an existing project, rather
    1.10      than starting a new project from scratch.</para>
    1.11  
    1.12 -  <para>In this appendix, we discuss how to import a project's history
    1.13 +  <para id="x_6e1">In this appendix, we discuss how to import a project's history
    1.14      into Mercurial, and what to look out for if you are used to a
    1.15      different revision control system.</para>
    1.16  
    1.17    <sect1>
    1.18      <title>Importing history from another system</title>
    1.19  
    1.20 -    <para>Mercurial ships with an extension named
    1.21 +    <para id="x_6e2">Mercurial ships with an extension named
    1.22        <literal>convert</literal>, which can import project history
    1.23        from most popular revision control systems.  At the time this
    1.24        book was written, it could import history from the following
    1.25        systems:</para>
    1.26      <itemizedlist>
    1.27        <listitem>
    1.28 -	<para>Subversion</para>
    1.29 -      </listitem>
    1.30 -      <listitem>
    1.31 -	<para>CVS</para>
    1.32 -      </listitem>
    1.33 -      <listitem>
    1.34 -	<para>git</para>
    1.35 -      </listitem>
    1.36 -      <listitem>
    1.37 -	<para>Darcs</para>
    1.38 -      </listitem>
    1.39 -      <listitem>
    1.40 -	<para>Bazaar</para>
    1.41 -      </listitem>
    1.42 -      <listitem>
    1.43 -	<para>Monotone</para>
    1.44 -      </listitem>
    1.45 -      <listitem>
    1.46 -	<para>GNU Arch</para>
    1.47 -      </listitem>
    1.48 -      <listitem>
    1.49 -	<para>Mercurial</para>
    1.50 +	<para id="x_6e3">Subversion</para>
    1.51 +      </listitem>
    1.52 +      <listitem>
    1.53 +	<para id="x_6e4">CVS</para>
    1.54 +      </listitem>
    1.55 +      <listitem>
    1.56 +	<para id="x_6e5">git</para>
    1.57 +      </listitem>
    1.58 +      <listitem>
    1.59 +	<para id="x_6e6">Darcs</para>
    1.60 +      </listitem>
    1.61 +      <listitem>
    1.62 +	<para id="x_6e7">Bazaar</para>
    1.63 +      </listitem>
    1.64 +      <listitem>
    1.65 +	<para id="x_6e8">Monotone</para>
    1.66 +      </listitem>
    1.67 +      <listitem>
    1.68 +	<para id="x_6e9">GNU Arch</para>
    1.69 +      </listitem>
    1.70 +      <listitem>
    1.71 +	<para id="x_6ea">Mercurial</para>
    1.72        </listitem>
    1.73      </itemizedlist>
    1.74  
    1.75 -    <para>(To see why Mercurial itself is supported as a source, see
    1.76 +    <para id="x_6eb">(To see why Mercurial itself is supported as a source, see
    1.77        <xref linkend="svn.filemap"/>.)</para>
    1.78  
    1.79 -    <para>You can enable the extension in the usual way, by editing
    1.80 +    <para id="x_6ec">You can enable the extension in the usual way, by editing
    1.81        your <filename>~/.hgrc</filename> file.</para>
    1.82  
    1.83      <programlisting>[extensions]
    1.84  convert =</programlisting>
    1.85  
    1.86 -    <para>This will make a <command>hg convert</command> command
    1.87 +    <para id="x_6ed">This will make a <command>hg convert</command> command
    1.88        available.  The command is easy to use.  For instance, this
    1.89        command will import the Subversion history for the Nose unit
    1.90        testing framework into Mercurial.</para>
    1.91  
    1.92      <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
    1.93  
    1.94 -    <para>The <literal>convert</literal> extension operates
    1.95 +    <para id="x_6ee">The <literal>convert</literal> extension operates
    1.96        incrementally.  In other words, after you have run <command>hg
    1.97  	convert</command> once, running it again will import any new
    1.98        revisions committed after the first run began.  Incremental
    1.99 @@ -78,13 +78,13 @@
   1.100      <sect2>
   1.101        <title>Mapping user names</title>
   1.102  
   1.103 -      <para>Some revision control tools save only short usernames with
   1.104 +      <para id="x_6ef">Some revision control tools save only short usernames with
   1.105  	commits, and these can be difficult to interpret.  The norm
   1.106  	with Mercurial is to save a committer's name and email
   1.107  	address, which is much more useful for talking to them after
   1.108  	the fact.</para>
   1.109  
   1.110 -      <para>If you are converting a tree from a revision control
   1.111 +      <para id="x_6f0">If you are converting a tree from a revision control
   1.112  	system that uses short names, you can map those names to
   1.113  	longer equivalents by passing a <option>--authors</option>
   1.114  	option to <command>hg convert</command>.  This option accepts
   1.115 @@ -94,7 +94,7 @@
   1.116        <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
   1.117  soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
   1.118  
   1.119 -      <para>Whenever <literal>convert</literal> encounters a commit
   1.120 +      <para id="x_6f1">Whenever <literal>convert</literal> encounters a commit
   1.121  	with the username <literal>arist</literal> in the source
   1.122  	repository, it will use the name <literal>Aristotle
   1.123  	  &lt;aristotle@phil.example.gr&gt;</literal> in the converted
   1.124 @@ -105,19 +105,19 @@
   1.125      <sect2 id="svn.filemap">
   1.126        <title>Tidying up the tree</title>
   1.127  
   1.128 -      <para>Not all projects have pristine history.  There may be a
   1.129 +      <para id="x_6f2">Not all projects have pristine history.  There may be a
   1.130  	directory that should never have been checked in, a file that
   1.131  	is too big, or a whole hierarchy that needs to be
   1.132  	refactored.</para>
   1.133  
   1.134 -      <para>The <literal>convert</literal> extension supports the idea
   1.135 +      <para id="x_6f3">The <literal>convert</literal> extension supports the idea
   1.136  	of a <quote>file map</quote> that can reorganize the files and
   1.137  	directories in a project as it imports the project's history.
   1.138  	This is useful not only when importing history from other
   1.139  	revision control systems, but also to prune or refactor a
   1.140  	Mercurial tree.</para>
   1.141  
   1.142 -      <para>To specify a file map, use the <option>--filemap</option>
   1.143 +      <para id="x_6f4">To specify a file map, use the <option>--filemap</option>
   1.144  	option and supply a file name.  A file map contains lines of the
   1.145  	following forms.</para>
   1.146  
   1.147 @@ -131,14 +131,14 @@
   1.148  rename from/some/path to/some/other/place
   1.149  </programlisting>
   1.150  
   1.151 -      <para>The <literal>include</literal> directive causes a file, or
   1.152 +      <para id="x_6f5">The <literal>include</literal> directive causes a file, or
   1.153  	all files under a directory, to be included in the destination
   1.154  	repository.  This also excludes all other files and dirs not
   1.155  	explicitely included.  The <literal>exclude</literal>
   1.156  	directive causes files or directories to be omitted, and
   1.157  	others not explicitly mentioned to be included.</para>
   1.158  
   1.159 -      <para>To move a file or directory from one location to another,
   1.160 +      <para id="x_6f6">To move a file or directory from one location to another,
   1.161  	use the <literal>rename</literal> directive.  If you need to
   1.162  	move a file or directory from a subdirectory into the root of
   1.163  	the repository, use <literal>.</literal> as the second
   1.164 @@ -149,7 +149,7 @@
   1.165    <sect1>
   1.166      <title>Migrating from Subversion</title>
   1.167  
   1.168 -    <para>Subversion is currently the most popular open source
   1.169 +    <para id="x_6f7">Subversion is currently the most popular open source
   1.170        revision control system. Although there are many differences
   1.171        between Mercurial and Subversion, making the transition from
   1.172        Subversion to Mercurial is not particularly difficult.  The two
   1.173 @@ -159,7 +159,7 @@
   1.174      <sect2>
   1.175        <title>Philosophical differences</title>
   1.176  
   1.177 -      <para>The fundamental difference between Subversion and
   1.178 +      <para id="x_6f8">The fundamental difference between Subversion and
   1.179  	Mercurial is of course that Subversion is centralized, while
   1.180  	Mercurial is distributed.  Since Mercurial stores all of a
   1.181  	project's history on your local drive, it only needs to
   1.182 @@ -168,7 +168,7 @@
   1.183  	stores very little information locally, and the client must
   1.184  	thus contact its server for many common operations.</para>
   1.185  
   1.186 -      <para>Subversion more or less gets away without a well-defined
   1.187 +      <para id="x_6f9">Subversion more or less gets away without a well-defined
   1.188  	notion of a branch: which portion of a server's namespace
   1.189  	qualifies as a branch is a matter of convention, with the
   1.190  	software providing no enforcement.  Mercurial treats a
   1.191 @@ -177,14 +177,14 @@
   1.192        <sect3>
   1.193  	<title>Scope of commands</title>
   1.194  
   1.195 -	<para>Since Subversion doesn't know what parts of its
   1.196 +	<para id="x_6fa">Since Subversion doesn't know what parts of its
   1.197  	  namespace are really branches, it treats most commands as
   1.198  	  requests to operate at and below whatever directory you are
   1.199  	  currently visiting.  For instance, if you run <command>svn
   1.200  	    log</command>, you'll get the history of whatever part of
   1.201  	  the tree you're looking at, not the tree as a whole.</para>
   1.202  
   1.203 -	<para>Mercurial's commands behave differently, by defaulting
   1.204 +	<para id="x_6fb">Mercurial's commands behave differently, by defaulting
   1.205  	  to operating over an entire repository.  Run <command>hg
   1.206  	    log</command> and it will tell you the history of the
   1.207  	  entire tree, no matter what part of the working directory
   1.208 @@ -192,7 +192,7 @@
   1.209  	  just a particular file or directory, simply supply it by
   1.210  	  name, e.g. <command>hg log src</command>.</para>
   1.211  
   1.212 -	<para>From my own experience, this difference in default
   1.213 +	<para id="x_6fc">From my own experience, this difference in default
   1.214  	  behaviors is probably the most likely to trip you up if you
   1.215  	  have to switch back and forth frequently between the two
   1.216  	  tools.</para>
   1.217 @@ -201,7 +201,7 @@
   1.218        <sect3>
   1.219  	<title>Multi-user operation and safety</title>
   1.220  
   1.221 -	<para>With Subversion, it is normal (though slightly frowned
   1.222 +	<para id="x_6fd">With Subversion, it is normal (though slightly frowned
   1.223  	  upon) for multiple people to collaborate in a single branch.
   1.224  	  If Alice and Bob are working together, and Alice commits
   1.225  	  some changes to their shared branch, Bob must update his
   1.226 @@ -210,7 +210,7 @@
   1.227  	  made, he can corrupt or lose his modifications during and
   1.228  	  after his update.</para>
   1.229  
   1.230 -	<para>Mercurial encourages a commit-then-merge model instead.
   1.231 +	<para id="x_6fe">Mercurial encourages a commit-then-merge model instead.
   1.232  	  Bob commits his changes locally before pulling changes from,
   1.233  	  or pushing them to, the server that he shares with Alice.
   1.234  	  If Alice pushed her changes before Bob tries to push his, he
   1.235 @@ -219,7 +219,7 @@
   1.236  	  he makes a mistake during the merge, he still has the option
   1.237  	  of reverting to the commit that recorded his changes.</para>
   1.238  
   1.239 -	<para>It is worth emphasizing that these are the common ways
   1.240 +	<para id="x_6ff">It is worth emphasizing that these are the common ways
   1.241  	  of working with these tools. Subversion supports a safer
   1.242  	  work-in-your-own-branch model, but it is cumbersome enough
   1.243  	  in practice to not be widely used.  Mercurial can support
   1.244 @@ -231,15 +231,15 @@
   1.245        <sect3>
   1.246  	<title>Published vs local changes</title>
   1.247  
   1.248 -	<para>A Subversion <command>svn commit</command> command
   1.249 +	<para id="x_700">A Subversion <command>svn commit</command> command
   1.250  	  immediately publishes changes to a server, where they can be
   1.251  	  seen by everyone who has read access.</para>
   1.252  
   1.253 -	<para>With Mercurial, commits are always local, and must be
   1.254 +	<para id="x_701">With Mercurial, commits are always local, and must be
   1.255  	  published via a <command>hg push</command> command
   1.256  	  afterwards.</para>
   1.257  
   1.258 -	<para>Each approach has its advantages and disadvantages.  The
   1.259 +	<para id="x_702">Each approach has its advantages and disadvantages.  The
   1.260  	  Subversion model means that changes are published, and hence
   1.261  	  reviewable and usable, immediately.  On the other hand, this
   1.262  	  means that a user must have commit access to a repository in
   1.263 @@ -247,7 +247,7 @@
   1.264  	  is not lightly given out by most open source
   1.265  	  projects.</para>
   1.266  
   1.267 -	<para>The Mercurial approach allows anyone who can clone a
   1.268 +	<para id="x_703">The Mercurial approach allows anyone who can clone a
   1.269  	  repository to commit changes without the need for someone
   1.270  	  else's permission, and they can then publish their changes
   1.271  	  and continue to participate however they see fit.  The
   1.272 @@ -408,7 +408,7 @@
   1.273    <sect1>
   1.274      <title>Useful tips for newcomers</title>
   1.275  
   1.276 -    <para>Under some revision control systems, printing a diff for a
   1.277 +    <para id="x_704">Under some revision control systems, printing a diff for a
   1.278        single committed revision can be painful. For instance, with
   1.279        Subversion, to see what changed in revision 104654, you must
   1.280        type <command>svn diff -r104653:104654</command>. Mercurial
   1.281 @@ -417,7 +417,7 @@
   1.282        a log message followed by a diff, <command>hg log -r104654
   1.283  	-p</command>.</para>
   1.284  
   1.285 -    <para>When you run <command>hg status</command> without any
   1.286 +    <para id="x_705">When you run <command>hg status</command> without any
   1.287        arguments, it prints the status of the entire tree, with paths
   1.288        relative to the root of the repository.  This makes it tricky to
   1.289        copy a file name from the output of <command>hg status</command>