Dongsheng Song avatar Dongsheng Song committed 7e7c474

Oops, this is the real merge for my hg's oddity

Comments (0)

Files changed (39)

 .\#*
 .run
 .validated-00book.xml
+en/all-ids.dat
 web/hgbook/.database.sqlite3
 web/hgbook/secrets.py
 stylesheets/system-xsl
 
 <!-- Chapters. -->
 
-<!ENTITY ch01     SYSTEM "ch01-intro.xml">
-<!ENTITY ch02     SYSTEM "ch02-tour-basic.xml">
-<!ENTITY ch03     SYSTEM "ch03-tour-merge.xml">
-<!ENTITY ch04     SYSTEM "ch04-concepts.xml">
-<!ENTITY ch05     SYSTEM "ch05-daily.xml">
-<!ENTITY ch06     SYSTEM "ch06-collab.xml">
-<!ENTITY ch07     SYSTEM "ch07-filenames.xml">
-<!ENTITY ch08     SYSTEM "ch08-branch.xml">
-<!ENTITY ch09     SYSTEM "ch09-undo.xml">
-<!ENTITY ch10     SYSTEM "ch10-hook.xml">
-<!ENTITY ch11     SYSTEM "ch11-template.xml">
-<!ENTITY ch12     SYSTEM "ch12-mq.xml">
-<!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
-<!ENTITY ch14     SYSTEM "ch14-hgext.xml">
+<!ENTITY ch00     SYSTEM "ch00-preface.xml">
+<!ENTITY ch01     SYSTEM "ch01-tour-basic.xml">
+<!ENTITY ch02     SYSTEM "ch02-tour-merge.xml">
+<!ENTITY ch03     SYSTEM "ch03-concepts.xml">
+<!ENTITY ch04     SYSTEM "ch04-daily.xml">
+<!ENTITY ch05     SYSTEM "ch05-collab.xml">
+<!ENTITY ch06     SYSTEM "ch06-filenames.xml">
+<!ENTITY ch07     SYSTEM "ch07-branch.xml">
+<!ENTITY ch08     SYSTEM "ch08-undo.xml">
+<!ENTITY ch09     SYSTEM "ch09-hook.xml">
+<!ENTITY ch10     SYSTEM "ch10-template.xml">
+<!ENTITY ch11     SYSTEM "ch11-mq.xml">
+<!ENTITY ch12     SYSTEM "ch12-mq-collab.xml">
+<!ENTITY ch13     SYSTEM "ch13-hgext.xml">
 <!ENTITY appA     SYSTEM "appA-cmdref.xml">
 <!ENTITY appB     SYSTEM "appB-mq-ref.xml">
 <!ENTITY appC     SYSTEM "appC-srcinstall.xml">
   &ch11;
   &ch12;
   &ch13;
-  &ch14;
   <!-- &appA; -->
   &appB;
   &appC;
 
 all: web
 
-../stylesheets/system-xsl: $(system-xsl-dir)
+../xsl/system-xsl: $(system-xsl-dir)
 	ln -s $< $@
 
 web: ../xsl/system-xsl websup html
 
