Commits

Bryan O'Sullivan committed b90b024

WIP DocBook snapshot that all compiles. Mirabile dictu!

Comments (0)

Files changed (22)

 .*.swp
 .\#*
 .run
+xsl/system-xsl
 
 <!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 appA     SYSTEM "appA-cmdref.xml">
+<!ENTITY appB     SYSTEM "appB-mq-ref.xml">
+<!ENTITY appC     SYSTEM "appC-srcinstall.xml">
+<!ENTITY appD     SYSTEM "appD-license.xml">
 
 <!-- Include our standard shortcuts. -->
 
 
   &ch01;
   &ch02;
+  &ch03;
+  &ch04;
+  &ch05;
+  &ch06;
+  &ch07;
+  &ch08;
+  &ch09;
+  &ch10;
+  &ch11;
   &ch12;
+  &ch13;
+  &ch14;
+  <!-- &appA; -->
+  &appB;
+  &appC;
+  &appD;
 </book>
 
 xml-src-files := \
 	00book.xml \
-	ch01-intro.xml \
-	ch02-tour-basic.xml \
-	ch12-mq.xml
+	app*.xml \
+	ch*.xml
 
 image-dot := $(filter %.dot,$(image-sources))
 image-svg := $(filter %.svg,$(image-sources))

en/appA-cmdref.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="cmdref">
+<title>Command reference</title>
+
+<para>\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>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
+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>Omit date and time information when printing diff headers.</para>
+
+<para>\optref{diff}{B}{ignore-blank-lines}</para>
+
+<para>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>
+
+<para>Include files and directories whose names match the given patterns.
+</para>
+
+<para>\optref{diff}{X}{exclude}
+</para>
+
+<para>Exclude files and directories whose names match the given patterns.
+</para>
+
+<para>\optref{diff}{a}{text}
+</para>
+
+<para>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
+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>
+
+<para>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>
+
+<para>Print <command>git</command>-compatible diffs.  XXX reference a format
+description.
+</para>
+
+<para>\optref{diff}{p}{show-function}
+</para>
+
+<para>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>
+
+<para>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
+  working directory and the working directory.
+</para>
+</listitem>
+<listitem><para>Display the differences between the specified changeset and the
+  working directory.
+</para>
+</listitem>
+<listitem><para>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>
+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
+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
+<command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will
+transform files from their revision 20 contents to their revision 10
+contents.  You cannot reverse the ordering in this way if you are
+diffing against the working directory.
+</para>
+
+<para>\optref{diff}{w}{ignore-all-space}
+</para>
+
+<para>\cmdref{version}{print version and copyright information}
+</para>
+
+<para>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
+  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
+  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
+  have added that tag to any revision in the repository where they
+  built Mercurial.)
+</para>
+</listitem>
+<listitem><para>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
+  <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.
+</para>
+</listitem></itemizedlist>
+
+</sect2>
+<sect2>
+<title>Tips and tricks</title>
+
+<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
+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
+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,
+traditional diffs can't represent a change in whether or not a file is
+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
+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
+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>
+to merge two changesets, but you haven't yet committed the results of
+the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
+to see them).  While <command role="hg-cmd">hg status</command> prints modifications relative to
+<emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> still
+operates relative only to the first parent.  You can get it to print
+diffs relative to the second parent by specifying that parent with the
+<option role="hg-opt-diff">-r</option> option.  There is no way to print diffs relative to
+both parents.
+</para>
+
+</sect3>
+<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
+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
+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.
+</para>
+
+</sect3>
+</sect2>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->

