Dongsheng Song avatar Dongsheng Song committed 1c13ed2 Merge

Comments (0)

Files changed (295)

-[^/]+/build/
-[^/]+/fop/
-[^/]+/hello/
-[^/]+/html/
+[^/]+/htdocs/
 
 syntax: glob
 
 *.pyc
 *.rej
 *.run
-*-tmp.svg
 *~
-.*.swp
+.*.sw[op]
 .\#*
 .run
 .validated-00book.xml
 en/all-ids.dat
 web/hgbook/.database.sqlite3
 web/hgbook/secrets.py
+web/index-read.html.in
 stylesheets/system-xsl
+build
+en/html
+en/examples/results
+tools
 rev_id = $(shell hg parents --template '{node|short} ({date|shortdate})')
 
 images := \
-	en/images/feature-branches.png \
-	en/images/filelog.png \
-	en/images/metadata.png \
-	en/images/mq-stack.png \
-	en/images/revlog.png \
-	en/images/snapshot.png \
-	en/images/tour-history.png \
-	en/images/tour-merge-conflict.png \
-	en/images/tour-merge-merge.png \
-	en/images/tour-merge-pull.png \
-	en/images/tour-merge-sep-repos.png \
-	en/images/undo-manual-merge.png \
-	en/images/undo-manual.png \
-	en/images/undo-non-tip.png \
-	en/images/undo-simple.png \
-	en/images/wdir-after-commit.png \
-	en/images/wdir-branch.png \
-	en/images/wdir-merge.png \
-	en/images/wdir.png \
-	en/images/wdir-pre-branch.png
+	en/figs/feature-branches.png \
+	en/figs/filelog.png \
+	en/figs/metadata.png \
+	en/figs/mq-stack.png \
+	en/figs/revlog.png \
+	en/figs/snapshot.png \
+	en/figs/tour-history.png \
+	en/figs/tour-merge-conflict.png \
+	en/figs/tour-merge-merge.png \
+	en/figs/tour-merge-pull.png \
+	en/figs/tour-merge-sep-repos.png \
+	en/figs/undo-manual-merge.png \
+	en/figs/undo-manual.png \
+	en/figs/undo-non-tip.png \
+	en/figs/undo-simple.png \
+	en/figs/wdir-after-commit.png \
+	en/figs/wdir-branch.png \
+	en/figs/wdir-merge.png \
+	en/figs/wdir.png \
+	en/figs/wdir-pre-branch.png
 
 help:
 	@echo "  make html         [LINGUA=en|zh|...]"
 	@echo "  make clean        # Remove the build files."
 
 clean:
-	@rm -fr build po/*.mo hello en/hello en/html en/.validated-00book.xml \
-          stylesheets/system-xsl en/images/*-tmp.svg \
-          en/images/feature-branches.png \
-          en/images/filelog.png \
-          en/images/feature-branches.png \
-          en/images/filelog.png \
-          en/images/metadata.png \
-          en/images/mq-stack.png \
-          en/images/revlog.png \
-          en/images/snapshot.png \
-          en/images/tour-history.png \
-          en/images/tour-merge-conflict.png \
-          en/images/tour-merge-merge.png \
-          en/images/tour-merge-pull.png \
-          en/images/tour-merge-sep-repos.png \
-          en/images/undo-manual-merge.png \
-          en/images/undo-manual.png \
-          en/images/undo-non-tip.png \
-          en/images/undo-simple.png \
-          en/images/wdir-after-commit.png \
-          en/images/wdir-branch.png \
-          en/images/wdir-merge.png \
-          en/images/wdir-pre-branch.png \
-          en/images/wdir.png
+	@rm -fr build po/*.mo hello en/hello en/html en/.validated-00book.xml en/examples/.run en/examples/results \
+          stylesheets/system-xsl en/figs/*-tmp.svg \
+          en/figs/feature-branches.png \
+          en/figs/filelog.png \
+          en/figs/feature-branches.png \
+          en/figs/filelog.png \
+          en/figs/metadata.png \
+          en/figs/mq-stack.png \
+          en/figs/revlog.png \
+          en/figs/snapshot.png \
+          en/figs/tour-history.png \
+          en/figs/tour-merge-conflict.png \
+          en/figs/tour-merge-merge.png \
+          en/figs/tour-merge-pull.png \
+          en/figs/tour-merge-sep-repos.png \
+          en/figs/undo-manual-merge.png \
+          en/figs/undo-manual.png \
+          en/figs/undo-non-tip.png \
+          en/figs/undo-simple.png \
+          en/figs/wdir-after-commit.png \
+          en/figs/wdir-branch.png \
+          en/figs/wdir-merge.png \
+          en/figs/wdir-pre-branch.png \
+          en/figs/wdir.png
 
 all:
 ifdef LINGUA
 	xmllint --nonet --noout --postvalid --xinclude $<
 
 ifneq "$(findstring $(LINGUA),$(DBK_LANGUAGES))" ""
-build/$(LINGUA)/source/hgbook.xml: $(wildcard $(LINGUA)/*.xml) $(images)
-	mkdir -p build/$(LINGUA)/source
-	cp -r $(LINGUA)/* build/$(LINGUA)/source
-	xmllint --nonet --noent --xinclude --postvalid --output $@.tmp $(LINGUA)/00book.xml
+$(LINGUA)/examples/.run:
+	(cd $(LINGUA)/examples; ./run-example -v -a)
+
+build/$(LINGUA)/source/hgbook.xml: $(wildcard $(LINGUA)/*.xml) $(images) $(LINGUA)/examples/.run $(images)
+	mkdir -p build/$(LINGUA)/source/figs
+	cp $(LINGUA)/figs/*.png build/$(LINGUA)/source/figs
+	(cd $(LINGUA); xmllint --nonet --noent --xinclude --postvalid --output ../$@.tmp 00book.xml)
 	cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@
 else
-build/$(LINGUA)/source/hgbook.xml: $(wildcard en/*.xml) po/$(LINGUA).po $(images)
-	mkdir -p build/$(LINGUA)/source
-	cp -r en/images build/$(LINGUA)/source
-	cp -r en/examples build/$(LINGUA)/source
-	cp en/book-shortcuts.xml build/$(LINGUA)/source
-	for f in en/*.xml; do \
-	  if [ $$f != "en/book-shortcuts.xml" ]; then \
-	    $(TRANSLATE) -m $$f -p po/$(LINGUA).po -l build/$(LINGUA)/source/`basename $$f`; \
-	  fi \
-	done
-	xmllint --nonet --noent --xinclude --postvalid --output $@.tmp build/$(LINGUA)/source/00book.xml
+en/examples/.run:
+	(cd en/examples; ./run-example -v -a)
+
+build/en/source/hgbook.xml:
+	${MAKE} LINGUA=en $@
+
+build/$(LINGUA)/source/hgbook.xml: build/en/source/hgbook.xml po/$(LINGUA).po $(images)
+	mkdir -p build/$(LINGUA)/source/figs
+	$(TRANSLATE) -m build/en/source/hgbook.xml -p po/$(LINGUA).po -l $@.tmp
 	cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@
 endif
 
 html: build/$(LINGUA)/html/index.html
 
 build/$(LINGUA)/html/index.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html.xsl stylesheets/$(LINGUA)/html.xsl
-	mkdir -p build/$(LINGUA)/html/images
-	cp en/images/*.png build/$(LINGUA)/html/images
+	mkdir -p build/$(LINGUA)/html/figs
+	cp en/figs/*.png build/$(LINGUA)/html/figs
 	cp stylesheets/hgbook.css build/$(LINGUA)/html
 	xsltproc --output build/$(LINGUA)/html/ \
 	    stylesheets/$(LINGUA)/html.xsl build/$(LINGUA)/source/hgbook.xml
 html-single: build/$(LINGUA)/html-single/hgbook.html
 
 build/$(LINGUA)/html-single/hgbook.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html-single.xsl stylesheets/$(LINGUA)/html-single.xsl
-	mkdir -p build/$(LINGUA)/html-single/images
-	cp en/images/*.png build/$(LINGUA)/html-single/images
+	mkdir -p build/$(LINGUA)/html-single/figs
+	cp en/figs/*.png build/$(LINGUA)/html-single/figs
 	cp stylesheets/hgbook.css build/$(LINGUA)/html-single
 	xsltproc --output build/$(LINGUA)/html-single/hgbook.html \
 	    stylesheets/$(LINGUA)/html-single.xsl build/$(LINGUA)/source/hgbook.xml
 	(cd build/$(LINGUA)/source && ../../../tools/fop/fop.sh hgbook.fo ../pdf/hgbook.pdf)
 endif
 
-en/images/%.png: en/images/%.svg en/fixsvg
+en/figs/%.png: en/figs/%.svg en/fixsvg
 	en/fixsvg $<
 	inkscape -D -d 120 -e $@ $<-tmp.svg
 
-en/images/%.svg: en/images/%.dot
+en/figs/%.svg: en/figs/%.dot
 	dot -Tsvg -o $@ $<
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
 [
 <!-- Below are references to files in this directory. -->
 
 # This makefile requires GNU make.
 
-image-sources := \
-	feature-branches.dot \
-	filelog.svg \
-	kdiff3.png \
-	metadata.svg \
-	mq-stack.svg \
-	note.png \
-	revlog.svg \
-	snapshot.svg \
-	tour-history.svg \
-	tour-merge-conflict.svg \
-	tour-merge-merge.svg \
-	tour-merge-pull.svg \
-	tour-merge-sep-repos.svg \
-	undo-manual.dot \
-	undo-manual-merge.dot \
-	undo-non-tip.dot \
-	undo-simple.dot \
-	wdir.svg \
-	wdir-after-commit.svg \
-	wdir-branch.svg \
-	wdir-merge.svg \
-	wdir-pre-branch.svg
+image-sources := $(wildcard figs/*.dot figs/*.gif figs/*.png figs/*.svg)
 
 xml-src-files := \
 	00book.xml \
 
 image-dot := $(filter %.dot,$(image-sources))
 image-svg := $(filter %.svg,$(image-sources))
-image-png := $(filter %.png,$(image-sources))
+image-oth := $(filter %.gif %.png,$(image-sources))
 
-image-html := $(image-dot:%.dot=%.png) $(image-svg:%.svg=%.png) $(image-png)
+obj-web := html
+obj-websup := $(obj-web)/support
+obj-web-read := $(obj-web)/read
+
+image-web := \
+	$(image-dot:%.dot=$(obj-web-read)/%.png) \
+	$(image-svg:%.svg=$(obj-web-read)/%.png) \
+	$(image-oth:%=$(obj-web-read)/%)
 
 example-sources-by-name := \
 	backout \
 	$(example-sources-by-name:%=examples/%) \
 	$(wildcard examples/ch*/*)
 
-obj-web := html
-obj-websup := html/support
-
 extras-web-base := \
 	$(obj-web)/index.html \
 	$(obj-web)/robots.txt \
 
 all: web
 
-../xsl/system-xsl: $(system-xsl-dir)
+../stylesheets/system-xsl: $(system-xsl-dir)
 	ln -s $< $@
 
-web: ../xsl/system-xsl websup html
+web: ../stylesheets/system-xsl websup html
 