-html: ../stylesheets/system-xsl $(xml-src-files) valid
-	xsltproc $(xsltproc-opts) -o html/read/x ../stylesheets/chunk-stylesheet.xsl 00book.xml
+html: ../xsl/system-xsl $(xml-src-files) valid
+	xsltproc $(xsltproc-opts) -o html/read/x ../xsl/chunk-stylesheet.xsl 00book.xml
 	for i in html/read/*.html; do \
 	  gzip -9 -c $$i > $$i.gz; \
 	done
 
 websup: $(extras-web)
-	mkdir -p $(obj-websup)/images
-	cp ../stylesheets/system-xsl/images/*.png $(obj-websup)/images
-	cp -f ../web/icons/*.png $(obj-websup)/images
+	mkdir -p $(obj-websup)/figs
+	cp ../xsl/system-xsl/images/*.png $(obj-websup)/figs
+	cp -f ../web/icons/*.png $(obj-websup)/figs
+
+all-ids.dat: ../xsl/all-ids.xsl $(xml-src-files)
+	$(xsltproc) $(xsltproc-opts) -o $@ ../xsl/all-ids.xsl 00book.xml
 
 web: websup
 

en/appA-cmdref.xml

 <appendix id="cmdref">
 <title>Command reference</title>
 
-<para>\cmdref{add}{add files at the next commit}
+<para id="x_653">\cmdref{add}{add files at the next commit}
 \optref{add}{I}{include}
 \optref{add}{X}{exclude}
 \optref{add}{n}{dry-run}</para>
 
-<para>\cmdref{diff}{print changes in history or working directory}</para>
+<para id="x_654">\cmdref{diff}{print changes in history or working directory}</para>
 
-<para>Show differences between revisions for the specified files or
+<para id="x_655">Show differences between revisions for the specified files or
 directories, using the unified diff format.  For a description of the
 unified diff format, see section <xref linkend="sec.mq.patch"/>.</para>
 
-<para>By default, this command does not print diffs for files that Mercurial
+<para id="x_656">By default, this command does not print diffs for files that Mercurial
 considers to contain binary data.  To control this behaviour, see the
 <option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
 
 <sect2>
 <title>Options</title>
 
-<para>\loptref{diff}{nodates}</para>
+<para id="x_657">\loptref{diff}{nodates}</para>
 
-<para>Omit date and time information when printing diff headers.</para>
+<para id="x_658">Omit date and time information when printing diff headers.</para>
 
-<para>\optref{diff}{B}{ignore-blank-lines}</para>
+<para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para>
 
-<para>Do not print changes that only insert or delete blank lines.  A line
+<para id="x_65a">Do not print changes that only insert or delete blank lines.  A line
 that contains only whitespace is not considered blank.
 </para>
 
-<para>\optref{diff}{I}{include}
+<para id="x_65b">\optref{diff}{I}{include}
 </para>
 
-<para>Include files and directories whose names match the given patterns.
+<para id="x_65c">Include files and directories whose names match the given patterns.
 </para>
 
-<para>\optref{diff}{X}{exclude}
+<para id="x_65d">\optref{diff}{X}{exclude}
 </para>
 
-<para>Exclude files and directories whose names match the given patterns.
+<para id="x_65e">Exclude files and directories whose names match the given patterns.
 </para>
 
-<para>\optref{diff}{a}{text}
+<para id="x_65f">\optref{diff}{a}{text}
 </para>
 
-<para>If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
+<para id="x_660">If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
 diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
 forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
 all of them.
 </para>
 
-<para>This option is useful for files that are <quote>mostly text</quote> but have a
+<para id="x_661">This option is useful for files that are <quote>mostly text</quote> but have a
 few embedded NUL characters.  If you use it on files that contain a
 lot of binary data, its output will be incomprehensible.
 </para>
 
-<para>\optref{diff}{b}{ignore-space-change}
+<para id="x_662">\optref{diff}{b}{ignore-space-change}
 </para>
 
-<para>Do not print a line if the only change to that line is in the amount
+<para id="x_663">Do not print a line if the only change to that line is in the amount
 of white space it contains.
 </para>
 
-<para>\optref{diff}{g}{git}
+<para id="x_664">\optref{diff}{g}{git}
 </para>
 
-<para>Print <command>git</command>-compatible diffs.  XXX reference a format
+<para id="x_665">Print <command>git</command>-compatible diffs.  XXX reference a format
 description.
 </para>
 
-<para>\optref{diff}{p}{show-function}
+<para id="x_666">\optref{diff}{p}{show-function}
 </para>
 
-<para>Display the name of the enclosing function in a hunk header, using a
+<para id="x_667">Display the name of the enclosing function in a hunk header, using a
 simple heuristic.  This functionality is enabled by default, so the
 <option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
 the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
 
 <!-- &interaction.cmdref.diff-p; -->
 
-<para>\optref{diff}{r}{rev}
+<para id="x_668">\optref{diff}{r}{rev}
 </para>
 
-<para>Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
+<para id="x_669">Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
 accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
 compare.
 </para>
 
 <orderedlist>
-<listitem><para>Display the differences between the parent revision of the
+<listitem><para id="x_66a">Display the differences between the parent revision of the
   working directory and the working directory.
 </para>
 </listitem>
-<listitem><para>Display the differences between the specified changeset and the
+<listitem><para id="x_66b">Display the differences between the specified changeset and the
   working directory.
 </para>
 </listitem>
-<listitem><para>Display the differences between the two specified changesets.
+<listitem><para id="x_66c">Display the differences between the two specified changesets.
 </para>
 </listitem></orderedlist>
 
-<para>You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
+<para id="x_66d">You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
 options or revision range notation.  For example, the two revision
 specifications below are equivalent.
 </para>
 <programlisting>hg diff -r 10 -r 20
 hg diff -r10:20</programlisting>
 
-<para>When you provide two revisions, Mercurial treats the order of those
+<para id="x_66e">When you provide two revisions, Mercurial treats the order of those
 revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
 produce a diff that will transform files from their contents as of
 revision 10 to their contents as of revision 20, while
 diffing against the working directory.
 </para>
 
-<para>\optref{diff}{w}{ignore-all-space}
+<para id="x_66f">\optref{diff}{w}{ignore-all-space}
 </para>
 
-<para>\cmdref{version}{print version and copyright information}
+<para id="x_670">\cmdref{version}{print version and copyright information}
 </para>
 
-<para>This command displays the version of Mercurial you are running, and
+<para id="x_671">This command displays the version of Mercurial you are running, and
 its copyright license.  There are four kinds of version string that
 you may see.
 </para>
 <itemizedlist>
-<listitem><para>The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
+<listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
   not built in a Mercurial repository, and cannot determine its own
   version.
 </para>
 </listitem>
-<listitem><para>A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
+<listitem><para id="x_673">A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
   build of a revision of Mercurial that was identified by a specific
   tag in the repository where it was built.  (This doesn't necessarily
   mean that you're running an official release; someone else could
   built Mercurial.)
 </para>
 </listitem>
-<listitem><para>A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
+<listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
   is a build of the given revision of Mercurial.
 </para>
 </listitem>
-<listitem><para>A hexadecimal string followed by a date, such as
+<listitem><para id="x_675">A hexadecimal string followed by a date, such as
   <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
   revision of Mercurial, where the build repository contained some
   local changes that had not been committed.
 <sect3 id="cmdref.diff-vs-status">
 <title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
 
-<para>When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
+<para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
 that Mercurial will record changes for the next time you perform a
 commit.  If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
 prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
 listed.  There are two possible reasons for this.
 </para>
 
-<para>The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
+<para id="x_677">The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
 that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> command
 normally outputs unified diffs, which don't have the ability to
 represent some changes that Mercurial can track.  Most notably,
 executable, but Mercurial records this information.
 </para>
 
-<para>If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
+<para id="x_678">If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
 display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
 extra information.
 </para>
 
-<para>The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
+<para id="x_679">The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
 for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
 invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
 first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
 <sect3>
 <title>Generating safe binary diffs</title>
 
-<para>If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
+<para id="x_67a">If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
 diffs of files that are either <quote>mostly text</quote> or contain lots of
 binary data, those diffs cannot subsequently be applied by either
 Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
 command.
 </para>
 
-<para>If you want to generate a diff of a binary file that is safe to use as
+<para id="x_67b">If you want to generate a diff of a binary file that is safe to use as
 input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
 generate the patch.  The system <command>patch</command> command cannot handle
 binary patches at all.

en/appB-mq-ref.xml

   <sect1 id="sec.mqref.cmdref">
     <title>MQ command reference</title>
 
-    <para>For an overview of the commands provided by MQ, use the
+    <para id="x_5e8">For an overview of the commands provided by MQ, use the
       command <command role="hg-cmd">hg help mq</command>.</para>
 
     <sect2>
       <title><command role="hg-ext-mq">qapplied</command>&emdash;print
 	applied patches</title>
 
-      <para>The <command role="hg-ext-mq">qapplied</command> command
+      <para id="x_5e9">The <command role="hg-ext-mq">qapplied</command> command
 	prints the current stack of applied patches.  Patches are
 	printed in oldest-to-newest order, so the last patch in the
 	list is the <quote>top</quote> patch.</para>
       <title><command role="hg-ext-mq">qcommit</command>&emdash;commit
 	changes in the queue repository</title>
 
-      <para>The <command role="hg-ext-mq">qcommit</command> command
+      <para id="x_5ea">The <command role="hg-ext-mq">qcommit</command> command
 	commits any outstanding changes in the <filename
 	  role="special" class="directory">.hg/patches</filename>
 	repository.  This command only works if the <filename
 	after running <command
 	  role="hg-ext-mq">qinit</command>.</para>
 
-      <para>This command is shorthand for <command role="hg-cmd">hg
+      <para id="x_5eb">This command is shorthand for <command role="hg-cmd">hg
 	  commit --cwd .hg/patches</command>.</para>
     </sect2>
     <sect2>
 	from the <filename role="special">series</filename>
 	file}</title>
 
-      <para>The <command role="hg-ext-mq">qdelete</command> command
+      <para id="x_5ec">The <command role="hg-ext-mq">qdelete</command> command
 	removes the entry for a patch from the <filename
 	  role="special">series</filename> file in the <filename
 	  role="special" class="directory">.hg/patches</filename>
 	the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
 	to do that.</para>
 
-      <para>Options:</para>
+      <para id="x_5ed">Options:</para>
       <itemizedlist>
-	<listitem><para><option
+	<listitem><para id="x_5ee"><option
 	      role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
 	    patch file.</para>
 	</listitem></itemizedlist>
       <title><command role="hg-ext-mq">qdiff</command>&emdash;print a
 	diff of the topmost applied patch</title>
 
-      <para>The <command role="hg-ext-mq">qdiff</command> command
+      <para id="x_5ef">The <command role="hg-ext-mq">qdiff</command> command
 	prints a diff of the topmost applied patch. It is equivalent
 	to <command role="hg-cmd">hg diff -r-2:-1</command>.</para>
 
       <title><command role="hg-ext-mq">qfold</command>&emdash;merge
 	(<quote>fold</quote>) several patches into one</title>
 
-      <para>The <command role="hg-ext-mq">qfold</command> command
+      <para id="x_5f0">The <command role="hg-ext-mq">qfold</command> command
 	merges multiple patches into the topmost applied patch, so
 	that the topmost applied patch makes the union of all of the
 	changes in the patches in question.</para>
 
-      <para>The patches to fold must not be applied; <command
+      <para id="x_5f1">The patches to fold must not be applied; <command
 	  role="hg-ext-mq">qfold</command> will exit with an error if
 	any is.  The order in which patches are folded is significant;
 	<command role="hg-cmd">hg qfold a b</command> means
 	  <literal>a</literal>, followed by
 	  <literal>b</literal></quote>.</para>
 
-      <para>The comments from the folded patches are appended to the
+      <para id="x_5f2">The comments from the folded patches are appended to the
 	comments of the destination patch, with each block of comments
 	separated by three asterisk
 	(<quote><literal>*</literal></quote>) characters.  Use the
 	edit the commit message for the combined patch/changeset after
 	the folding has completed.</para>
 
-      <para>Options:</para>
+      <para id="x_5f3">Options:</para>
       <itemizedlist>
-	<listitem><para><option
+	<listitem><para id="x_5f4"><option
 	      role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
 	    commit message and patch description for the newly folded
 	    patch.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_5f5"><option
 	      role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
 	    contents of the given file as the new commit message and
 	    patch description for the folded patch.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_5f6"><option
 	      role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
 	    given text as the new commit message and patch description
 	    for the folded patch.</para>
 	  role="hg-ext-mq">qheader</command>&emdash;display the
 	header/description of a patch</title>
 
-      <para>The <command role="hg-ext-mq">qheader</command> command
+      <para id="x_5f7">The <command role="hg-ext-mq">qheader</command> command
 	prints the header, or description, of a patch.  By default, it
 	prints the header of the topmost applied patch. Given an
 	argument, it prints the header of the named patch.</para>
       <title><command role="hg-ext-mq">qimport</command>&emdash;import
 	a third-party patch into the queue</title>
 
-      <para>The <command role="hg-ext-mq">qimport</command> command
+      <para id="x_5f8">The <command role="hg-ext-mq">qimport</command> command
 	adds an entry for an external patch to the <filename
 	  role="special">series</filename> file, and copies the patch
 	into the <filename role="special"
 	the entry immediately after the topmost applied patch, but
 	does not push the patch.</para>
 
-      <para>If the <filename role="special"
+      <para id="x_5f9">If the <filename role="special"
 	  class="directory">.hg/patches</filename> directory is a
 	repository, <command role="hg-ext-mq">qimport</command>
 	automatically does an <command role="hg-cmd">hg add</command>
       <title><command role="hg-ext-mq">qinit</command>&emdash;prepare
 	a repository to work with MQ</title>
 
-      <para>The <command role="hg-ext-mq">qinit</command> command
+      <para id="x_5fa">The <command role="hg-ext-mq">qinit</command> command
 	prepares a repository to work with MQ.  It creates a directory
 	called <filename role="special"
 	  class="directory">.hg/patches</filename>.</para>
 
-      <para>Options:</para>
+      <para id="x_5fb">Options:</para>
       <itemizedlist>
-	<listitem><para><option
+	<listitem><para id="x_5fc"><option
 	      role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
 	    <filename role="special"
 	      class="directory">.hg/patches</filename> as a repository
 	    file.</para>
 	</listitem></itemizedlist>
 
-      <para>When the <filename role="special"
+      <para id="x_5fd">When the <filename role="special"
 	  class="directory">.hg/patches</filename> directory is a
 	repository, the <command role="hg-ext-mq">qimport</command>
 	and <command role="hg-ext-mq">qnew</command> commands
       <title><command role="hg-ext-mq">qnew</command>&emdash;create a
 	new patch</title>
 
-      <para>The <command role="hg-ext-mq">qnew</command> command
+      <para id="x_5fe">The <command role="hg-ext-mq">qnew</command> command
 	creates a new patch.  It takes one mandatory argument, the
 	name to use for the patch file.  The newly created patch is
 	created empty by default.  It is added to the <filename
 	topmost applied patch, and is immediately pushed on top of
 	that patch.</para>
 
-      <para>If <command role="hg-ext-mq">qnew</command> finds modified
+      <para id="x_5ff">If <command role="hg-ext-mq">qnew</command> finds modified
 	files in the working directory, it will refuse to create a new
 	patch unless the <option
 	  role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
 	  role="hg-ext-mq">qrefresh</command> your topmost applied
 	patch before you apply a new patch on top of it.</para>
 
-      <para>Options:</para>
+      <para id="x_600">Options:</para>
       <itemizedlist>
-	<listitem><para><option
+	<listitem><para id="x_601"><option
 	      role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
 	    patch if the contents of the working directory are
 	    modified.  Any outstanding modifications are added to the
 	    newly created patch, so after this command completes, the
 	    working directory will no longer be modified.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_602"><option
 	      role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
 	    text as the commit message. This text will be stored at
 	    the beginning of the patch file, before the patch
       <title><command role="hg-ext-mq">qnext</command>&emdash;print
 	the name of the next patch</title>
 
-      <para>The <command role="hg-ext-mq">qnext</command> command
+      <para id="x_603">The <command role="hg-ext-mq">qnext</command> command
 	prints the name name of the next patch in the <filename
 	  role="special">series</filename> file after the topmost
 	applied patch.  This patch will become the topmost applied
       <title><command role="hg-ext-mq">qpop</command>&emdash;pop
 	patches off the stack</title>
 
-      <para>The <command role="hg-ext-mq">qpop</command> command
+      <para id="x_604">The <command role="hg-ext-mq">qpop</command> command
 	removes applied patches from the top of the stack of applied
 	patches.  By default, it removes only one patch.</para>
 
-      <para>This command removes the changesets that represent the
+      <para id="x_605">This command removes the changesets that represent the
 	popped patches from the repository, and updates the working
 	directory to undo the effects of the patches.</para>
 
-      <para>This command takes an optional argument, which it uses as
+      <para id="x_606">This command takes an optional argument, which it uses as
 	the name or index of the patch to pop to.  If given a name, it
 	will pop patches until the named patch is the topmost applied
 	patch.  If given a number, <command
 	It pops patches until the patch identified by the given index
 	is the topmost applied patch.</para>
 
-      <para>The <command role="hg-ext-mq">qpop</command> command does
+      <para id="x_607">The <command role="hg-ext-mq">qpop</command> command does
 	not read or write patches or the <filename
 	  role="special">series</filename> file.  It is thus safe to
 	<command role="hg-ext-mq">qpop</command> a patch that you have
 	In the latter two cases, use the name of the patch as it was
 	when you applied it.</para>
 
-      <para>By default, the <command role="hg-ext-mq">qpop</command>
+      <para id="x_608">By default, the <command role="hg-ext-mq">qpop</command>
 	command will not pop any patches if the working directory has
 	been modified.  You can override this behaviour using the
 	<option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
 	which reverts all modifications in the working
 	directory.</para>
 
-      <para>Options:</para>
+      <para id="x_609">Options:</para>
       <itemizedlist>
-	<listitem><para><option
+	<listitem><para id="x_60a"><option
 	      role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
 	    applied patches.  This returns the repository to its state
 	    before you applied any patches.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_60b"><option
 	      role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
 	    revert any modifications to the working directory when
 	    popping.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_60c"><option
 	      role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
 	    from the named queue.</para>
 	</listitem></itemizedlist>
 
-      <para>The <command role="hg-ext-mq">qpop</command> command
+      <para id="x_60d">The <command role="hg-ext-mq">qpop</command> command
 	removes one line from the end of the <filename
 	  role="special">status</filename> file for each patch that it
 	pops.</para>
       <title><command role="hg-ext-mq">qprev</command>&emdash;print
 	the name of the previous patch</title>
 
-      <para>The <command role="hg-ext-mq">qprev</command> command
+      <para id="x_60e">The <command role="hg-ext-mq">qprev</command> command
 	prints the name of the patch in the <filename
 	  role="special">series</filename> file that comes before the
 	topmost applied patch. This will become the topmost applied
       <title><command role="hg-ext-mq">qpush</command>&emdash;push
 	patches onto the stack</title>
 
-      <para>The <command role="hg-ext-mq">qpush</command> command adds
+      <para id="x_60f">The <command role="hg-ext-mq">qpush</command> command adds
 	patches onto the applied stack.  By default, it adds only one
 	patch.</para>
 
-      <para>This command creates a new changeset to represent each
+      <para id="x_610">This command creates a new changeset to represent each
 	applied patch, and updates the working directory to apply the
 	effects of the patches.</para>
 
-      <para>The default data used when creating a changeset are as
+      <para id="x_611">The default data used when creating a changeset are as
 	follows:</para>
       <itemizedlist>
-	<listitem><para>The commit date and time zone are the current
+	<listitem><para id="x_612">The commit date and time zone are the current
 	    date and time zone.  Because these data are used to
 	    compute the identity of a changeset, this means that if
 	    you <command role="hg-ext-mq">qpop</command> a patch and
 	    changeset that you push will have a different identity
 	    than the changeset you popped.</para>
 	</listitem>
-	<listitem><para>The author is the same as the default used by
+	<listitem><para id="x_613">The author is the same as the default used by
 	    the <command role="hg-cmd">hg commit</command>
 	    command.</para>
 	</listitem>
-	<listitem><para>The commit message is any text from the patch
+	<listitem><para id="x_614">The commit message is any text from the patch
 	    file that comes before the first diff header.  If there is
 	    no such text, a default commit message is used that
 	    identifies the name of the patch.</para>
 	</listitem></itemizedlist>
-      <para>If a patch contains a Mercurial patch header (XXX add
+      <para id="x_615">If a patch contains a Mercurial patch header (XXX add
 	link), the information in the patch header overrides these
 	defaults.</para>
 
-      <para>Options:</para>
+      <para id="x_616">Options:</para>
       <itemizedlist>
-	<listitem><para><option
+	<listitem><para id="x_617"><option
 	      role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
 	    unapplied patches from the <filename
 	      role="special">series</filename> file until there are
 	    none left to push.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_618"><option
 	      role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
 	    of the patch to the end of the commit message.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_619"><option
 	      role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
 	    fails to apply cleanly, use the entry for the patch in
 	    another saved queue to compute the parameters for a
 	    normal Mercurial merge machinery.  Use the resolution of
 	    the merge as the new patch content.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_61a"><option
 	      role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
 	    named queue if merging while pushing.</para>
 	</listitem></itemizedlist>
 
-      <para>The <command role="hg-ext-mq">qpush</command> command
+      <para id="x_61b">The <command role="hg-ext-mq">qpush</command> command
 	reads, but does not modify, the <filename
 	  role="special">series</filename> file.  It appends one line
 	to the <command role="hg-cmd">hg status</command> file for
 	  role="hg-ext-mq">qrefresh</command>&emdash;update the
 	topmost applied patch</title>
 
-      <para>The <command role="hg-ext-mq">qrefresh</command> command
+      <para id="x_61c">The <command role="hg-ext-mq">qrefresh</command> command
 	updates the topmost applied patch.  It modifies the patch,
 	removes the old changeset that represented the patch, and
 	creates a new changeset to represent the modified
 	patch.</para>
 
-      <para>The <command role="hg-ext-mq">qrefresh</command> command
+      <para id="x_61d">The <command role="hg-ext-mq">qrefresh</command> command
 	looks for the following modifications:</para>
       <itemizedlist>
-	<listitem><para>Changes to the commit message, i.e. the text
+	<listitem><para id="x_61e">Changes to the commit message, i.e. the text
 	    before the first diff header in the patch file, are
 	    reflected in the new changeset that represents the
 	    patch.</para>
 	</listitem>
-	<listitem><para>Modifications to tracked files in the working
+	<listitem><para id="x_61f">Modifications to tracked files in the working
 	    directory are added to the patch.</para>
 	</listitem>
-	<listitem><para>Changes to the files tracked using <command
+	<listitem><para id="x_620">Changes to the files tracked using <command
 	      role="hg-cmd">hg add</command>, <command
 	      role="hg-cmd">hg copy</command>, <command
 	      role="hg-cmd">hg remove</command>, or <command
 	    removed files and rename sources are removed.</para>
 	</listitem></itemizedlist>
 
-      <para>Even if <command role="hg-ext-mq">qrefresh</command>
+      <para id="x_621">Even if <command role="hg-ext-mq">qrefresh</command>
 	detects no changes, it still recreates the changeset that
 	represents the patch.  This causes the identity of the
 	changeset to differ from the previous changeset that
 	identified the patch.</para>
 
-      <para>Options:</para>
+      <para id="x_622">Options:</para>
       <itemizedlist>
-	<listitem><para><option
+	<listitem><para id="x_623"><option
 	      role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
 	    the commit and patch description, using the preferred text
 	    editor.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_624"><option
 	      role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
 	    the commit message and patch description, using the given
 	    text.</para>
 	</listitem>
-	<listitem><para><option
+	<listitem><para id="x_625"><option
 	      role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
 	    the commit message and patch description, using text from
 	    the given file.</para>
       <title><command role="hg-ext-mq">qrename</command>&emdash;rename
 	a patch</title>
 
-      <para>The <command role="hg-ext-mq">qrename</command> command
+      <para id="x_626">The <command role="hg-ext-mq">qrename</command> command
 	renames a patch, and changes the entry for the patch in the
 	<filename role="special">series</filename> file.</para>
 
-      <para>With a single argument, <command
+      <para id="x_627">With a single argument, <command
 	  role="hg-ext-mq">qrename</command> renames the topmost
 	applied patch.  With two arguments, it renames its first
 	argument to its second.</para>
 	  role="hg-ext-mq">qrestore</command>&emdash;restore saved
 	queue state</title>
 
-      <para>XXX No idea what this does.</para>
+      <para id="x_628">XXX No idea what this does.</para>
 
     </sect2>
     <sect2>
       <title><command role="hg-ext-mq">qsave</command>&emdash;save
 	current queue state</title>
 
-      <para>XXX Likewise.</para>
+      <para id="x_629">XXX Likewise.</para>
 
     </sect2>
     <sect2>
       <title><command role="hg-ext-mq">qseries</command>&emdash;print
 	the entire patch series</title>
 
-      <para>The <command role="hg-ext-mq">qseries</command> command
+      <para id="x_62a">The <command role="hg-ext-mq">qseries</command> command
 	prints the entire patch series from the <filename
 	  role="special">series</filename> file.  It prints only patch
 	names, not empty lines or comments.  It prints in order from
       <title><command role="hg-ext-mq">qtop</command>&emdash;print the
 	name of the current patch</title>
 
-      <para>The <command role="hg-ext-mq">qtop</command> prints the
+      <para id="x_62b">The <command role="hg-ext-mq">qtop</command> prints the
 	name of the topmost currently applied patch.</para>
 
     </sect2>
 	  role="hg-ext-mq">qunapplied</command>&emdash;print patches
 	not yet applied</title>
 
-      <para>The <command role="hg-ext-mq">qunapplied</command> command
+      <para id="x_62c">The <command role="hg-ext-mq">qunapplied</command> command
 	prints the names of patches from the <filename
 	  role="special">series</filename> file that are not yet
 	applied.  It prints them in order from the next patch that
       <title><command role="hg-cmd">hg strip</command>&emdash;remove a
 	revision and descendants</title>
 
-      <para>The <command role="hg-cmd">hg strip</command> command
+      <para id="x_62d">The <command role="hg-cmd">hg strip</command> command
 	removes a revision, and all of its descendants, from the
 	repository.  It undoes the effects of the removed revisions
 	from the repository, and updates the working directory to the
 	first parent of the removed revision.</para>
 
-      <para>The <command role="hg-cmd">hg strip</command> command
+      <para id="x_62e">The <command role="hg-cmd">hg strip</command> command
 	saves a backup of the removed changesets in a bundle, so that
 	they can be reapplied if removed in error.</para>
 
-      <para>Options:</para>
+      <para id="x_62f">Options:</para>
       <itemizedlist>
-	<listitem><para><option role="hg-opt-strip">-b</option>: Save
+	<listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save
 	    unrelated changesets that are intermixed with the stripped
 	    changesets in the backup bundle.</para>
 	</listitem>
-	<listitem><para><option role="hg-opt-strip">-f</option>: If a
+	<listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
 	    branch has multiple heads, remove all heads. XXX This
 	    should be renamed, and use <literal>-f</literal> to strip
 	    revs when there are pending changes.</para>
 	</listitem>
-	<listitem><para><option role="hg-opt-strip">-n</option>: Do
+	<listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
 	    not save a backup bundle.</para>
 	</listitem></itemizedlist>
 
       <title>The <filename role="special">series</filename>
 	file</title>
 
-      <para>The <filename role="special">series</filename> file
+      <para id="x_633">The <filename role="special">series</filename> file
 	contains a list of the names of all patches that MQ can apply.
 	It is represented as a list of names, with one name saved per
 	line.  Leading and trailing white space in each line are
 	ignored.</para>
 
-      <para>Lines may contain comments.  A comment begins with the
+      <para id="x_634">Lines may contain comments.  A comment begins with the
 	<quote><literal>#</literal></quote> character, and extends to
 	the end of the line.  Empty lines, and lines that contain only
 	comments, are ignored.</para>
 
-      <para>You will often need to edit the <filename
+      <para id="x_635">You will often need to edit the <filename
 	  role="special">series</filename> file by hand, hence the
 	support for comments and empty lines noted above.  For
 	example, you can comment out a patch temporarily, and <command
 	patches are applied by reordering their entries in the
 	<filename role="special">series</filename> file.</para>
 
-      <para>Placing the <filename role="special">series</filename>
+      <para id="x_636">Placing the <filename role="special">series</filename>
 	file under revision control is also supported; it is a good
 	idea to place all of the patches that it refers to under
 	revision control, as well.  If you create a patch directory
       <title>The <filename role="special">status</filename>
 	file</title>
 
-      <para>The <filename role="special">status</filename> file
+      <para id="x_637">The <filename role="special">status</filename> file
 	contains the names and changeset hashes of all patches that MQ
 	currently has applied.  Unlike the <filename
 	  role="special">series</filename> file, this file is not

en/appC-srcinstall.xml

   <sect1 id="sec.srcinstall.unixlike">
     <title>On a Unix-like system</title>
 
-    <para>If you are using a Unix-like system that has a sufficiently
+    <para id="x_5e0">If you are using a Unix-like system that has a sufficiently
       recent version of Python (2.3 or newer) available, it is easy to
       install Mercurial from source.</para>
     <orderedlist>
-      <listitem><para>Download a recent source tarball from <ulink
+      <listitem><para id="x_5e1">Download a recent source tarball from <ulink
 	    url="http://www.selenic.com/mercurial/download">http://www.selenic.com/mercurial/download</ulink>.</para>
       </listitem>
-      <listitem><para>Unpack the tarball:</para>
+      <listitem><para id="x_5e2">Unpack the tarball:</para>
 	<programlisting>gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting>
       </listitem>
-      <listitem><para>Go into the source directory and run the
+      <listitem><para id="x_5e3">Go into the source directory and run the
 	  installer script.  This will build Mercurial and install it
 	  in your home directory.</para>
 	<programlisting>cd mercurial-MYVERSION
 python setup.py install --force --home=$HOME</programlisting>
       </listitem>
     </orderedlist>
-    <para>Once the install finishes, Mercurial will be in the
+    <para id="x_5e4">Once the install finishes, Mercurial will be in the
       <literal>bin</literal> subdirectory of your home directory.
       Don't forget to make sure that this directory is present in your
       shell's search path.</para>
 
-    <para>You will probably need to set the <envar>PYTHONPATH</envar>
+    <para id="x_5e5">You will probably need to set the <envar>PYTHONPATH</envar>
       environment variable so that the Mercurial executable can find
       the rest of the Mercurial packages.  For example, on my laptop,
       I have set it to <literal>/home/bos/lib/python</literal>.  The
   <sect1>
     <title>On Windows</title>
 
-    <para>Building and installing Mercurial on Windows requires a
+    <para id="x_5e6">Building and installing Mercurial on Windows requires a
       variety of tools, a fair amount of technical knowledge, and
       considerable patience.  I very much <emphasis>do not
 	recommend</emphasis> this route if you are a <quote>casual
 	user</quote>.  Unless you intend to hack on Mercurial, I
       strongly suggest that you use a binary package instead.</para>
 
-    <para>If you are intent on building Mercurial from source on
+    <para id="x_5e7">If you are intent on building Mercurial from source on
       Windows, follow the <quote>hard way</quote> directions on the
       Mercurial wiki at <ulink
 	url="http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall">http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>, 

en/appD-license.xml

   <?dbhtml filename="open-publication-license.html"?>
   <title>Open Publication License</title>
 
-  <para>Version 1.0, 8 June 1999</para>
+  <para id="x_638">Version 1.0, 8 June 1999</para>
 
   <sect1>
     <title>Requirements on both unmodified and modified
       versions</title>
 
-    <para>The Open Publication works may be reproduced and distributed
+    <para id="x_639">The Open Publication works may be reproduced and distributed
       in whole or in part, in any medium physical or electronic,
       provided that the terms of this license are adhered to, and that
       this license or an incorporation of it by reference (with any
       options elected by the author(s) and/or publisher) is displayed
       in the reproduction.</para>
 
-    <para>Proper form for an incorporation by reference is as
+    <para id="x_63a">Proper form for an incorporation by reference is as
       follows:</para>
 
     <blockquote>
-      <para>  Copyright (c) <emphasis>year</emphasis> by
+      <para id="x_63b">  Copyright (c) <emphasis>year</emphasis> by
 	<emphasis>author's name or designee</emphasis>. This material
 	may be distributed only subject to the terms and conditions
 	set forth in the Open Publication License,
 	  url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
     </blockquote>
 
-    <para>The reference must be immediately followed with any options
+    <para id="x_63c">The reference must be immediately followed with any options
       elected by the author(s) and/or publisher of the document (see
       section <xref linkend="sec.opl.options"/>).</para>
 
-    <para>Commercial redistribution of Open Publication-licensed
+    <para id="x_63d">Commercial redistribution of Open Publication-licensed
       material is permitted.</para>
 
-    <para>Any publication in standard (paper) book form shall require
+    <para id="x_63e">Any publication in standard (paper) book form shall require
       the citation of the original publisher and author. The publisher
       and author's names shall appear on all outer surfaces of the
       book. On all outer surfaces of the book the original publisher's
   <sect1>
     <title>Copyright</title>
 
-    <para>The copyright to each Open Publication is owned by its
+    <para id="x_63f">The copyright to each Open Publication is owned by its
       author(s) or designee.</para>
 
   </sect1>
   <sect1>
     <title>Scope of license</title>
 
-    <para>The following license terms apply to all Open Publication
+    <para id="x_640">The following license terms apply to all Open Publication
       works, unless otherwise explicitly stated in the
       document.</para>
 
-    <para>Mere aggregation of Open Publication works or a portion of
+    <para id="x_641">Mere aggregation of Open Publication works or a portion of
       an Open Publication work with other works or programs on the
       same media shall not cause this license to apply to those other
       works. The aggregate work shall contain a notice specifying the
       inclusion of the Open Publication material and appropriate
       copyright notice.</para>
 
-    <para><emphasis role="bold">Severability</emphasis>. If any part
+    <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part
       of this license is found to be unenforceable in any
       jurisdiction, the remaining portions of the license remain in
       force.</para>
 
-    <para><emphasis role="bold">No warranty</emphasis>. Open
+    <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open
       Publication works are licensed and provided <quote>as is</quote>
       without warranty of any kind, express or implied, including, but
       not limited to, the implied warranties of merchantability and
   <sect1>
     <title>Requirements on modified works</title>
 
-    <para>All modified versions of documents covered by this license,
+    <para id="x_644">All modified versions of documents covered by this license,
       including translations, anthologies, compilations and partial
       documents, must meet the following requirements:</para>
 
     <orderedlist>
-      <listitem><para>The modified version must be labeled as
+      <listitem><para id="x_645">The modified version must be labeled as
 	  such.</para>
       </listitem>
-      <listitem><para>The person making the modifications must be
+      <listitem><para id="x_646">The person making the modifications must be
 	  identified and the modifications dated.</para>
       </listitem>
-      <listitem><para>Acknowledgement of the original author and
+      <listitem><para id="x_647">Acknowledgement of the original author and
 	  publisher if applicable must be retained according to normal
 	  academic citation practices.</para>
       </listitem>
-      <listitem><para>The location of the original unmodified document
+      <listitem><para id="x_648">The location of the original unmodified document
 	  must be identified.</para>
       </listitem>
-      <listitem><para>The original author's (or authors') name(s) may
+      <listitem><para id="x_649">The original author's (or authors') name(s) may
 	  not be used to assert or imply endorsement of the resulting
 	  document without the original author's (or authors')
 	  permission.</para>
   <sect1>
     <title>Good-practice recommendations</title>
 
-    <para>In addition to the requirements of this license, it is
+    <para id="x_64a">In addition to the requirements of this license, it is
       requested from and strongly recommended of redistributors
       that:</para>
 
     <orderedlist>
-      <listitem><para>If you are distributing Open Publication works
+      <listitem><para id="x_64b">If you are distributing Open Publication works
 	  on hardcopy or CD-ROM, you provide email notification to the
 	  authors of your intent to redistribute at least thirty days
 	  before your manuscript or media freeze, to give the authors
 	  time to provide updated documents. This notification should
 	  describe modifications, if any, made to the document.</para>
       </listitem>
-      <listitem><para>All substantive modifications (including
+      <listitem><para id="x_64c">All substantive modifications (including
 	  deletions) be either clearly marked up in the document or
 	  else described in an attachment to the document.</para>
       </listitem>
-      <listitem><para>Finally, while it is not mandatory under this
+      <listitem><para id="x_64d">Finally, while it is not mandatory under this
 	  license, it is considered good form to offer a free copy of
 	  any hardcopy and CD-ROM expression of an Open
 	  Publication-licensed work to its author(s).</para>
   <sect1 id="sec.opl.options">
     <title>License options</title>
 
-    <para>The author(s) and/or publisher of an Open
+    <para id="x_64e">The author(s) and/or publisher of an Open
       Publication-licensed document may elect certain options by
       appending language to the reference to or copy of the license.
       These options are considered part of the license instance and
       reference) in derived works.</para>
 
     <orderedlist>
-      <listitem><para>To prohibit distribution of substantively
+      <listitem><para id="x_64f">To prohibit distribution of substantively
 	  modified versions without the explicit permission of the
 	  author(s). <quote>Substantive modification</quote> is
 	  defined as a change to the semantic content of the document,
 	  and excludes mere changes in format or typographical
 	  corrections.</para>
       </listitem>
-      <listitem><para>  To accomplish this, add the phrase
+      <listitem><para id="x_650">  To accomplish this, add the phrase
 	  <quote>Distribution of substantively modified versions of
 	    this document is prohibited without the explicit
 	    permission of the copyright holder.</quote> to the license
 	  reference or copy.</para>
       </listitem>
-      <listitem><para>To prohibit any publication of this work or
+      <listitem><para id="x_651">To prohibit any publication of this work or
 	  derivative works in whole or in part in standard (paper)
 	  book form for commercial purposes is prohibited unless prior
 	  permission is obtained from the copyright holder.</para>
       </listitem>
-      <listitem><para>To accomplish this, add the phrase
+      <listitem><para id="x_652">To accomplish this, add the phrase
 	  <quote>Distribution of the work or derivative of the work in
 	    any standard (paper) book form is prohibited unless prior
 	    permission is obtained from the copyright holder.</quote>
+#!/usr/bin/env python
+#
+# Add unique ID attributes to para tags.  This script should only be
+# run by one person, since otherwise it introduces the possibility of
+# chaotic conflicts among tags.
+
+import glob, os, re, sys
+
+tagged = re.compile('<para[^>]* id="x_([0-9a-f]+)"[^>]*>', re.M)
+untagged = re.compile('<para>')
+
+names = glob.glob('ch*.xml') + glob.glob('app*.xml')
+
+# First pass: find the highest-numbered paragraph ID.
+
+biggest_id = 0
+seen = set()
+errs = 0
+
+for name in names:
+    for m in tagged.finditer(open(name).read()):
+        i = int(m.group(1),16)
+        if i in seen:
+            print >> sys.stderr, '%s: duplication of ID %s' % (name, i)
+            errs += 1
+        seen.add(i)
+        if i > biggest_id:
+            biggest_id = i
+
+def retag(s):
+    global biggest_id
+    biggest_id += 1
+    return '<para id="x_%x">' % biggest_id
+
+# Second pass: add IDs to paragraphs that currently lack them.
+
+for name in names:
+    f = open(name).read()
+    f1 = untagged.sub(retag, f)
+    if f1 != f:
+        tmpname = name + '.tmp'
+        fp = open(tmpname, 'w')
+        fp.write(f1)
+        fp.close()
+        os.rename(tmpname, name)
+
+sys.exit(errs)

en/ch00-preface.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
 <preface id="chap.preface">
+  <?dbhtml filename="preface.html"?>
   <title>Preface</title>
 
-  <para>Distributed revision control is a relatively new territory,
-    and has thus far grown due to people's willingness to strike out
-    into ill-charted territory.</para>
+  <sect1>
+    <title>Why revision control? Why Mercurial?</title>
 
-  <para>I am writing a book about distributed revision control because
-    I believe that it is an important subject that deserves a field
-    guide. I chose to write about Mercurial because it is the easiest
-    tool to learn the terrain with, and yet it scales to the demands
-    of real, challenging environments where many other revision
-    control tools fail.</para>
+    <para id="x_6d">Revision control is the process of managing multiple
+      versions of a piece of information.  In its simplest form, this
+      is something that many people do by hand: every time you modify
+      a file, save it under a new name that contains a number, each
+      one higher than the number of the preceding version.</para>
+
+    <para id="x_6e">Manually managing multiple versions of even a single file is
+      an error-prone task, though, so software tools to help automate
+      this process have long been available.  The earliest automated
+      revision control tools were intended to help a single user to
+      manage revisions of a single file.  Over the past few decades,
+      the scope of revision control tools has expanded greatly; they
+      now manage multiple files, and help multiple people to work
+      together.  The best modern revision control tools have no
+      problem coping with thousands of people working together on
+      projects that consist of hundreds of thousands of files.</para>
+
+    <para id="x_6f">The arrival of distributed revision control is relatively
+      recent, and so far this new field has grown due to people's
+      willingness to explore ill-charted territory.</para>
+
+    <para id="x_70">I am writing a book about distributed revision control
+      because I believe that it is an important subject that deserves
+      a field guide. I chose to write about Mercurial because it is
+      the easiest tool to learn the terrain with, and yet it scales to
+      the demands of real, challenging environments where many other
+      revision control tools buckle.</para>
+
+    <sect2>
+      <title>Why use revision control?</title>
+
+      <para id="x_71">There are a number of reasons why you or your team might
+	want to use an automated revision control tool for a
+	project.</para>
+
+      <itemizedlist>
+	<listitem><para id="x_72">It will track the history and evolution of
+	    your project, so you don't have to.  For every change,
+	    you'll have a log of <emphasis>who</emphasis> made it;
+	    <emphasis>why</emphasis> they made it;
+	    <emphasis>when</emphasis> they made it; and
+	    <emphasis>what</emphasis> the change
+	    was.</para></listitem>
+	<listitem><para id="x_73">When you're working with other people,
+	    revision control software makes it easier for you to
+	    collaborate.  For example, when people more or less
+	    simultaneously make potentially incompatible changes, the
+	    software will help you to identify and resolve those
+	    conflicts.</para></listitem>
+	<listitem><para id="x_74">It can help you to recover from mistakes.  If
+	    you make a change that later turns out to be in error, you
+	    can revert to an earlier version of one or more files.  In
+	    fact, a <emphasis>really</emphasis> good revision control
+	    tool will even help you to efficiently figure out exactly
+	    when a problem was introduced (see section <xref
+	      linkend="sec.undo.bisect"/> for details).</para></listitem>
+	<listitem><para id="x_75">It will help you to work simultaneously on,
+	    and manage the drift between, multiple versions of your
+	    project.</para></listitem>
+      </itemizedlist>
+
+      <para id="x_76">Most of these reasons are equally valid---at least in
+	theory---whether you're working on a project by yourself, or
+	with a hundred other people.</para>
+
+      <para id="x_77">A key question about the practicality of revision control
+	at these two different scales (<quote>lone hacker</quote> and
+	<quote>huge team</quote>) is how its
+	<emphasis>benefits</emphasis> compare to its
+	<emphasis>costs</emphasis>.  A revision control tool that's
+	difficult to understand or use is going to impose a high
+	cost.</para>
+
+      <para id="x_78">A five-hundred-person project is likely to collapse under
+	its own weight almost immediately without a revision control
+	tool and process. In this case, the cost of using revision
+	control might hardly seem worth considering, since
+	<emphasis>without</emphasis> it, failure is almost
+	guaranteed.</para>
+
+      <para id="x_79">On the other hand, a one-person <quote>quick hack</quote>
+	might seem like a poor place to use a revision control tool,
+	because surely the cost of using one must be close to the
+	overall cost of the project.  Right?</para>
+
+      <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of
+	these scales of development.  You can learn the basics in just
+	a few minutes, and due to its low overhead, you can apply
+	revision control to the smallest of projects with ease.  Its
+	simplicity means you won't have a lot of abstruse concepts or
+	command sequences competing for mental space with whatever
+	you're <emphasis>really</emphasis> trying to do.  At the same
+	time, Mercurial's high performance and peer-to-peer nature let
+	you scale painlessly to handle large projects.</para>
+
+      <para id="x_7b">No revision control tool can rescue a poorly run project,
+	but a good choice of tools can make a huge difference to the
+	fluidity with which you can work on a project.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>The many names of revision control</title>
+
+      <para id="x_7c">Revision control is a diverse field, so much so that it is
+	referred to by many names and acronyms.  Here are a few of the
+	more common variations you'll encounter:</para>
+      <itemizedlist>
+	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
+	<listitem><para id="x_7e">Software configuration management (SCM), or
+	    configuration management</para></listitem>
+	<listitem><para id="x_7f">Source code management</para></listitem>
+	<listitem><para id="x_80">Source code control, or source
+	    control</para></listitem>
+	<listitem><para id="x_81">Version control
+	    (VCS)</para></listitem></itemizedlist>
+      <para id="x_82">Some people claim that these terms actually have different
+	meanings, but in practice they overlap so much that there's no
+	agreed or even useful way to tease them apart.</para>
+
+    </sect2>
+  </sect1>
 
   <sect1>
     <title>This book is a work in progress</title>
 
-    <para>I am releasing this book while I am still writing it, in the
-      hope that it will prove useful to others.  I also hope that
-      readers will contribute as they see fit.</para>
+    <para id="x_83">I am releasing this book while I am still writing it, in the
+      hope that it will prove useful to others.  I am writing under an
+      open license in the hope that you, my readers, will contribute
+      feedback and perhaps content of your own.</para>
 
   </sect1>
   <sect1>
     <title>About the examples in this book</title>
 
-    <para>This book takes an unusual approach to code samples.  Every
+    <para id="x_84">This book takes an unusual approach to code samples.  Every
       example is <quote>live</quote>---each one is actually the result
       of a shell script that executes the Mercurial commands you see.
       Every time an image of the book is built from its sources, all
       the example scripts are automatically run, and their current
       results compared against their expected results.</para>
 
-    <para>The advantage of this approach is that the examples are
+    <para id="x_85">The advantage of this approach is that the examples are
       always accurate; they describe <emphasis>exactly</emphasis> the
       behaviour of the version of Mercurial that's mentioned at the
       front of the book.  If I update the version of Mercurial that
       I'm documenting, and the output of some command changes, the
       build fails.</para>
 
-    <para>There is a small disadvantage to this approach, which is
+    <para id="x_86">There is a small disadvantage to this approach, which is
       that the dates and times you'll see in examples tend to be
       <quote>squashed</quote> together in a way that they wouldn't be
       if the same commands were being typed by a human.  Where a human
       resulting timestamps correspondingly spread out, my automated
       example scripts run many commands in one second.</para>
 
-    <para>As an instance of this, several consecutive commits in an
+    <para id="x_87">As an instance of this, several consecutive commits in an
       example can show up as having occurred during the same second.
       You can see this occur in the <literal
 	role="hg-ext">bisect</literal> example in section <xref
 	id="sec.undo.bisect"/>, for instance.</para>
 
-    <para>So when you're reading examples, don't place too much weight
+    <para id="x_88">So when you're reading examples, don't place too much weight
       on the dates or times you see in the output of commands.  But
       <emphasis>do</emphasis> be confident that the behaviour you're
       seeing is consistent and reproducible.</para>
 
   </sect1>
+
   <sect1>
-    <title>Colophon---this book is Free</title>
+    <title>Trends in the field</title>
 
-    <para>This book is licensed under the Open Publication License,
+    <para id="x_89">There has been an unmistakable trend in the development and
+      use of revision control tools over the past four decades, as
+      people have become familiar with the capabilities of their tools
+      and constrained by their limitations.</para>
+
+    <para id="x_8a">The first generation began by managing single files on
+      individual computers.  Although these tools represented a huge
+      advance over ad-hoc manual revision control, their locking model
+      and reliance on a single computer limited them to small,
+      tightly-knit teams.</para>
+
+    <para id="x_8b">The second generation loosened these constraints by moving
+      to network-centered architectures, and managing entire projects
+      at a time.  As projects grew larger, they ran into new problems.
+      With clients needing to talk to servers very frequently, server
+      scaling became an issue for large projects.  An unreliable
+      network connection could prevent remote users from being able to
+      talk to the server at all.  As open source projects started
+      making read-only access available anonymously to anyone, people
+      without commit privileges found that they could not use the
+      tools to interact with a project in a natural way, as they could
+      not record their changes.</para>
+
+    <para id="x_8c">The current generation of revision control tools is
+      peer-to-peer in nature.  All of these systems have dropped the
+      dependency on a single central server, and allow people to
+      distribute their revision control data to where it's actually
+      needed.  Collaboration over the Internet has moved from
+      constrained by technology to a matter of choice and consensus.
+      Modern tools can operate offline indefinitely and autonomously,
+      with a network connection only needed when syncing changes with
+      another repository.</para>
+
+  </sect1>
+  <sect1>
+    <title>A few of the advantages of distributed revision
+      control</title>
+
+    <para id="x_8d">Even though distributed revision control tools have for
+      several years been as robust and usable as their
+      previous-generation counterparts, people using older tools have
+      not yet necessarily woken up to their advantages.  There are a
+      number of ways in which distributed tools shine relative to
+      centralised ones.</para>
+
+    <para id="x_8e">For an individual developer, distributed tools are almost
+      always much faster than centralised tools.  This is for a simple
+      reason: a centralised tool needs to talk over the network for
+      many common operations, because most metadata is stored in a
+      single copy on the central server.  A distributed tool stores
+      all of its metadata locally.  All else being equal, talking over
+      the network adds overhead to a centralised tool.  Don't
+      underestimate the value of a snappy, responsive tool: you're
+      going to spend a lot of time interacting with your revision
+      control software.</para>
+
+    <para id="x_8f">Distributed tools are indifferent to the vagaries of your
+      server infrastructure, again because they replicate metadata to
+      so many locations.  If you use a centralised system and your
+      server catches fire, you'd better hope that your backup media
+      are reliable, and that your last backup was recent and actually
+      worked.  With a distributed tool, you have many backups
+      available on every contributor's computer.</para>
+
+    <para id="x_90">The reliability of your network will affect distributed
+      tools far less than it will centralised tools.  You can't even
+      use a centralised tool without a network connection, except for
+      a few highly constrained commands.  With a distributed tool, if
+      your network connection goes down while you're working, you may
+      not even notice.  The only thing you won't be able to do is talk
+      to repositories on other computers, something that is relatively
+      rare compared with local operations.  If you have a far-flung
+      team of collaborators, this may be significant.</para>
+
+    <sect2>
+      <title>Advantages for open source projects</title>
+
+      <para id="x_91">If you take a shine to an open source project and decide
+	that you would like to start hacking on it, and that project
+	uses a distributed revision control tool, you are at once a
+	peer with the people who consider themselves the
+	<quote>core</quote> of that project.  If they publish their
+	repositories, you can immediately copy their project history,
+	start making changes, and record your work, using the same
+	tools in the same ways as insiders.  By contrast, with a
+	centralised tool, you must use the software in a <quote>read
+	  only</quote> mode unless someone grants you permission to
+	commit changes to their central server.  Until then, you won't
+	be able to record changes, and your local modifications will
+	be at risk of corruption any time you try to update your
+	client's view of the repository.</para>
+
+      <sect3>
+	<title>The forking non-problem</title>
+
+	<para id="x_92">It has been suggested that distributed revision control
+	  tools pose some sort of risk to open source projects because
+	  they make it easy to <quote>fork</quote> the development of
+	  a project.  A fork happens when there are differences in
+	  opinion or attitude between groups of developers that cause
+	  them to decide that they can't work together any longer.
+	  Each side takes a more or less complete copy of the
+	  project's source code, and goes off in its own
+	  direction.</para>
+
+	<para id="x_93">Sometimes the camps in a fork decide to reconcile their
+	  differences. With a centralised revision control system, the
+	  <emphasis>technical</emphasis> process of reconciliation is
+	  painful, and has to be performed largely by hand.  You have
+	  to decide whose revision history is going to
+	  <quote>win</quote>, and graft the other team's changes into
+	  the tree somehow. This usually loses some or all of one
+	  side's revision history.</para>
+
+	<para id="x_94">What distributed tools do with respect to forking is
+	  they make forking the <emphasis>only</emphasis> way to
+	  develop a project.  Every single change that you make is
+	  potentially a fork point.  The great strength of this
+	  approach is that a distributed revision control tool has to
+	  be really good at <emphasis>merging</emphasis> forks,
+	  because forks are absolutely fundamental: they happen all
+	  the time.</para>
+
+	<para id="x_95">If every piece of work that everybody does, all the
+	  time, is framed in terms of forking and merging, then what
+	  the open source world refers to as a <quote>fork</quote>
+	  becomes <emphasis>purely</emphasis> a social issue.  If
+	  anything, distributed tools <emphasis>lower</emphasis> the
+	  likelihood of a fork:</para>
+	<itemizedlist>
+	  <listitem><para id="x_96">They eliminate the social distinction that
+	      centralised tools impose: that between insiders (people
+	      with commit access) and outsiders (people
+	      without).</para></listitem>
+	  <listitem><para id="x_97">They make it easier to reconcile after a
+	      social fork, because all that's involved from the
+	      perspective of the revision control software is just
+	      another merge.</para></listitem></itemizedlist>
+
+	<para id="x_98">Some people resist distributed tools because they want
+	  to retain tight control over their projects, and they
+	  believe that centralised tools give them this control.
+	  However, if you're of this belief, and you publish your CVS
+	  or Subversion repositories publicly, there are plenty of
+	  tools available that can pull out your entire project's
+	  history (albeit slowly) and recreate it somewhere that you
+	  don't control.  So while your control in this case is
+	  illusory, you are forgoing the ability to fluidly
+	  collaborate with whatever people feel compelled to mirror
+	  and fork your history.</para>
+
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Advantages for commercial projects</title>
+
+      <para id="x_99">Many commercial projects are undertaken by teams that are
+	scattered across the globe.  Contributors who are far from a
+	central server will see slower command execution and perhaps
+	less reliability.  Commercial revision control systems attempt
+	to ameliorate these problems with remote-site replication
+	add-ons that are typically expensive to buy and cantankerous
+	to administer.  A distributed system doesn't suffer from these
+	problems in the first place.  Better yet, you can easily set
+	up multiple authoritative servers, say one per site, so that
+	there's no redundant communication between repositories over
+	expensive long-haul network links.</para>
+
+      <para id="x_9a">Centralised revision control systems tend to have
+	relatively low scalability.  It's not unusual for an expensive
+	centralised system to fall over under the combined load of
+	just a few dozen concurrent users.  Once again, the typical
+	response tends to be an expensive and clunky replication
+	facility.  Since the load on a central server---if you have
+	one at all---is many times lower with a distributed tool
+	(because all of the data is replicated everywhere), a single
+	cheap server can handle the needs of a much larger team, and
+	replication to balance load becomes a simple matter of
+	scripting.</para>
+
+      <para id="x_9b">If you have an employee in the field, troubleshooting a
+	problem at a customer's site, they'll benefit from distributed
+	revision control. The tool will let them generate custom
+	builds, try different fixes in isolation from each other, and
+	search efficiently through history for the sources of bugs and
+	regressions in the customer's environment, all without needing
+	to connect to your company's network.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Why choose Mercurial?</title>
+
+    <para id="x_9c">Mercurial has a unique set of properties that make it a
+      particularly good choice as a revision control system.</para>
+    <itemizedlist>
+      <listitem><para id="x_9d">It is easy to learn and use.</para></listitem>
+      <listitem><para id="x_9e">It is lightweight.</para></listitem>
+      <listitem><para id="x_9f">It scales excellently.</para></listitem>
+      <listitem><para id="x_a0">It is easy to
+	  customise.</para></listitem></itemizedlist>
+
+    <para id="x_a1">If you are at all familiar with revision control systems,
+      you should be able to get up and running with Mercurial in less
+      than five minutes.  Even if not, it will take no more than a few
+      minutes longer.  Mercurial's command and feature sets are
+      generally uniform and consistent, so you can keep track of a few
+      general rules instead of a host of exceptions.</para>
+
+    <para id="x_a2">On a small project, you can start working with Mercurial in
+      moments. Creating new changes and branches; transferring changes
+      around (whether locally or over a network); and history and
+      status operations are all fast.  Mercurial attempts to stay
+      nimble and largely out of your way by combining low cognitive
+      overhead with blazingly fast operations.</para>
+
+    <para id="x_a3">The usefulness of Mercurial is not limited to small
+      projects: it is used by projects with hundreds to thousands of
+      contributors, each containing tens of thousands of files and
+      hundreds of megabytes of source code.</para>
+
+    <para id="x_a4">If the core functionality of Mercurial is not enough for
+      you, it's easy to build on.  Mercurial is well suited to
+      scripting tasks, and its clean internals and implementation in
+      Python make it easy to add features in the form of extensions.
+      There are a number of popular and useful extensions already
+      available, ranging from helping to identify bugs to improving
+      performance.</para>
+
+  </sect1>
+  <sect1>
+    <title>Mercurial compared with other tools</title>
+
+    <para id="x_a5">Before you read on, please understand that this section
+      necessarily reflects my own experiences, interests, and (dare I
+      say it) biases.  I have used every one of the revision control
+      tools listed below, in most cases for several years at a
+      time.</para>
+
+
+    <sect2>
+      <title>Subversion</title>
+
+      <para id="x_a6">Subversion is a popular revision control tool, developed
+	to replace CVS.  It has a centralised client/server
+	architecture.</para>
+
+      <para id="x_a7">Subversion and Mercurial have similarly named commands for
+	performing the same operations, so if you're familiar with
+	one, it is easy to learn to use the other.  Both tools are
+	portable to all popular operating systems.</para>
+
+      <para id="x_a8">Prior to version 1.5, Subversion had no useful support for
+	merges. At the time of writing, its merge tracking capability
+	is new, and known to be <ulink
+	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
+	  and buggy</ulink>.</para>
+
+      <para id="x_a9">Mercurial has a substantial performance advantage over
+	Subversion on every revision control operation I have
+	benchmarked.  I have measured its advantage as ranging from a
+	factor of two to a factor of six when compared with Subversion
+	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
+	fastest access method available.  In more realistic
+	deployments involving a network-based store, Subversion will
+	be at a substantially larger disadvantage.  Because many
+	Subversion commands must talk to the server and Subversion
+	does not have useful replication facilities, server capacity
+	and network bandwidth become bottlenecks for modestly large
+	projects.</para>
+
+      <para id="x_aa">Additionally, Subversion incurs substantial storage
+	overhead to avoid network transactions for a few common
+	operations, such as finding modified files
+	(<literal>status</literal>) and displaying modifications
+	against the current revision (<literal>diff</literal>).  As a
+	result, a Subversion working copy is often the same size as,
+	or larger than, a Mercurial repository and working directory,
+	even though the Mercurial repository contains a complete
+	history of the project.</para>
+
+      <para id="x_ab">Subversion is widely supported by third party tools.
+	Mercurial currently lags considerably in this area.  This gap
+	is closing, however, and indeed some of Mercurial's GUI tools
+	now outshine their Subversion equivalents.  Like Mercurial,
+	Subversion has an excellent user manual.</para>
+
+      <para id="x_ac">Because Subversion doesn't store revision history on the
+	client, it is well suited to managing projects that deal with
+	lots of large, opaque binary files.  If you check in fifty
+	revisions to an incompressible 10MB file, Subversion's
+	client-side space usage stays constant The space used by any
+	distributed SCM will grow rapidly in proportion to the number
+	of revisions, because the differences between each revision
+	are large.</para>
+
+      <para id="x_ad">In addition, it's often difficult or, more usually,
+	impossible to merge different versions of a binary file.
+	Subversion's ability to let a user lock a file, so that they
+	temporarily have the exclusive right to commit changes to it,
+	can be a significant advantage to a project where binary files
+	are widely used.</para>
+
+      <para id="x_ae">Mercurial can import revision history from a Subversion
+	repository. It can also export revision history to a
+	Subversion repository.  This makes it easy to <quote>test the
+	  waters</quote> and use Mercurial and Subversion in parallel
+	before deciding to switch.  History conversion is incremental,
+	so you can perform an initial conversion, then small
+	additional conversions afterwards to bring in new
+	changes.</para>
+
+
+    </sect2>
+    <sect2>
+      <title>Git</title>
+
+      <para id="x_af">Git is a distributed revision control tool that was
+	developed for managing the Linux kernel source tree.  Like
+	Mercurial, its early design was somewhat influenced by
+	Monotone.</para>
+
+      <para id="x_b0">Git has a very large command set, with version 1.5.0
+	providing 139 individual commands.  It has something of a
+	reputation for being difficult to learn.  Compared to Git,
+	Mercurial has a strong focus on simplicity.</para>
+
+      <para id="x_b1">In terms of performance, Git is extremely fast.  In
+	several cases, it is faster than Mercurial, at least on Linux,
+	while Mercurial performs better on other operations.  However,
+	on Windows, the performance and general level of support that
+	Git provides is, at the time of writing, far behind that of
+	Mercurial.</para>
+
+      <para id="x_b2">While a Mercurial repository needs no maintenance, a Git
+	repository requires frequent manual <quote>repacks</quote> of
+	its metadata.  Without these, performance degrades, while
+	space usage grows rapidly.  A server that contains many Git
+	repositories that are not rigorously and frequently repacked
+	will become heavily disk-bound during backups, and there have
+	been instances of daily backups taking far longer than 24
+	hours as a result.  A freshly packed Git repository is
+	slightly smaller than a Mercurial repository, but an unpacked
+	repository is several orders of magnitude larger.</para>
+
+      <para id="x_b3">The core of Git is written in C.  Many Git commands are
+	implemented as shell or Perl scripts, and the quality of these
+	scripts varies widely. I have encountered several instances
+	where scripts charged along blindly in the presence of errors
+	that should have been fatal.</para>
+
+      <para id="x_b4">Mercurial can import revision history from a Git
+	repository.</para>
+
+
+    </sect2>
+    <sect2>
+      <title>CVS</title>
+
+      <para id="x_b5">CVS is probably the most widely used revision control tool
+	in the world.  Due to its age and internal untidiness, it has
+	been only lightly maintained for many years.</para>
+
+      <para id="x_b6">It has a centralised client/server architecture.  It does
+	not group related file changes into atomic commits, making it
+	easy for people to <quote>break the build</quote>: one person
+	can successfully commit part of a change and then be blocked
+	by the need for a merge, causing other people to see only a
+	portion of the work they intended to do.  This also affects
+	how you work with project history.  If you want to see all of
+	the modifications someone made as part of a task, you will
+	need to manually inspect the descriptions and timestamps of
+	the changes made to each file involved (if you even know what
+	those files were).</para>
+
+      <para id="x_b7">CVS has a muddled notion of tags and branches that I will
+	not attempt to even describe.  It does not support renaming of
+	files or directories well, making it easy to corrupt a
+	repository.  It has almost no internal consistency checking
+	capabilities, so it is usually not even possible to tell
+	whether or how a repository is corrupt.  I would not recommend
+	CVS for any project, existing or new.</para>
+
+      <para id="x_b8">Mercurial can import CVS revision history.  However, there
+	are a few caveats that apply; these are true of every other
+	revision control tool's CVS importer, too.  Due to CVS's lack
+	of atomic changes and unversioned filesystem hierarchy, it is
+	not possible to reconstruct CVS history completely accurately;
+	some guesswork is involved, and renames will usually not show
+	up.  Because a lot of advanced CVS administration has to be
+	done by hand and is hence error-prone, it's common for CVS
+	importers to run into multiple problems with corrupted
+	repositories (completely bogus revision timestamps and files
+	that have remained locked for over a decade are just two of
+	the less interesting problems I can recall from personal
+	experience).</para>
+
+      <para id="x_b9">Mercurial can import revision history from a CVS
+	repository.</para>
+
+
+    </sect2>
+    <sect2>
+      <title>Commercial tools</title>
+
+      <para id="x_ba">Perforce has a centralised client/server architecture,
+	with no client-side caching of any data.  Unlike modern
+	revision control tools, Perforce requires that a user run a
+	command to inform the server about every file they intend to
+	edit.</para>
+
+      <para id="x_bb">The performance of Perforce is quite good for small teams,
+	but it falls off rapidly as the number of users grows beyond a
+	few dozen. Modestly large Perforce installations require the
+	deployment of proxies to cope with the load their users
+	generate.</para>
+
+
+    </sect2>
+    <sect2>
+      <title>Choosing a revision control tool</title>
+
+      <para id="x_bc">With the exception of CVS, all of the tools listed above
+	have unique strengths that suit them to particular styles of
+	work.  There is no single revision control tool that is best
+	in all situations.</para>
+
+      <para id="x_bd">As an example, Subversion is a good choice for working
+	with frequently edited binary files, due to its centralised
+	nature and support for file locking.</para>
+
+      <para id="x_be">I personally find Mercurial's properties of simplicity,
+	performance, and good merge support to be a compelling
+	combination that has served me well for several years.</para>
+
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Switching from another tool to Mercurial</title>
+
+    <para id="x_bf">Mercurial is bundled with an extension named <literal
+	role="hg-ext">convert</literal>, which can incrementally
+      import revision history from several other revision control
+      tools.  By <quote>incremental</quote>, I mean that you can
+      convert all of a project's history to date in one go, then rerun
+      the conversion later to obtain new changes that happened after
+      the initial conversion.</para>
+
+    <para id="x_c0">The revision control tools supported by <literal
+	role="hg-ext">convert</literal> are as follows:</para>
+    <itemizedlist>
+      <listitem><para id="x_c1">Subversion</para></listitem>
+      <listitem><para id="x_c2">CVS</para></listitem>
+      <listitem><para id="x_c3">Git</para></listitem>
+      <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist>
+
+    <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can
+      export changes from Mercurial to Subversion.  This makes it
+      possible to try Subversion and Mercurial in parallel before
+      committing to a switchover, without risking the loss of any
+      work.</para>
+
+    <para id="x_c6">The <command role="hg-ext-convert">convert</command> command
+      is easy to use.  Simply point it at the path or URL of the
+      source repository, optionally give it the name of the
+      destination repository, and it will start working.  After the
+      initial conversion, just run the same command again to import
+      new changes.</para>
+  </sect1>
+
+  <sect1>
+    <title>A short history of revision control</title>
+
+    <para id="x_c7">The best known of the old-time revision control tools is
+      SCCS (Source Code Control System), which Marc Rochkind wrote at
+      Bell Labs, in the early 1970s.  SCCS operated on individual
+      files, and required every person working on a project to have
+      access to a shared workspace on a single system.  Only one
+      person could modify a file at any time; arbitration for access
+      to files was via locks.  It was common for people to lock files,
+      and later forget to unlock them, preventing anyone else from
+      modifying those files without the help of an
+      administrator.</para>
+
+    <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the
+      early 1980s; he called his program RCS (Revision Control System).
+      Like SCCS, RCS required developers to work in a single shared
+      workspace, and to lock files to prevent multiple people from
+      modifying them simultaneously.</para>
+
+    <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block
+      for a set of shell scripts he initially called cmt, but then
+      renamed to CVS (Concurrent Versions System).  The big innovation
+      of CVS was that it let developers work simultaneously and
+      somewhat independently in their own personal workspaces.  The
+      personal workspaces prevented developers from stepping on each
+      other's toes all the time, as was common with SCCS and RCS. Each
+      developer had a copy of every project file, and could modify
+      their copies independently.  They had to merge their edits prior
+      to committing changes to the central repository.</para>
+
+    <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote
+      them in C, releasing in 1989 the code that has since developed
+      into the modern version of CVS.  CVS subsequently acquired the
+      ability to operate over a network connection, giving it a
+      client/server architecture.  CVS's architecture is centralised;
+      only the server has a copy of the history of the project. Client
+      workspaces just contain copies of recent versions of the
+      project's files, and a little metadata to tell them where the
+      server is.  CVS has been enormously successful; it is probably
+      the world's most widely used revision control system.</para>
+
+    <para id="x_cb">In the early 1990s, Sun Microsystems developed an early
+      distributed revision control system, called TeamWare.  A
+      TeamWare workspace contains a complete copy of the project's
+      history.  TeamWare has no notion of a central repository.  (CVS
+      relied upon RCS for its history storage; TeamWare used
+      SCCS.)</para>
+
+    <para id="x_cc">As the 1990s progressed, awareness grew of a number of
+      problems with CVS.  It records simultaneous changes to multiple
+      files individually, instead of grouping them together as a
+      single logically atomic operation.  It does not manage its file
+      hierarchy well; it is easy to make a mess of a repository by
+      renaming files and directories.  Worse, its source code is
+      difficult to read and maintain, which made the <quote>pain
+	level</quote> of fixing these architectural problems
+      prohibitive.</para>
+
+    <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had
+      worked on CVS, started a project to replace it with a tool that
+      would have a better architecture and cleaner code.  The result,
+      Subversion, does not stray from CVS's centralised client/server
+      model, but it adds multi-file atomic commits, better namespace
+      management, and a number of other features that make it a
+      generally better tool than CVS. Since its initial release, it
+      has rapidly grown in popularity.</para>
+
+    <para id="x_ce">More or less simultaneously, Graydon Hoare began working on
+      an ambitious distributed revision control system that he named
+      Monotone. While Monotone addresses many of CVS's design flaws
+      and has a peer-to-peer architecture, it goes beyond earlier (and
+      subsequent) revision control tools in a number of innovative
+      ways.  It uses cryptographic hashes as identifiers, and has an
+      integral notion of <quote>trust</quote> for code from different
+      sources.</para>
+
+    <para id="x_cf">Mercurial began life in 2005.  While a few aspects of its
+      design are influenced by Monotone, Mercurial focuses on ease of
+      use, high performance, and scalability to very large
+      projects.</para>
+
+  </sect1>
+
+  <sect1>
+    <title>Colophon&emdash;this book is Free</title>
+
+    <para id="x_d0">This book is licensed under the Open Publication License,
       and is produced entirely using Free Software tools.  It is
       typeset with DocBook XML.  Illustrations are drawn and rendered with
       <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
 
-    <para>The complete source code for this book is published as a
+    <para id="x_d1">The complete source code for this book is published as a
       Mercurial repository, at <ulink
 	url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
 

en/ch01-intro.xml

-<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
-
-<chapter id="chap.intro">
-  <?dbhtml filename="introduction.html"?>
-  <title>Introduction</title>
-
-  <sect1>
-    <title>About revision control</title>
-
-    <para>Revision control is the process of managing multiple
-      versions of a piece of information.  In its simplest form, this
-      is something that many people do by hand: every time you modify
-      a file, save it under a new name that contains a number, each
-      one higher than the number of the preceding version.</para>
-
-    <para>Manually managing multiple versions of even a single file is
-      an error-prone task, though, so software tools to help automate
-      this process have long been available.  The earliest automated
-      revision control tools were intended to help a single user to
-      manage revisions of a single file.  Over the past few decades,
-      the scope of revision control tools has expanded greatly; they
-      now manage multiple files, and help multiple people to work
-      together.  The best modern revision control tools have no
-      problem coping with thousands of people working together on
-      projects that consist of hundreds of thousands of files.</para>
-
-    <sect2>
-      <title>Why use revision control?</title>
-
-      <para>There are a number of reasons why you or your team might
-	want to use an automated revision control tool for a
-	project.</para>
-      <itemizedlist>
-	<listitem><para>It will track the history and evolution of
-	    your project, so you don't have to.  For every change,
-	    you'll have a log of <emphasis>who</emphasis> made it;
-	    <emphasis>why</emphasis> they made it;
-	    <emphasis>when</emphasis> they made it; and
-	    <emphasis>what</emphasis> the change
-	    was.</para></listitem>
-	<listitem><para>When you're working with other people,
-	    revision control software makes it easier for you to
-	    collaborate.  For example, when people more or less
-	    simultaneously make potentially incompatible changes, the
-	    software will help you to identify and resolve those
-	    conflicts.</para></listitem>
-	<listitem><para>It can help you to recover from mistakes.  If
-	    you make a change that later turns out to be in error, you
-	    can revert to an earlier version of one or more files.  In
-	    fact, a <emphasis>really</emphasis> good revision control
-	    tool will even help you to efficiently figure out exactly
-	    when a problem was introduced (see section <xref
-	      linkend="sec.undo.bisect"/> for details).</para></listitem>
-	<listitem><para>It will help you to work simultaneously on,
-	    and manage the drift between, multiple versions of your
-	    project.</para></listitem></itemizedlist>
-      <para>Most of these reasons are equally valid---at least in
-	theory---whether you're working on a project by yourself, or
-	with a hundred other people.</para>
-
-      <para>A key question about the practicality of revision control
-	at these two different scales (<quote>lone hacker</quote> and
-	<quote>huge team</quote>) is how its
-	<emphasis>benefits</emphasis> compare to its
-	<emphasis>costs</emphasis>.  A revision control tool that's
-	difficult to understand or use is going to impose a high
-	cost.</para>
-
-      <para>A five-hundred-person project is likely to collapse under
-	its own weight almost immediately without a revision control
-	tool and process. In this case, the cost of using revision
-	control might hardly seem worth considering, since
-	<emphasis>without</emphasis> it, failure is almost
-	guaranteed.</para>
-
-      <para>On the other hand, a one-person <quote>quick hack</quote>
-	might seem like a poor place to use a revision control tool,
-	because surely the cost of using one must be close to the
-	overall cost of the project.  Right?</para>
-
-      <para>Mercurial uniquely supports <emphasis>both</emphasis> of
-	these scales of development.  You can learn the basics in just
-	a few minutes, and due to its low overhead, you can apply
-	revision control to the smallest of projects with ease.  Its
-	simplicity means you won't have a lot of abstruse concepts or
-	command sequences competing for mental space with whatever
-	you're <emphasis>really</emphasis> trying to do.  At the same
-	time, Mercurial's high performance and peer-to-peer nature let
-	you scale painlessly to handle large projects.</para>
-
-      <para>No revision control tool can rescue a poorly run project,
-	but a good choice of tools can make a huge difference to the
-	fluidity with which you can work on a project.</para>
-
-    </sect2>
-    <sect2>
-      <title>The many names of revision control</title>
-
-      <para>Revision control is a diverse field, so much so that it
-	doesn't actually have a single name or acronym.  Here are a
-	few of the more common names and acronyms you'll
-	encounter:</para>
-      <itemizedlist>
-	<listitem><para>Revision control (RCS)</para></listitem>
-	<listitem><para>Software configuration management (SCM), or
-	    configuration management</para></listitem>
-	<listitem><para>Source code management</para></listitem>
-	<listitem><para>Source code control, or source
-	    control</para></listitem>
-	<listitem><para>Version control
-	    (VCS)</para></listitem></itemizedlist>
-      <para>Some people claim that these terms actually have different
-	meanings, but in practice they overlap so much that there's no
-	agreed or even useful way to tease them apart.</para>
-
-    </sect2>
-  </sect1>
-  <sect1>
-    <title>A short history of revision control</title>
-
-    <para>The best known of the old-time revision control tools is
-      SCCS (Source Code Control System), which Marc Rochkind wrote at
-      Bell Labs, in the early 1970s.  SCCS operated on individual
-      files, and required every person working on a project to have
-      access to a shared workspace on a single system.  Only one
-      person could modify a file at any time; arbitration for access
-      to files was via locks.  It was common for people to lock files,
-      and later forget to unlock them, preventing anyone else from
-      modifying those files without the help of an
-      administrator.</para>
-
-    <para>Walter Tichy developed a free alternative to SCCS in the
-      early 1980s; he called his program RCS (Revision Control System).
-      Like SCCS, RCS required developers to work in a single shared
-      workspace, and to lock files to prevent multiple people from
-      modifying them simultaneously.</para>
-
-    <para>Later in the 1980s, Dick Grune used RCS as a building block
-      for a set of shell scripts he initially called cmt, but then
-      renamed to CVS (Concurrent Versions System).  The big innovation
-      of CVS was that it let developers work simultaneously and
-      somewhat independently in their own personal workspaces.  The
-      personal workspaces prevented developers from stepping on each
-      other's toes all the time, as was common with SCCS and RCS. Each
-      developer had a copy of every project file, and could modify
-      their copies independently.  They had to merge their edits prior
-      to committing changes to the central repository.</para>
-
-    <para>Brian Berliner took Grune's original scripts and rewrote
-      them in C, releasing in 1989 the code that has since developed
-      into the modern version of CVS.  CVS subsequently acquired the
-      ability to operate over a network connection, giving it a
-      client/server architecture.  CVS's architecture is centralised;
-      only the server has a copy of the history of the project. Client
-      workspaces just contain copies of recent versions of the
-      project's files, and a little metadata to tell them where the
-      server is.  CVS has been enormously successful; it is probably
-      the world's most widely used revision control system.</para>
-
-    <para>In the early 1990s, Sun Microsystems developed an early
-      distributed revision control system, called TeamWare.  A
-      TeamWare workspace contains a complete copy of the project's
-      history.  TeamWare has no notion of a central repository.  (CVS
-      relied upon RCS for its history storage; TeamWare used
-      SCCS.)</para>
-
-    <para>As the 1990s progressed, awareness grew of a number of
-      problems with CVS.  It records simultaneous changes to multiple
-      files individually, instead of grouping them together as a
-      single logically atomic operation.  It does not manage its file
-      hierarchy well; it is easy to make a mess of a repository by
-      renaming files and directories.  Worse, its source code is
-      difficult to read and maintain, which made the <quote>pain
-	level</quote> of fixing these architectural problems
-      prohibitive.</para>
-
-    <para>In 2001, Jim Blandy and Karl Fogel, two developers who had
-      worked on CVS, started a project to replace it with a tool that
-      would have a better architecture and cleaner code.  The result,
-      Subversion, does not stray from CVS's centralised client/server
-      model, but it adds multi-file atomic commits, better namespace
-      management, and a number of other features that make it a
-      generally better tool than CVS. Since its initial release, it
-      has rapidly grown in popularity.</para>