en/appB-mq-ref.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="chap:mqref">
+  <title>Mercurial Queues reference</title>
+
+  <sect1 id="sec:mqref:cmdref">
+    <title>MQ command reference</title>
+
+    <para>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
+	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>
+
+    </sect2>
+    <sect2>
+      <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
+	commits any outstanding changes in the <filename
+	  role="special" class="directory">.hg/patches</filename>
+	repository.  This command only works if the <filename
+	  role="special" class="directory">.hg/patches</filename>
+	directory is a repository, i.e. you created the directory
+	using <command role="hg-cmd">hg qinit <option
+	    role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
+	ran <command role="hg-cmd">hg init</command> in the directory
+	after running <command
+	  role="hg-ext-mq">qinit</command>.</para>
+
+      <para>This command is shorthand for <command role="hg-cmd">hg
+	  commit --cwd .hg/patches</command>.</para>
+
+      <para>\subsection{<command
+	  role="hg-ext-mq">qdelete</command>&emdash;delete a patch
+	from the <filename role="special">series</filename>
+	file}</para>
+
+      <para>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>
+	directory.  It does not pop the patch if the patch is already
+	applied.  By default, it does not delete the patch file; use
+	the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
+	to do that.</para>
+
+      <para>Options:</para>
+      <itemizedlist>
+	<listitem><para><option
+	      role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
+	    patch file.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <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
+	prints a diff of the topmost applied patch. It is equivalent
+	to <command role="hg-cmd">hg diff -r-2:-1</command>.</para>
+
+    </sect2>
+    <sect2>
+      <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
+	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
+	  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
+	<quote>apply the current topmost patch, followed by
+	  <literal>a</literal>, followed by
+	  <literal>b</literal></quote>.</para>
+
+      <para>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
+	<option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
+	edit the commit message for the combined patch/changeset after
+	the folding has completed.</para>
+
+      <para>Options:</para>
+      <itemizedlist>
+	<listitem><para><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
+	      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
+	      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>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command
+	  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
+	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>
+
+    </sect2>
+    <sect2>
+      <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
+	adds an entry for an external patch to the <filename
+	  role="special">series</filename> file, and copies the patch
+	into the <filename role="special"
+	  class="directory">.hg/patches</filename> directory.  It adds
+	the entry immediately after the topmost applied patch, but
+	does not push the patch.</para>
+
+      <para>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>
+	of the imported patch.</para>
+
+    </sect2>
+    <sect2>
+      <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
+	prepares a repository to work with MQ.  It creates a directory
+	called <filename role="special"
+	  class="directory">.hg/patches</filename>.</para>
+
+      <para>Options:</para>
+      <itemizedlist>
+	<listitem><para><option
+	      role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
+	    <filename role="special"
+	      class="directory">.hg/patches</filename> as a repository
+	    in its own right.  Also creates a <filename
+	      role="special">.hgignore</filename> file that will
+	    ignore the <filename role="special">status</filename>
+	    file.</para>
+	</listitem></itemizedlist>
+
+      <para>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
+	automatically <command role="hg-cmd">hg add</command> new
+	patches.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qnew</command>&emdash;create a
+	new patch</title>
+
+      <para>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
+	  role="special">series</filename> file after the current
+	topmost applied patch, and is immediately pushed on top of
+	that patch.</para>
+
+      <para>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
+	(see below).  This behaviour allows you to <command
+	  role="hg-ext-mq">qrefresh</command> your topmost applied
+	patch before you apply a new patch on top of it.</para>
+
+      <para>Options:</para>
+      <itemizedlist>
+	<listitem><para><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
+	      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
+	    data.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <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
+	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
+	patch if you run <command
+	  role="hg-ext-mq">qpush</command>.</para>
+
+    </sect2>
+    <sect2>
+      <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
+	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
+	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
+	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
+	  role="hg-ext-mq">qpop</command> treats the number as an
+	index into the entries in the series file, counting from zero
+	(empty lines and lines containing only comments do not count).
+	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
+	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
+	removed from the <filename role="special">series</filename>
+	file, or a patch that you have renamed or deleted entirely.
+	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>
+	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>
+      <itemizedlist>
+	<listitem><para><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
+	      role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
+	    revert any modifications to the working directory when
+	    popping.</para>
+	</listitem>
+	<listitem><para><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
+	removes one line from the end of the <filename
+	  role="special">status</filename> file for each patch that it
+	pops.</para>
+
+    </sect2>
+    <sect2>
+      <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
+	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
+	patch if you run <command
+	  role="hg-ext-mq">qpop</command>.</para>
+
+    </sect2>
+    <sect2 id="sec:mqref:cmd:qpush">
+      <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
+	patches onto the applied stack.  By default, it adds only one
+	patch.</para>
+
+      <para>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
+	follows:</para>
+      <itemizedlist>
+	<listitem><para>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
+	    <command role="hg-ext-mq">qpush</command> it again, the
+	    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
+	    the <command role="hg-cmd">hg commit</command>
+	    command.</para>
+	</listitem>
+	<listitem><para>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
+	link), the information in the patch header overrides these
+	defaults.</para>
+
+      <para>Options:</para>
+      <itemizedlist>
+	<listitem><para><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
+	      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
+	      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
+	    three-way merge, and perform a three-way merge using the
+	    normal Mercurial merge machinery.  Use the resolution of
+	    the merge as the new patch content.</para>
+	</listitem>
+	<listitem><para><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
+	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
+	each patch that it pushes.</para>
+
+    </sect2>
+    <sect2>
+      <title><command
+	  role="hg-ext-mq">qrefresh</command>&emdash;update the
+	topmost applied patch</title>
+
+      <para>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
+	looks for the following modifications:</para>
+      <itemizedlist>
+	<listitem><para>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
+	    directory are added to the patch.</para>
+	</listitem>
+	<listitem><para>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
+	      role="hg-cmd">hg rename</command>.  Added files and copy
+	    and rename destinations are added to the patch, while
+	    removed files and rename sources are removed.</para>
+	</listitem></itemizedlist>
+
+      <para>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>
+      <itemizedlist>
+	<listitem><para><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
+	      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
+	      role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
+	    the commit message and patch description, using text from
+	    the given file.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qrename</command>&emdash;rename
+	a patch</title>
+
+      <para>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
+	  role="hg-ext-mq">qrename</command> renames the topmost
+	applied patch.  With two arguments, it renames its first
+	argument to its second.</para>
+
+    </sect2>
+    <sect2>
+      <title><command
+	  role="hg-ext-mq">qrestore</command>&emdash;restore saved
+	queue state</title>
+
+      <para>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>
+
+    </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
+	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
+	first to be applied to last.</para>
+
+    </sect2>
+    <sect2>
+      <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
+	name of the topmost currently applied patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command
+	  role="hg-ext-mq">qunapplied</command>&emdash;print patches
+	not yet applied</title>
+
+      <para>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
+	will be pushed to the last.</para>
+
+    </sect2>
+    <sect2>
+      <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
+	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
+	saves a backup of the removed changesets in a bundle, so that
+	they can be reapplied if removed in error.</para>
+
+      <para>Options:</para>
+      <itemizedlist>
+	<listitem><para><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
+	    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
+	    not save a backup bundle.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>MQ file reference</title>
+
+    <sect2>
+      <title>The <filename role="special">series</filename>
+	file</title>
+
+      <para>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
+	<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
+	  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
+	  role="hg-ext-mq">qpush</command> will skip over that patch
+	when applying patches.  You can also change the order in which
+	patches are applied by reordering their entries in the
+	<filename role="special">series</filename> file.</para>
+
+      <para>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
+	using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
+	option to <command role="hg-ext-mq">qinit</command>, this will
+	be done for you automatically.</para>
+
+    </sect2>
+    <sect2>
+      <title>The <filename role="special">status</filename>
+	file</title>
+
+      <para>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
+	intended for editing.  You should not place this file under
+	revision control, or modify it in any way.  It is used by MQ
+	strictly for internal book-keeping.</para>
+
+    </sect2>
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->

en/appC-srcinstall.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="chap:srcinstall">
+  <title>Installing Mercurial from source</title>
+
+  <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
+      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
+	    url="http://www.selenic.com/mercurial/download">http://www.selenic.com/mercurial/download</ulink>.</para>
+      </listitem>
+      <listitem><para>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
+	  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
+      <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>
+      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
+      exact path that you will need to use depends on how Python was
+      built for your system, but should be easy to figure out.  If
+      you're uncertain, look through the output of the installer
+      script above, and see where the contents of the
+      <literal>mercurial</literal> directory were installed to.</para>
+
+  </sect1>
+  <sect1>
+    <title>On Windows</title>
+
+    <para>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
+      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>, 
+      and expect the process to involve a lot of fiddly work.</para>
+
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->