-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 \
+html: $(obj-web-read)/index.html
+
+../web/index-read.html.in: ../web/genindex.py $(xml-src-files)
+	$<
+
+$(obj-web-read)/index.html: ../stylesheets/system-xsl .validated-00book.xml ../web/index-read.html.in
+	xsltproc $(xsltproc-opts) -o $(obj-web-read)/x ../stylesheets/chunk-stylesheet.xsl 00book.xml
+	python ../web/texpand.py ../web/index-read.html.in html/read/index.html
+	for i in $(obj-web-read)/*.html; do \
 	  gzip -9 -c $$i > $$i.gz; \
 	done
 
-websup: $(extras-web)
-	mkdir -p $(obj-websup)/figs
-	cp ../xsl/system-xsl/images/*.png $(obj-websup)/figs
+websup: $(extras-web) $(image-web)
+	mkdir -p $(obj-websup)/figs $(obj-web-read)/figs
+	cp ../stylesheets/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
+all-ids.dat: ../stylesheets/all-ids.xsl $(xml-src-files)
+	$(xsltproc) $(xsltproc-opts) -o $@ ../stylesheets/all-ids.xsl 00book.xml
 
 web: websup
 
 
 # Produce 90dpi PNGs for the web.
 
-%.png: %.svg fixsvg
+$(obj-web-read)/figs/%.png: $(obj-web-read)/figs/%.svg fixsvg
+	mkdir -p $(dir $@)
 	./fixsvg $<
 	inkscape -D -e $@ $<-tmp.svg
 	rm $<-tmp.svg
 
-%.svg: %.dot
+$(obj-web-read)/figs/%.png: figs/%.svg fixsvg
+	mkdir -p $(dir $@)
+	./fixsvg $<
+	inkscape -D -e $@ $<-tmp.svg
+	rm $<-tmp.svg
+
+$(obj-web-read)/figs/%.gif: figs/%.gif
+	cp $< $@
+
+$(obj-web-read)/figs/%.png: figs/%.png
+	cp $< $@
+
+$(obj-web-read)/figs/%.svg: figs/%.dot
+	mkdir -p $(dir $@)
 	dot -Tsvg -o $@ $<
 
 examples: $(example-prereqs) examples/.run
 	rsync -avz --delete dist sp.red-bean.com:public_html/hgbook
 
 vpath %.css ../web
+vpath %.html.in ../web
 vpath %.js ../web/javascript
 
 $(obj-websup)/%.css: %.css

en/appA-cmdref.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
 <appendix id="cmdref">
+  <?dbhtml filename="command-reference.html"?>
 <title>Command reference</title>
 
 <para id="x_653">\cmdref{add}{add files at the next commit}
 
 <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>
+unified diff format, see <xref linkend="sec:mq:patch"/>.</para>
 
 <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
 
 <sect2>
 <title>Options</title>
-
+x
 <para id="x_657">\loptref{diff}{nodates}</para>
 
 <para id="x_658">Omit date and time information when printing diff headers.</para>
 <sect2>
 <title>Tips and tricks</title>
 
-<sect3 id="cmdref.diff-vs-status">
+<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 id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files

en/appB-mq-ref.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<appendix id="chap.mqref">
+<appendix id="chap:mqref">
   <?dbhtml filename="mercurial-queues-reference.html"?>
   <title>Mercurial Queues reference</title>
 
-  <sect1 id="sec.mqref.cmdref">
+  <sect1 id="sec:mqref:cmdref">
     <title>MQ command reference</title>
 
     <para id="x_5e8">For an overview of the commands provided by MQ, use the
 	  role="hg-ext-mq">qpop</command>.</para>
 
     </sect2>
-    <sect2 id="sec.mqref.cmd.qpush">
+    <sect2 id="sec:mqref:cmd:qpush">
       <title><command role="hg-ext-mq">qpush</command>&emdash;push
 	patches onto the stack</title>
 

en/appC-srcinstall.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<appendix id="chap.srcinstall">
+<appendix id="chap:srcinstall">
   <?dbhtml filename="installing-mercurial-from-source.html"?>
   <title>Installing Mercurial from source</title>
 
-  <sect1 id="sec.srcinstall.unixlike">
+  <sect1 id="sec:srcinstall:unixlike">
     <title>On a Unix-like system</title>
 
     <para id="x_5e0">If you are using a Unix-like system that has a sufficiently

en/appD-license.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<appendix id="cha.opl">
+<appendix id="cha:opl">
   <?dbhtml filename="open-publication-license.html"?>
   <title>Open Publication License</title>
 
 
     <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>
+      <xref linkend="sec:opl:options"/>).</para>
 
     <para id="x_63d">Commercial redistribution of Open Publication-licensed
       material is permitted.</para>
       </listitem></orderedlist>
 
   </sect1>
-  <sect1 id="sec.opl.options">
+  <sect1 id="sec:opl:options">
     <title>License options</title>
 
     <para id="x_64e">The author(s) and/or publisher of an Open

en/ch00-preface.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<preface id="chap.preface">
+<preface id="chap:preface">
   <?dbhtml filename="preface.html"?>
   <title>Preface</title>
 
 	    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>
+	    when a problem was introduced (see <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>
     <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
-	linkend="sec.undo.bisect"/>, for instance.</para>
+	role="hg-ext">bisect</literal> example in <xref
+	linkend="sec:undo:bisect"/>, for instance.</para>
 
     <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

en/ch01-tour-basic.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<chapter id="chap.tour-basic">
+<chapter id="chap:tour-basic">
   <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
   <title>A tour of Mercurial: the basics</title>
 
-  <sect1 id="sec.tour.install">
+  <sect1 id="sec:tour:install">
     <title>Installing Mercurial on your system</title>
 
-    <para>Prebuilt binary packages of Mercurial are available for
+    <para id="x_1">Prebuilt binary packages of Mercurial are available for
       every popular operating system.  These make it easy to start
       using Mercurial on your computer immediately.</para>
 
     <sect2>
       <title>Linux</title>
 
-      <para>Because each Linux distribution has its own packaging
+      <para id="x_2">Because each Linux distribution has its own packaging
 	tools, policies, and rate of development, it's difficult to
 	give a comprehensive set of instructions on how to install
 	Mercurial binaries.  The version of Mercurial that you will
 	end up with can vary depending on how active the person is who
 	maintains the package for your distribution.</para>
 
-      <para>To keep things simple, I will focus on installing
+      <para id="x_3">To keep things simple, I will focus on installing
 	Mercurial from the command line under the most popular Linux
 	distributions.  Most of these distributions provide graphical
 	package managers that will let you install Mercurial with a
 	<literal>mercurial</literal>.</para>
 
       <itemizedlist>
-	<listitem><para>Debian:</para>
+	<listitem><para id="x_4">Debian:</para>
 	  <programlisting>apt-get install mercurial</programlisting></listitem>
-	<listitem><para>Fedora Core:</para>
+	<listitem><para id="x_5">Fedora Core:</para>
 	  <programlisting>yum install mercurial</programlisting></listitem>
-	<listitem><para>Gentoo:</para>
+	<listitem><para id="x_6">Gentoo:</para>
 	  <programlisting>emerge mercurial</programlisting></listitem>
-	<listitem><para>OpenSUSE:</para>
+	<listitem><para id="x_7">OpenSUSE:</para>
 	  <programlisting>yum install mercurial</programlisting></listitem>
-	<listitem><para>Ubuntu: Ubuntu's Mercurial package is based on
+	<listitem><para id="x_8">Ubuntu: Ubuntu's Mercurial package is based on
 	    Debian's.  To install it, run the following
 	    command.</para>
 	  <programlisting>apt-get install mercurial</programlisting></listitem>
     <sect2>
       <title>Solaris</title>
 
-      <para>SunFreeWare, at <ulink
+      <para id="x_9">SunFreeWare, at <ulink
 	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
 	is a good source for a large number of pre-built Solaris
 	packages for 32 and 64 bit Intel and Sparc architectures,
     <sect2>
       <title>Mac OS X</title>
 
-      <para>Lee Cantey publishes an installer of Mercurial for Mac OS
+      <para id="x_a">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
 	is easy to do; simply follow the instructions on Lee's
 	site.</para>
 
-      <para>It's also possible to install Mercurial using Fink or
+      <para id="x_b">It's also possible to install Mercurial using Fink or
 	MacPorts, two popular free package managers for Mac OS X.  If
 	you have Fink, use <command>sudo apt-get install
 	  mercurial-py25</command>.  If MacPorts, <command>sudo port
     <sect2>
       <title>Windows</title>
 
-      <para>Lee Cantey publishes an installer of Mercurial for Windows
+      <para id="x_c">Lee Cantey publishes an installer of Mercurial for Windows
 	at <ulink
 	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
 	This package has no external dependencies; it <quote>just
 	  works</quote>.</para>
 
       <note>
-	<para>  The Windows version of Mercurial does not
+	<para id="x_d">  The Windows version of Mercurial does not
 	  automatically convert line endings between Windows and Unix
 	  styles.  If you want to share work with Unix users, you must
 	  do a little additional configuration work. XXX Flesh this
   <sect1>
     <title>Getting started</title>
 
-    <para>To begin, we'll use the <command role="hg-cmd">hg
+    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
 	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
     <sect2>
       <title>Built-in help</title>
 
-      <para>Mercurial provides a built-in help system.  This is
+      <para id="x_f">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
 
 	&interaction.tour.help;
 
-	<para>For a more impressive level of detail (which you won't
+	<para id="x_10">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
   <sect1>
     <title>Working with a repository</title>
 
-    <para>In Mercurial, everything happens inside a
+    <para id="x_11">In Mercurial, everything happens inside a
       <emphasis>repository</emphasis>.  The repository for a project
       contains all of the files that <quote>belong to</quote> that
       project, along with a historical record of the project's
       files.</para>
 
-    <para>There's nothing particularly magical about a repository; it
+    <para id="x_12">There's nothing particularly magical about a repository; it
       is simply a directory tree in your filesystem that Mercurial
       treats as special. You can rename or delete a repository any
       time you like, using either the command line or your file
     <sect2>
       <title>Making a local copy of a repository</title>
 
-      <para><emphasis>Copying</emphasis> a repository is just a little
+      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
 	bit special.  While you could use a normal file copying
 	command to make a copy of a repository, it's best to use a
 	built-in command that Mercurial provides.  This command is
 
       &interaction.tour.clone;
 
-      <para>If our clone succeeded, we should now have a local
+      <para id="x_14">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
+      <para id="x_15">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,
+      <para id="x_16">Every Mercurial repository is complete, self-contained,
 	and independent.  It contains its own private copy of a
 	project's files and history.  A cloned repository remembers
 	the location of the repository it was cloned from, but it does
 	not communicate with that repository, or any other, unless you
 	tell it to.</para>
 
-      <para>What this means for now is that we're free to experiment
+      <para id="x_17">What this means for now is that we're free to experiment
 	with our repository, safe in the knowledge that it's a private
 	<quote>sandbox</quote> that won't affect anyone else.</para>
 
     <sect2>
       <title>What's in a repository?</title>
 
-      <para>When we take a more detailed look inside a repository, we
+      <para id="x_18">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.</para>
 
       &interaction.tour.ls-a;
 
-      <para>The contents of the <filename
+      <para id="x_19">The contents of the <filename
 	  class="directory">.hg</filename> directory and its
 	subdirectories are private to Mercurial.  Every other file and
 	directory in the repository is yours to do with as you
 	please.</para>
 
-      <para>To introduce a little terminology, the <filename
+      <para id="x_1a">To introduce a little terminology, the <filename
 	  class="directory">.hg</filename> directory is the
 	<quote>real</quote> repository, and all of the files and
 	directories that coexist with it are said to live in the
   <sect1>
     <title>A tour through history</title>
 
-    <para>One of the first things we might want to do with a new,
+    <para id="x_1b">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.</para>
 
     &interaction.tour.log;
 
-    <para>By default, this command prints a brief paragraph of output
+    <para id="x_1c">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>
 
-    <para>The fields in a record of output from <command
+    <para id="x_1d">The fields in a record of output from <command
 	role="hg-cmd">hg log</command> are as follows.</para>
     <itemizedlist>
-      <listitem><para><literal>changeset</literal>: This field has the
+      <listitem><para id="x_1e"><literal>changeset</literal>: This field has the
 	  format of a number, followed by a colon, followed by a
 	  hexadecimal string.  These are
 	  <emphasis>identifiers</emphasis> for the changeset.  There
 	  are two identifiers because the number is shorter and easier
 	  to type than the hex string.</para></listitem>
-      <listitem><para><literal>user</literal>: The identity of the
+      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
 	  person who created the changeset.  This is a free-form
 	  field, but it most often contains a person's name and email
 	  address.</para></listitem>
-      <listitem><para><literal>date</literal>: The date and time on
+      <listitem><para id="x_20"><literal>date</literal>: The date and time on
 	  which the changeset was created, and the timezone in which
 	  it was created.  (The date and time are local to that
 	  timezone; they display what time and date it was for the
 	  person who created the changeset.)</para></listitem>
-      <listitem><para><literal>summary</literal>: The first line of
+      <listitem><para id="x_21"><literal>summary</literal>: The first line of
 	  the text message that the creator of the changeset entered
 	  to describe the changeset.</para></listitem></itemizedlist>
-    <para>The default output printed by <command role="hg-cmd">hg
+    <para id="x_22">The default output printed by <command role="hg-cmd">hg
 	log</command> is purely a summary; it is missing a lot of
       detail.</para>
 
-    <para>Figure <xref endterm="fig.tour-basic.history.caption"
-        linkend="fig.tour-basic.history"/> provides a
-      graphical representation of the history of the <filename
+    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
+      a graphical representation of the history of the <filename
 	class="directory">hello</filename> repository, to make it a
       little easier to see which direction history is
       <quote>flowing</quote> in.  We'll be returning to this figure
       several times in this chapter and the chapter that
       follows.</para>
 
-    <informalfigure id="fig.tour-basic.history">
+    <figure id="fig:tour-basic:history">
+      <title>Graphical history of the <filename
+	  class="directory">hello</filename> repository</title>
       <mediaobject>
-	<imageobject><imagedata fileref="images/tour-history.png"/></imageobject>
+	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
 	<textobject><phrase>XXX add text</phrase></textobject>
-	<caption><para id="fig.tour-basic.history.caption">Graphical history of
-	    the <filename class="directory">hello</filename> repository</para>
-	</caption>
       </mediaobject>
-    </informalfigure>
+    </figure>
 
     <sect2>
       <title>Changesets, revisions, and talking to other
 	people</title>
 
-      <para>As English is a notoriously sloppy language, and computer
+      <para id="x_25">As English is a notoriously sloppy language, and computer
 	science has a hallowed history of terminological confusion
 	(why use one term when four will do?), revision control has a
 	variety of words and phrases that mean the same thing.  If you
 	<quote>cset</quote>, and sometimes a changeset is referred to
 	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
 
-      <para>While it doesn't matter what <emphasis>word</emphasis> you
+      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
 	use to refer to the concept of <quote>a changeset</quote>, the
 	<emphasis>identifier</emphasis> that you use to refer to
 	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
 	  log</command> identifies a changeset using both a number and
 	a hexadecimal string.</para>
       <itemizedlist>
-	<listitem><para>The revision number is <emphasis>only valid in
+	<listitem><para id="x_27">The revision number is <emphasis>only valid in
 	      that repository</emphasis>,</para></listitem>
-	<listitem><para>while the hex string is the
+	<listitem><para id="x_28">while the hex string is the
 	    <emphasis>permanent, unchanging identifier</emphasis> that
 	    will always identify that exact changeset in
 	    <emphasis>every</emphasis> copy of the
 	    repository.</para></listitem></itemizedlist>
-      <para>This distinction is important.  If you send someone an
+      <para id="x_29">This distinction is important.  If you send someone an
 	email talking about <quote>revision 33</quote>, there's a high
 	likelihood that their revision 33 will <emphasis>not be the
 	  same</emphasis> as yours.  The reason for this is that a
 	repositories. Three changes $a,b,c$ can easily appear in one
 	repository as $0,1,2$, while in another as $1,0,2$.</para>
 
-      <para>Mercurial uses revision numbers purely as a convenient
+      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
 	shorthand.  If you need to discuss a changeset with someone,
 	or make a record of a changeset for some other reason (for
 	example, in a bug report), use the hexadecimal
     <sect2>
       <title>Viewing specific revisions</title>
 
-      <para>To narrow the output of <command role="hg-cmd">hg
+      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
 	  log</command> down to a single revision, use the <option
 	  role="hg-opt-log">-r</option> (or <option
 	  role="hg-opt-log">--rev</option>) option.  You can use
 
       &interaction.tour.log-r;
 
-      <para>If you want to see the history of several revisions
+      <para id="x_2c">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 <literal>abc</literal> and
       
 	&interaction.tour.log.range;
 
-      <para>Mercurial also honours the order in which you specify
+      <para id="x_2d">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>
       <title>More detailed information</title>
 
-      <para>While the summary information printed by <command
+      <para id="x_2e">While the summary information printed by <command
 	  role="hg-cmd">hg log</command> is useful if you already know
 	what you're looking for, you may need to see a complete
 	description of the change, or a list of the files changed, if
 
       &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
-	<option role="hg-opt-log">--patch</option>) option.  This
-	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).</para>
+      <para id="x_2f">If you want to see both the description and
+	content of a change, add the <option
+	  role="hg-opt-log">-p</option> (or <option
+	  role="hg-opt-log">--patch</option>) option.  This displays
+	the content of a change as a <emphasis>unified diff</emphasis>
+	(if you've never seen a unified diff before, see <xref
+	  linkend="sec:mq:patch"/> for an overview).</para>
 
       &interaction.tour.log-vp;
 
   <sect1>
     <title>All about command options</title>
 
-    <para>Let's take a brief break from exploring Mercurial commands
+    <para id="x_30">Let's take a brief break from exploring Mercurial commands
       to discuss a pattern in the way that they work; you may find
       this useful to keep in mind as we continue our tour.</para>
 
-    <para>Mercurial has a consistent and straightforward approach to
+    <para id="x_31">Mercurial has a consistent and straightforward approach to
       dealing with the options that you can pass to commands.  It
       follows the conventions for options that are common to modern
       Linux and Unix systems.</para>
     <itemizedlist>
-      <listitem><para>Every option has a long name.  For example, as
+      <listitem><para id="x_32">Every option has a long name.  For example, as
 	  we've already seen, the <command role="hg-cmd">hg
 	    log</command> command accepts a <option
 	    role="hg-opt-log">--rev</option> option.</para></listitem>
-      <listitem><para>Most options have short names, too.  Instead of
+      <listitem><para id="x_33">Most options have short names, too.  Instead of
 	  <option role="hg-opt-log">--rev</option>, we can use <option
 	    role="hg-opt-log">-r</option>.  (The reason that some
 	  options don't have short names is that the options in
 	  question are rarely used.)</para></listitem>
-      <listitem><para>Long options start with two dashes (e.g. <option
+      <listitem><para id="x_34">Long options start with two dashes (e.g. <option
 	    role="hg-opt-log">--rev</option>), while short options
 	  start with one (e.g. <option
 	    role="hg-opt-log">-r</option>).</para></listitem>
-      <listitem><para>Option naming and usage is consistent across
+      <listitem><para id="x_35">Option naming and usage is consistent across
 	  commands.  For example, every command that lets you specify
 	  a changeset ID or revision number accepts both <option
 	    role="hg-opt-log">-r</option> and <option
 	    role="hg-opt-log">--rev</option>
 	  arguments.</para></listitem></itemizedlist>
-    <para>In the examples throughout this book, I use short options
+    <para id="x_36">In the examples throughout this book, I use short options
       instead of long.  This just reflects my own preference, so don't
       read anything significant into it.</para>
 
-    <para>Most commands that print output of some kind will print more
+    <para id="x_37">Most commands that print output of some kind will print more
       output when passed a <option role="hg-opt-global">-v</option>
       (or <option role="hg-opt-global">--verbose</option>) option, and
       less when passed <option role="hg-opt-global">-q</option> (or
   <sect1>
     <title>Making and reviewing changes</title>
 
-    <para>Now that we have a grasp of viewing history in Mercurial,
+    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
       let's take a look at making some changes and examining
       them.</para>
 
-    <para>The first thing we'll do is isolate our experiment in a
+    <para id="x_39">The first thing we'll do is isolate our experiment in a
       repository of its own.  We use the <command role="hg-cmd">hg
 	clone</command> command, but we don't need to clone a copy of
       the remote repository.  Since we already have a copy of it
 
     &interaction.tour.reclone;
 
-    <para>As an aside, it's often good practice to keep a
+    <para id="x_3a">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
       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>
+    <para id="x_3b">In our <filename class="directory">my-hello</filename>
       repository, we have a file <filename>hello.c</filename> that
       contains the classic <quote>hello, world</quote> program. Let's
       use the ancient and venerable <command>sed</command> command to
 
     &interaction.tour.sed;
 
-    <para>Mercurial's <command role="hg-cmd">hg status</command>
+    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
       command will tell us what Mercurial knows about the files in the
       repository.</para>
 
     &interaction.tour.status;
 
-    <para>The <command role="hg-cmd">hg status</command> command
+    <para id="x_3d">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
       for files that have not been modified.</para>
 
-    <para>The <quote><literal>M</literal></quote> indicates that
+    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
       Mercurial has noticed that we modified
       <filename>hello.c</filename>.  We didn't need to
       <emphasis>inform</emphasis> Mercurial that we were going to
       file after we were done; it was able to figure this out
       itself.</para>
 
-    <para>It's a little bit helpful to know that we've modified
+    <para id="x_3f">It's a little bit helpful to know that we've modified
       <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>
   <sect1>
     <title>Recording changes in a new changeset</title>
 
-    <para>We can modify files, build and test our changes, and use
+    <para id="x_40">We can modify files, build and test our changes, and use
       <command role="hg-cmd">hg status</command> and <command
 	role="hg-cmd">hg diff</command> to review our changes, until
       we're satisfied with what we've done and arrive at a natural
       stopping point where we want to record our work in a new
       changeset.</para>
 
-    <para>The <command role="hg-cmd">hg commit</command> command lets
+    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
       us create a new changeset; we'll usually refer to this as
       <quote>making a commit</quote> or
       <quote>committing</quote>.</para>
     <sect2>
       <title>Setting up a username</title>
 
-      <para>When you try to run <command role="hg-cmd">hg
+      <para id="x_42">When you try to run <command role="hg-cmd">hg
 	  commit</command> for the first time, it is not guaranteed to
 	succeed.  Mercurial records your name and address with each
 	change that you commit, so that you and others will later be
 	change with.  It will attempt each of the following methods,
 	in order:</para>
       <orderedlist>
-	<listitem><para>If you specify a <option
+	<listitem><para id="x_43">If you specify a <option
 	      role="hg-opt-commit">-u</option> option to the <command
 	      role="hg-cmd">hg commit</command> command on the command
 	    line, followed by a username, this is always given the
 	    highest precedence.</para></listitem>
-	<listitem><para>If you have set the <envar>HGUSER</envar>
+	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
 	    environment variable, this is checked
 	    next.</para></listitem>
-	<listitem><para>If you create a file in your home directory
-	    called <filename role="special">.hgrc</filename>, with a
-	    <envar role="rc-item-ui">username</envar> entry, that will
-	    be used next.  To see what the contents of this file
-	    should look like, refer to section <xref
-	      linkend="sec.tour-basic.username"/>
+	<listitem><para id="x_45">If you create a file in your home
+	    directory called <filename
+	      role="special">.hgrc</filename>, with a <envar
+	      role="rc-item-ui">username</envar> entry, that will be
+	    used next.  To see what the contents of this file should
+	    look like, refer to <xref
+	      linkend="sec:tour-basic:username"/>
 	    below.</para></listitem>
-	<listitem><para>If you have set the <envar>EMAIL</envar>
+	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
 	    environment variable, this will be used
 	    next.</para></listitem>
-	<listitem><para>Mercurial will query your system to find out
+	<listitem><para id="x_47">Mercurial will query your system to find out
 	    your local user name and host name, and construct a
 	    username from these components. Since this often results
 	    in a username that is not very useful, it will print a
 	    warning if it has to do
 	    this.</para></listitem>
       </orderedlist>
-      <para>If all of these mechanisms fail, Mercurial will
+      <para id="x_48">If all of these mechanisms fail, Mercurial will
 	  fail, printing an error message.  In this case, it will not
 	  let you commit until you set up a
 	  username.</para>
-      <para>You should think of the <envar>HGUSER</envar> environment
+      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
 	variable and the <option role="hg-opt-commit">-u</option>
 	option to the <command role="hg-cmd">hg commit</command>
 	command as ways to <emphasis>override</emphasis> Mercurial's
 	and most robust way to set a username for yourself is by
 	creating a <filename role="special">.hgrc</filename> file; see
 	below for details.</para>
-      <sect3 id="sec.tour-basic.username">
+      <sect3 id="sec:tour-basic:username">
 	<title>Creating a Mercurial configuration file</title>
 
-	<para>To set a user name, use your favourite editor
+	<para id="x_4a">To set a user name, use your favourite editor
 	    to create a file called <filename
 	      role="special">.hgrc</filename> in your home directory.
 	    Mercurial will use this file to look up your personalised
 username = Firstname Lastname
 &lt;email.address@domain.net&gt;</programlisting>
 
-	<para>The <quote><literal>[ui]</literal></quote> line begins a
+	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
 	  <emphasis>section</emphasis> of the config file, so you can
 	  read the <quote><literal>username = ...</literal></quote>
 	  line as meaning <quote>set the value of the
       <sect3>
 	<title>Choosing a user name</title>
 
-	<para>You can use any text you like as the value of
+	<para id="x_4c">You can use any text you like as the value of
 	    the <literal>username</literal> config item, since this
 	    information is for reading by other people, but for
 	    interpreting by Mercurial.  The convention that most
 	    people follow is to use their name and email address, as
 	    in the example above.</para>
 	<note>
-	  <para>Mercurial's built-in web server obfuscates
+	  <para id="x_4d">Mercurial's built-in web server obfuscates
 	      email addresses, to make it more difficult for the email
 	      harvesting tools that spammers use. This reduces the
 	      likelihood that you'll start receiving more junk email
     <sect2>
       <title>Writing a commit message</title>
 
-      <para>When we commit a change, Mercurial drops us into
+      <para id="x_4e">When we commit a change, Mercurial drops us into
 	  a text editor, to enter a message that will describe the
 	  modifications we've made in this changeset.  This is called
 	  the <emphasis>commit message</emphasis>.  It will be a
 
        &interaction.tour.commit;
 
-      <para>The editor that the <command role="hg-cmd">hg
+      <para id="x_4f">The editor that the <command role="hg-cmd">hg
 	    commit</command> command drops us into will contain an
 	  empty line, followed by a number of lines starting with
 	  <quote><literal>HG:</literal></quote>.</para>
 
     <programlisting>XXX fix this XXX</programlisting>
 
-      <para>Mercurial ignores the lines that start with
+      <para id="x_50">Mercurial ignores the lines that start with
 	  <quote><literal>HG:</literal></quote>; it uses them only to
 	  tell us which files it's recording changes to.  Modifying or
 	  deleting these lines has no effect.</para>
     <sect2>
       <title>Writing a good commit message</title>
 
-      <para>Since <command role="hg-cmd">hg log</command>
+      <para id="x_51">Since <command role="hg-cmd">hg log</command>
 	  only prints the first line of a commit message by default,
 	  it's best to write a commit message whose first line stands
 	  alone.  Here's a real example of a commit message that
 date:        Tue Sep 26 21:37:07 2006 -0700
 summary:     include buildmeister/commondefs. Add exports.</programlisting>
 
-      <para>As far as the remainder of the contents of the
+      <para id="x_52">As far as the remainder of the contents of the
 	  commit message are concerned, there are no hard-and-fast
 	  rules.  Mercurial itself doesn't interpret or care about the
 	  contents of the commit message, though your project may have
 	  policies that dictate a certain kind of
 	  formatting.</para>
-      <para>My personal preference is for short, but
+      <para id="x_53">My personal preference is for short, but
 	  informative, commit messages that tell me something that I
 	  can't figure out with a quick glance at the output of
 	  <command role="hg-cmd">hg log
     <sect2>
       <title>Aborting a commit</title>
 
-      <para>If you decide that you don't want to commit
+      <para id="x_54">If you decide that you don't want to commit
 	  while in the middle of editing a commit message, simply exit
 	  from your editor without saving the file that it's editing.
 	  This will cause nothing to happen to either the repository
 	  or the working directory.</para>
-      <para>If we run the <command role="hg-cmd">hg
+      <para id="x_55">If we run the <command role="hg-cmd">hg
 	    commit</command> command without any arguments, it records
 	  all of the changes we've made, as reported by <command
 	    role="hg-cmd">hg status</command> and <command
     <sect2>
       <title>Admiring our new handiwork</title>
 
-      <para>Once we've finished the commit, we can use the
+      <para id="x_56">Once we've finished the commit, we can use the
 	  <command role="hg-cmd">hg tip</command> command to display
 	  the changeset we just created.  This command produces output
 	  that is identical to <command role="hg-cmd">hg
 
       &interaction.tour.tip;
 
-      <para>We refer to
+      <para id="x_57">We refer to
 	  the newest revision in the repository as the tip revision,
 	  or simply the tip.</para>
     </sect2>
   <sect1>
     <title>Sharing changes</title>
 
-    <para>We mentioned earlier that repositories in
+    <para id="x_58">We mentioned earlier that repositories in
 	Mercurial are self-contained.  This means that the changeset
 	we just created exists only in our <filename
 	  class="directory">my-hello</filename> repository.  Let's
 	look at a few ways that we can propagate this change into
 	other repositories.</para>
 
-    <sect2 id="sec.tour.pull">
+    <sect2 id="sec:tour:pull">
       <title>Pulling changes from another repository</title>
-      <para>To get started, let's clone our original
+      <para id="x_59">To get started, let's clone our original
 	  <filename class="directory">hello</filename> repository,
 	  which does not contain the change we just committed.  We'll
 	  call our temporary repository <filename
 
       &interaction.tour.clone-pull;
 
-      <para>We'll use the <command role="hg-cmd">hg
+      <para id="x_5a">We'll use the <command role="hg-cmd">hg
 	    pull</command> command to bring changes from <filename
 	    class="directory">my-hello</filename> into <filename
 	    class="directory">hello-pull</filename>.  However, blindly
 
       &interaction.tour.incoming;
 
-      <para>(Of course, someone could
+      <para id="x_5b">(Of course, someone could
 	  cause more changesets to appear in the repository that we
 	  ran <command role="hg-cmd">hg incoming</command> in, before
 	  we get a chance to <command role="hg-cmd">hg pull</command>
 	  the changes, so that we could end up pulling changes that we
 	  didn't expect.)</para>
 
-      <para>Bringing changes into a repository is a simple
+      <para id="x_5c">Bringing changes into a repository is a simple
 	  matter of running the <command role="hg-cmd">hg
 	    pull</command> command, and telling it which repository to
 	  pull from.</para>
 
       &interaction.tour.pull;
 
-      <para>As you can see
+      <para id="x_5d">As you can see
 	  from the before-and-after output of <command
 	    role="hg-cmd">hg tip</command>, we have successfully
 	  pulled changes into our repository.  There remains one step
     <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
+      <para id="x_5e">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
+	<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
+      <para id="x_5f">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
 	  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
+      <para id="x_60">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
-	    linkend="sec.tour.pull"/> when we ran it without <option
+      <para id="x_61">If you look back at the output of <command
+	  role="hg-cmd">hg pull</command> in <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>
 
       <!-- &interaction.xxx.fixme; -->
 
-      <para>To find out what revision the working directory is at, use
+      <para id="x_62">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
-	   endterm="fig.tour-basic.history.caption" 
-	   linkend="fig.tour-basic.history"/>,
+      <para id="x_63">If you look back at <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
 	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,
+      <para id="x_64">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
+      <para id="x_65">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
     <sect2>
       <title>Pushing changes to another repository</title>
 
-      <para>Mercurial lets us push changes to another
+      <para id="x_66">Mercurial lets us push changes to another
 	  repository, from the repository we're currently visiting.
 	  As with the example of <command role="hg-cmd">hg
 	    pull</command> above, we'll create a temporary repository
 
       &interaction.tour.clone-push;
 
-      <para>The <command role="hg-cmd">hg outgoing</command> command
+      <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command
 	  tells us what changes would be pushed into another
 	  repository.</para>
 
       &interaction.tour.outgoing;
 
-      <para>And the
+      <para id="x_68">And the
 	  <command role="hg-cmd">hg push</command> command does the
 	  actual push.</para>
 
       &interaction.tour.push;
 
-      <para>As with
+      <para id="x_69">As with
 	  <command role="hg-cmd">hg pull</command>, the <command
 	    role="hg-cmd">hg push</command> command does not update
 	  the working directory in the repository that it's pushing
 	  does not provide a <literal>-u</literal> option that updates
 	  the other repository's working directory.)</para>
 
-      <para>What happens if we try to pull or push changes
+      <para id="x_6a">What happens if we try to pull or push changes
 	  and the receiving repository already has those changes?
 	  Nothing too exciting.</para>
 
     <sect2>
       <title>Sharing changes over a network</title>
 
-      <para>The commands we have covered in the previous few
+      <para id="x_6b">The commands we have covered in the previous few
 	  sections are not limited to working with local repositories.
 	  Each works in exactly the same fashion over a network
 	  connection; simply pass in a URL instead of a local
 	
       &interaction.tour.outgoing.net;
 
-      <para>In this example, we
+      <para id="x_6c">In this example, we
 	  can see what changes we could push to the remote repository,
 	  but the repository is understandably not set up to let
 	  anonymous users push to it.</para>

en/ch02-tour-merge.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<chapter id="chap.tour-merge">
+<chapter id="chap:tour-merge">
   <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
   <title>A tour of Mercurial: merging work</title>
 
-  <para>We've now covered cloning a repository, making changes in a
+  <para id="x_338">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
+    <para id="x_339">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
+      <listitem><para id="x_33a">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
+      <listitem><para id="x_33b">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,
+    <para id="x_33c">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
+    <para id="x_33d">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 endterm="fig.tour-merge.sep-repos.caption"
-	linkend="fig.tour-merge.sep-repos"/>.</para>
+      illustrated in <xref
+	linkend="fig:tour-merge:sep-repos"/>.</para>
 
     &interaction.tour.merge.cat;
 
-    <informalfigure id="fig.tour-merge.sep-repos">
+    <figure id="fig:tour-merge:sep-repos">
+      <title>Divergent recent histories of the <filename
+	  class="directory">my-hello</filename> and <filename
+	  class="directory">my-new-hello</filename>
+	repositories</title>
       <mediaobject>
-	<imageobject><imagedata fileref="images/tour-merge-sep-repos.png"/></imageobject>
+	<imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
 	<textobject><phrase>XXX add text</phrase></textobject>
-	<caption><para id="fig.tour-merge.sep-repos.caption">Divergent recent
-	  histories of the <filename
-	      class="directory">my-hello</filename> and <filename
-	      class="directory">my-new-hello</filename>
-	    repositories</para></caption>
       </mediaobject>
-    </informalfigure>
+    </figure>
 
-    <para>We already know that pulling changes from our <filename
+    <para id="x_33f">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>
+    <para id="x_340">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,
+      <para id="x_341">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">
+      <figure id="fig:tour-merge:pull">
+	<title>Repository contents after pulling from <filename
+	    class="directory">my-hello</filename> into <filename
+	    class="directory">my-new-hello</filename></title>
 	<mediaobject>
-	  <imageobject><imagedata fileref="images/tour-merge-pull.png"/></imageobject>
+	  <imageobject>
+	    <imagedata fileref="figs/tour-merge-pull.png"/>
+	  </imageobject>
 	  <textobject><phrase>XXX add text</phrase></textobject>
-	  <caption><para id="fig.tour-merge.pull.caption">Repository contents after
-	    pulling from <filename class="directory">my-hello</filename> into
-	    <filename class="directory">my-new-hello</filename></para></caption>
 	</mediaobject>
-      </informalfigure>
+      </figure>
 
-      <para>In figure <xref endterm="fig.tour-merge.pull.caption"
-        linkend="fig.tour-merge.pull"/>, you can
+      <para id="x_343">In <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
-	  endterm="fig.tour-merge.sep-repos.caption" 
-	  linkend="fig.tour-merge.sep-repos"/>, we can see that the
+	a new revision has been added.  By referring to <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
     <sect2>
       <title>Performing the merge</title>
 
-      <para>What happens if we try to use the normal <command
+      <para id="x_344">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
+      <para id="x_345">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
 
       &interaction.tour.merge.merge;
 
-      <informalfigure id="fig.tour-merge.merge">
+      <figure id="fig:tour-merge:merge">
+	<title>Working directory and repository during merge, and
+	  following commit</title>
 	<mediaobject>
-	  <imageobject><imagedata fileref="images/tour-merge-merge.png"/></imageobject>
+	  <imageobject>
+	    <imagedata fileref="figs/tour-merge-merge.png"/>
+	  </imageobject>
 	  <textobject><phrase>XXX add text</phrase></textobject>
-	  <caption><para id="fig.tour-merge.merge.caption">Working directory and
-	      repository during merge, and following commit</para></caption>
 	</mediaobject>
-      </informalfigure>
+      </figure>
 
-      <para>This updates the working directory so that it contains
+      <para id="x_347">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
     <sect2>
       <title>Committing the results of the merge</title>
 
-      <para>Whenever we've done a merge, <command role="hg-cmd">hg
+      <para id="x_348">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
+      <para id="x_349">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 endterm="fig.tour-merge.merge.caption"
-	  linkend="fig.tour-merge.merge"/>, you can see a
+      <para id="x_34a">In <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
   <sect1>
     <title>Merging conflicting changes</title>
 
-    <para>Most merges are simple affairs, but sometimes you'll find
+    <para id="x_34b">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 id="fig.tour-merge.conflict">
+    <figure id="fig:tour-merge:conflict">
+      <title>Conflicting changes to a document</title>
       <mediaobject>
-        <imageobject><imagedata fileref="images/tour-merge-conflict.png"/>
-        </imageobject>
-        <textobject><phrase>XXX add text</phrase></textobject>
-        <caption><para id="fig.tour-merge.conflict.caption">Conflicting
-          changes to a document</para></caption>
+	<imageobject><imagedata fileref="figs/tour-merge-conflict.png"/></imageobject>
+	<textobject><phrase>XXX add text</phrase></textobject>
       </mediaobject>
-    </informalfigure>
+    </figure>
 
-    <para>Figure <xref endterm="fig.tour-merge.conflict.caption"
-      linkend="fig.tour-merge.conflict"/> illustrates
+    <para id="x_34d"><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
+    <para id="x_34e">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
       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
+    <para id="x_34f">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
+      <para id="x_350">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 endterm="fig.tour-merge.kdiff3.caption"
-	linkend="fig.tour-merge.kdiff3"/>.  The kind of
+	<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>
+	<listitem><para id="x_351">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
+	<listitem><para id="x_352">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
+	<listitem><para id="x_353">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
+      <para id="x_354">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
+      <para id="x_355">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 width="100%" fileref="images/kdiff3.png"/>
-          </imageobject>
-          <textobject><phrase>XXX add text</phrase></textobject>
-          <caption><para id="fig.tour-merge.kdiff3.caption">Using
-            <command>kdiff3</command> to merge versions of a file</para>
-          </caption>
-        </mediaobject>
-      </informalfigure>
+      <figure id="fig:tour-merge:kdiff3">
+	<title>Using <command>kdiff3</command> to merge versions of a
+	  file</title>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
+	  <textobject>
+	    <phrase>XXX add text</phrase>
+	  </textobject>
+	</mediaobject>
+      </figure>
 
-      <para>For each conflicting portion of the file, we can choose to
+      <para id="x_357">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
+      <para id="x_358">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
     <sect2>
       <title>A worked example</title>
 
-      <para>In this example, we will reproduce the file modification
-	history of figure <xref endterm="fig.tour-merge.conflict.caption"
-	linkend="fig.tour-merge.conflict"/>
+      <para id="x_359">In this example, we will reproduce the file modification
+	history of <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
+      <para id="x_35a">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
+      <para id="x_35b">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
 
       &interaction.tour-merge-conflict.son;
 
-      <para>Having created two
+      <para id="x_35c">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
+      <para id="x_35d">In this example, I won't use Mercurial's normal
 	<command>hgmerge</command> program to do the merge, because it