en/appD-license.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="cha:opl">
+  <title>Open Publication License</title>
+
+  <para>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
+      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
+      follows:</para>
+
+    <blockquote>
+      <para>  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,
+	v<emphasis>x.y</emphasis> or later (the latest version is
+	presently available at <ulink
+	  url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
+    </blockquote>
+
+    <para>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
+      material is permitted.</para>
+
+    <para>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
+      name shall be as large as the title of the work and cited as
+      possessive with respect to the title.</para>
+
+  </sect1>
+  <sect1>
+    <title>Copyright</title>
+
+    <para>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
+      works, unless otherwise explicitly stated in the
+      document.</para>
+
+    <para>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
+      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
+      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
+      fitness for a particular purpose or a warranty of
+      non-infringement.</para>
+
+  </sect1>
+  <sect1>
+    <title>Requirements on modified works</title>
+
+    <para>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
+	  such.</para>
+      </listitem>
+      <listitem><para>The person making the modifications must be
+	  identified and the modifications dated.</para>
+      </listitem>
+      <listitem><para>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
+	  must be identified.</para>
+      </listitem>
+      <listitem><para>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>
+      </listitem></orderedlist>
+
+  </sect1>
+  <sect1>
+    <title>Good-practice recommendations</title>
+
+    <para>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
+	  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
+	  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
+	  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>
+      </listitem></orderedlist>
+
+  </sect1>
+  <sect1 id="sec:opl:options">
+    <title>License options</title>
+
+    <para>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
+      must be included with the license (or its incorporation by
+      reference) in derived works.</para>
+
+    <orderedlist>
+      <listitem><para>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
+	  <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
+	  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
+	  <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>
+	  to the license reference or copy.</para>
+      </listitem></orderedlist>
+
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->

en/ch00-preface.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<preface id="chap:preface">
+  <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>
+
+  <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>
+
+  <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>
+
+  </sect1>
+  <sect1>
+    <title>About the examples in this book</title>
+
+    <para>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
+      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
+      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
+      can issue no more than one command every few seconds, with any
+      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
+      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
+      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>
+
+    <para>This book is licensed under the Open Publication License,
+      and is produced entirely using Free Software tools.  It is
+      typeset with \LaTeX{}; 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
+      Mercurial repository, at <ulink
+	url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
+
+  </sect1>
+</preface>
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "preface")
+end:
+-->

en/ch02-tour-basic.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<chapter>
+<chapter id="chap:tour-basic">
   <title>A tour of Mercurial: the basics</title>
-  <para>\label{chap:tour-basic}</para>
 
-  <sect1>
+  <sect1 id="sec:tour:install">
     <title>Installing Mercurial on your system</title>
-    <para>\label{sec:tour:install}</para>
 
     <para>Prebuilt binary packages of Mercurial are available for
       every popular operating system.  These make it easy to start
       <para>Lee Cantey publishes an installer of Mercurial for Mac OS
 	X at <ulink
 	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
-	This package works on both Intel- and Power-based Macs.
-	Before you can use it, you must install a compatible version
-	of Universal MacPython <citation>web:macpython</citation>.
-	This is easy to do; simply follow the instructions on Lee's
+	This package works on both Intel- and Power-based Macs. Before
+	you can use it, you must install a compatible version of
+	Universal MacPython <citation>web:macpython</citation>. This
+	is easy to do; simply follow the instructions on Lee's
 	site.</para>
 
       <para>It's also possible to install Mercurial using Fink or
 	version</command> command to find out whether Mercurial is
       actually installed properly.  The actual version information
       that it prints isn't so important; it's whether it prints
-      anything at all that we care about. <!--
-      &interaction.tour.version; --></para>
+      anything at all that we care about.</para>
+
+      <!-- &interaction.tour.version; -->
 
     <sect2>
       <title>Built-in help</title>
 
       <para>Mercurial provides a built-in help system.  This is
-	invaluable for those times when you find yourself stuck trying
-	to remember how to run a command.  If you are completely
-	stuck, simply run <command role="hg-cmd">hg help</command>; it
-	will print a brief list of commands, along with a description
-	of what each does.  If you ask for help on a specific command
-	(as below), it prints more detailed information. <!--
-	&interaction.tour.help; --> For a more impressive level of
-	detail (which you won't usually need) run <command
-	  role="hg-cmd">hg help <option
-	    role="hg-opt-global">-v</option></command>.  The <option
-	  role="hg-opt-global">-v</option> option is short for <option
-	  role="hg-opt-global">--verbose</option>, and tells Mercurial
-	to print more information than it usually would.</para>
+	  invaluable for those times when you find yourself stuck
+	  trying to remember how to run a command.  If you are
+	  completely stuck, simply run <command role="hg-cmd">hg
+	    help</command>; it will print a brief list of commands,
+	  along with a description of what each does.  If you ask for
+	  help on a specific command (as below), it prints more
+	  detailed information.</para>
+
+	<!-- &interaction.tour.help; -->
+
+	<para>For a more impressive level of detail (which you won't
+	  usually need) run <command role="hg-cmd">hg help <option
+	      role="hg-opt-global">-v</option></command>.  The <option
+	    role="hg-opt-global">-v</option> option is short for
+	  <option role="hg-opt-global">--verbose</option>, and tells
+	  Mercurial to print more information than it usually
+	  would.</para>
 
     </sect2>
   </sect1>
 	command to make a copy of a repository, it's best to use a
 	built-in command that Mercurial provides.  This command is
 	called <command role="hg-cmd">hg clone</command>, because it
-	creates an identical copy of an existing repository. <!--
-	&interaction.tour.clone; --> If our clone succeeded, we should
-	now have a local directory called <filename
-	  class="directory">hello</filename>.  This directory will
-	contain some files. <!-- &interaction.tour.ls; --> These files
-	have the same contents and history in our repository as they
-	do in the repository we cloned.</para>
+	creates an identical copy of an existing repository.</para>
+
+      <!-- &interaction.tour.clone; -->
+
+      <para>If our clone succeeded, we should now have a local
+	directory called <filename class="directory">hello</filename>.
+	This directory will contain some files.</para>
+
+      <!-- &interaction.tour.ls; -->
+
+      <para>These files have the same contents and history in our
+	repository as they do in the repository we cloned.</para>
 
       <para>Every Mercurial repository is complete, self-contained,
 	and independent.  It contains its own private copy of a
       <para>When we take a more detailed look inside a repository, we
 	can see that it contains a directory named <filename
 	  class="directory">.hg</filename>.  This is where Mercurial
-	keeps all of its metadata for the repository. <!--
-	&interaction.tour.ls-a; --></para>
+	keeps all of its metadata for the repository.</para>
+
+      <!-- &interaction.tour.ls-a; -->
 
       <para>The contents of the <filename
 	  class="directory">.hg</filename> directory and its
     <para>One of the first things we might want to do with a new,
       unfamiliar repository is understand its history.  The <command
 	role="hg-cmd">hg log</command> command gives us a view of
-      history. <!-- &interaction.tour.log; --> By default, this
-      command prints a brief paragraph of output for each change to
-      the project that was recorded.  In Mercurial terminology, we
-      call each of these recorded events a
+      history.</para>
+
+    <!-- &interaction.tour.log; -->
+
+    <para>By default, this command prints a brief paragraph of output
+      for each change to the project that was recorded.  In Mercurial
+      terminology, we call each of these recorded events a
       <emphasis>changeset</emphasis>, because it can contain a record
       of changes to several files.</para>
 
 	  role="hg-opt-log">-r</option> (or <option
 	  role="hg-opt-log">--rev</option>) option.  You can use
 	either a revision number or a long-form changeset identifier,
-	and you can provide as many revisions as you want.  <!--
-	&interaction.tour.log-r; --></para>
+	and you can provide as many revisions as you want.</para>
+
+      <!-- &interaction.tour.log-r; -->
 
       <para>If you want to see the history of several revisions
 	without having to list each one, you can use <emphasis>range
 	  notation</emphasis>; this lets you express the idea <quote>I
-	  want all revisions between $a$ and $b$, inclusive</quote>.
-	<!-- &interaction.tour.log.range; --> Mercurial also honours
-	the order in which you specify revisions, so <command
-	  role="hg-cmd">hg log -r 2:4</command> prints $2,3,4$ while
-	<command role="hg-cmd">hg log -r 4:2</command> prints
-	$4,3,2$.</para>
+	  want all revisions between <literal>abc</literal> and
+	  <literal>def</literal>, inclusive</quote>.</para>
+      
+	<!-- &interaction.tour.log.range; -->
+
+      <para>Mercurial also honours the order in which you specify
+	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
+	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
+	  4:2</command> prints 4, 3, and 2.</para>
 
     </sect2>
     <sect2>
 	looking for. The <command role="hg-cmd">hg log</command>
 	command's <option role="hg-opt-global">-v</option> (or <option
 	  role="hg-opt-global">--verbose</option>) option gives you
-	this extra detail. <!-- &interaction.tour.log-v; --></para>
+	this extra detail.</para>
+
+      <!-- &interaction.tour.log-v; -->
 
       <para>If you want to see both the description and content of a
 	change, add the <option role="hg-opt-log">-p</option> (or
 	displays the content of a change as a <emphasis>unified
 	  diff</emphasis> (if you've never seen a unified diff before,
 	see section <xref linkend="sec:mq:patch"/> for an
-	overview). <!-- &interaction.tour.log-vp; --></para>
+	overview).</para>
+
+      <!-- &interaction.tour.log-vp; -->
 
     </sect2>
   </sect1>
       the remote repository.  Since we already have a copy of it
       locally, we can just clone that instead.  This is much faster
       than cloning over the network, and cloning a local repository
-      uses less disk space in most cases, too. <!--
-      &interaction.tour.reclone; --> As an aside, it's often good
-      practice to keep a <quote>pristine</quote> copy of a remote
-      repository around, which you can then make temporary clones of
-      to create sandboxes for each task you want to work on.  This
-      lets you work on multiple tasks in parallel, each isolated from
-      the others until it's complete and you're ready to integrate it
-      back.  Because local clones are so cheap, there's almost no
-      overhead to cloning and destroying repositories whenever you
-      want.</para>
+      uses less disk space in most cases, too.</para>
+
+    <!-- &interaction.tour.reclone; -->
+
+    <para>As an aside, it's often good practice to keep a
+      <quote>pristine</quote> copy of a remote repository around,
+      which you can then make temporary clones of to create sandboxes
+      for each task you want to work on.  This lets you work on
+      multiple tasks in parallel, each isolated from the others until
+      it's complete and you're ready to integrate it back.  Because
+      local clones are so cheap, there's almost no overhead to cloning
+      and destroying repositories whenever you want.</para>
 
     <para>In our <filename class="directory">my-hello</filename>
       repository, we have a file <filename>hello.c</filename> that
       to write a scripted example this way.  Since you're not under
       the same constraint, you probably won't want to use
       <command>sed</command>; simply use your preferred text editor to
-      do the same thing.) <!-- &interaction.tour.sed; --></para>
+      do the same thing.)</para>
+
+    <!-- &interaction.tour.sed; -->
 
     <para>Mercurial's <command role="hg-cmd">hg status</command>
       command will tell us what Mercurial knows about the files in the
-      repository. <!-- &interaction.tour.status; --> The <command
-	role="hg-cmd">hg status</command> command prints no output for
-      some files, but a line starting with
+      repository.</para>
+
+    <!-- &interaction.tour.status; -->
+
+    <para>The <command role="hg-cmd">hg status</command> command
+      prints no output for some files, but a line starting with
       <quote><literal>M</literal></quote> for
       <filename>hello.c</filename>.  Unless you tell it to, <command
 	role="hg-cmd">hg status</command> will not print any output
       <filename>hello.c</filename>, but we might prefer to know
       exactly <emphasis>what</emphasis> changes we've made to it.  To
       do this, we use the <command role="hg-cmd">hg diff</command>
-      command. <!-- &interaction.tour.diff; --></para>
+      command.</para>
+
+    <!-- &interaction.tour.diff; -->
 
   </sect1>
   <sect1>
     <sect2>
       <title>Updating the working directory</title>
 
-      <para>We have so far glossed over the relationship
-	  between a repository and its working directory.  The
-	  <command role="hg-cmd">hg pull</command> command that we ran
-	  in section <xref linkend="sec:tour:pull"/> brought changes into
-	  the
-	  repository, but if we check, there's no sign of those
-	  changes in the working directory.  This is because <command
-	    role="hg-cmd">hg pull</command> does not (by default)
-	  touch the working directory.  Instead, we use the <command
-	    role="hg-cmd">hg update</command> command to do this. <!--
-	  &interaction.tour.update; --></para>
-      <para>It might seem a bit strange that <command
-	    role="hg-cmd">hg pull</command> doesn't update the working
-	  directory automatically.  There's actually a good reason for
-	  this: you can use <command role="hg-cmd">hg update</command>
-	  to update the working directory to the state it was in at
-	  <emphasis>any revision</emphasis> in the history of the
-	  repository.  If you had the working directory updated to an
-	  old revision---to hunt down the origin of a bug, say---and
-	  ran a <command role="hg-cmd">hg pull</command> which
-	  automatically updated the working directory to a new
-	  revision, you might not be terribly happy.</para>
-      <para>However, since pull-then-update is such a common
-	  thing to do, Mercurial lets you combine the two by passing
-	  the <option role="hg-opt-pull">-u</option> option to
-	  <command role="hg-cmd">hg
-	    pull</command>.</para>
+      <para>We have so far glossed over the relationship between a
+	repository and its working directory.  The <command
+	  role="hg-cmd">hg pull</command> command that we ran in
+	section <xref linkend="sec:tour:pull"/> brought changes
+	into the repository, but if we check, there's no sign of those
+	changes in the working directory.  This is because <command
+	  role="hg-cmd">hg pull</command> does not (by default) touch
+	the working directory.  Instead, we use the <command
+	  role="hg-cmd">hg update</command> command to do this.</para>
+
+      <!-- &interaction.tour.update; -->
+
+      <para>It might seem a bit strange that <command role="hg-cmd">hg
+	  pull</command> doesn't update the working directory
+	automatically.  There's actually a good reason for this: you
+	can use <command role="hg-cmd">hg update</command> to update
+	the working directory to the state it was in at <emphasis>any
+	  revision</emphasis> in the history of the repository.  If
+	you had the working directory updated to an old revision---to
+	hunt down the origin of a bug, say---and ran a <command
+	  role="hg-cmd">hg pull</command> which automatically updated
+	the working directory to a new revision, you might not be
+	terribly happy.</para>
+      <para>However, since pull-then-update is such a common thing to
+	do, Mercurial lets you combine the two by passing the <option
+	  role="hg-opt-pull">-u</option> option to <command
+	  role="hg-cmd">hg pull</command>.</para>
 
       <para>If you look back at the output of <command
-	    role="hg-cmd">hg pull</command> in section <xref
+	  role="hg-cmd">hg pull</command> in section <xref
 	    linkend="sec:tour:pull"/> when we ran it without <option
-	    role="hg-opt-pull">-u</option>, you can see that it
-	  printed a helpful reminder that we'd have to take an
-	  explicit step to update the working
-	  directory:</para>
+	  role="hg-opt-pull">-u</option>, you can see that it printed
+	a helpful reminder that we'd have to take an explicit step to
+	update the working directory:</para>
 
       <!-- &interaction.xxx.fixme; -->
 
-      <para>To find out what revision the working directory
-	  is at, use the <command role="hg-cmd">hg parents</command>
-	  command.</para>
+      <para>To find out what revision the working directory is at, use
+	the <command role="hg-cmd">hg parents</command>
+	command.</para>
 
       <!-- &interaction.tour.parents; -->
 
-      <para>If you look
-	  back at figure <xref linkend="fig:tour-basic:history"/>, you'll
-	  see arrows connecting each changeset.  The node that the
-	  arrow leads <emphasis>from</emphasis> in each case is a
-	  parent, and the node that the arrow leads
-	  <emphasis>to</emphasis> is its child.  The working directory
-	  has a parent in just the same way; this is the changeset
-	  that the working directory currently
-	  contains.</para>
-      <para>To update the working directory to a particular
-	  revision, give a revision number or changeset ID to the
-	  <command role="hg-cmd">hg update</command> command. <!--
-	  &interaction.tour.older; --> If you omit an explicit
-	  revision, <command role="hg-cmd">hg update</command> will
-	  update to the tip revision, as shown by the second call to
-	  <command role="hg-cmd">hg update</command> in the example
-	  above.</para>
+      <para>If you look back at figure <xref
+	  linkend="fig:tour-basic:history"/>,
+	you'll see arrows connecting each changeset.  The node that
+	the arrow leads <emphasis>from</emphasis> in each case is a
+	parent, and the node that the arrow leads
+	<emphasis>to</emphasis> is its child.  The working directory
+	has a parent in just the same way; this is the changeset that
+	the working directory currently contains.</para>
+
+      <para>To update the working directory to a particular revision,
+
+	give a revision number or changeset ID to the <command
+	  role="hg-cmd">hg update</command> command.</para>
+
+      <!-- &interaction.tour.older; -->
+
+      <para>If you omit an explicit revision, <command
+	  role="hg-cmd">hg update</command> will update to the tip
+	revision, as shown by the second call to <command
+	  role="hg-cmd">hg update</command> in the example
+	above.</para>
     </sect2>
 
     <sect2>

en/ch03-tour-merge.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:tour-merge">
+  <title>A tour of Mercurial: merging work</title>
+
+  <para>We've now covered cloning a repository, making changes in a
+    repository, and pulling or pushing changes from one repository
+    into another.  Our next step is <emphasis>merging</emphasis>
+    changes from separate repositories.</para>
+
+  <sect1>
+    <title>Merging streams of work</title>
+
+    <para>Merging is a fundamental part of working with a distributed
+      revision control tool.</para>
+    <itemizedlist>
+      <listitem><para>Alice and Bob each have a personal copy of a
+	  repository for a project they're collaborating on.  Alice
+	  fixes a bug in her repository; Bob adds a new feature in
+	  his.  They want the shared repository to contain both the
+	  bug fix and the new feature.</para>
+      </listitem>
+      <listitem><para>I frequently work on several different tasks for
+	  a single project at once, each safely isolated in its own
+	  repository. Working this way means that I often need to
+	  merge one piece of my own work with another.</para>
+      </listitem></itemizedlist>
+
+    <para>Because merging is such a common thing to need to do,
+      Mercurial makes it easy.  Let's walk through the process.  We'll
+      begin by cloning yet another repository (see how often they
+      spring up?) and making a change in it.</para>
+
+    <!-- &interaction.tour.merge.clone; -->
+
+    <para>We should now have two copies of
+      <filename>hello.c</filename> with different contents.  The
+      histories of the two repositories have also diverged, as
+      illustrated in figure <xref
+	linkend="fig:tour-merge:sep-repos"/>.</para>
+
+    <!-- &interaction.tour.merge.cat; -->
+
+    <informalfigure id="fig:tour-merge:sep-repos">
+      <mediaobject>
+	<imageobject><imagedata fileref="tour-merge-sep-repos"/></imageobject>
+	<textobject><phrase>XXX add text</phrase></textobject>
+	<caption><para>Divergent recent histories of the <filename
+	      class="directory">my-hello</filename> and <filename
+	      class="directory">my-new-hello</filename>
+	    repositories</para></caption>
+      </mediaobject>
+    </informalfigure>
+
+    <para>We already know that pulling changes from our <filename
+	class="directory">my-hello</filename> repository will have no
+      effect on the working directory.</para>
+
+    <!-- &interaction.tour.merge.pull; -->
+
+    <para>However, the <command role="hg-cmd">hg pull</command>
+      command says something about <quote>heads</quote>.</para>
+
+    <sect2>
+      <title>Head changesets</title>
+
+      <para>A head is a change that has no descendants, or children,
+	as they're also known.  The tip revision is thus a head,
+	because the newest revision in a repository doesn't have any
+	children, but a repository can contain more than one
+	head.</para>
+
+      <informalfigure id="fig:tour-merge:pull">
+	<mediaobject><imageobject><imagedata
+				    fileref="tour-merge-pull"/></imageobject><textobject><phrase>XXX 
+	      add text</phrase></textobject>
+	  <caption><para>Repository contents after pulling from
+	      <filename class="directory">my-hello</filename> into
+	      <filename
+		class="directory">my-new-hello</filename></para></caption>
+	</mediaobject>
+      </informalfigure>
+
+      <para>In figure <xref linkend="fig:tour-merge:pull"/>, you can
+	see the effect of the pull from <filename
+	  class="directory">my-hello</filename> into <filename
+	  class="directory">my-new-hello</filename>.  The history that
+	was already present in <filename
+	  class="directory">my-new-hello</filename> is untouched, but
+	a new revision has been added.  By referring to figure <xref
+	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
+	<emphasis>changeset ID</emphasis> remains the same in the new
+	repository, but the <emphasis>revision number</emphasis> has
+	changed.  (This, incidentally, is a fine example of why it's
+	not safe to use revision numbers when discussing changesets.)
+	We can view the heads in a repository using the <command
+	  role="hg-cmd">hg heads</command> command.</para>
+
+      <!-- &interaction.tour.merge.heads; -->
+
+    </sect2>
+    <sect2>
+      <title>Performing the merge</title>
+
+      <para>What happens if we try to use the normal <command
+	  role="hg-cmd">hg update</command> command to update to the
+	new tip?</para>
+
+      <!-- &interaction.tour.merge.update; -->
+
+      <para>Mercurial is telling us that the <command role="hg-cmd">hg
+	  update</command> command won't do a merge; it won't update
+	the working directory when it thinks we might be wanting to do
+	a merge, unless we force it to do so.  Instead, we use the
+	<command role="hg-cmd">hg merge</command> command to merge the
+	two heads.</para>
+
+      <!-- &interaction.tour.merge.merge; -->
+
+      <informalfigure id="fig:tour-merge:merge">
+
+	<mediaobject><imageobject><imagedata
+				    fileref="tour-merge-merge"/></imageobject><textobject><phrase>XXX 
+	      add text</phrase></textobject>
+	  <caption><para>Working directory and repository during
+	      merge, and following commit</para></caption>
+	</mediaobject>
+      </informalfigure>
+
+      <para>This updates the working directory so that it contains
+	changes from <emphasis>both</emphasis> heads, which is
+	reflected in both the output of <command role="hg-cmd">hg
+	  parents</command> and the contents of
+	<filename>hello.c</filename>.</para>
+
+      <!-- &interaction.tour.merge.parents; -->
+
+    </sect2>
+    <sect2>
+      <title>Committing the results of the merge</title>
+
+      <para>Whenever we've done a merge, <command role="hg-cmd">hg
+	  parents</command> will display two parents until we <command
+	  role="hg-cmd">hg commit</command> the results of the
+	  merge.</para>
+
+	<!-- &interaction.tour.merge.commit; -->
+
+      <para>We now have a new tip revision; notice that it has
+	<emphasis>both</emphasis> of our former heads as its parents.
+	These are the same revisions that were previously displayed by
+	<command role="hg-cmd">hg parents</command>.</para>
+
+      <!-- &interaction.tour.merge.tip; -->
+
+      <para>In figure <xref
+	  linkend="fig:tour-merge:merge"/>, you can see a
+	representation of what happens to the working directory during
+	the merge, and how this affects the repository when the commit
+	happens.  During the merge, the working directory has two
+	parent changesets, and these become the parents of the new
+	changeset.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Merging conflicting changes</title>
+
+    <para>Most merges are simple affairs, but sometimes you'll find
+      yourself merging changes where each modifies the same portions
+      of the same files.  Unless both modifications are identical,
+      this results in a <emphasis>conflict</emphasis>, where you have
+      to decide how to reconcile the different changes into something
+      coherent.</para>
+
+    <informalfigure>
+
+      <mediaobject id="fig:tour-merge:conflict">
+	<imageobject><imagedata fileref="tour-merge-conflict"/></imageobject>
+	<textobject><phrase>XXX add text</phrase></textobject>
+	<caption><para>Conflicting changes to a
+	    document</para></caption>      </mediaobject>
+    </informalfigure>
+
+    <para>Figure <xref linkend="fig:tour-merge:conflict"/> illustrates
+      an instance of two conflicting changes to a document.  We
+      started with a single version of the file; then we made some
+      changes; while someone else made different changes to the same
+      text.  Our task in resolving the conflicting changes is to
+      decide what the file should look like.</para>
+
+    <para>Mercurial doesn't have a built-in facility for handling
+      conflicts. Instead, it runs an external program called
+      <command>hgmerge</command>.  This is a shell script that is
+      bundled with Mercurial; you can change it to behave however you
+      please.  What it does by default is try to find one of several
+      different merging tools that are likely to be installed on your
+      system.  It first tries a few fully automatic merging tools; if
+      these don't succeed (because the resolution process requires
+      human guidance) or aren't present, the script tries a few
+      different graphical merging tools.</para>
+
+    <para>It's also possible to get Mercurial to run another program
+      or script instead of <command>hgmerge</command>, by setting the
+      <envar>HGMERGE</envar> environment variable to the name of your
+      preferred program.</para>
+
+    <sect2>
+      <title>Using a graphical merge tool</title>
+
+      <para>My preferred graphical merge tool is
+	<command>kdiff3</command>, which I'll use to describe the
+	features that are common to graphical file merging tools.  You
+	can see a screenshot of <command>kdiff3</command> in action in
+	figure <xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
+	merge it is performing is called a <emphasis>three-way
+	  merge</emphasis>, because there are three different versions
+	of the file of interest to us.  The tool thus splits the upper
+	portion of the window into three panes:</para>
+      <itemizedlist>
+	<listitem><para>At the left is the <emphasis>base</emphasis>
+	    version of the file, i.e. the most recent version from
+	    which the two versions we're trying to merge are
+	    descended.</para>
+	</listitem>
+	<listitem><para>In the middle is <quote>our</quote> version of
+	    the file, with the contents that we modified.</para>
+	</listitem>
+	<listitem><para>On the right is <quote>their</quote> version
+	    of the file, the one that from the changeset that we're
+	    trying to merge with.</para>
+	</listitem></itemizedlist>
+      <para>In the pane below these is the current
+	<emphasis>result</emphasis> of the merge. Our task is to
+	replace all of the red text, which indicates unresolved
+	conflicts, with some sensible merger of the
+	<quote>ours</quote> and <quote>theirs</quote> versions of the
+	file.</para>
+
+      <para>All four of these panes are <emphasis>locked
+	  together</emphasis>; if we scroll vertically or horizontally
+	in any of them, the others are updated to display the
+	corresponding sections of their respective files.</para>
+
+      <informalfigure id="fig:tour-merge:kdiff3">
+	<mediaobject><imageobject><imagedata
+				    fileref="kdiff3"/></imageobject><textobject><phrase>XXX 
+	      add text</phrase></textobject>
+	  <caption><para>Using <command>kdiff3</command> to merge
+	      versions of a file</para></caption>
+	</mediaobject>
+      </informalfigure>
+
+      <para>For each conflicting portion of the file, we can choose to
+	resolve the conflict using some combination of text from the
+	base version, ours, or theirs.  We can also manually edit the
+	merged file at any time, in case we need to make further
+	modifications.</para>
+
+      <para>There are <emphasis>many</emphasis> file merging tools
+	available, too many to cover here.  They vary in which
+	platforms they are available for, and in their particular
+	strengths and weaknesses.  Most are tuned for merging files
+	containing plain text, while a few are aimed at specialised
+	file formats (generally XML).</para>
+
+    </sect2>
+    <sect2>
+      <title>A worked example</title>
+
+      <para>In this example, we will reproduce the file modification
+	history of figure <xref linkend="fig:tour-merge:conflict"/>
+	above.  Let's begin by creating a repository with a base
+	version of our document.</para>
+
+      <!-- &interaction.tour-merge-conflict.wife; -->
+
+      <para>We'll clone the repository and make a change to the
+	file.</para>
+
+      <!-- &interaction.tour-merge-conflict.cousin; -->
+
+      <para>And another clone, to simulate someone else making a
+	change to the file. (This hints at the idea that it's not all
+	that unusual to merge with yourself when you isolate tasks in
+	separate repositories, and indeed to find and resolve
+	conflicts while doing so.)</para>
+
+      <!-- &interaction.tour-merge-conflict.son; -->
+
+      <para>Having created two
+	different versions of the file, we'll set up an environment
+	suitable for running our merge.</para>
+
+      <!-- &interaction.tour-merge-conflict.pull; -->
+
+      <para>In this example, I won't use Mercurial's normal
+	<command>hgmerge</command> program to do the merge, because it
+	would drop my nice automated example-running tool into a
+	graphical user interface.  Instead, I'll set
+	<envar>HGMERGE</envar> to tell Mercurial to use the
+	non-interactive <command>merge</command> command.  This is
+	bundled with many Unix-like systems. If you're following this
+	example on your computer, don't bother setting
+	<envar>HGMERGE</envar>.</para>
+
+      <para><emphasis role="bold">XXX FIX THIS
+	  EXAMPLE.</emphasis></para>
+
+      <!-- &interaction.tour-merge-conflict.merge; -->
+
+      <para>Because <command>merge</command> can't resolve the
+	conflicting changes, it leaves <emphasis>merge
+	  markers</emphasis> inside the file that has conflicts,
+	indicating which lines have conflicts, and whether they came
+	from our version of the file or theirs.</para>
+
+      <para>Mercurial can tell from the way <command>merge</command>
+	exits that it wasn't able to merge successfully, so it tells
+	us what commands we'll need to run if we want to redo the
+	merging operation.  This could be useful if, for example, we
+	were running a graphical merge tool and quit because we were
+	confused or realised we had made a mistake.</para>
+
+      <para>If automatic or manual merges fail, there's nothing to
+	prevent us from <quote>fixing up</quote> the affected files
+	ourselves, and committing the results of our merge:</para>
+
+      <!-- &interaction.tour-merge-conflict.commit; -->
+
+    </sect2>
+  </sect1>
+  <sect1 id="sec:tour-merge:fetch">
+    <title>Simplifying the pull-merge-commit sequence</title>
+
+    <para>The process of merging changes as outlined above is
+      straightforward, but requires running three commands in
+      sequence.</para>
+    <programlisting>
+      hg pull hg merge hg commit -m 'Merged remote changes'
+    </programlisting>
+    <para>In the case of the final commit, you also need to enter a
+      commit message, which is almost always going to be a piece of
+      uninteresting <quote>boilerplate</quote> text.</para>
+
+    <para>It would be nice to reduce the number of steps needed, if
+      this were possible.  Indeed, Mercurial is distributed with an
+      extension called <literal role="hg-ext">fetch</literal> that
+      does just this.</para>
+
+    <para>Mercurial provides a flexible extension mechanism that lets
+      people extend its functionality, while keeping the core of
+      Mercurial small and easy to deal with.  Some extensions add new
+      commands that you can use from the command line, while others
+      work <quote>behind the scenes,</quote> for example adding
+      capabilities to the server.</para>
+
+    <para>The <literal role="hg-ext">fetch</literal> extension adds a
+      new command called, not surprisingly, <command role="hg-cmd">hg
+	fetch</command>.  This extension acts as a combination of
+      <command role="hg-cmd">hg pull</command>, <command
+	role="hg-cmd">hg update</command> and <command
+	role="hg-cmd">hg merge</command>.  It begins by pulling
+      changes from another repository into the current repository.  If
+      it finds that the changes added a new head to the repository, it
+      begins a merge, then commits the result of the merge with an
+      automatically-generated commit message.  If no new heads were
+      added, it updates the working directory to the new tip
+      changeset.</para>
+
+    <para>Enabling the <literal role="hg-ext">fetch</literal>
+      extension is easy.  Edit your <filename
+	role="special">.hgrc</filename>, and either go to the <literal
+	role="rc-extensions">extensions</literal> section or create an
+      <literal role="rc-extensions">extensions</literal> section. Then
+      add a line that simply reads <quote><literal>fetch
+	</literal></quote>.</para>
+    <programlisting>
+      [extensions] fetch =
+    </programlisting>
+    <para>(Normally, on the right-hand side of the
+      <quote><literal>=</literal></quote> would appear the location of
+      the extension, but since the <literal
+	role="hg-ext">fetch</literal> extension is in the standard
+      distribution, Mercurial knows where to search for it.)</para>
+
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->

en/ch04-concepts.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:concepts">
+  <title>Behind the scenes</title>
+
+  <para>Unlike many revision control systems, the concepts upon which
+    Mercurial is built are simple enough that it's easy to understand
+    how the software really works.  Knowing this certainly isn't
+    necessary, but I find it useful to have a <quote>mental
+      model</quote> of what's going on.</para>
+
+  <para>This understanding gives me confidence that Mercurial has been
+    carefully designed to be both <emphasis>safe</emphasis> and
+    <emphasis>efficient</emphasis>.  And just as importantly, if it's
+    easy for me to retain a good idea of what the software is doing
+    when I perform a revision control task, I'm less likely to be
+    surprised by its behaviour.</para>
+
+  <para>In this chapter, we'll initially cover the core concepts
+    behind Mercurial's design, then continue to discuss some of the
+    interesting details of its implementation.</para>
+
+  <sect1>
+    <title>Mercurial's historical record</title>
+
+    <sect2>
+      <title>Tracking the history of a single file</title>
+
+      <para>When Mercurial tracks modifications to a file, it stores
+	the history of that file in a metadata object called a
+	<emphasis>filelog</emphasis>.  Each entry in the filelog
+	contains enough information to reconstruct one revision of the
+	file that is being tracked.  Filelogs are stored as files in
+	the <filename role="special"
+	  class="directory">.hg/store/data</filename> directory.  A
+	filelog contains two kinds of information: revision data, and
+	an index to help Mercurial to find a revision
+	efficiently.</para>
+
+      <para>A file that is large, or has a lot of history, has its
+	filelog stored in separate data
+	(<quote><literal>.d</literal></quote> suffix) and index
+	(<quote><literal>.i</literal></quote> suffix) files.  For
+	small files without much history, the revision data and index
+	are combined in a single <quote><literal>.i</literal></quote>
+	file.  The correspondence between a file in the working
+	directory and the filelog that tracks its history in the
+	repository is illustrated in figure <xref
+	  linkend="fig:concepts:filelog"/>.</para>
+
+      <informalfigure id="fig:concepts:filelog">
+	<mediaobject><imageobject><imagedata
+				    fileref="filelog"/></imageobject><textobject><phrase>XXX 
+	      add text</phrase></textobject>
+	  <caption><para>Relationships between files in working
+	      directory and filelogs in
+	      repository</para></caption></mediaobject>
+      </informalfigure>
+
+    </sect2>
+    <sect2>
+      <title>Managing tracked files</title>
+
+      <para>Mercurial uses a structure called a
+	<emphasis>manifest</emphasis> to collect together information
+	about the files that it tracks.  Each entry in the manifest
+	contains information about the files present in a single
+	changeset.  An entry records which files are present in the
+	changeset, the revision of each file, and a few other pieces
+	of file metadata.</para>
+
+    </sect2>
+    <sect2>
+      <title>Recording changeset information</title>
+
+      <para>The <emphasis>changelog</emphasis> contains information
+	about each changeset.  Each revision records who committed a
+	change, the changeset comment, other pieces of
+	changeset-related information, and the revision of the
+	manifest to use.</para>
+
+    </sect2>
+    <sect2>
+      <title>Relationships between revisions</title>
+
+      <para>Within a changelog, a manifest, or a filelog, each
+	revision stores a pointer to its immediate parent (or to its
+	two parents, if it's a merge revision).  As I mentioned above,
+	there are also relationships between revisions
+	<emphasis>across</emphasis> these structures, and they are
+	hierarchical in nature.</para>
+
+      <para>For every changeset in a repository, there is exactly one
+	revision stored in the changelog.  Each revision of the
+	changelog contains a pointer to a single revision of the
+	manifest.  A revision of the manifest stores a pointer to a
+	single revision of each filelog tracked when that changeset
+	was created.  These relationships are illustrated in figure
+	<xref linkend="fig:concepts:metadata"/>.</para>
+
+      <informalfigure id="fig:concepts:metadata">
+	<mediaobject><imageobject><imagedata
+				    fileref="metadata"/></imageobject><textobject><phrase>XXX 
+	      add text</phrase></textobject><caption><para>Metadata
+	      relationships</para></caption>
+	</mediaobject>
+      </informalfigure>
+
+      <para>As the illustration shows, there is
+	<emphasis>not</emphasis> a <quote>one to one</quote>
+	relationship between revisions in the changelog, manifest, or
+	filelog. If the manifest hasn't changed between two
+	changesets, the changelog entries for those changesets will
+	point to the same revision of the manifest.  If a file that
+	Mercurial tracks hasn't changed between two changesets, the
+	entry for that file in the two revisions of the manifest will
+	point to the same revision of its filelog.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Safe, efficient storage</title>
+
+    <para>The underpinnings of changelogs, manifests, and filelogs are
+      provided by a single structure called the
+      <emphasis>revlog</emphasis>.</para>
+
+    <sect2>
+      <title>Efficient storage</title>
+
+      <para>The revlog provides efficient storage of revisions using a
+	<emphasis>delta</emphasis> mechanism.  Instead of storing a
+	complete copy of a file for each revision, it stores the
+	changes needed to transform an older revision into the new
+	revision.  For many kinds of file data, these deltas are
+	typically a fraction of a percent of the size of a full copy