1.1 --- a/.hgignore	Fri Mar 20 17:17:55 2009 +0800
     1.2 +++ b/.hgignore	Mon Mar 30 16:23:33 2009 +0800
     1.3 @@ -1,7 +1,4 @@
     1.4 -[^/]+/build/
     1.5 -[^/]+/fop/
     1.6 -[^/]+/hello/
     1.7 -[^/]+/html/
     1.8 +[^/]+/htdocs/
     1.9  
    1.10  syntax: glob
    1.11  
    1.12 @@ -13,13 +10,17 @@
    1.13  *.pyc
    1.14  *.rej
    1.15  *.run
    1.16 -*-tmp.svg
    1.17  *~
    1.18 -.*.swp
    1.19 +.*.sw[op]
    1.20  .\#*
    1.21  .run
    1.22  .validated-00book.xml
    1.23  en/all-ids.dat
    1.24  web/hgbook/.database.sqlite3
    1.25  web/hgbook/secrets.py
    1.26 +web/index-read.html.in
    1.27  stylesheets/system-xsl
    1.28 +build
    1.29 +en/html
    1.30 +en/examples/results
    1.31 +tools
    1.32 \ No newline at end of file

     2.1 --- a/Makefile	Fri Mar 20 17:17:55 2009 +0800
     2.2 +++ b/Makefile	Mon Mar 30 16:23:33 2009 +0800
     2.3 @@ -20,26 +20,26 @@
     2.4  rev_id = $(shell hg parents --template '{node|short} ({date|shortdate})')
     2.5  
     2.6  images := \
     2.7 -	en/images/feature-branches.png \
     2.8 -	en/images/filelog.png \
     2.9 -	en/images/metadata.png \
    2.10 -	en/images/mq-stack.png \
    2.11 -	en/images/revlog.png \
    2.12 -	en/images/snapshot.png \
    2.13 -	en/images/tour-history.png \
    2.14 -	en/images/tour-merge-conflict.png \
    2.15 -	en/images/tour-merge-merge.png \
    2.16 -	en/images/tour-merge-pull.png \
    2.17 -	en/images/tour-merge-sep-repos.png \
    2.18 -	en/images/undo-manual-merge.png \
    2.19 -	en/images/undo-manual.png \
    2.20 -	en/images/undo-non-tip.png \
    2.21 -	en/images/undo-simple.png \
    2.22 -	en/images/wdir-after-commit.png \
    2.23 -	en/images/wdir-branch.png \
    2.24 -	en/images/wdir-merge.png \
    2.25 -	en/images/wdir.png \
    2.26 -	en/images/wdir-pre-branch.png
    2.27 +	en/figs/feature-branches.png \
    2.28 +	en/figs/filelog.png \
    2.29 +	en/figs/metadata.png \
    2.30 +	en/figs/mq-stack.png \
    2.31 +	en/figs/revlog.png \
    2.32 +	en/figs/snapshot.png \
    2.33 +	en/figs/tour-history.png \
    2.34 +	en/figs/tour-merge-conflict.png \
    2.35 +	en/figs/tour-merge-merge.png \
    2.36 +	en/figs/tour-merge-pull.png \
    2.37 +	en/figs/tour-merge-sep-repos.png \
    2.38 +	en/figs/undo-manual-merge.png \
    2.39 +	en/figs/undo-manual.png \
    2.40 +	en/figs/undo-non-tip.png \
    2.41 +	en/figs/undo-simple.png \
    2.42 +	en/figs/wdir-after-commit.png \
    2.43 +	en/figs/wdir-branch.png \
    2.44 +	en/figs/wdir-merge.png \
    2.45 +	en/figs/wdir.png \
    2.46 +	en/figs/wdir-pre-branch.png
    2.47  
    2.48  help:
    2.49  	@echo "  make html         [LINGUA=en|zh|...]"
    2.50 @@ -53,30 +53,30 @@
    2.51  	@echo "  make clean        # Remove the build files."
    2.52  
    2.53  clean:
    2.54 -	@rm -fr build po/*.mo hello en/hello en/html en/.validated-00book.xml \
    2.55 -          stylesheets/system-xsl en/images/*-tmp.svg \
    2.56 -          en/images/feature-branches.png \
    2.57 -          en/images/filelog.png \
    2.58 -          en/images/feature-branches.png \
    2.59 -          en/images/filelog.png \
    2.60 -          en/images/metadata.png \
    2.61 -          en/images/mq-stack.png \
    2.62 -          en/images/revlog.png \
    2.63 -          en/images/snapshot.png \
    2.64 -          en/images/tour-history.png \
    2.65 -          en/images/tour-merge-conflict.png \
    2.66 -          en/images/tour-merge-merge.png \
    2.67 -          en/images/tour-merge-pull.png \
    2.68 -          en/images/tour-merge-sep-repos.png \
    2.69 -          en/images/undo-manual-merge.png \
    2.70 -          en/images/undo-manual.png \
    2.71 -          en/images/undo-non-tip.png \
    2.72 -          en/images/undo-simple.png \
    2.73 -          en/images/wdir-after-commit.png \
    2.74 -          en/images/wdir-branch.png \
    2.75 -          en/images/wdir-merge.png \
    2.76 -          en/images/wdir-pre-branch.png \
    2.77 -          en/images/wdir.png
    2.78 +	@rm -fr build po/*.mo hello en/hello en/html en/.validated-00book.xml en/examples/.run en/examples/results \
    2.79 +          stylesheets/system-xsl en/figs/*-tmp.svg \
    2.80 +          en/figs/feature-branches.png \
    2.81 +          en/figs/filelog.png \
    2.82 +          en/figs/feature-branches.png \
    2.83 +          en/figs/filelog.png \
    2.84 +          en/figs/metadata.png \
    2.85 +          en/figs/mq-stack.png \
    2.86 +          en/figs/revlog.png \
    2.87 +          en/figs/snapshot.png \
    2.88 +          en/figs/tour-history.png \
    2.89 +          en/figs/tour-merge-conflict.png \
    2.90 +          en/figs/tour-merge-merge.png \
    2.91 +          en/figs/tour-merge-pull.png \
    2.92 +          en/figs/tour-merge-sep-repos.png \
    2.93 +          en/figs/undo-manual-merge.png \
    2.94 +          en/figs/undo-manual.png \
    2.95 +          en/figs/undo-non-tip.png \
    2.96 +          en/figs/undo-simple.png \
    2.97 +          en/figs/wdir-after-commit.png \
    2.98 +          en/figs/wdir-branch.png \
    2.99 +          en/figs/wdir-merge.png \
   2.100 +          en/figs/wdir-pre-branch.png \
   2.101 +          en/figs/wdir.png
   2.102  
   2.103  all:
   2.104  ifdef LINGUA
   2.105 @@ -133,23 +133,24 @@
   2.106  	xmllint --nonet --noout --postvalid --xinclude $<
   2.107  
   2.108  ifneq "$(findstring $(LINGUA),$(DBK_LANGUAGES))" ""
   2.109 -build/$(LINGUA)/source/hgbook.xml: $(wildcard $(LINGUA)/*.xml) $(images)
   2.110 -	mkdir -p build/$(LINGUA)/source
   2.111 -	cp -r $(LINGUA)/* build/$(LINGUA)/source
   2.112 -	xmllint --nonet --noent --xinclude --postvalid --output $@.tmp $(LINGUA)/00book.xml
   2.113 +$(LINGUA)/examples/.run:
   2.114 +	(cd $(LINGUA)/examples; ./run-example -v -a)
   2.115 +
   2.116 +build/$(LINGUA)/source/hgbook.xml: $(wildcard $(LINGUA)/*.xml) $(images) $(LINGUA)/examples/.run $(images)
   2.117 +	mkdir -p build/$(LINGUA)/source/figs
   2.118 +	cp $(LINGUA)/figs/*.png build/$(LINGUA)/source/figs
   2.119 +	(cd $(LINGUA); xmllint --nonet --noent --xinclude --postvalid --output ../$@.tmp 00book.xml)
   2.120  	cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@
   2.121  else
   2.122 -build/$(LINGUA)/source/hgbook.xml: $(wildcard en/*.xml) po/$(LINGUA).po $(images)
   2.123 -	mkdir -p build/$(LINGUA)/source
   2.124 -	cp -r en/images build/$(LINGUA)/source
   2.125 -	cp -r en/examples build/$(LINGUA)/source
   2.126 -	cp en/book-shortcuts.xml build/$(LINGUA)/source
   2.127 -	for f in en/*.xml; do \
   2.128 -	  if [ $$f != "en/book-shortcuts.xml" ]; then \
   2.129 -	    $(TRANSLATE) -m $$f -p po/$(LINGUA).po -l build/$(LINGUA)/source/`basename $$f`; \
   2.130 -	  fi \
   2.131 -	done
   2.132 -	xmllint --nonet --noent --xinclude --postvalid --output $@.tmp build/$(LINGUA)/source/00book.xml
   2.133 +en/examples/.run:
   2.134 +	(cd en/examples; ./run-example -v -a)
   2.135 +
   2.136 +build/en/source/hgbook.xml:
   2.137 +	${MAKE} LINGUA=en $@
   2.138 +
   2.139 +build/$(LINGUA)/source/hgbook.xml: build/en/source/hgbook.xml po/$(LINGUA).po $(images)
   2.140 +	mkdir -p build/$(LINGUA)/source/figs
   2.141 +	$(TRANSLATE) -m build/en/source/hgbook.xml -p po/$(LINGUA).po -l $@.tmp
   2.142  	cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@
   2.143  endif
   2.144  
   2.145 @@ -164,8 +165,8 @@
   2.146  html: build/$(LINGUA)/html/index.html
   2.147  
   2.148  build/$(LINGUA)/html/index.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html.xsl stylesheets/$(LINGUA)/html.xsl
   2.149 -	mkdir -p build/$(LINGUA)/html/images
   2.150 -	cp en/images/*.png build/$(LINGUA)/html/images
   2.151 +	mkdir -p build/$(LINGUA)/html/figs
   2.152 +	cp en/figs/*.png build/$(LINGUA)/html/figs
   2.153  	cp stylesheets/hgbook.css build/$(LINGUA)/html
   2.154  	xsltproc --output build/$(LINGUA)/html/ \
   2.155  	    stylesheets/$(LINGUA)/html.xsl build/$(LINGUA)/source/hgbook.xml
   2.156 @@ -180,8 +181,8 @@
   2.157  html-single: build/$(LINGUA)/html-single/hgbook.html
   2.158  
   2.159  build/$(LINGUA)/html-single/hgbook.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html-single.xsl stylesheets/$(LINGUA)/html-single.xsl
   2.160 -	mkdir -p build/$(LINGUA)/html-single/images
   2.161 -	cp en/images/*.png build/$(LINGUA)/html-single/images
   2.162 +	mkdir -p build/$(LINGUA)/html-single/figs
   2.163 +	cp en/figs/*.png build/$(LINGUA)/html-single/figs
   2.164  	cp stylesheets/hgbook.css build/$(LINGUA)/html-single
   2.165  	xsltproc --output build/$(LINGUA)/html-single/hgbook.html \
   2.166  	    stylesheets/$(LINGUA)/html-single.xsl build/$(LINGUA)/source/hgbook.xml
   2.167 @@ -210,9 +211,9 @@
   2.168  	(cd build/$(LINGUA)/source && ../../../tools/fop/fop.sh hgbook.fo ../pdf/hgbook.pdf)
   2.169  endif
   2.170  
   2.171 -en/images/%.png: en/images/%.svg en/fixsvg
   2.172 +en/figs/%.png: en/figs/%.svg en/fixsvg
   2.173  	en/fixsvg $<
   2.174  	inkscape -D -d 120 -e $@ $<-tmp.svg
   2.175  
   2.176 -en/images/%.svg: en/images/%.dot
   2.177 +en/figs/%.svg: en/figs/%.dot
   2.178  	dot -Tsvg -o $@ $<

     3.1 --- a/en/00book.xml	Fri Mar 20 17:17:55 2009 +0800
     3.2 +++ b/en/00book.xml	Mon Mar 30 16:23:33 2009 +0800
     3.3 @@ -1,7 +1,7 @@
     3.4  <?xml version="1.0" encoding="UTF-8"?>
     3.5  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     3.6 -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
     3.7 - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
     3.8 +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
     3.9 + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
    3.10  [
    3.11  <!-- Below are references to files in this directory. -->
    3.12  

     4.1 --- a/en/Makefile	Fri Mar 20 17:17:55 2009 +0800
     4.2 +++ b/en/Makefile	Mon Mar 30 16:23:33 2009 +0800
     4.3 @@ -1,28 +1,6 @@
     4.4  # This makefile requires GNU make.
     4.5  
     4.6 -image-sources := \
     4.7 -	feature-branches.dot \
     4.8 -	filelog.svg \
     4.9 -	kdiff3.png \
    4.10 -	metadata.svg \
    4.11 -	mq-stack.svg \
    4.12 -	note.png \
    4.13 -	revlog.svg \
    4.14 -	snapshot.svg \
    4.15 -	tour-history.svg \
    4.16 -	tour-merge-conflict.svg \
    4.17 -	tour-merge-merge.svg \
    4.18 -	tour-merge-pull.svg \
    4.19 -	tour-merge-sep-repos.svg \
    4.20 -	undo-manual.dot \
    4.21 -	undo-manual-merge.dot \
    4.22 -	undo-non-tip.dot \
    4.23 -	undo-simple.dot \
    4.24 -	wdir.svg \
    4.25 -	wdir-after-commit.svg \
    4.26 -	wdir-branch.svg \
    4.27 -	wdir-merge.svg \
    4.28 -	wdir-pre-branch.svg
    4.29 +image-sources := $(wildcard figs/*.dot figs/*.gif figs/*.png figs/*.svg)
    4.30  
    4.31  xml-src-files := \
    4.32  	00book.xml \
    4.33 @@ -31,9 +9,16 @@
    4.34  
    4.35  image-dot := $(filter %.dot,$(image-sources))
    4.36  image-svg := $(filter %.svg,$(image-sources))
    4.37 -image-png := $(filter %.png,$(image-sources))
    4.38 -
    4.39 -image-html := $(image-dot:%.dot=%.png) $(image-svg:%.svg=%.png) $(image-png)
    4.40 +image-oth := $(filter %.gif %.png,$(image-sources))
    4.41 +
    4.42 +obj-web := html
    4.43 +obj-websup := $(obj-web)/support
    4.44 +obj-web-read := $(obj-web)/read
    4.45 +
    4.46 +image-web := \
    4.47 +	$(image-dot:%.dot=$(obj-web-read)/%.png) \
    4.48 +	$(image-svg:%.svg=$(obj-web-read)/%.png) \
    4.49 +	$(image-oth:%=$(obj-web-read)/%)
    4.50  
    4.51  example-sources-by-name := \
    4.52  	backout \
    4.53 @@ -71,9 +56,6 @@
    4.54  	$(example-sources-by-name:%=examples/%) \
    4.55  	$(wildcard examples/ch*/*)
    4.56  
    4.57 -obj-web := html
    4.58 -obj-websup := html/support
    4.59 -
    4.60  extras-web-base := \
    4.61  	$(obj-web)/index.html \
    4.62  	$(obj-web)/robots.txt \
    4.63 @@ -130,24 +112,30 @@
    4.64  
    4.65  all: web
    4.66  
    4.67 -../xsl/system-xsl: $(system-xsl-dir)
    4.68 +../stylesheets/system-xsl: $(system-xsl-dir)
    4.69  	ln -s $< $@
    4.70  
    4.71 -web: ../xsl/system-xsl websup html
    4.72 -
    4.73 -html: ../xsl/system-xsl $(xml-src-files) valid
    4.74 -	xsltproc $(xsltproc-opts) -o html/read/x ../xsl/chunk-stylesheet.xsl 00book.xml
    4.75 -	for i in html/read/*.html; do \
    4.76 +web: ../stylesheets/system-xsl websup html
    4.77 +
    4.78 +html: $(obj-web-read)/index.html
    4.79 +
    4.80 +../web/index-read.html.in: ../web/genindex.py $(xml-src-files)
    4.81 +	$<
    4.82 +
    4.83 +$(obj-web-read)/index.html: ../stylesheets/system-xsl .validated-00book.xml ../web/index-read.html.in
    4.84 +	xsltproc $(xsltproc-opts) -o $(obj-web-read)/x ../stylesheets/chunk-stylesheet.xsl 00book.xml
    4.85 +	python ../web/texpand.py ../web/index-read.html.in html/read/index.html
    4.86 +	for i in $(obj-web-read)/*.html; do \
    4.87  	  gzip -9 -c $$i > $$i.gz; \
    4.88  	done
    4.89  
    4.90 -websup: $(extras-web)
    4.91 -	mkdir -p $(obj-websup)/figs
    4.92 -	cp ../xsl/system-xsl/images/*.png $(obj-websup)/figs
    4.93 +websup: $(extras-web) $(image-web)
    4.94 +	mkdir -p $(obj-websup)/figs $(obj-web-read)/figs
    4.95 +	cp ../stylesheets/system-xsl/images/*.png $(obj-websup)/figs
    4.96  	cp -f ../web/icons/*.png $(obj-websup)/figs
    4.97  
    4.98 -all-ids.dat: ../xsl/all-ids.xsl $(xml-src-files)
    4.99 -	$(xsltproc) $(xsltproc-opts) -o $@ ../xsl/all-ids.xsl 00book.xml
   4.100 +all-ids.dat: ../stylesheets/all-ids.xsl $(xml-src-files)
   4.101 +	$(xsltproc) $(xsltproc-opts) -o $@ ../stylesheets/all-ids.xsl 00book.xml
   4.102  
   4.103  web: websup
   4.104  
   4.105 @@ -159,12 +147,26 @@
   4.106  
   4.107  # Produce 90dpi PNGs for the web.
   4.108  
   4.109 -%.png: %.svg fixsvg
   4.110 +$(obj-web-read)/figs/%.png: $(obj-web-read)/figs/%.svg fixsvg
   4.111 +	mkdir -p $(dir $@)
   4.112  	./fixsvg $<
   4.113  	inkscape -D -e $@ $<-tmp.svg
   4.114  	rm $<-tmp.svg
   4.115  
   4.116 -%.svg: %.dot
   4.117 +$(obj-web-read)/figs/%.png: figs/%.svg fixsvg
   4.118 +	mkdir -p $(dir $@)
   4.119 +	./fixsvg $<
   4.120 +	inkscape -D -e $@ $<-tmp.svg
   4.121 +	rm $<-tmp.svg
   4.122 +
   4.123 +$(obj-web-read)/figs/%.gif: figs/%.gif
   4.124 +	cp $< $@
   4.125 +
   4.126 +$(obj-web-read)/figs/%.png: figs/%.png
   4.127 +	cp $< $@
   4.128 +
   4.129 +$(obj-web-read)/figs/%.svg: figs/%.dot
   4.130 +	mkdir -p $(dir $@)
   4.131  	dot -Tsvg -o $@ $<
   4.132  
   4.133  examples: $(example-prereqs) examples/.run
   4.134 @@ -188,6 +190,7 @@
   4.135  	rsync -avz --delete dist sp.red-bean.com:public_html/hgbook
   4.136  
   4.137  vpath %.css ../web
   4.138 +vpath %.html.in ../web
   4.139  vpath %.js ../web/javascript
   4.140  
   4.141  $(obj-websup)/%.css: %.css

     5.1 --- a/en/appA-cmdref.xml	Fri Mar 20 17:17:55 2009 +0800
     5.2 +++ b/en/appA-cmdref.xml	Mon Mar 30 16:23:33 2009 +0800
     5.3 @@ -1,6 +1,7 @@
     5.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     5.5  
     5.6  <appendix id="cmdref">
     5.7 +  <?dbhtml filename="command-reference.html"?>
     5.8  <title>Command reference</title>
     5.9  
    5.10  <para id="x_653">\cmdref{add}{add files at the next commit}
    5.11 @@ -12,7 +13,7 @@
    5.12  
    5.13  <para id="x_655">Show differences between revisions for the specified files or
    5.14  directories, using the unified diff format.  For a description of the
    5.15 -unified diff format, see section <xref linkend="sec.mq.patch"/>.</para>
    5.16 +unified diff format, see <xref linkend="sec:mq:patch"/>.</para>
    5.17  
    5.18  <para id="x_656">By default, this command does not print diffs for files that Mercurial
    5.19  considers to contain binary data.  To control this behaviour, see the
    5.20 @@ -20,7 +21,7 @@
    5.21  
    5.22  <sect2>
    5.23  <title>Options</title>
    5.24 -
    5.25 +x
    5.26  <para id="x_657">\loptref{diff}{nodates}</para>
    5.27  
    5.28  <para id="x_658">Omit date and time information when printing diff headers.</para>
    5.29 @@ -158,7 +159,7 @@
    5.30  <sect2>
    5.31  <title>Tips and tricks</title>
    5.32  
    5.33 -<sect3 id="cmdref.diff-vs-status">
    5.34 +<sect3 id="cmdref:diff-vs-status">
    5.35  <title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
    5.36  
    5.37  <para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files

     6.1 --- a/en/appB-mq-ref.xml	Fri Mar 20 17:17:55 2009 +0800
     6.2 +++ b/en/appB-mq-ref.xml	Mon Mar 30 16:23:33 2009 +0800
     6.3 @@ -1,10 +1,10 @@
     6.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     6.5  
     6.6 -<appendix id="chap.mqref">
     6.7 +<appendix id="chap:mqref">
     6.8    <?dbhtml filename="mercurial-queues-reference.html"?>
     6.9    <title>Mercurial Queues reference</title>
    6.10  
    6.11 -  <sect1 id="sec.mqref.cmdref">
    6.12 +  <sect1 id="sec:mqref:cmdref">
    6.13      <title>MQ command reference</title>
    6.14  
    6.15      <para id="x_5e8">For an overview of the commands provided by MQ, use the
    6.16 @@ -296,7 +296,7 @@
    6.17  	  role="hg-ext-mq">qpop</command>.</para>
    6.18  
    6.19      </sect2>
    6.20 -    <sect2 id="sec.mqref.cmd.qpush">
    6.21 +    <sect2 id="sec:mqref:cmd:qpush">
    6.22        <title><command role="hg-ext-mq">qpush</command>&emdash;push
    6.23  	patches onto the stack</title>
    6.24  

     7.1 --- a/en/appC-srcinstall.xml	Fri Mar 20 17:17:55 2009 +0800
     7.2 +++ b/en/appC-srcinstall.xml	Mon Mar 30 16:23:33 2009 +0800
     7.3 @@ -1,10 +1,10 @@
     7.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     7.5  
     7.6 -<appendix id="chap.srcinstall">
     7.7 +<appendix id="chap:srcinstall">
     7.8    <?dbhtml filename="installing-mercurial-from-source.html"?>
     7.9    <title>Installing Mercurial from source</title>
    7.10  
    7.11 -  <sect1 id="sec.srcinstall.unixlike">
    7.12 +  <sect1 id="sec:srcinstall:unixlike">
    7.13      <title>On a Unix-like system</title>
    7.14  
    7.15      <para id="x_5e0">If you are using a Unix-like system that has a sufficiently

     8.1 --- a/en/appD-license.xml	Fri Mar 20 17:17:55 2009 +0800
     8.2 +++ b/en/appD-license.xml	Mon Mar 30 16:23:33 2009 +0800
     8.3 @@ -1,6 +1,6 @@
     8.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     8.5  
     8.6 -<appendix id="cha.opl">
     8.7 +<appendix id="cha:opl">
     8.8    <?dbhtml filename="open-publication-license.html"?>
     8.9    <title>Open Publication License</title>
    8.10  
    8.11 @@ -32,7 +32,7 @@
    8.12  
    8.13      <para id="x_63c">The reference must be immediately followed with any options
    8.14        elected by the author(s) and/or publisher of the document (see
    8.15 -      section <xref linkend="sec.opl.options"/>).</para>
    8.16 +      <xref linkend="sec:opl:options"/>).</para>
    8.17  
    8.18      <para id="x_63d">Commercial redistribution of Open Publication-licensed
    8.19        material is permitted.</para>
    8.20 @@ -133,7 +133,7 @@
    8.21        </listitem></orderedlist>
    8.22  
    8.23    </sect1>
    8.24 -  <sect1 id="sec.opl.options">
    8.25 +  <sect1 id="sec:opl:options">
    8.26      <title>License options</title>
    8.27  
    8.28      <para id="x_64e">The author(s) and/or publisher of an Open

     9.1 --- a/en/ch00-preface.xml	Fri Mar 20 17:17:55 2009 +0800
     9.2 +++ b/en/ch00-preface.xml	Mon Mar 30 16:23:33 2009 +0800
     9.3 @@ -1,6 +1,6 @@
     9.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     9.5  
     9.6 -<preface id="chap.preface">
     9.7 +<preface id="chap:preface">
     9.8    <?dbhtml filename="preface.html"?>
     9.9    <title>Preface</title>
    9.10  
    9.11 @@ -61,8 +61,8 @@
    9.12  	    can revert to an earlier version of one or more files.  In
    9.13  	    fact, a <emphasis>really</emphasis> good revision control
    9.14  	    tool will even help you to efficiently figure out exactly
    9.15 -	    when a problem was introduced (see section <xref
    9.16 -	      linkend="sec.undo.bisect"/> for details).</para></listitem>
    9.17 +	    when a problem was introduced (see <xref
    9.18 +	      linkend="sec:undo:bisect"/> for details).</para></listitem>
    9.19  	<listitem><para id="x_75">It will help you to work simultaneously on,
    9.20  	    and manage the drift between, multiple versions of your
    9.21  	    project.</para></listitem>
    9.22 @@ -167,8 +167,8 @@
    9.23      <para id="x_87">As an instance of this, several consecutive commits in an
    9.24        example can show up as having occurred during the same second.
    9.25        You can see this occur in the <literal
    9.26 -	role="hg-ext">bisect</literal> example in section <xref
    9.27 -	linkend="sec.undo.bisect"/>, for instance.</para>
    9.28 +	role="hg-ext">bisect</literal> example in <xref
    9.29 +	linkend="sec:undo:bisect"/>, for instance.</para>
    9.30  
    9.31      <para id="x_88">So when you're reading examples, don't place too much weight
    9.32        on the dates or times you see in the output of commands.  But

    10.1 --- a/en/ch01-tour-basic.xml	Fri Mar 20 17:17:55 2009 +0800
    10.2 +++ b/en/ch01-tour-basic.xml	Mon Mar 30 16:23:33 2009 +0800
    10.3 @@ -1,27 +1,27 @@
    10.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    10.5  
    10.6 -<chapter id="chap.tour-basic">
    10.7 +<chapter id="chap:tour-basic">
    10.8    <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
    10.9    <title>A tour of Mercurial: the basics</title>
   10.10  
   10.11 -  <sect1 id="sec.tour.install">
   10.12 +  <sect1 id="sec:tour:install">
   10.13      <title>Installing Mercurial on your system</title>
   10.14  
   10.15 -    <para>Prebuilt binary packages of Mercurial are available for
   10.16 +    <para id="x_1">Prebuilt binary packages of Mercurial are available for
   10.17        every popular operating system.  These make it easy to start
   10.18        using Mercurial on your computer immediately.</para>
   10.19  
   10.20      <sect2>
   10.21        <title>Linux</title>
   10.22  
   10.23 -      <para>Because each Linux distribution has its own packaging
   10.24 +      <para id="x_2">Because each Linux distribution has its own packaging
   10.25  	tools, policies, and rate of development, it's difficult to
   10.26  	give a comprehensive set of instructions on how to install
   10.27  	Mercurial binaries.  The version of Mercurial that you will
   10.28  	end up with can vary depending on how active the person is who
   10.29  	maintains the package for your distribution.</para>
   10.30  
   10.31 -      <para>To keep things simple, I will focus on installing
   10.32 +      <para id="x_3">To keep things simple, I will focus on installing
   10.33  	Mercurial from the command line under the most popular Linux
   10.34  	distributions.  Most of these distributions provide graphical
   10.35  	package managers that will let you install Mercurial with a
   10.36 @@ -29,15 +29,15 @@
   10.37  	<literal>mercurial</literal>.</para>
   10.38  
   10.39        <itemizedlist>
   10.40 -	<listitem><para>Debian:</para>
   10.41 +	<listitem><para id="x_4">Debian:</para>
   10.42  	  <programlisting>apt-get install mercurial</programlisting></listitem>
   10.43 -	<listitem><para>Fedora Core:</para>
   10.44 +	<listitem><para id="x_5">Fedora Core:</para>
   10.45  	  <programlisting>yum install mercurial</programlisting></listitem>
   10.46 -	<listitem><para>Gentoo:</para>
   10.47 +	<listitem><para id="x_6">Gentoo:</para>
   10.48  	  <programlisting>emerge mercurial</programlisting></listitem>
   10.49 -	<listitem><para>OpenSUSE:</para>
   10.50 +	<listitem><para id="x_7">OpenSUSE:</para>
   10.51  	  <programlisting>yum install mercurial</programlisting></listitem>
   10.52 -	<listitem><para>Ubuntu: Ubuntu's Mercurial package is based on
   10.53 +	<listitem><para id="x_8">Ubuntu: Ubuntu's Mercurial package is based on
   10.54  	    Debian's.  To install it, run the following
   10.55  	    command.</para>
   10.56  	  <programlisting>apt-get install mercurial</programlisting></listitem>
   10.57 @@ -47,7 +47,7 @@
   10.58      <sect2>
   10.59        <title>Solaris</title>
   10.60  
   10.61 -      <para>SunFreeWare, at <ulink
   10.62 +      <para id="x_9">SunFreeWare, at <ulink
   10.63  	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
   10.64  	is a good source for a large number of pre-built Solaris
   10.65  	packages for 32 and 64 bit Intel and Sparc architectures,
   10.66 @@ -57,7 +57,7 @@
   10.67      <sect2>
   10.68        <title>Mac OS X</title>
   10.69  
   10.70 -      <para>Lee Cantey publishes an installer of Mercurial for Mac OS
   10.71 +      <para id="x_a">Lee Cantey publishes an installer of Mercurial for Mac OS
   10.72  	X at <ulink
   10.73  	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
   10.74  	This package works on both Intel- and Power-based Macs. Before
   10.75 @@ -66,7 +66,7 @@
   10.76  	is easy to do; simply follow the instructions on Lee's
   10.77  	site.</para>
   10.78  
   10.79 -      <para>It's also possible to install Mercurial using Fink or
   10.80 +      <para id="x_b">It's also possible to install Mercurial using Fink or
   10.81  	MacPorts, two popular free package managers for Mac OS X.  If
   10.82  	you have Fink, use <command>sudo apt-get install
   10.83  	  mercurial-py25</command>.  If MacPorts, <command>sudo port
   10.84 @@ -76,14 +76,14 @@
   10.85      <sect2>
   10.86        <title>Windows</title>
   10.87  
   10.88 -      <para>Lee Cantey publishes an installer of Mercurial for Windows
   10.89 +      <para id="x_c">Lee Cantey publishes an installer of Mercurial for Windows
   10.90  	at <ulink
   10.91  	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
   10.92  	This package has no external dependencies; it <quote>just
   10.93  	  works</quote>.</para>
   10.94  
   10.95        <note>
   10.96 -	<para>  The Windows version of Mercurial does not
   10.97 +	<para id="x_d">  The Windows version of Mercurial does not
   10.98  	  automatically convert line endings between Windows and Unix
   10.99  	  styles.  If you want to share work with Unix users, you must
  10.100  	  do a little additional configuration work. XXX Flesh this
  10.101 @@ -95,7 +95,7 @@
  10.102    <sect1>
  10.103      <title>Getting started</title>
  10.104  
  10.105 -    <para>To begin, we'll use the <command role="hg-cmd">hg
  10.106 +    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
  10.107  	version</command> command to find out whether Mercurial is
  10.108        actually installed properly.  The actual version information
  10.109        that it prints isn't so important; it's whether it prints
  10.110 @@ -106,7 +106,7 @@
  10.111      <sect2>
  10.112        <title>Built-in help</title>
  10.113  
  10.114 -      <para>Mercurial provides a built-in help system.  This is
  10.115 +      <para id="x_f">Mercurial provides a built-in help system.  This is
  10.116  	  invaluable for those times when you find yourself stuck
  10.117  	  trying to remember how to run a command.  If you are
  10.118  	  completely stuck, simply run <command role="hg-cmd">hg
  10.119 @@ -117,7 +117,7 @@
  10.120  
  10.121  	&interaction.tour.help;
  10.122  
  10.123 -	<para>For a more impressive level of detail (which you won't
  10.124 +	<para id="x_10">For a more impressive level of detail (which you won't
  10.125  	  usually need) run <command role="hg-cmd">hg help <option
  10.126  	      role="hg-opt-global">-v</option></command>.  The <option
  10.127  	    role="hg-opt-global">-v</option> option is short for
  10.128 @@ -130,13 +130,13 @@
  10.129    <sect1>
  10.130      <title>Working with a repository</title>
  10.131  
  10.132 -    <para>In Mercurial, everything happens inside a
  10.133 +    <para id="x_11">In Mercurial, everything happens inside a
  10.134        <emphasis>repository</emphasis>.  The repository for a project
  10.135        contains all of the files that <quote>belong to</quote> that
  10.136        project, along with a historical record of the project's
  10.137        files.</para>
  10.138  
  10.139 -    <para>There's nothing particularly magical about a repository; it
  10.140 +    <para id="x_12">There's nothing particularly magical about a repository; it
  10.141        is simply a directory tree in your filesystem that Mercurial
  10.142        treats as special. You can rename or delete a repository any
  10.143        time you like, using either the command line or your file
  10.144 @@ -145,7 +145,7 @@
  10.145      <sect2>
  10.146        <title>Making a local copy of a repository</title>
  10.147  
  10.148 -      <para><emphasis>Copying</emphasis> a repository is just a little
  10.149 +      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
  10.150  	bit special.  While you could use a normal file copying
  10.151  	command to make a copy of a repository, it's best to use a
  10.152  	built-in command that Mercurial provides.  This command is
  10.153 @@ -154,23 +154,23 @@
  10.154  
  10.155        &interaction.tour.clone;
  10.156  
  10.157 -      <para>If our clone succeeded, we should now have a local
  10.158 +      <para id="x_14">If our clone succeeded, we should now have a local
  10.159  	directory called <filename class="directory">hello</filename>.
  10.160  	This directory will contain some files.</para>
  10.161  
  10.162        &interaction.tour.ls;
  10.163  
  10.164 -      <para>These files have the same contents and history in our
  10.165 +      <para id="x_15">These files have the same contents and history in our
  10.166  	repository as they do in the repository we cloned.</para>
  10.167  
  10.168 -      <para>Every Mercurial repository is complete, self-contained,
  10.169 +      <para id="x_16">Every Mercurial repository is complete, self-contained,
  10.170  	and independent.  It contains its own private copy of a
  10.171  	project's files and history.  A cloned repository remembers
  10.172  	the location of the repository it was cloned from, but it does
  10.173  	not communicate with that repository, or any other, unless you
  10.174  	tell it to.</para>
  10.175  
  10.176 -      <para>What this means for now is that we're free to experiment
  10.177 +      <para id="x_17">What this means for now is that we're free to experiment
  10.178  	with our repository, safe in the knowledge that it's a private
  10.179  	<quote>sandbox</quote> that won't affect anyone else.</para>
  10.180  
  10.181 @@ -178,20 +178,20 @@
  10.182      <sect2>
  10.183        <title>What's in a repository?</title>
  10.184  
  10.185 -      <para>When we take a more detailed look inside a repository, we
  10.186 +      <para id="x_18">When we take a more detailed look inside a repository, we
  10.187  	can see that it contains a directory named <filename
  10.188  	  class="directory">.hg</filename>.  This is where Mercurial
  10.189  	keeps all of its metadata for the repository.</para>
  10.190  
  10.191        &interaction.tour.ls-a;
  10.192  
  10.193 -      <para>The contents of the <filename
  10.194 +      <para id="x_19">The contents of the <filename
  10.195  	  class="directory">.hg</filename> directory and its
  10.196  	subdirectories are private to Mercurial.  Every other file and
  10.197  	directory in the repository is yours to do with as you
  10.198  	please.</para>
  10.199  
  10.200 -      <para>To introduce a little terminology, the <filename
  10.201 +      <para id="x_1a">To introduce a little terminology, the <filename
  10.202  	  class="directory">.hg</filename> directory is the
  10.203  	<quote>real</quote> repository, and all of the files and
  10.204  	directories that coexist with it are said to live in the
  10.205 @@ -208,68 +208,66 @@
  10.206    <sect1>
  10.207      <title>A tour through history</title>
  10.208  
  10.209 -    <para>One of the first things we might want to do with a new,
  10.210 +    <para id="x_1b">One of the first things we might want to do with a new,
  10.211        unfamiliar repository is understand its history.  The <command
  10.212  	role="hg-cmd">hg log</command> command gives us a view of
  10.213        history.</para>
  10.214  
  10.215      &interaction.tour.log;
  10.216  
  10.217 -    <para>By default, this command prints a brief paragraph of output
  10.218 +    <para id="x_1c">By default, this command prints a brief paragraph of output
  10.219        for each change to the project that was recorded.  In Mercurial
  10.220        terminology, we call each of these recorded events a
  10.221        <emphasis>changeset</emphasis>, because it can contain a record
  10.222        of changes to several files.</para>
  10.223  
  10.224 -    <para>The fields in a record of output from <command
  10.225 +    <para id="x_1d">The fields in a record of output from <command
  10.226  	role="hg-cmd">hg log</command> are as follows.</para>
  10.227      <itemizedlist>
  10.228 -      <listitem><para><literal>changeset</literal>: This field has the
  10.229 +      <listitem><para id="x_1e"><literal>changeset</literal>: This field has the
  10.230  	  format of a number, followed by a colon, followed by a
  10.231  	  hexadecimal string.  These are
  10.232  	  <emphasis>identifiers</emphasis> for the changeset.  There
  10.233  	  are two identifiers because the number is shorter and easier
  10.234  	  to type than the hex string.</para></listitem>
  10.235 -      <listitem><para><literal>user</literal>: The identity of the
  10.236 +      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
  10.237  	  person who created the changeset.  This is a free-form
  10.238  	  field, but it most often contains a person's name and email
  10.239  	  address.</para></listitem>
  10.240 -      <listitem><para><literal>date</literal>: The date and time on
  10.241 +      <listitem><para id="x_20"><literal>date</literal>: The date and time on
  10.242  	  which the changeset was created, and the timezone in which
  10.243  	  it was created.  (The date and time are local to that
  10.244  	  timezone; they display what time and date it was for the
  10.245  	  person who created the changeset.)</para></listitem>
  10.246 -      <listitem><para><literal>summary</literal>: The first line of
  10.247 +      <listitem><para id="x_21"><literal>summary</literal>: The first line of
  10.248  	  the text message that the creator of the changeset entered
  10.249  	  to describe the changeset.</para></listitem></itemizedlist>
  10.250 -    <para>The default output printed by <command role="hg-cmd">hg
  10.251 +    <para id="x_22">The default output printed by <command role="hg-cmd">hg
  10.252  	log</command> is purely a summary; it is missing a lot of
  10.253        detail.</para>
  10.254  
  10.255 -    <para>Figure <xref endterm="fig.tour-basic.history.caption"
  10.256 -        linkend="fig.tour-basic.history"/> provides a
  10.257 -      graphical representation of the history of the <filename
  10.258 +    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
  10.259 +      a graphical representation of the history of the <filename
  10.260  	class="directory">hello</filename> repository, to make it a
  10.261        little easier to see which direction history is
  10.262        <quote>flowing</quote> in.  We'll be returning to this figure
  10.263        several times in this chapter and the chapter that
  10.264        follows.</para>
  10.265  
  10.266 -    <informalfigure id="fig.tour-basic.history">
  10.267 +    <figure id="fig:tour-basic:history">
  10.268 +      <title>Graphical history of the <filename
  10.269 +	  class="directory">hello</filename> repository</title>
  10.270        <mediaobject>
  10.271 -	<imageobject><imagedata fileref="images/tour-history.png"/></imageobject>
  10.272 +	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
  10.273  	<textobject><phrase>XXX add text</phrase></textobject>
  10.274 -	<caption><para id="fig.tour-basic.history.caption">Graphical history of
  10.275 -	    the <filename class="directory">hello</filename> repository</para>
  10.276 -	</caption>
  10.277        </mediaobject>
  10.278 -    </informalfigure>
  10.279 +    </figure>
  10.280  
  10.281      <sect2>
  10.282        <title>Changesets, revisions, and talking to other
  10.283  	people</title>
  10.284  
  10.285 -      <para>As English is a notoriously sloppy language, and computer
  10.286 +      <para id="x_25">As English is a notoriously sloppy language, and computer
  10.287  	science has a hallowed history of terminological confusion
  10.288  	(why use one term when four will do?), revision control has a
  10.289  	variety of words and phrases that mean the same thing.  If you
  10.290 @@ -279,7 +277,7 @@
  10.291  	<quote>cset</quote>, and sometimes a changeset is referred to
  10.292  	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
  10.293  
  10.294 -      <para>While it doesn't matter what <emphasis>word</emphasis> you
  10.295 +      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
  10.296  	use to refer to the concept of <quote>a changeset</quote>, the
  10.297  	<emphasis>identifier</emphasis> that you use to refer to
  10.298  	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
  10.299 @@ -288,14 +286,14 @@
  10.300  	  log</command> identifies a changeset using both a number and
  10.301  	a hexadecimal string.</para>
  10.302        <itemizedlist>
  10.303 -	<listitem><para>The revision number is <emphasis>only valid in
  10.304 +	<listitem><para id="x_27">The revision number is <emphasis>only valid in
  10.305  	      that repository</emphasis>,</para></listitem>
  10.306 -	<listitem><para>while the hex string is the
  10.307 +	<listitem><para id="x_28">while the hex string is the
  10.308  	    <emphasis>permanent, unchanging identifier</emphasis> that
  10.309  	    will always identify that exact changeset in
  10.310  	    <emphasis>every</emphasis> copy of the
  10.311  	    repository.</para></listitem></itemizedlist>
  10.312 -      <para>This distinction is important.  If you send someone an
  10.313 +      <para id="x_29">This distinction is important.  If you send someone an
  10.314  	email talking about <quote>revision 33</quote>, there's a high
  10.315  	likelihood that their revision 33 will <emphasis>not be the
  10.316  	  same</emphasis> as yours.  The reason for this is that a
  10.317 @@ -305,7 +303,7 @@
  10.318  	repositories. Three changes $a,b,c$ can easily appear in one
  10.319  	repository as $0,1,2$, while in another as $1,0,2$.</para>
  10.320  
  10.321 -      <para>Mercurial uses revision numbers purely as a convenient
  10.322 +      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
  10.323  	shorthand.  If you need to discuss a changeset with someone,
  10.324  	or make a record of a changeset for some other reason (for
  10.325  	example, in a bug report), use the hexadecimal
  10.326 @@ -315,7 +313,7 @@
  10.327      <sect2>
  10.328        <title>Viewing specific revisions</title>
  10.329  
  10.330 -      <para>To narrow the output of <command role="hg-cmd">hg
  10.331 +      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
  10.332  	  log</command> down to a single revision, use the <option
  10.333  	  role="hg-opt-log">-r</option> (or <option
  10.334  	  role="hg-opt-log">--rev</option>) option.  You can use
  10.335 @@ -324,7 +322,7 @@
  10.336  
  10.337        &interaction.tour.log-r;
  10.338  
  10.339 -      <para>If you want to see the history of several revisions
  10.340 +      <para id="x_2c">If you want to see the history of several revisions
  10.341  	without having to list each one, you can use <emphasis>range
  10.342  	  notation</emphasis>; this lets you express the idea <quote>I
  10.343  	  want all revisions between <literal>abc</literal> and
  10.344 @@ -332,7 +330,7 @@
  10.345        
  10.346  	&interaction.tour.log.range;
  10.347  
  10.348 -      <para>Mercurial also honours the order in which you specify
  10.349 +      <para id="x_2d">Mercurial also honours the order in which you specify
  10.350  	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
  10.351  	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
  10.352  	  4:2</command> prints 4, 3, and 2.</para>
  10.353 @@ -341,7 +339,7 @@
  10.354      <sect2>
  10.355        <title>More detailed information</title>
  10.356  
  10.357 -      <para>While the summary information printed by <command
  10.358 +      <para id="x_2e">While the summary information printed by <command
  10.359  	  role="hg-cmd">hg log</command> is useful if you already know
  10.360  	what you're looking for, you may need to see a complete
  10.361  	description of the change, or a list of the files changed, if
  10.362 @@ -353,13 +351,13 @@
  10.363  
  10.364        &interaction.tour.log-v;
  10.365  
  10.366 -      <para>If you want to see both the description and content of a
  10.367 -	change, add the <option role="hg-opt-log">-p</option> (or
  10.368 -	<option role="hg-opt-log">--patch</option>) option.  This
  10.369 -	displays the content of a change as a <emphasis>unified
  10.370 -	  diff</emphasis> (if you've never seen a unified diff before,
  10.371 -	see section <xref linkend="sec.mq.patch"/> for an
  10.372 -	overview).</para>
  10.373 +      <para id="x_2f">If you want to see both the description and
  10.374 +	content of a change, add the <option
  10.375 +	  role="hg-opt-log">-p</option> (or <option
  10.376 +	  role="hg-opt-log">--patch</option>) option.  This displays
  10.377 +	the content of a change as a <emphasis>unified diff</emphasis>
  10.378 +	(if you've never seen a unified diff before, see <xref
  10.379 +	  linkend="sec:mq:patch"/> for an overview).</para>
  10.380  
  10.381        &interaction.tour.log-vp;
  10.382  
  10.383 @@ -368,39 +366,39 @@
  10.384    <sect1>
  10.385      <title>All about command options</title>
  10.386  
  10.387 -    <para>Let's take a brief break from exploring Mercurial commands
  10.388 +    <para id="x_30">Let's take a brief break from exploring Mercurial commands
  10.389        to discuss a pattern in the way that they work; you may find
  10.390        this useful to keep in mind as we continue our tour.</para>
  10.391  
  10.392 -    <para>Mercurial has a consistent and straightforward approach to
  10.393 +    <para id="x_31">Mercurial has a consistent and straightforward approach to
  10.394        dealing with the options that you can pass to commands.  It
  10.395        follows the conventions for options that are common to modern
  10.396        Linux and Unix systems.</para>
  10.397      <itemizedlist>
  10.398 -      <listitem><para>Every option has a long name.  For example, as
  10.399 +      <listitem><para id="x_32">Every option has a long name.  For example, as
  10.400  	  we've already seen, the <command role="hg-cmd">hg
  10.401  	    log</command> command accepts a <option
  10.402  	    role="hg-opt-log">--rev</option> option.</para></listitem>
  10.403 -      <listitem><para>Most options have short names, too.  Instead of
  10.404 +      <listitem><para id="x_33">Most options have short names, too.  Instead of
  10.405  	  <option role="hg-opt-log">--rev</option>, we can use <option
  10.406  	    role="hg-opt-log">-r</option>.  (The reason that some
  10.407  	  options don't have short names is that the options in
  10.408  	  question are rarely used.)</para></listitem>
  10.409 -      <listitem><para>Long options start with two dashes (e.g. <option
  10.410 +      <listitem><para id="x_34">Long options start with two dashes (e.g. <option
  10.411  	    role="hg-opt-log">--rev</option>), while short options
  10.412  	  start with one (e.g. <option
  10.413  	    role="hg-opt-log">-r</option>).</para></listitem>
  10.414 -      <listitem><para>Option naming and usage is consistent across
  10.415 +      <listitem><para id="x_35">Option naming and usage is consistent across
  10.416  	  commands.  For example, every command that lets you specify
  10.417  	  a changeset ID or revision number accepts both <option
  10.418  	    role="hg-opt-log">-r</option> and <option
  10.419  	    role="hg-opt-log">--rev</option>
  10.420  	  arguments.</para></listitem></itemizedlist>
  10.421 -    <para>In the examples throughout this book, I use short options
  10.422 +    <para id="x_36">In the examples throughout this book, I use short options
  10.423        instead of long.  This just reflects my own preference, so don't
  10.424        read anything significant into it.</para>
  10.425  
  10.426 -    <para>Most commands that print output of some kind will print more
  10.427 +    <para id="x_37">Most commands that print output of some kind will print more
  10.428        output when passed a <option role="hg-opt-global">-v</option>
  10.429        (or <option role="hg-opt-global">--verbose</option>) option, and
  10.430        less when passed <option role="hg-opt-global">-q</option> (or
  10.431 @@ -410,11 +408,11 @@
  10.432    <sect1>
  10.433      <title>Making and reviewing changes</title>
  10.434  
  10.435 -    <para>Now that we have a grasp of viewing history in Mercurial,
  10.436 +    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
  10.437        let's take a look at making some changes and examining
  10.438        them.</para>
  10.439  
  10.440 -    <para>The first thing we'll do is isolate our experiment in a
  10.441 +    <para id="x_39">The first thing we'll do is isolate our experiment in a
  10.442        repository of its own.  We use the <command role="hg-cmd">hg
  10.443  	clone</command> command, but we don't need to clone a copy of
  10.444        the remote repository.  Since we already have a copy of it
  10.445 @@ -424,7 +422,7 @@
  10.446  
  10.447      &interaction.tour.reclone;
  10.448  
  10.449 -    <para>As an aside, it's often good practice to keep a
  10.450 +    <para id="x_3a">As an aside, it's often good practice to keep a
  10.451        <quote>pristine</quote> copy of a remote repository around,
  10.452        which you can then make temporary clones of to create sandboxes
  10.453        for each task you want to work on.  This lets you work on
  10.454 @@ -433,7 +431,7 @@
  10.455        local clones are so cheap, there's almost no overhead to cloning
  10.456        and destroying repositories whenever you want.</para>
  10.457  
  10.458 -    <para>In our <filename class="directory">my-hello</filename>
  10.459 +    <para id="x_3b">In our <filename class="directory">my-hello</filename>
  10.460        repository, we have a file <filename>hello.c</filename> that
  10.461        contains the classic <quote>hello, world</quote> program. Let's
  10.462        use the ancient and venerable <command>sed</command> command to
  10.463 @@ -446,20 +444,20 @@
  10.464  
  10.465      &interaction.tour.sed;
  10.466  
  10.467 -    <para>Mercurial's <command role="hg-cmd">hg status</command>
  10.468 +    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
  10.469        command will tell us what Mercurial knows about the files in the
  10.470        repository.</para>
  10.471  
  10.472      &interaction.tour.status;
  10.473  
  10.474 -    <para>The <command role="hg-cmd">hg status</command> command
  10.475 +    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
  10.476        prints no output for some files, but a line starting with
  10.477        <quote><literal>M</literal></quote> for
  10.478        <filename>hello.c</filename>.  Unless you tell it to, <command
  10.479  	role="hg-cmd">hg status</command> will not print any output
  10.480        for files that have not been modified.</para>
  10.481  
  10.482 -    <para>The <quote><literal>M</literal></quote> indicates that
  10.483 +    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
  10.484        Mercurial has noticed that we modified
  10.485        <filename>hello.c</filename>.  We didn't need to
  10.486        <emphasis>inform</emphasis> Mercurial that we were going to
  10.487 @@ -467,7 +465,7 @@
  10.488        file after we were done; it was able to figure this out
  10.489        itself.</para>
  10.490  
  10.491 -    <para>It's a little bit helpful to know that we've modified
  10.492 +    <para id="x_3f">It's a little bit helpful to know that we've modified
  10.493        <filename>hello.c</filename>, but we might prefer to know
  10.494        exactly <emphasis>what</emphasis> changes we've made to it.  To
  10.495        do this, we use the <command role="hg-cmd">hg diff</command>
  10.496 @@ -479,14 +477,14 @@
  10.497    <sect1>
  10.498      <title>Recording changes in a new changeset</title>
  10.499  
  10.500 -    <para>We can modify files, build and test our changes, and use
  10.501 +    <para id="x_40">We can modify files, build and test our changes, and use
  10.502        <command role="hg-cmd">hg status</command> and <command
  10.503  	role="hg-cmd">hg diff</command> to review our changes, until
  10.504        we're satisfied with what we've done and arrive at a natural
  10.505        stopping point where we want to record our work in a new
  10.506        changeset.</para>
  10.507  
  10.508 -    <para>The <command role="hg-cmd">hg commit</command> command lets
  10.509 +    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
  10.510        us create a new changeset; we'll usually refer to this as
  10.511        <quote>making a commit</quote> or
  10.512        <quote>committing</quote>.</para>
  10.513 @@ -494,7 +492,7 @@
  10.514      <sect2>
  10.515        <title>Setting up a username</title>
  10.516  
  10.517 -      <para>When you try to run <command role="hg-cmd">hg
  10.518 +      <para id="x_42">When you try to run <command role="hg-cmd">hg
  10.519  	  commit</command> for the first time, it is not guaranteed to
  10.520  	succeed.  Mercurial records your name and address with each
  10.521  	change that you commit, so that you and others will later be
  10.522 @@ -503,36 +501,37 @@
  10.523  	change with.  It will attempt each of the following methods,
  10.524  	in order:</para>
  10.525        <orderedlist>
  10.526 -	<listitem><para>If you specify a <option
  10.527 +	<listitem><para id="x_43">If you specify a <option
  10.528  	      role="hg-opt-commit">-u</option> option to the <command
  10.529  	      role="hg-cmd">hg commit</command> command on the command
  10.530  	    line, followed by a username, this is always given the
  10.531  	    highest precedence.</para></listitem>
  10.532 -	<listitem><para>If you have set the <envar>HGUSER</envar>
  10.533 +	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
  10.534  	    environment variable, this is checked
  10.535  	    next.</para></listitem>
  10.536 -	<listitem><para>If you create a file in your home directory
  10.537 -	    called <filename role="special">.hgrc</filename>, with a
  10.538 -	    <envar role="rc-item-ui">username</envar> entry, that will
  10.539 -	    be used next.  To see what the contents of this file
  10.540 -	    should look like, refer to section <xref
  10.541 -	      linkend="sec.tour-basic.username"/>
  10.542 +	<listitem><para id="x_45">If you create a file in your home
  10.543 +	    directory called <filename
  10.544 +	      role="special">.hgrc</filename>, with a <envar
  10.545 +	      role="rc-item-ui">username</envar> entry, that will be
  10.546 +	    used next.  To see what the contents of this file should
  10.547 +	    look like, refer to <xref
  10.548 +	      linkend="sec:tour-basic:username"/>
  10.549  	    below.</para></listitem>
  10.550 -	<listitem><para>If you have set the <envar>EMAIL</envar>
  10.551 +	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
  10.552  	    environment variable, this will be used
  10.553  	    next.</para></listitem>
  10.554 -	<listitem><para>Mercurial will query your system to find out
  10.555 +	<listitem><para id="x_47">Mercurial will query your system to find out
  10.556  	    your local user name and host name, and construct a
  10.557  	    username from these components. Since this often results
  10.558  	    in a username that is not very useful, it will print a
  10.559  	    warning if it has to do
  10.560  	    this.</para></listitem>
  10.561        </orderedlist>
  10.562 -      <para>If all of these mechanisms fail, Mercurial will
  10.563 +      <para id="x_48">If all of these mechanisms fail, Mercurial will
  10.564  	  fail, printing an error message.  In this case, it will not
  10.565  	  let you commit until you set up a
  10.566  	  username.</para>
  10.567 -      <para>You should think of the <envar>HGUSER</envar> environment
  10.568 +      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
  10.569  	variable and the <option role="hg-opt-commit">-u</option>
  10.570  	option to the <command role="hg-cmd">hg commit</command>
  10.571  	command as ways to <emphasis>override</emphasis> Mercurial's
  10.572 @@ -540,10 +539,10 @@
  10.573  	and most robust way to set a username for yourself is by
  10.574  	creating a <filename role="special">.hgrc</filename> file; see
  10.575  	below for details.</para>
  10.576 -      <sect3 id="sec.tour-basic.username">
  10.577 +      <sect3 id="sec:tour-basic:username">
  10.578  	<title>Creating a Mercurial configuration file</title>
  10.579  
  10.580 -	<para>To set a user name, use your favourite editor
  10.581 +	<para id="x_4a">To set a user name, use your favourite editor
  10.582  	    to create a file called <filename
  10.583  	      role="special">.hgrc</filename> in your home directory.
  10.584  	    Mercurial will use this file to look up your personalised
  10.585 @@ -555,7 +554,7 @@
  10.586  username = Firstname Lastname
  10.587  &lt;email.address@domain.net&gt;</programlisting>
  10.588  
  10.589 -	<para>The <quote><literal>[ui]</literal></quote> line begins a
  10.590 +	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
  10.591  	  <emphasis>section</emphasis> of the config file, so you can
  10.592  	  read the <quote><literal>username = ...</literal></quote>
  10.593  	  line as meaning <quote>set the value of the
  10.594 @@ -570,14 +569,14 @@
  10.595        <sect3>
  10.596  	<title>Choosing a user name</title>
  10.597  
  10.598 -	<para>You can use any text you like as the value of
  10.599 +	<para id="x_4c">You can use any text you like as the value of
  10.600  	    the <literal>username</literal> config item, since this
  10.601  	    information is for reading by other people, but for
  10.602  	    interpreting by Mercurial.  The convention that most
  10.603  	    people follow is to use their name and email address, as
  10.604  	    in the example above.</para>
  10.605  	<note>
  10.606 -	  <para>Mercurial's built-in web server obfuscates
  10.607 +	  <para id="x_4d">Mercurial's built-in web server obfuscates
  10.608  	      email addresses, to make it more difficult for the email
  10.609  	      harvesting tools that spammers use. This reduces the
  10.610  	      likelihood that you'll start receiving more junk email
  10.611 @@ -589,7 +588,7 @@
  10.612      <sect2>
  10.613        <title>Writing a commit message</title>
  10.614  
  10.615 -      <para>When we commit a change, Mercurial drops us into
  10.616 +      <para id="x_4e">When we commit a change, Mercurial drops us into
  10.617  	  a text editor, to enter a message that will describe the
  10.618  	  modifications we've made in this changeset.  This is called
  10.619  	  the <emphasis>commit message</emphasis>.  It will be a
  10.620 @@ -599,14 +598,14 @@
  10.621  
  10.622         &interaction.tour.commit;
  10.623  
  10.624 -      <para>The editor that the <command role="hg-cmd">hg
  10.625 +      <para id="x_4f">The editor that the <command role="hg-cmd">hg
  10.626  	    commit</command> command drops us into will contain an
  10.627  	  empty line, followed by a number of lines starting with
  10.628  	  <quote><literal>HG:</literal></quote>.</para>
  10.629  
  10.630      <programlisting>XXX fix this XXX</programlisting>
  10.631  
  10.632 -      <para>Mercurial ignores the lines that start with
  10.633 +      <para id="x_50">Mercurial ignores the lines that start with
  10.634  	  <quote><literal>HG:</literal></quote>; it uses them only to
  10.635  	  tell us which files it's recording changes to.  Modifying or
  10.636  	  deleting these lines has no effect.</para>
  10.637 @@ -614,7 +613,7 @@
  10.638      <sect2>
  10.639        <title>Writing a good commit message</title>
  10.640  
  10.641 -      <para>Since <command role="hg-cmd">hg log</command>
  10.642 +      <para id="x_51">Since <command role="hg-cmd">hg log</command>
  10.643  	  only prints the first line of a commit message by default,
  10.644  	  it's best to write a commit message whose first line stands
  10.645  	  alone.  Here's a real example of a commit message that
  10.646 @@ -628,13 +627,13 @@
  10.647  date:        Tue Sep 26 21:37:07 2006 -0700
  10.648  summary:     include buildmeister/commondefs. Add exports.</programlisting>
  10.649  
  10.650 -      <para>As far as the remainder of the contents of the
  10.651 +      <para id="x_52">As far as the remainder of the contents of the
  10.652  	  commit message are concerned, there are no hard-and-fast
  10.653  	  rules.  Mercurial itself doesn't interpret or care about the
  10.654  	  contents of the commit message, though your project may have
  10.655  	  policies that dictate a certain kind of
  10.656  	  formatting.</para>
  10.657 -      <para>My personal preference is for short, but
  10.658 +      <para id="x_53">My personal preference is for short, but
  10.659  	  informative, commit messages that tell me something that I
  10.660  	  can't figure out with a quick glance at the output of
  10.661  	  <command role="hg-cmd">hg log
  10.662 @@ -643,12 +642,12 @@
  10.663      <sect2>
  10.664        <title>Aborting a commit</title>
  10.665  
  10.666 -      <para>If you decide that you don't want to commit
  10.667 +      <para id="x_54">If you decide that you don't want to commit
  10.668  	  while in the middle of editing a commit message, simply exit
  10.669  	  from your editor without saving the file that it's editing.
  10.670  	  This will cause nothing to happen to either the repository
  10.671  	  or the working directory.</para>
  10.672 -      <para>If we run the <command role="hg-cmd">hg
  10.673 +      <para id="x_55">If we run the <command role="hg-cmd">hg
  10.674  	    commit</command> command without any arguments, it records
  10.675  	  all of the changes we've made, as reported by <command
  10.676  	    role="hg-cmd">hg status</command> and <command
  10.677 @@ -657,7 +656,7 @@
  10.678      <sect2>
  10.679        <title>Admiring our new handiwork</title>
  10.680  
  10.681 -      <para>Once we've finished the commit, we can use the
  10.682 +      <para id="x_56">Once we've finished the commit, we can use the
  10.683  	  <command role="hg-cmd">hg tip</command> command to display
  10.684  	  the changeset we just created.  This command produces output
  10.685  	  that is identical to <command role="hg-cmd">hg
  10.686 @@ -666,7 +665,7 @@
  10.687  
  10.688        &interaction.tour.tip;
  10.689  
  10.690 -      <para>We refer to
  10.691 +      <para id="x_57">We refer to
  10.692  	  the newest revision in the repository as the tip revision,
  10.693  	  or simply the tip.</para>
  10.694      </sect2>
  10.695 @@ -675,16 +674,16 @@
  10.696    <sect1>
  10.697      <title>Sharing changes</title>
  10.698  
  10.699 -    <para>We mentioned earlier that repositories in
  10.700 +    <para id="x_58">We mentioned earlier that repositories in
  10.701  	Mercurial are self-contained.  This means that the changeset
  10.702  	we just created exists only in our <filename
  10.703  	  class="directory">my-hello</filename> repository.  Let's
  10.704  	look at a few ways that we can propagate this change into
  10.705  	other repositories.</para>
  10.706  
  10.707 -    <sect2 id="sec.tour.pull">
  10.708 +    <sect2 id="sec:tour:pull">
  10.709        <title>Pulling changes from another repository</title>
  10.710 -      <para>To get started, let's clone our original
  10.711 +      <para id="x_59">To get started, let's clone our original
  10.712  	  <filename class="directory">hello</filename> repository,
  10.713  	  which does not contain the change we just committed.  We'll
  10.714  	  call our temporary repository <filename
  10.715 @@ -692,7 +691,7 @@
  10.716  
  10.717        &interaction.tour.clone-pull;
  10.718  
  10.719 -      <para>We'll use the <command role="hg-cmd">hg
  10.720 +      <para id="x_5a">We'll use the <command role="hg-cmd">hg
  10.721  	    pull</command> command to bring changes from <filename
  10.722  	    class="directory">my-hello</filename> into <filename
  10.723  	    class="directory">hello-pull</filename>.  However, blindly
  10.724 @@ -705,21 +704,21 @@
  10.725  
  10.726        &interaction.tour.incoming;
  10.727  
  10.728 -      <para>(Of course, someone could
  10.729 +      <para id="x_5b">(Of course, someone could
  10.730  	  cause more changesets to appear in the repository that we
  10.731  	  ran <command role="hg-cmd">hg incoming</command> in, before
  10.732  	  we get a chance to <command role="hg-cmd">hg pull</command>
  10.733  	  the changes, so that we could end up pulling changes that we
  10.734  	  didn't expect.)</para>
  10.735  
  10.736 -      <para>Bringing changes into a repository is a simple
  10.737 +      <para id="x_5c">Bringing changes into a repository is a simple
  10.738  	  matter of running the <command role="hg-cmd">hg
  10.739  	    pull</command> command, and telling it which repository to
  10.740  	  pull from.</para>
  10.741  
  10.742        &interaction.tour.pull;
  10.743  
  10.744 -      <para>As you can see
  10.745 +      <para id="x_5d">As you can see
  10.746  	  from the before-and-after output of <command
  10.747  	    role="hg-cmd">hg tip</command>, we have successfully
  10.748  	  pulled changes into our repository.  There remains one step
  10.749 @@ -729,19 +728,19 @@
  10.750      <sect2>
  10.751        <title>Updating the working directory</title>
  10.752  
  10.753 -      <para>We have so far glossed over the relationship between a
  10.754 -	repository and its working directory.  The <command
  10.755 +      <para id="x_5e">We have so far glossed over the relationship
  10.756 +	between a repository and its working directory.  The <command
  10.757  	  role="hg-cmd">hg pull</command> command that we ran in
  10.758 -	section <xref linkend="sec.tour.pull"/> brought changes
  10.759 -	into the repository, but if we check, there's no sign of those
  10.760 -	changes in the working directory.  This is because <command
  10.761 +	<xref linkend="sec:tour:pull"/> brought changes into the
  10.762 +	repository, but if we check, there's no sign of those changes
  10.763 +	in the working directory.  This is because <command
  10.764  	  role="hg-cmd">hg pull</command> does not (by default) touch
  10.765  	the working directory.  Instead, we use the <command
  10.766  	  role="hg-cmd">hg update</command> command to do this.</para>
  10.767  
  10.768        &interaction.tour.update;
  10.769  
  10.770 -      <para>It might seem a bit strange that <command role="hg-cmd">hg
  10.771 +      <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg
  10.772  	  pull</command> doesn't update the working directory
  10.773  	automatically.  There's actually a good reason for this: you
  10.774  	can use <command role="hg-cmd">hg update</command> to update
  10.775 @@ -752,29 +751,28 @@
  10.776  	  role="hg-cmd">hg pull</command> which automatically updated
  10.777  	the working directory to a new revision, you might not be
  10.778  	terribly happy.</para>
  10.779 -      <para>However, since pull-then-update is such a common thing to
  10.780 +      <para id="x_60">However, since pull-then-update is such a common thing to
  10.781  	do, Mercurial lets you combine the two by passing the <option
  10.782  	  role="hg-opt-pull">-u</option> option to <command
  10.783  	  role="hg-cmd">hg pull</command>.</para>
  10.784  
  10.785 -      <para>If you look back at the output of <command
  10.786 -	  role="hg-cmd">hg pull</command> in section <xref
  10.787 -	    linkend="sec.tour.pull"/> when we ran it without <option
  10.788 +      <para id="x_61">If you look back at the output of <command
  10.789 +	  role="hg-cmd">hg pull</command> in <xref
  10.790 +	    linkend="sec:tour:pull"/> when we ran it without <option
  10.791  	  role="hg-opt-pull">-u</option>, you can see that it printed
  10.792  	a helpful reminder that we'd have to take an explicit step to
  10.793  	update the working directory:</para>
  10.794  
  10.795        <!-- &interaction.xxx.fixme; -->
  10.796  
  10.797 -      <para>To find out what revision the working directory is at, use
  10.798 +      <para id="x_62">To find out what revision the working directory is at, use
  10.799  	the <command role="hg-cmd">hg parents</command>
  10.800  	command.</para>
  10.801  
  10.802        &interaction.tour.parents;
  10.803  
  10.804 -      <para>If you look back at figure <xref
  10.805 -	   endterm="fig.tour-basic.history.caption" 
  10.806 -	   linkend="fig.tour-basic.history"/>,
  10.807 +      <para id="x_63">If you look back at <xref
  10.808 +	  linkend="fig:tour-basic:history"/>,
  10.809  	you'll see arrows connecting each changeset.  The node that
  10.810  	the arrow leads <emphasis>from</emphasis> in each case is a
  10.811  	parent, and the node that the arrow leads
  10.812 @@ -782,14 +780,14 @@
  10.813  	has a parent in just the same way; this is the changeset that
  10.814  	the working directory currently contains.</para>
  10.815  
  10.816 -      <para>To update the working directory to a particular revision,
  10.817 +      <para id="x_64">To update the working directory to a particular revision,
  10.818  
  10.819  	give a revision number or changeset ID to the <command
  10.820  	  role="hg-cmd">hg update</command> command.</para>
  10.821  
  10.822        &interaction.tour.older;
  10.823  
  10.824 -      <para>If you omit an explicit revision, <command
  10.825 +      <para id="x_65">If you omit an explicit revision, <command
  10.826  	  role="hg-cmd">hg update</command> will update to the tip
  10.827  	revision, as shown by the second call to <command
  10.828  	  role="hg-cmd">hg update</command> in the example
  10.829 @@ -799,7 +797,7 @@
  10.830      <sect2>
  10.831        <title>Pushing changes to another repository</title>
  10.832  
  10.833 -      <para>Mercurial lets us push changes to another
  10.834 +      <para id="x_66">Mercurial lets us push changes to another
  10.835  	  repository, from the repository we're currently visiting.
  10.836  	  As with the example of <command role="hg-cmd">hg
  10.837  	    pull</command> above, we'll create a temporary repository
  10.838 @@ -807,19 +805,19 @@
  10.839  
  10.840        &interaction.tour.clone-push;
  10.841  
  10.842 -      <para>The <command role="hg-cmd">hg outgoing</command> command
  10.843 +      <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command
  10.844  	  tells us what changes would be pushed into another
  10.845  	  repository.</para>
  10.846  
  10.847        &interaction.tour.outgoing;
  10.848  
  10.849 -      <para>And the
  10.850 +      <para id="x_68">And the
  10.851  	  <command role="hg-cmd">hg push</command> command does the
  10.852  	  actual push.</para>
  10.853  
  10.854        &interaction.tour.push;
  10.855  
  10.856 -      <para>As with
  10.857 +      <para id="x_69">As with
  10.858  	  <command role="hg-cmd">hg pull</command>, the <command
  10.859  	    role="hg-cmd">hg push</command> command does not update
  10.860  	  the working directory in the repository that it's pushing
  10.861 @@ -828,7 +826,7 @@
  10.862  	  does not provide a <literal>-u</literal> option that updates
  10.863  	  the other repository's working directory.)</para>
  10.864  
  10.865 -      <para>What happens if we try to pull or push changes
  10.866 +      <para id="x_6a">What happens if we try to pull or push changes
  10.867  	  and the receiving repository already has those changes?
  10.868  	  Nothing too exciting.</para>
  10.869  
  10.870 @@ -837,7 +835,7 @@
  10.871      <sect2>
  10.872        <title>Sharing changes over a network</title>
  10.873  
  10.874 -      <para>The commands we have covered in the previous few
  10.875 +      <para id="x_6b">The commands we have covered in the previous few
  10.876  	  sections are not limited to working with local repositories.
  10.877  	  Each works in exactly the same fashion over a network
  10.878  	  connection; simply pass in a URL instead of a local
  10.879 @@ -845,7 +843,7 @@
  10.880  	
  10.881        &interaction.tour.outgoing.net;
  10.882  
  10.883 -      <para>In this example, we
  10.884 +      <para id="x_6c">In this example, we
  10.885  	  can see what changes we could push to the remote repository,
  10.886  	  but the repository is understandably not set up to let
  10.887  	  anonymous users push to it.</para>

    11.1 --- a/en/ch02-tour-merge.xml	Fri Mar 20 17:17:55 2009 +0800
    11.2 +++ b/en/ch02-tour-merge.xml	Mon Mar 30 16:23:33 2009 +0800
    11.3 @@ -1,10 +1,10 @@
    11.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    11.5  
    11.6 -<chapter id="chap.tour-merge">
    11.7 +<chapter id="chap:tour-merge">
    11.8    <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
    11.9    <title>A tour of Mercurial: merging work</title>
   11.10  
   11.11 -  <para>We've now covered cloning a repository, making changes in a
   11.12 +  <para id="x_338">We've now covered cloning a repository, making changes in a
   11.13      repository, and pulling or pushing changes from one repository
   11.14      into another.  Our next step is <emphasis>merging</emphasis>
   11.15      changes from separate repositories.</para>
   11.16 @@ -12,86 +12,85 @@
   11.17    <sect1>
   11.18      <title>Merging streams of work</title>
   11.19  
   11.20 -    <para>Merging is a fundamental part of working with a distributed
   11.21 +    <para id="x_339">Merging is a fundamental part of working with a distributed
   11.22        revision control tool.</para>
   11.23      <itemizedlist>
   11.24 -      <listitem><para>Alice and Bob each have a personal copy of a
   11.25 +      <listitem><para id="x_33a">Alice and Bob each have a personal copy of a
   11.26  	  repository for a project they're collaborating on.  Alice
   11.27  	  fixes a bug in her repository; Bob adds a new feature in
   11.28  	  his.  They want the shared repository to contain both the
   11.29  	  bug fix and the new feature.</para>
   11.30        </listitem>
   11.31 -      <listitem><para>I frequently work on several different tasks for
   11.32 +      <listitem><para id="x_33b">I frequently work on several different tasks for
   11.33  	  a single project at once, each safely isolated in its own
   11.34  	  repository. Working this way means that I often need to
   11.35  	  merge one piece of my own work with another.</para>
   11.36        </listitem></itemizedlist>
   11.37  
   11.38 -    <para>Because merging is such a common thing to need to do,
   11.39 +    <para id="x_33c">Because merging is such a common thing to need to do,
   11.40        Mercurial makes it easy.  Let's walk through the process.  We'll
   11.41        begin by cloning yet another repository (see how often they
   11.42        spring up?) and making a change in it.</para>
   11.43  
   11.44      &interaction.tour.merge.clone;
   11.45  
   11.46 -    <para>We should now have two copies of
   11.47 +    <para id="x_33d">We should now have two copies of
   11.48        <filename>hello.c</filename> with different contents.  The
   11.49        histories of the two repositories have also diverged, as
   11.50 -      illustrated in figure <xref endterm="fig.tour-merge.sep-repos.caption"
   11.51 -	linkend="fig.tour-merge.sep-repos"/>.</para>
   11.52 +      illustrated in <xref
   11.53 +	linkend="fig:tour-merge:sep-repos"/>.</para>
   11.54  
   11.55      &interaction.tour.merge.cat;
   11.56  
   11.57 -    <informalfigure id="fig.tour-merge.sep-repos">
   11.58 +    <figure id="fig:tour-merge:sep-repos">
   11.59 +      <title>Divergent recent histories of the <filename
   11.60 +	  class="directory">my-hello</filename> and <filename
   11.61 +	  class="directory">my-new-hello</filename>
   11.62 +	repositories</title>
   11.63        <mediaobject>
   11.64 -	<imageobject><imagedata fileref="images/tour-merge-sep-repos.png"/></imageobject>
   11.65 +	<imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
   11.66  	<textobject><phrase>XXX add text</phrase></textobject>
   11.67 -	<caption><para id="fig.tour-merge.sep-repos.caption">Divergent recent
   11.68 -	  histories of the <filename
   11.69 -	      class="directory">my-hello</filename> and <filename
   11.70 -	      class="directory">my-new-hello</filename>
   11.71 -	    repositories</para></caption>
   11.72        </mediaobject>
   11.73 -    </informalfigure>
   11.74 -
   11.75 -    <para>We already know that pulling changes from our <filename
   11.76 +    </figure>
   11.77 +
   11.78 +    <para id="x_33f">We already know that pulling changes from our <filename
   11.79  	class="directory">my-hello</filename> repository will have no
   11.80        effect on the working directory.</para>
   11.81  
   11.82      &interaction.tour.merge.pull;
   11.83  
   11.84 -    <para>However, the <command role="hg-cmd">hg pull</command>
   11.85 +    <para id="x_340">However, the <command role="hg-cmd">hg pull</command>
   11.86        command says something about <quote>heads</quote>.</para>
   11.87  
   11.88      <sect2>
   11.89        <title>Head changesets</title>
   11.90  
   11.91 -      <para>A head is a change that has no descendants, or children,
   11.92 +      <para id="x_341">A head is a change that has no descendants, or children,
   11.93  	as they're also known.  The tip revision is thus a head,
   11.94  	because the newest revision in a repository doesn't have any
   11.95  	children, but a repository can contain more than one
   11.96  	head.</para>
   11.97  
   11.98 -      <informalfigure id="fig.tour-merge.pull">
   11.99 +      <figure id="fig:tour-merge:pull">
  11.100 +	<title>Repository contents after pulling from <filename
  11.101 +	    class="directory">my-hello</filename> into <filename
  11.102 +	    class="directory">my-new-hello</filename></title>
  11.103  	<mediaobject>
  11.104 -	  <imageobject><imagedata fileref="images/tour-merge-pull.png"/></imageobject>
  11.105 +	  <imageobject>
  11.106 +	    <imagedata fileref="figs/tour-merge-pull.png"/>
  11.107 +	  </imageobject>
  11.108  	  <textobject><phrase>XXX add text</phrase></textobject>
  11.109 -	  <caption><para id="fig.tour-merge.pull.caption">Repository contents after
  11.110 -	    pulling from <filename class="directory">my-hello</filename> into
  11.111 -	    <filename class="directory">my-new-hello</filename></para></caption>
  11.112  	</mediaobject>
  11.113 -      </informalfigure>
  11.114 -
  11.115 -      <para>In figure <xref endterm="fig.tour-merge.pull.caption"
  11.116 -        linkend="fig.tour-merge.pull"/>, you can
  11.117 +      </figure>
  11.118 +
  11.119 +      <para id="x_343">In <xref linkend="fig:tour-merge:pull"/>, you can
  11.120  	see the effect of the pull from <filename
  11.121  	  class="directory">my-hello</filename> into <filename
  11.122  	  class="directory">my-new-hello</filename>.  The history that
  11.123  	was already present in <filename
  11.124  	  class="directory">my-new-hello</filename> is untouched, but
  11.125 -	a new revision has been added.  By referring to figure <xref
  11.126 -	  endterm="fig.tour-merge.sep-repos.caption" 
  11.127 -	  linkend="fig.tour-merge.sep-repos"/>, we can see that the
  11.128 +	a new revision has been added.  By referring to <xref
  11.129 +	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
  11.130  	<emphasis>changeset ID</emphasis> remains the same in the new
  11.131  	repository, but the <emphasis>revision number</emphasis> has
  11.132  	changed.  (This, incidentally, is a fine example of why it's
  11.133 @@ -105,13 +104,13 @@
  11.134      <sect2>
  11.135        <title>Performing the merge</title>
  11.136  
  11.137 -      <para>What happens if we try to use the normal <command
  11.138 +      <para id="x_344">What happens if we try to use the normal <command
  11.139  	  role="hg-cmd">hg update</command> command to update to the
  11.140  	new tip?</para>
  11.141  
  11.142        &interaction.tour.merge.update;
  11.143  
  11.144 -      <para>Mercurial is telling us that the <command role="hg-cmd">hg
  11.145 +      <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
  11.146  	  update</command> command won't do a merge; it won't update
  11.147  	the working directory when it thinks we might be wanting to do
  11.148  	a merge, unless we force it to do so.  Instead, we use the
  11.149 @@ -120,16 +119,18 @@
  11.150  
  11.151        &interaction.tour.merge.merge;
  11.152  
  11.153 -      <informalfigure id="fig.tour-merge.merge">
  11.154 +      <figure id="fig:tour-merge:merge">
  11.155 +	<title>Working directory and repository during merge, and
  11.156 +	  following commit</title>
  11.157  	<mediaobject>
  11.158 -	  <imageobject><imagedata fileref="images/tour-merge-merge.png"/></imageobject>
  11.159 +	  <imageobject>
  11.160 +	    <imagedata fileref="figs/tour-merge-merge.png"/>
  11.161 +	  </imageobject>
  11.162  	  <textobject><phrase>XXX add text</phrase></textobject>
  11.163 -	  <caption><para id="fig.tour-merge.merge.caption">Working directory and
  11.164 -	      repository during merge, and following commit</para></caption>
  11.165  	</mediaobject>
  11.166 -      </informalfigure>
  11.167 -
  11.168 -      <para>This updates the working directory so that it contains
  11.169 +      </figure>
  11.170 +
  11.171 +      <para id="x_347">This updates the working directory so that it contains
  11.172  	changes from <emphasis>both</emphasis> heads, which is
  11.173  	reflected in both the output of <command role="hg-cmd">hg
  11.174  	  parents</command> and the contents of
  11.175 @@ -141,22 +142,22 @@
  11.176      <sect2>
  11.177        <title>Committing the results of the merge</title>
  11.178  
  11.179 -      <para>Whenever we've done a merge, <command role="hg-cmd">hg
  11.180 +      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
  11.181  	  parents</command> will display two parents until we <command
  11.182  	  role="hg-cmd">hg commit</command> the results of the
  11.183  	  merge.</para>
  11.184  
  11.185  	&interaction.tour.merge.commit;
  11.186  
  11.187 -      <para>We now have a new tip revision; notice that it has
  11.188 +      <para id="x_349">We now have a new tip revision; notice that it has
  11.189  	<emphasis>both</emphasis> of our former heads as its parents.
  11.190  	These are the same revisions that were previously displayed by
  11.191  	<command role="hg-cmd">hg parents</command>.</para>
  11.192  
  11.193        &interaction.tour.merge.tip;
  11.194  
  11.195 -      <para>In figure <xref endterm="fig.tour-merge.merge.caption"
  11.196 -	  linkend="fig.tour-merge.merge"/>, you can see a
  11.197 +      <para id="x_34a">In <xref
  11.198 +	  linkend="fig:tour-merge:merge"/>, you can see a
  11.199  	representation of what happens to the working directory during
  11.200  	the merge, and how this affects the repository when the commit
  11.201  	happens.  During the merge, the working directory has two
  11.202 @@ -168,32 +169,29 @@
  11.203    <sect1>
  11.204      <title>Merging conflicting changes</title>
  11.205  
  11.206 -    <para>Most merges are simple affairs, but sometimes you'll find
  11.207 +    <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
  11.208        yourself merging changes where each modifies the same portions
  11.209        of the same files.  Unless both modifications are identical,
  11.210        this results in a <emphasis>conflict</emphasis>, where you have
  11.211        to decide how to reconcile the different changes into something
  11.212        coherent.</para>
  11.213  
  11.214 -    <informalfigure id="fig.tour-merge.conflict">
  11.215 +    <figure id="fig:tour-merge:conflict">
  11.216 +      <title>Conflicting changes to a document</title>
  11.217        <mediaobject>
  11.218 -        <imageobject><imagedata fileref="images/tour-merge-conflict.png"/>
  11.219 -        </imageobject>
  11.220 -        <textobject><phrase>XXX add text</phrase></textobject>
  11.221 -        <caption><para id="fig.tour-merge.conflict.caption">Conflicting
  11.222 -          changes to a document</para></caption>
  11.223 +	<imageobject><imagedata fileref="figs/tour-merge-conflict.png"/></imageobject>
  11.224 +	<textobject><phrase>XXX add text</phrase></textobject>
  11.225        </mediaobject>
  11.226 -    </informalfigure>
  11.227 -
  11.228 -    <para>Figure <xref endterm="fig.tour-merge.conflict.caption"
  11.229 -      linkend="fig.tour-merge.conflict"/> illustrates
  11.230 +    </figure>
  11.231 +
  11.232 +    <para id="x_34d"><xref linkend="fig:tour-merge:conflict"/> illustrates
  11.233        an instance of two conflicting changes to a document.  We
  11.234        started with a single version of the file; then we made some
  11.235        changes; while someone else made different changes to the same
  11.236        text.  Our task in resolving the conflicting changes is to
  11.237        decide what the file should look like.</para>
  11.238  
  11.239 -    <para>Mercurial doesn't have a built-in facility for handling
  11.240 +    <para id="x_34e">Mercurial doesn't have a built-in facility for handling
  11.241        conflicts. Instead, it runs an external program called
  11.242        <command>hgmerge</command>.  This is a shell script that is
  11.243        bundled with Mercurial; you can change it to behave however you
  11.244 @@ -204,7 +202,7 @@
  11.245        human guidance) or aren't present, the script tries a few
  11.246        different graphical merging tools.</para>
  11.247  
  11.248 -    <para>It's also possible to get Mercurial to run another program
  11.249 +    <para id="x_34f">It's also possible to get Mercurial to run another program
  11.250        or script instead of <command>hgmerge</command>, by setting the
  11.251        <envar>HGMERGE</envar> environment variable to the name of your
  11.252        preferred program.</para>
  11.253 @@ -212,59 +210,59 @@
  11.254      <sect2>
  11.255        <title>Using a graphical merge tool</title>
  11.256  
  11.257 -      <para>My preferred graphical merge tool is
  11.258 +      <para id="x_350">My preferred graphical merge tool is
  11.259  	<command>kdiff3</command>, which I'll use to describe the
  11.260  	features that are common to graphical file merging tools.  You
  11.261  	can see a screenshot of <command>kdiff3</command> in action in
  11.262 -	figure <xref endterm="fig.tour-merge.kdiff3.caption"
  11.263 -	linkend="fig.tour-merge.kdiff3"/>.  The kind of
  11.264 +	<xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
  11.265  	merge it is performing is called a <emphasis>three-way
  11.266  	  merge</emphasis>, because there are three different versions
  11.267  	of the file of interest to us.  The tool thus splits the upper
  11.268  	portion of the window into three panes:</para>
  11.269        <itemizedlist>
  11.270 -	<listitem><para>At the left is the <emphasis>base</emphasis>
  11.271 +	<listitem><para id="x_351">At the left is the <emphasis>base</emphasis>
  11.272  	    version of the file, i.e. the most recent version from
  11.273  	    which the two versions we're trying to merge are
  11.274  	    descended.</para>
  11.275  	</listitem>
  11.276 -	<listitem><para>In the middle is <quote>our</quote> version of
  11.277 +	<listitem><para id="x_352">In the middle is <quote>our</quote> version of
  11.278  	    the file, with the contents that we modified.</para>
  11.279  	</listitem>
  11.280 -	<listitem><para>On the right is <quote>their</quote> version
  11.281 +	<listitem><para id="x_353">On the right is <quote>their</quote> version
  11.282  	    of the file, the one that from the changeset that we're
  11.283  	    trying to merge with.</para>
  11.284  	</listitem></itemizedlist>
  11.285 -      <para>In the pane below these is the current
  11.286 +      <para id="x_354">In the pane below these is the current
  11.287  	<emphasis>result</emphasis> of the merge. Our task is to
  11.288  	replace all of the red text, which indicates unresolved
  11.289  	conflicts, with some sensible merger of the
  11.290  	<quote>ours</quote> and <quote>theirs</quote> versions of the
  11.291  	file.</para>
  11.292  
  11.293 -      <para>All four of these panes are <emphasis>locked
  11.294 +      <para id="x_355">All four of these panes are <emphasis>locked
  11.295  	  together</emphasis>; if we scroll vertically or horizontally
  11.296  	in any of them, the others are updated to display the
  11.297  	corresponding sections of their respective files.</para>
  11.298  
  11.299 -      <informalfigure id="fig.tour-merge.kdiff3">
  11.300 -        <mediaobject>
  11.301 -          <imageobject><imagedata width="100%" fileref="images/kdiff3.png"/>
  11.302 -          </imageobject>
  11.303 -          <textobject><phrase>XXX add text</phrase></textobject>
  11.304 -          <caption><para id="fig.tour-merge.kdiff3.caption">Using
  11.305 -            <command>kdiff3</command> to merge versions of a file</para>
  11.306 -          </caption>
  11.307 -        </mediaobject>
  11.308 -      </informalfigure>
  11.309 -
  11.310 -      <para>For each conflicting portion of the file, we can choose to
  11.311 +      <figure id="fig:tour-merge:kdiff3">
  11.312 +	<title>Using <command>kdiff3</command> to merge versions of a
  11.313 +	  file</title>
  11.314 +	<mediaobject>
  11.315 +	  <imageobject>
  11.316 +	    <imagedata imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
  11.317 +	  <textobject>
  11.318 +	    <phrase>XXX add text</phrase>
  11.319 +	  </textobject>
  11.320 +	</mediaobject>
  11.321 +      </figure>
  11.322 +
  11.323 +      <para id="x_357">For each conflicting portion of the file, we can choose to
  11.324  	resolve the conflict using some combination of text from the
  11.325  	base version, ours, or theirs.  We can also manually edit the
  11.326  	merged file at any time, in case we need to make further
  11.327  	modifications.</para>
  11.328  
  11.329 -      <para>There are <emphasis>many</emphasis> file merging tools
  11.330 +      <para id="x_358">There are <emphasis>many</emphasis> file merging tools
  11.331  	available, too many to cover here.  They vary in which
  11.332  	platforms they are available for, and in their particular
  11.333  	strengths and weaknesses.  Most are tuned for merging files
  11.334 @@ -275,20 +273,19 @@
  11.335      <sect2>
  11.336        <title>A worked example</title>
  11.337  
  11.338 -      <para>In this example, we will reproduce the file modification
  11.339 -	history of figure <xref endterm="fig.tour-merge.conflict.caption"
  11.340 -	linkend="fig.tour-merge.conflict"/>
  11.341 +      <para id="x_359">In this example, we will reproduce the file modification
  11.342 +	history of <xref linkend="fig:tour-merge:conflict"/>
  11.343  	above.  Let's begin by creating a repository with a base
  11.344  	version of our document.</para>
  11.345  
  11.346        &interaction.tour-merge-conflict.wife;
  11.347  
  11.348 -      <para>We'll clone the repository and make a change to the
  11.349 +      <para id="x_35a">We'll clone the repository and make a change to the
  11.350  	file.</para>
  11.351  
  11.352        &interaction.tour-merge-conflict.cousin;
  11.353  
  11.354 -      <para>And another clone, to simulate someone else making a
  11.355 +      <para id="x_35b">And another clone, to simulate someone else making a
  11.356  	change to the file. (This hints at the idea that it's not all
  11.357  	that unusual to merge with yourself when you isolate tasks in
  11.358  	separate repositories, and indeed to find and resolve
  11.359 @@ -296,13 +293,13 @@
  11.360  
  11.361        &interaction.tour-merge-conflict.son;
  11.362  
  11.363 -      <para>Having created two
  11.364 +      <para id="x_35c">Having created two
  11.365  	different versions of the file, we'll set up an environment
  11.366  	suitable for running our merge.</para>
  11.367  
  11.368        &interaction.tour-merge-conflict.pull;
  11.369  
  11.370 -      <para>In this example, I won't use Mercurial's normal
  11.371 +      <para id="x_35d">In this example, I won't use Mercurial's normal
  11.372  	<command>hgmerge</command> program to do the merge, because it
  11.373  	would drop my nice automated example-running tool into a
  11.374  	graphical user interface.  Instead, I'll set
  11.375 @@ -312,25 +309,25 @@
  11.376  	example on your computer, don't bother setting
  11.377  	<envar>HGMERGE</envar>.</para>
  11.378  
  11.379 -      <para><emphasis role="bold">XXX FIX THIS
  11.380 +      <para id="x_35e"><emphasis role="bold">XXX FIX THIS
  11.381  	  EXAMPLE.</emphasis></para>
  11.382  
  11.383        &interaction.tour-merge-conflict.merge;
  11.384  
  11.385 -      <para>Because <command>merge</command> can't resolve the
  11.386 +      <para id="x_35f">Because <command>merge</command> can't resolve the
  11.387  	conflicting changes, it leaves <emphasis>merge
  11.388  	  markers</emphasis> inside the file that has conflicts,
  11.389  	indicating which lines have conflicts, and whether they came
  11.390  	from our version of the file or theirs.</para>
  11.391  
  11.392 -      <para>Mercurial can tell from the way <command>merge</command>
  11.393 +      <para id="x_360">Mercurial can tell from the way <command>merge</command>
  11.394  	exits that it wasn't able to merge successfully, so it tells
  11.395  	us what commands we'll need to run if we want to redo the
  11.396  	merging operation.  This could be useful if, for example, we
  11.397  	were running a graphical merge tool and quit because we were
  11.398  	confused or realised we had made a mistake.</para>
  11.399  
  11.400 -      <para>If automatic or manual merges fail, there's nothing to
  11.401 +      <para id="x_361">If automatic or manual merges fail, there's nothing to
  11.402  	prevent us from <quote>fixing up</quote> the affected files
  11.403  	ourselves, and committing the results of our merge:</para>
  11.404  
  11.405 @@ -338,32 +335,32 @@
  11.406  
  11.407      </sect2>
  11.408    </sect1>
  11.409 -  <sect1 id="sec.tour-merge.fetch">
  11.410 +  <sect1 id="sec:tour-merge:fetch">
  11.411      <title>Simplifying the pull-merge-commit sequence</title>
  11.412  
  11.413 -    <para>The process of merging changes as outlined above is
  11.414 +    <para id="x_362">The process of merging changes as outlined above is
  11.415        straightforward, but requires running three commands in
  11.416        sequence.</para>
  11.417      <programlisting>hg pull
  11.418  hg merge
  11.419  hg commit -m 'Merged remote changes'</programlisting>
  11.420 -    <para>In the case of the final commit, you also need to enter a
  11.421 +    <para id="x_363">In the case of the final commit, you also need to enter a
  11.422        commit message, which is almost always going to be a piece of
  11.423        uninteresting <quote>boilerplate</quote> text.</para>
  11.424  
  11.425 -    <para>It would be nice to reduce the number of steps needed, if
  11.426 +    <para id="x_364">It would be nice to reduce the number of steps needed, if
  11.427        this were possible.  Indeed, Mercurial is distributed with an
  11.428        extension called <literal role="hg-ext">fetch</literal> that
  11.429        does just this.</para>
  11.430  
  11.431 -    <para>Mercurial provides a flexible extension mechanism that lets
  11.432 +    <para id="x_365">Mercurial provides a flexible extension mechanism that lets
  11.433        people extend its functionality, while keeping the core of
  11.434        Mercurial small and easy to deal with.  Some extensions add new
  11.435        commands that you can use from the command line, while others
  11.436        work <quote>behind the scenes,</quote> for example adding
  11.437        capabilities to the server.</para>
  11.438  
  11.439 -    <para>The <literal role="hg-ext">fetch</literal> extension adds a
  11.440 +    <para id="x_366">The <literal role="hg-ext">fetch</literal> extension adds a
  11.441        new command called, not surprisingly, <command role="hg-cmd">hg
  11.442  	fetch</command>.  This extension acts as a combination of
  11.443        <command role="hg-cmd">hg pull</command>, <command
  11.444 @@ -376,7 +373,7 @@
  11.445        added, it updates the working directory to the new tip
  11.446        changeset.</para>
  11.447  
  11.448 -    <para>Enabling the <literal role="hg-ext">fetch</literal>
  11.449 +    <para id="x_367">Enabling the <literal role="hg-ext">fetch</literal>
  11.450        extension is easy.  Edit your <filename
  11.451  	role="special">.hgrc</filename>, and either go to the <literal
  11.452  	role="rc-extensions">extensions</literal> section or create an
  11.453 @@ -385,7 +382,7 @@
  11.454  	</literal></quote>.</para>
  11.455      <programlisting>[extensions]
  11.456  fetch =</programlisting>
  11.457 -    <para>(Normally, on the right-hand side of the
  11.458 +    <para id="x_368">(Normally, on the right-hand side of the
  11.459        <quote><literal>=</literal></quote> would appear the location of
  11.460        the extension, but since the <literal
  11.461  	role="hg-ext">fetch</literal> extension is in the standard

    12.1 --- a/en/ch03-concepts.xml	Fri Mar 20 17:17:55 2009 +0800
    12.2 +++ b/en/ch03-concepts.xml	Mon Mar 30 16:23:33 2009 +0800
    12.3 @@ -1,23 +1,23 @@
    12.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    12.5  
    12.6 -<chapter id="chap.concepts">
    12.7 +<chapter id="chap:concepts">
    12.8    <?dbhtml filename="behind-the-scenes.html"?>
    12.9    <title>Behind the scenes</title>
   12.10  
   12.11 -  <para>Unlike many revision control systems, the concepts upon which
   12.12 +  <para id="x_2e8">Unlike many revision control systems, the concepts upon which
   12.13      Mercurial is built are simple enough that it's easy to understand
   12.14      how the software really works.  Knowing this certainly isn't
   12.15      necessary, but I find it useful to have a <quote>mental
   12.16        model</quote> of what's going on.</para>
   12.17  
   12.18 -  <para>This understanding gives me confidence that Mercurial has been
   12.19 +  <para id="x_2e9">This understanding gives me confidence that Mercurial has been
   12.20      carefully designed to be both <emphasis>safe</emphasis> and
   12.21      <emphasis>efficient</emphasis>.  And just as importantly, if it's
   12.22      easy for me to retain a good idea of what the software is doing
   12.23      when I perform a revision control task, I'm less likely to be
   12.24      surprised by its behaviour.</para>
   12.25  
   12.26 -  <para>In this chapter, we'll initially cover the core concepts
   12.27 +  <para id="x_2ea">In this chapter, we'll initially cover the core concepts
   12.28      behind Mercurial's design, then continue to discuss some of the
   12.29      interesting details of its implementation.</para>
   12.30  
   12.31 @@ -27,7 +27,7 @@
   12.32      <sect2>
   12.33        <title>Tracking the history of a single file</title>
   12.34  
   12.35 -      <para>When Mercurial tracks modifications to a file, it stores
   12.36 +      <para id="x_2eb">When Mercurial tracks modifications to a file, it stores
   12.37  	the history of that file in a metadata object called a
   12.38  	<emphasis>filelog</emphasis>.  Each entry in the filelog
   12.39  	contains enough information to reconstruct one revision of the
   12.40 @@ -38,7 +38,7 @@
   12.41  	an index to help Mercurial to find a revision
   12.42  	efficiently.</para>
   12.43  
   12.44 -      <para>A file that is large, or has a lot of history, has its
   12.45 +      <para id="x_2ec">A file that is large, or has a lot of history, has its
   12.46  	filelog stored in separate data
   12.47  	(<quote><literal>.d</literal></quote> suffix) and index
   12.48  	(<quote><literal>.i</literal></quote> suffix) files.  For
   12.49 @@ -46,25 +46,23 @@
   12.50  	are combined in a single <quote><literal>.i</literal></quote>
   12.51  	file.  The correspondence between a file in the working
   12.52  	directory and the filelog that tracks its history in the
   12.53 -	repository is illustrated in figure <xref
   12.54 -	  endterm="fig.concepts.filelog.caption"
   12.55 -	  linkend="fig.concepts.filelog"/>.</para>
   12.56 -
   12.57 -      <informalfigure id="fig.concepts.filelog">
   12.58 -        <mediaobject>
   12.59 -          <imageobject><imagedata fileref="images/filelog.png"/></imageobject>
   12.60 -          <textobject><phrase>XXX add text</phrase></textobject>
   12.61 -          <caption><para id="fig.concepts.filelog.caption">Relationships between
   12.62 -            files in working directory and filelogs in repository</para>
   12.63 -          </caption>
   12.64 -        </mediaobject>
   12.65 -      </informalfigure>
   12.66 +	repository is illustrated in <xref
   12.67 +	  linkend="fig:concepts:filelog"/>.</para>
   12.68 +
   12.69 +      <figure id="fig:concepts:filelog">
   12.70 +	<title>Relationships between files in working directory and
   12.71 +	  filelogs in repository</title>
   12.72 +	<mediaobject>
   12.73 +	  <imageobject><imagedata fileref="figs/filelog.png"/></imageobject>
   12.74 +	  <textobject><phrase>XXX add text</phrase></textobject>
   12.75 +	</mediaobject>
   12.76 +      </figure>
   12.77  
   12.78      </sect2>
   12.79      <sect2>
   12.80        <title>Managing tracked files</title>
   12.81  
   12.82 -      <para>Mercurial uses a structure called a
   12.83 +      <para id="x_2ee">Mercurial uses a structure called a
   12.84  	<emphasis>manifest</emphasis> to collect together information
   12.85  	about the files that it tracks.  Each entry in the manifest
   12.86  	contains information about the files present in a single
   12.87 @@ -76,7 +74,7 @@
   12.88      <sect2>
   12.89        <title>Recording changeset information</title>
   12.90  
   12.91 -      <para>The <emphasis>changelog</emphasis> contains information
   12.92 +      <para id="x_2ef">The <emphasis>changelog</emphasis> contains information
   12.93  	about each changeset.  Each revision records who committed a
   12.94  	change, the changeset comment, other pieces of
   12.95  	changeset-related information, and the revision of the
   12.96 @@ -86,32 +84,30 @@
   12.97      <sect2>
   12.98        <title>Relationships between revisions</title>
   12.99  
  12.100 -      <para>Within a changelog, a manifest, or a filelog, each
  12.101 +      <para id="x_2f0">Within a changelog, a manifest, or a filelog, each
  12.102  	revision stores a pointer to its immediate parent (or to its
  12.103  	two parents, if it's a merge revision).  As I mentioned above,
  12.104  	there are also relationships between revisions
  12.105  	<emphasis>across</emphasis> these structures, and they are
  12.106  	hierarchical in nature.</para>
  12.107  
  12.108 -      <para>For every changeset in a repository, there is exactly one
  12.109 +      <para id="x_2f1">For every changeset in a repository, there is exactly one
  12.110  	revision stored in the changelog.  Each revision of the
  12.111  	changelog contains a pointer to a single revision of the
  12.112  	manifest.  A revision of the manifest stores a pointer to a
  12.113  	single revision of each filelog tracked when that changeset
  12.114 -	was created.  These relationships are illustrated in figure
  12.115 -	<xref endterm="fig.concepts.metadata.caption"
  12.116 -	  linkend="fig.concepts.metadata"/>.</para>
  12.117 -
  12.118 -      <informalfigure id="fig.concepts.metadata">
  12.119 -        <mediaobject>
  12.120 -          <imageobject><imagedata fileref="images/metadata.png"/></imageobject>
  12.121 -          <textobject><phrase>XXX add text</phrase></textobject>
  12.122 -          <caption><para id="fig.concepts.metadata.caption">Metadata
  12.123 -            relationships</para></caption>
  12.124 -        </mediaobject>
  12.125 -      </informalfigure>
  12.126 -
  12.127 -      <para>As the illustration shows, there is
  12.128 +	was created.  These relationships are illustrated in
  12.129 +	<xref linkend="fig:concepts:metadata"/>.</para>
  12.130 +
  12.131 +      <figure id="fig:concepts:metadata">
  12.132 +	<title>Metadata relationships</title>
  12.133 +	<mediaobject>
  12.134 +	  <imageobject><imagedata fileref="figs/metadata.png"/></imageobject>
  12.135 +	  <textobject><phrase>XXX add text</phrase></textobject>
  12.136 +	</mediaobject>
  12.137 +      </figure>
  12.138 +
  12.139 +      <para id="x_2f3">As the illustration shows, there is
  12.140  	<emphasis>not</emphasis> a <quote>one to one</quote>
  12.141  	relationship between revisions in the changelog, manifest, or
  12.142  	filelog. If the manifest hasn't changed between two
  12.143 @@ -126,14 +122,14 @@
  12.144    <sect1>
  12.145      <title>Safe, efficient storage</title>
  12.146  
  12.147 -    <para>The underpinnings of changelogs, manifests, and filelogs are
  12.148 +    <para id="x_2f4">The underpinnings of changelogs, manifests, and filelogs are
  12.149        provided by a single structure called the
  12.150        <emphasis>revlog</emphasis>.</para>
  12.151  
  12.152      <sect2>
  12.153        <title>Efficient storage</title>
  12.154  
  12.155 -      <para>The revlog provides efficient storage of revisions using a
  12.156 +      <para id="x_2f5">The revlog provides efficient storage of revisions using a
  12.157  	<emphasis>delta</emphasis> mechanism.  Instead of storing a
  12.158  	complete copy of a file for each revision, it stores the
  12.159  	changes needed to transform an older revision into the new
  12.160 @@ -141,7 +137,7 @@
  12.161  	typically a fraction of a percent of the size of a full copy
  12.162  	of a file.</para>
  12.163  
  12.164 -      <para>Some obsolete revision control systems can only work with
  12.165 +      <para id="x_2f6">Some obsolete revision control systems can only work with
  12.166  	deltas of text files.  They must either store binary files as
  12.167  	complete snapshots or encoded into a text representation, both
  12.168  	of which are wasteful approaches.  Mercurial can efficiently
  12.169 @@ -149,16 +145,16 @@
  12.170  	doesn't need to treat text as special.</para>
  12.171  
  12.172      </sect2>
  12.173 -    <sect2 id="sec.concepts.txn">
  12.174 +    <sect2 id="sec:concepts:txn">
  12.175        <title>Safe operation</title>
  12.176  
  12.177 -      <para>Mercurial only ever <emphasis>appends</emphasis> data to
  12.178 +      <para id="x_2f7">Mercurial only ever <emphasis>appends</emphasis> data to
  12.179  	the end of a revlog file. It never modifies a section of a
  12.180  	file after it has written it.  This is both more robust and
  12.181  	efficient than schemes that need to modify or rewrite
  12.182  	data.</para>
  12.183  
  12.184 -      <para>In addition, Mercurial treats every write as part of a
  12.185 +      <para id="x_2f8">In addition, Mercurial treats every write as part of a
  12.186  	<emphasis>transaction</emphasis> that can span a number of
  12.187  	files.  A transaction is <emphasis>atomic</emphasis>: either
  12.188  	the entire transaction succeeds and its effects are all
  12.189 @@ -168,7 +164,7 @@
  12.190  	writing it, the reader will never see a partially written
  12.191  	result that might confuse it.</para>
  12.192  
  12.193 -      <para>The fact that Mercurial only appends to files makes it
  12.194 +      <para id="x_2f9">The fact that Mercurial only appends to files makes it
  12.195  	easier to provide this transactional guarantee.  The easier it
  12.196  	is to do stuff like this, the more confident you should be
  12.197  	that it's done correctly.</para>
  12.198 @@ -177,7 +173,7 @@
  12.199      <sect2>
  12.200        <title>Fast retrieval</title>
  12.201  
  12.202 -      <para>Mercurial cleverly avoids a pitfall common to all earlier
  12.203 +      <para id="x_2fa">Mercurial cleverly avoids a pitfall common to all earlier
  12.204  	revision control systems: the problem of <emphasis>inefficient
  12.205  	  retrieval</emphasis>. Most revision control systems store
  12.206  	the contents of a revision as an incremental series of
  12.207 @@ -188,16 +184,15 @@
  12.208  	file accumulates, the more revisions you must read, hence the
  12.209  	longer it takes to reconstruct a particular revision.</para>
  12.210  
  12.211 -      <informalfigure id="fig.concepts.snapshot">
  12.212 -        <mediaobject>
  12.213 -          <imageobject><imagedata fileref="images/snapshot.png"/></imageobject>
  12.214 -          <textobject><phrase>XXX add text</phrase></textobject>
  12.215 -          <caption><para id="fig.concepts.snapshot.caption">Snapshot of
  12.216 -            a revlog, with incremental deltas</para></caption>
  12.217 -        </mediaobject>
  12.218 -      </informalfigure>
  12.219 -
  12.220 -      <para>The innovation that Mercurial applies to this problem is
  12.221 +      <figure id="fig:concepts:snapshot">
  12.222 +	<title>Snapshot of a revlog, with incremental deltas</title>
  12.223 +	<mediaobject>
  12.224 +	  <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject>
  12.225 +	  <textobject><phrase>XXX add text</phrase></textobject>
  12.226 +	</mediaobject>
  12.227 +      </figure>
  12.228 +
  12.229 +      <para id="x_2fc">The innovation that Mercurial applies to this problem is
  12.230  	simple but effective.  Once the cumulative amount of delta
  12.231  	information stored since the last snapshot exceeds a fixed
  12.232  	threshold, it stores a new snapshot (compressed, of course),
  12.233 @@ -206,8 +201,7 @@
  12.234  	quickly.  This approach works so well that it has since been
  12.235  	copied by several other revision control systems.</para>
  12.236  
  12.237 -      <para>Figure <xref endterm="fig.concepts.snapshot.caption"
  12.238 -          linkend="fig.concepts.snapshot"/> illustrates
  12.239 +      <para id="x_2fd"><xref linkend="fig:concepts:snapshot"/> illustrates
  12.240  	the idea.  In an entry in a revlog's index file, Mercurial
  12.241  	stores the range of entries from the data file that it must
  12.242  	read to reconstruct a particular revision.</para>
  12.243 @@ -215,7 +209,7 @@
  12.244        <sect3>
  12.245  	<title>Aside: the influence of video compression</title>
  12.246  
  12.247 -	<para>If you're familiar with video compression or have ever
  12.248 +	<para id="x_2fe">If you're familiar with video compression or have ever
  12.249  	  watched a TV feed through a digital cable or satellite
  12.250  	  service, you may know that most video compression schemes
  12.251  	  store each frame of video as a delta against its predecessor
  12.252 @@ -224,7 +218,7 @@
  12.253  	  visual errors accumulate over the course of a number of
  12.254  	  inter-frame deltas.</para>
  12.255  
  12.256 -	<para>Because it's possible for a video stream to <quote>drop
  12.257 +	<para id="x_2ff">Because it's possible for a video stream to <quote>drop
  12.258  	    out</quote> occasionally due to signal glitches, and to
  12.259  	  limit the accumulation of artefacts introduced by the lossy
  12.260  	  compression process, video encoders periodically insert a
  12.261 @@ -240,24 +234,24 @@
  12.262      <sect2>
  12.263        <title>Identification and strong integrity</title>
  12.264  
  12.265 -      <para>Along with delta or snapshot information, a revlog entry
  12.266 +      <para id="x_300">Along with delta or snapshot information, a revlog entry
  12.267  	contains a cryptographic hash of the data that it represents.
  12.268  	This makes it difficult to forge the contents of a revision,
  12.269  	and easy to detect accidental corruption.</para>
  12.270  
  12.271 -      <para>Hashes provide more than a mere check against corruption;
  12.272 +      <para id="x_301">Hashes provide more than a mere check against corruption;
  12.273  	they are used as the identifiers for revisions.  The changeset
  12.274  	identification hashes that you see as an end user are from
  12.275  	revisions of the changelog.  Although filelogs and the
  12.276  	manifest also use hashes, Mercurial only uses these behind the
  12.277  	scenes.</para>
  12.278  
  12.279 -      <para>Mercurial verifies that hashes are correct when it
  12.280 +      <para id="x_302">Mercurial verifies that hashes are correct when it
  12.281  	retrieves file revisions and when it pulls changes from
  12.282  	another repository.  If it encounters an integrity problem, it
  12.283  	will complain and stop whatever it's doing.</para>
  12.284  
  12.285 -      <para>In addition to the effect it has on retrieval efficiency,
  12.286 +      <para id="x_303">In addition to the effect it has on retrieval efficiency,
  12.287  	Mercurial's use of periodic snapshots makes it more robust
  12.288  	against partial data corruption.  If a revlog becomes partly
  12.289  	corrupted due to a hardware error or system bug, it's often
  12.290 @@ -271,7 +265,7 @@
  12.291    <sect1>
  12.292      <title>Revision history, branching, and merging</title>
  12.293  
  12.294 -    <para>Every entry in a Mercurial revlog knows the identity of its
  12.295 +    <para id="x_304">Every entry in a Mercurial revlog knows the identity of its
  12.296        immediate ancestor revision, usually referred to as its
  12.297        <emphasis>parent</emphasis>.  In fact, a revision contains room
  12.298        for not one parent, but two.  Mercurial uses a special hash,
  12.299 @@ -279,14 +273,13 @@
  12.300        <quote>there is no parent here</quote>.  This hash is simply a
  12.301        string of zeroes.</para>
  12.302  
  12.303 -    <para>In figure <xref endterm="fig.concepts.revlog.caption"
  12.304 -        linkend="fig.concepts.revlog"/>, you can see
  12.305 +    <para id="x_305">In <xref linkend="fig:concepts:revlog"/>, you can see
  12.306        an example of the conceptual structure of a revlog.  Filelogs,
  12.307        manifests, and changelogs all have this same structure; they
  12.308        differ only in the kind of data stored in each delta or
  12.309        snapshot.</para>
  12.310  
  12.311 -    <para>The first revision in a revlog (at the bottom of the image)
  12.312 +    <para id="x_306">The first revision in a revlog (at the bottom of the image)
  12.313        has the null ID in both of its parent slots.  For a
  12.314        <quote>normal</quote> revision, its first parent slot contains
  12.315        the ID of its parent revision, and its second contains the null
  12.316 @@ -295,23 +288,22 @@
  12.317        revision that represents a merge between branches has two normal
  12.318        revision IDs in its parent slots.</para>
  12.319  
  12.320 -    <informalfigure id="fig.concepts.revlog">
  12.321 +    <figure id="fig:concepts:revlog">
  12.322 +      <title>The conceptual structure of a revlog</title>
  12.323        <mediaobject>
  12.324 -        <imageobject><imagedata fileref="images/revlog.png"/></imageobject>
  12.325 -        <textobject><phrase>XXX add text</phrase></textobject>        
  12.326 -	<caption><para id="fig.concepts.revlog.caption">Revision in revlog</para>
  12.327 -	</caption>
  12.328 +	<imageobject><imagedata fileref="figs/revlog.png"/></imageobject>
  12.329 +	<textobject><phrase>XXX add text</phrase></textobject>
  12.330        </mediaobject>
  12.331 -    </informalfigure>
  12.332 +    </figure>
  12.333  
  12.334    </sect1>
  12.335    <sect1>
  12.336      <title>The working directory</title>
  12.337  
  12.338 -    <para>In the working directory, Mercurial stores a snapshot of the
  12.339 +    <para id="x_307">In the working directory, Mercurial stores a snapshot of the
  12.340        files from the repository as of a particular changeset.</para>
  12.341  
  12.342 -    <para>The working directory <quote>knows</quote> which changeset
  12.343 +    <para id="x_308">The working directory <quote>knows</quote> which changeset
  12.344        it contains.  When you update the working directory to contain a
  12.345        particular changeset, Mercurial looks up the appropriate
  12.346        revision of the manifest to find out which files it was tracking
  12.347 @@ -320,13 +312,13 @@
  12.348        those files, with the same contents it had when the changeset
  12.349        was committed.</para>
  12.350  
  12.351 -    <para>The <emphasis>dirstate</emphasis> contains Mercurial's
  12.352 +    <para id="x_309">The <emphasis>dirstate</emphasis> contains Mercurial's
  12.353        knowledge of the working directory.  This details which
  12.354        changeset the working directory is updated to, and all of the
  12.355        files that Mercurial is tracking in the working
  12.356        directory.</para>
  12.357  
  12.358 -    <para>Just as a revision of a revlog has room for two parents, so
  12.359 +    <para id="x_30a">Just as a revision of a revlog has room for two parents, so
  12.360        that it can represent either a normal revision (with one parent)
  12.361        or a merge of two earlier revisions, the dirstate has slots for
  12.362        two parents.  When you use the <command role="hg-cmd">hg
  12.363 @@ -342,38 +334,35 @@
  12.364      <sect2>
  12.365        <title>What happens when you commit</title>
  12.366  
  12.367 -      <para>The dirstate stores parent information for more than just
  12.368 +      <para id="x_30b">The dirstate stores parent information for more than just
  12.369  	book-keeping purposes.  Mercurial uses the parents of the
  12.370  	dirstate as <emphasis>the parents of a new
  12.371  	  changeset</emphasis> when you perform a commit.</para>
  12.372  
  12.373 -      <informalfigure id="fig.concepts.wdir">
  12.374 -        <mediaobject>
  12.375 -          <imageobject><imagedata fileref="images/wdir.png"/></imageobject>
  12.376 -          <textobject><phrase>XXX add text</phrase></textobject>
  12.377 -          <caption><para id="fig.concepts.wdir.caption">The working
  12.378 -            directory can have two parents</para></caption>
  12.379 -        </mediaobject>
  12.380 -      </informalfigure>
  12.381 -
  12.382 -      <para>Figure <xref endterm="fig.concepts.wdir.caption"
  12.383 -          linkend="fig.concepts.wdir"/> shows the
  12.384 +      <figure id="fig:concepts:wdir">
  12.385 +	<title>The working directory can have two parents</title>
  12.386 +	<mediaobject>
  12.387 +	  <imageobject><imagedata fileref="figs/wdir.png"/></imageobject>
  12.388 +	  <textobject><phrase>XXX add text</phrase></textobject>
  12.389 +	</mediaobject>
  12.390 +      </figure>
  12.391 +
  12.392 +      <para id="x_30d"><xref linkend="fig:concepts:wdir"/> shows the
  12.393  	normal state of the working directory, where it has a single
  12.394  	changeset as parent.  That changeset is the
  12.395  	<emphasis>tip</emphasis>, the newest changeset in the
  12.396  	repository that has no children.</para>
  12.397  
  12.398 -      <informalfigure id="fig.concepts.wdir-after-commit">
  12.399 -        <mediaobject>
  12.400 -          <imageobject><imagedata fileref="images/wdir-after-commit.png"/>
  12.401 -          </imageobject>
  12.402 -          <textobject><phrase>XXX add text</phrase></textobject>
  12.403 -          <caption><para id="fig.concepts.wdir-after-commit.caption">The working
  12.404 -            directory gains new parents after a commit</para></caption>
  12.405 -        </mediaobject>
  12.406 -      </informalfigure>
  12.407 -
  12.408 -      <para>It's useful to think of the working directory as
  12.409 +      <figure id="fig:concepts:wdir-after-commit">
  12.410 +	<title>The working directory gains new parents after a
  12.411 +	  commit</title>
  12.412 +	<mediaobject>
  12.413 +	  <imageobject><imagedata fileref="figs/wdir-after-commit.png"/></imageobject>
  12.414 +	  <textobject><phrase>XXX add text</phrase></textobject>
  12.415 +	</mediaobject>
  12.416 +      </figure>
  12.417 +
  12.418 +      <para id="x_30f">It's useful to think of the working directory as
  12.419  	<quote>the changeset I'm about to commit</quote>.  Any files
  12.420  	that you tell Mercurial that you've added, removed, renamed,
  12.421  	or copied will be reflected in that changeset, as will
  12.422 @@ -381,12 +370,11 @@
  12.423  	the new changeset will have the parents of the working
  12.424  	directory as its parents.</para>
  12.425  
  12.426 -      <para>After a commit, Mercurial will update the parents of the
  12.427 -	working directory, so that the first parent is the ID of the
  12.428 -	new changeset, and the second is the null ID.  This is shown
  12.429 -	in figure <xref endterm="fig.concepts.wdir-after-commit.caption"
  12.430 -	  linkend="fig.concepts.wdir-after-commit"/>.
  12.431 -	Mercurial
  12.432 +      <para id="x_310">After a commit, Mercurial will update the
  12.433 +	parents of the working directory, so that the first parent is
  12.434 +	the ID of the new changeset, and the second is the null ID.
  12.435 +	This is shown in <xref
  12.436 +	  linkend="fig:concepts:wdir-after-commit"/>. Mercurial
  12.437  	doesn't touch any of the files in the working directory when
  12.438  	you commit; it just modifies the dirstate to note its new
  12.439  	parents.</para>
  12.440 @@ -395,7 +383,7 @@
  12.441      <sect2>
  12.442        <title>Creating a new head</title>
  12.443  
  12.444 -      <para>It's perfectly normal to update the working directory to a
  12.445 +      <para id="x_311">It's perfectly normal to update the working directory to a
  12.446  	changeset other than the current tip.  For example, you might
  12.447  	want to know what your project looked like last Tuesday, or
  12.448  	you could be looking through changesets to see which one
  12.449 @@ -404,43 +392,39 @@
  12.450  	interested in, and then examine the files in the working
  12.451  	directory directly to see their contents as they were when you
  12.452  	committed that changeset.  The effect of this is shown in
  12.453 -	figure <xref endterm="fig.concepts.wdir-pre-branch.caption"
  12.454 -	  linkend="fig.concepts.wdir-pre-branch"/>.</para>
  12.455 -
  12.456 -      <informalfigure id="fig.concepts.wdir-pre-branch">
  12.457 -        <mediaobject>
  12.458 -          <imageobject><imagedata fileref="images/wdir-pre-branch.png"/>
  12.459 -          </imageobject>
  12.460 -          <textobject><phrase>XXX add text</phrase></textobject>
  12.461 -          <caption><para id="fig.concepts.wdir-pre-branch.caption">The working
  12.462 -            directory, updated to an older changeset</para></caption>
  12.463 -        </mediaobject>
  12.464 -      </informalfigure>
  12.465 -
  12.466 -      <para>Having updated the working directory to an older
  12.467 -	changeset, what happens if you make some changes, and then
  12.468 -	commit?  Mercurial behaves in the same way as I outlined
  12.469 +	<xref linkend="fig:concepts:wdir-pre-branch"/>.</para>
  12.470 +
  12.471 +      <figure id="fig:concepts:wdir-pre-branch">
  12.472 +	<title>The working directory, updated to an older
  12.473 +	  changeset</title>
  12.474 +	<mediaobject>
  12.475 +	  <imageobject><imagedata fileref="figs/wdir-pre-branch.png"/></imageobject>
  12.476 +	  <textobject><phrase>XXX add text</phrase></textobject>
  12.477 +	</mediaobject>
  12.478 +      </figure>
  12.479 +
  12.480 +      <para id="x_313">Having updated the working directory to an
  12.481 +	older changeset, what happens if you make some changes, and
  12.482 +	then commit?  Mercurial behaves in the same way as I outlined
  12.483  	above.  The parents of the working directory become the
  12.484  	parents of the new changeset.  This new changeset has no
  12.485  	children, so it becomes the new tip.  And the repository now
  12.486  	contains two changesets that have no children; we call these
  12.487  	<emphasis>heads</emphasis>.  You can see the structure that
  12.488 -	this creates in figure <xref
  12.489 -	  endterm="fig.concepts.wdir-branch.caption"
  12.490 -	  linkend="fig.concepts.wdir-branch"/>.</para>
  12.491 -
  12.492 -      <informalfigure id="fig.concepts.wdir-branch">
  12.493 -        <mediaobject>
  12.494 -          <imageobject><imagedata fileref="images/wdir-branch.png"/>
  12.495 -          </imageobject>
  12.496 -          <textobject><phrase>XXX add text</phrase></textobject>
  12.497 -          <caption><para id="fig.concepts.wdir-branch.caption">After a
  12.498 -            commit made while synced to an older changeset</para></caption>
  12.499 -        </mediaobject>
  12.500 -      </informalfigure>
  12.501 +	this creates in <xref
  12.502 +	  linkend="fig:concepts:wdir-branch"/>.</para>
  12.503 +
  12.504 +      <figure id="fig:concepts:wdir-branch">
  12.505 +	<title>After a commit made while synced to an older
  12.506 +	  changeset</title>
  12.507 +	<mediaobject>
  12.508 +	  <imageobject><imagedata fileref="figs/wdir-branch.png"/></imageobject>
  12.509 +	  <textobject><phrase>XXX add text</phrase></textobject>
  12.510 +	</mediaobject>
  12.511 +      </figure>
  12.512  
  12.513        <note>
  12.514 -	<para>  If you're new to Mercurial, you should keep in mind a
  12.515 +	<para id="x_315">  If you're new to Mercurial, you should keep in mind a
  12.516  	  common <quote>error</quote>, which is to use the <command
  12.517  	    role="hg-cmd">hg pull</command> command without any
  12.518  	  options.  By default, the <command role="hg-cmd">hg
  12.519 @@ -452,7 +436,7 @@
  12.520  	  a new head, because your working directory isn't synced to
  12.521  	  whatever the current tip is.</para>
  12.522  
  12.523 -	<para>  I put the word <quote>error</quote> in quotes because
  12.524 +	<para id="x_316">  I put the word <quote>error</quote> in quotes because
  12.525  	  all that you need to do to rectify this situation is
  12.526  	  <command role="hg-cmd">hg merge</command>, then <command
  12.527  	    role="hg-cmd">hg commit</command>.  In other words, this
  12.528 @@ -466,67 +450,66 @@
  12.529      <sect2>
  12.530        <title>Merging heads</title>
  12.531  
  12.532 -      <para>When you run the <command role="hg-cmd">hg merge</command>
  12.533 -	command, Mercurial leaves the first parent of the working
  12.534 -	directory unchanged, and sets the second parent to the
  12.535 -	changeset you're merging with, as shown in figure <xref
  12.536 -	  endterm="fig.concepts.wdir-merge.caption" 
  12.537 -	  linkend="fig.concepts.wdir-merge"/>.</para>
  12.538 -
  12.539 -      <informalfigure id="fig.concepts.wdir-merge">
  12.540 -        <mediaobject>
  12.541 -          <imageobject><imagedata fileref="images/wdir-merge.png"/>
  12.542 -          </imageobject>
  12.543 -          <textobject><phrase>XXX add text</phrase></textobject>
  12.544 -          <caption><para id="fig.concepts.wdir-merge.caption">Merging two
  12.545 -            heads</para></caption>
  12.546 -        </mediaobject>
  12.547 -      </informalfigure>
  12.548 -
  12.549 -      <para>Mercurial also has to modify the working directory, to
  12.550 +      <para id="x_317">When you run the <command role="hg-cmd">hg
  12.551 +	  merge</command> command, Mercurial leaves the first parent
  12.552 +	of the working directory unchanged, and sets the second parent
  12.553 +	to the changeset you're merging with, as shown in <xref
  12.554 +	  linkend="fig:concepts:wdir-merge"/>.</para>
  12.555 +
  12.556 +      <figure id="fig:concepts:wdir-merge">
  12.557 +	<title>Merging two heads</title>
  12.558 +	<mediaobject>
  12.559 +	  <imageobject>
  12.560 +	    <imagedata fileref="figs/wdir-merge.png"/>
  12.561 +	  </imageobject>
  12.562 +	  <textobject><phrase>XXX add text</phrase></textobject>
  12.563 +	</mediaobject>
  12.564 +      </figure>
  12.565 +
  12.566 +      <para id="x_319">Mercurial also has to modify the working directory, to
  12.567  	merge the files managed in the two changesets.  Simplified a
  12.568  	little, the merging process goes like this, for every file in
  12.569  	the manifests of both changesets.</para>
  12.570        <itemizedlist>
  12.571 -	<listitem><para>If neither changeset has modified a file, do
  12.572 +	<listitem><para id="x_31a">If neither changeset has modified a file, do
  12.573  	    nothing with that file.</para>
  12.574  	</listitem>
  12.575 -	<listitem><para>If one changeset has modified a file, and the
  12.576 +	<listitem><para id="x_31b">If one changeset has modified a file, and the
  12.577  	    other hasn't, create the modified copy of the file in the
  12.578  	    working directory.</para>
  12.579  	</listitem>
  12.580 -	<listitem><para>If one changeset has removed a file, and the
  12.581 +	<listitem><para id="x_31c">If one changeset has removed a file, and the
  12.582  	    other hasn't (or has also deleted it), delete the file
  12.583  	    from the working directory.</para>
  12.584  	</listitem>
  12.585 -	<listitem><para>If one changeset has removed a file, but the
  12.586 +	<listitem><para id="x_31d">If one changeset has removed a file, but the
  12.587  	    other has modified the file, ask the user what to do: keep
  12.588  	    the modified file, or remove it?</para>
  12.589  	</listitem>
  12.590 -	<listitem><para>If both changesets have modified a file,
  12.591 +	<listitem><para id="x_31e">If both changesets have modified a file,
  12.592  	    invoke an external merge program to choose the new
  12.593  	    contents for the merged file.  This may require input from
  12.594  	    the user.</para>
  12.595  	</listitem>
  12.596 -	<listitem><para>If one changeset has modified a file, and the
  12.597 +	<listitem><para id="x_31f">If one changeset has modified a file, and the
  12.598  	    other has renamed or copied the file, make sure that the
  12.599  	    changes follow the new name of the file.</para>
  12.600  	</listitem></itemizedlist>
  12.601 -      <para>There are more details&emdash;merging has plenty of corner
  12.602 +      <para id="x_320">There are more details&emdash;merging has plenty of corner
  12.603  	cases&emdash;but these are the most common choices that are
  12.604  	involved in a merge.  As you can see, most cases are
  12.605  	completely automatic, and indeed most merges finish
  12.606  	automatically, without requiring your input to resolve any
  12.607  	conflicts.</para>
  12.608  
  12.609 -      <para>When you're thinking about what happens when you commit
  12.610 +      <para id="x_321">When you're thinking about what happens when you commit
  12.611  	after a merge, once again the working directory is <quote>the
  12.612  	  changeset I'm about to commit</quote>.  After the <command
  12.613  	  role="hg-cmd">hg merge</command> command completes, the
  12.614  	working directory has two parents; these will become the
  12.615  	parents of the new changeset.</para>
  12.616  
  12.617 -      <para>Mercurial lets you perform multiple merges, but you must
  12.618 +      <para id="x_322">Mercurial lets you perform multiple merges, but you must
  12.619  	commit the results of each individual merge as you go.  This
  12.620  	is necessary because Mercurial only tracks two parents for
  12.621  	both revisions and the working directory.  While it would be
  12.622 @@ -539,7 +522,7 @@
  12.623    <sect1>
  12.624      <title>Other interesting design features</title>
  12.625  
  12.626 -    <para>In the sections above, I've tried to highlight some of the
  12.627 +    <para id="x_323">In the sections above, I've tried to highlight some of the
  12.628        most important aspects of Mercurial's design, to illustrate that
  12.629        it pays careful attention to reliability and performance.
  12.630        However, the attention to detail doesn't stop there.  There are
  12.631 @@ -552,13 +535,13 @@
  12.632      <sect2>
  12.633        <title>Clever compression</title>
  12.634  
  12.635 -      <para>When appropriate, Mercurial will store both snapshots and
  12.636 +      <para id="x_324">When appropriate, Mercurial will store both snapshots and
  12.637  	deltas in compressed form.  It does this by always
  12.638  	<emphasis>trying to</emphasis> compress a snapshot or delta,
  12.639  	but only storing the compressed version if it's smaller than
  12.640  	the uncompressed version.</para>
  12.641  
  12.642 -      <para>This means that Mercurial does <quote>the right
  12.643 +      <para id="x_325">This means that Mercurial does <quote>the right
  12.644  	  thing</quote> when storing a file whose native form is
  12.645  	compressed, such as a <literal>zip</literal> archive or a JPEG
  12.646  	image.  When these types of files are compressed a second
  12.647 @@ -566,7 +549,7 @@
  12.648  	once-compressed form, and so Mercurial will store the plain
  12.649  	<literal>zip</literal> or JPEG.</para>
  12.650  
  12.651 -      <para>Deltas between revisions of a compressed file are usually
  12.652 +      <para id="x_326">Deltas between revisions of a compressed file are usually
  12.653  	larger than snapshots of the file, and Mercurial again does
  12.654  	<quote>the right thing</quote> in these cases.  It finds that
  12.655  	such a delta exceeds the threshold at which it should store a
  12.656 @@ -577,7 +560,7 @@
  12.657        <sect3>
  12.658  	<title>Network recompression</title>
  12.659  
  12.660 -	<para>When storing revisions on disk, Mercurial uses the
  12.661 +	<para id="x_327">When storing revisions on disk, Mercurial uses the
  12.662  	  <quote>deflate</quote> compression algorithm (the same one
  12.663  	  used by the popular <literal>zip</literal> archive format),
  12.664  	  which balances good speed with a respectable compression
  12.665 @@ -585,7 +568,7 @@
  12.666  	  network connection, Mercurial uncompresses the compressed
  12.667  	  revision data.</para>
  12.668  
  12.669 -	<para>If the connection is over HTTP, Mercurial recompresses
  12.670 +	<para id="x_328">If the connection is over HTTP, Mercurial recompresses
  12.671  	  the entire stream of data using a compression algorithm that
  12.672  	  gives a better compression ratio (the Burrows-Wheeler
  12.673  	  algorithm from the widely used <literal>bzip2</literal>
  12.674 @@ -595,7 +578,7 @@
  12.675  	  transferred, yielding better network performance over almost
  12.676  	  all kinds of network.</para>
  12.677  
  12.678 -	<para>(If the connection is over <command>ssh</command>,
  12.679 +	<para id="x_329">(If the connection is over <command>ssh</command>,
  12.680  	  Mercurial <emphasis>doesn't</emphasis> recompress the
  12.681  	  stream, because <command>ssh</command> can already do this
  12.682  	  itself.)</para>
  12.683 @@ -605,20 +588,20 @@
  12.684      <sect2>
  12.685        <title>Read/write ordering and atomicity</title>
  12.686  
  12.687 -      <para>Appending to files isn't the whole story when it comes to
  12.688 -	guaranteeing that a reader won't see a partial write.  If you
  12.689 -	recall figure <xref endterm="fig.concepts.metadata.caption"
  12.690 -	linkend="fig.concepts.metadata"/>, revisions in the
  12.691 -	changelog point to revisions in the manifest, and revisions in
  12.692 -	the manifest point to revisions in filelogs.  This hierarchy
  12.693 -	is deliberate.</para>
  12.694 -
  12.695 -      <para>A writer starts a transaction by writing filelog and
  12.696 +      <para id="x_32a">Appending to files isn't the whole story when
  12.697 +	it comes to guaranteeing that a reader won't see a partial
  12.698 +	write.  If you recall <xref linkend="fig:concepts:metadata"/>,
  12.699 +	revisions in
  12.700 +	the changelog point to revisions in the manifest, and
  12.701 +	revisions in the manifest point to revisions in filelogs.
  12.702 +	This hierarchy is deliberate.</para>
  12.703 +
  12.704 +      <para id="x_32b">A writer starts a transaction by writing filelog and
  12.705  	manifest data, and doesn't write any changelog data until
  12.706  	those are finished.  A reader starts by reading changelog
  12.707  	data, then manifest data, followed by filelog data.</para>
  12.708  
  12.709 -      <para>Since the writer has always finished writing filelog and
  12.710 +      <para id="x_32c">Since the writer has always finished writing filelog and
  12.711  	manifest data before it writes to the changelog, a reader will
  12.712  	never read a pointer to a partially written manifest revision
  12.713  	from the changelog, and it will never read a pointer to a
  12.714 @@ -628,7 +611,7 @@
  12.715      <sect2>
  12.716        <title>Concurrent access</title>
  12.717  
  12.718 -      <para>The read/write ordering and atomicity guarantees mean that
  12.719 +      <para id="x_32d">The read/write ordering and atomicity guarantees mean that
  12.720  	Mercurial never needs to <emphasis>lock</emphasis> a
  12.721  	repository when it's reading data, even if the repository is
  12.722  	being written to while the read is occurring. This has a big
  12.723 @@ -637,7 +620,7 @@
  12.724  	safely all at once, no matter whether it's being written to or
  12.725  	not.</para>
  12.726  
  12.727 -      <para>The lockless nature of reading means that if you're
  12.728 +      <para id="x_32e">The lockless nature of reading means that if you're
  12.729  	sharing a repository on a multi-user system, you don't need to
  12.730  	grant other local users permission to
  12.731  	<emphasis>write</emphasis> to your repository in order for
  12.732 @@ -650,7 +633,7 @@
  12.733  	which of course makes for all kinds of nasty and annoying
  12.734  	security and administrative problems.)</para>
  12.735  
  12.736 -      <para>Mercurial uses locks to ensure that only one process can
  12.737 +      <para id="x_32f">Mercurial uses locks to ensure that only one process can
  12.738  	write to a repository at a time (the locking mechanism is safe
  12.739  	even over filesystems that are notoriously hostile to locking,
  12.740  	such as NFS).  If a repository is locked, a writer will wait
  12.741 @@ -664,7 +647,7 @@
  12.742        <sect3>
  12.743  	<title>Safe dirstate access</title>
  12.744  
  12.745 -	<para>As with revision data, Mercurial doesn't take a lock to
  12.746 +	<para id="x_330">As with revision data, Mercurial doesn't take a lock to
  12.747  	  read the dirstate file; it does acquire a lock to write it.
  12.748  	  To avoid the possibility of reading a partially written copy
  12.749  	  of the dirstate file, Mercurial writes to a file with a
  12.750 @@ -679,17 +662,17 @@
  12.751      <sect2>
  12.752        <title>Avoiding seeks</title>
  12.753  
  12.754 -      <para>Critical to Mercurial's performance is the avoidance of
  12.755 +      <para id="x_331">Critical to Mercurial's performance is the avoidance of
  12.756  	seeks of the disk head, since any seek is far more expensive
  12.757  	than even a comparatively large read operation.</para>
  12.758  
  12.759 -      <para>This is why, for example, the dirstate is stored in a
  12.760 +      <para id="x_332">This is why, for example, the dirstate is stored in a
  12.761  	single file.  If there were a dirstate file per directory that
  12.762  	Mercurial tracked, the disk would seek once per directory.
  12.763  	Instead, Mercurial reads the entire single dirstate file in
  12.764  	one step.</para>
  12.765  
  12.766 -      <para>Mercurial also uses a <quote>copy on write</quote> scheme
  12.767 +      <para id="x_333">Mercurial also uses a <quote>copy on write</quote> scheme
  12.768  	when cloning a repository on local storage.  Instead of
  12.769  	copying every revlog file from the old repository into the new
  12.770  	repository, it makes a <quote>hard link</quote>, which is a
  12.771 @@ -700,7 +683,7 @@
  12.772  	one repository is using the file, so Mercurial makes a new
  12.773  	copy of the file that is private to this repository.</para>
  12.774  
  12.775 -      <para>A few revision control developers have pointed out that
  12.776 +      <para id="x_334">A few revision control developers have pointed out that
  12.777  	this idea of making a complete private copy of a file is not
  12.778  	very efficient in its use of storage.  While this is true,
  12.779  	storage is cheap, and this method gives the highest
  12.780 @@ -714,21 +697,21 @@
  12.781      <sect2>
  12.782        <title>Other contents of the dirstate</title>
  12.783  
  12.784 -      <para>Because Mercurial doesn't force you to tell it when you're
  12.785 +      <para id="x_335">Because Mercurial doesn't force you to tell it when you're
  12.786  	modifying a file, it uses the dirstate to store some extra
  12.787  	information so it can determine efficiently whether you have
  12.788  	modified a file.  For each file in the working directory, it
  12.789  	stores the time that it last modified the file itself, and the
  12.790  	size of the file at that time.</para>
  12.791  
  12.792 -      <para>When you explicitly <command role="hg-cmd">hg
  12.793 +      <para id="x_336">When you explicitly <command role="hg-cmd">hg
  12.794  	  add</command>, <command role="hg-cmd">hg remove</command>,
  12.795  	<command role="hg-cmd">hg rename</command> or <command
  12.796  	  role="hg-cmd">hg copy</command> files, Mercurial updates the
  12.797  	dirstate so that it knows what to do with those files when you
  12.798  	commit.</para>
  12.799  
  12.800 -      <para>When Mercurial is checking the states of files in the
  12.801 +      <para id="x_337">When Mercurial is checking the states of files in the
  12.802  	working directory, it first checks a file's modification time.
  12.803  	If that has not changed, the file must not have been modified.
  12.804  	If the file's size has changed, the file must have been

    13.1 --- a/en/ch04-daily.xml	Fri Mar 20 17:17:55 2009 +0800
    13.2 +++ b/en/ch04-daily.xml	Mon Mar 30 16:23:33 2009 +0800
    13.3 @@ -1,6 +1,6 @@
    13.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    13.5  
    13.6 -<chapter id="chap.daily">
    13.7 +<chapter id="chap:daily">
    13.8    <?dbhtml filename="mercurial-in-daily-use.html"?>
    13.9    <title>Mercurial in daily use</title>
   13.10  
   13.11 @@ -274,7 +274,7 @@
   13.12        &interaction.daily.copy.merge;
   13.13  
   13.14      </sect2>
   13.15 -    <sect2 id="sec.daily.why-copy">
   13.16 +    <sect2 id="sec:daily:why-copy">
   13.17        <title>Why should changes follow copies?</title>
   13.18  
   13.19        <para id="x_1c4">This behaviour, of changes to a file propagating out to
   13.20 @@ -328,7 +328,7 @@
   13.21  	Unix-like systems, that's <command>cp</command>) to make a
   13.22  	copy of a file, then <command role="hg-cmd">hg add</command>
   13.23  	the new copy by hand.  Before you do so, though, please do
   13.24 -	reread section <xref linkend="sec.daily.why-copy"/>, and make
   13.25 +	reread <xref linkend="sec:daily:why-copy"/>, and make
   13.26  	an informed
   13.27  	decision that this behaviour is not appropriate to your
   13.28  	specific case.</para>
   13.29 @@ -529,10 +529,10 @@
   13.30        decide it was a mistake, you can still do something about it,
   13.31        though your options may be more limited.</para>
   13.32  
   13.33 -    <para id="x_1e5">For more information about the <command role="hg-cmd">hg
   13.34 -	revert</command> command, and details about how to deal with
   13.35 -      changes you have already committed, see chapter <xref
   13.36 -	linkend="chap.undo"/>.</para>
   13.37 +    <para id="x_1e5">For more information about the <command
   13.38 +	role="hg-cmd">hg revert</command> command, and details about
   13.39 +      how to deal with changes you have already committed, see <xref
   13.40 +	linkend="chap:undo"/>.</para>
   13.41  
   13.42    </sect1>
   13.43  </chapter>

    14.1 --- a/en/ch05-collab.xml	Fri Mar 20 17:17:55 2009 +0800
    14.2 +++ b/en/ch05-collab.xml	Mon Mar 30 16:23:33 2009 +0800
    14.3 @@ -1,10 +1,10 @@
    14.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    14.5  
    14.6 -<chapter id="cha.collab">
    14.7 +<chapter id="cha:collab">
    14.8    <?dbhtml filename="collaborating-with-other-people.html"?>
    14.9    <title>Collaborating with other people</title>
   14.10  
   14.11 -  <para>As a completely decentralised tool, Mercurial doesn't impose
   14.12 +  <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
   14.13      any policy on how people ought to work with each other.  However,
   14.14      if you're new to distributed revision control, it helps to have
   14.15      some tools and examples in mind when you're thinking about
   14.16 @@ -13,15 +13,15 @@
   14.17    <sect1>
   14.18      <title>Mercurial's web interface</title>
   14.19  
   14.20 -    <para>Mercurial has a powerful web interface that provides several
   14.21 +    <para id="x_44b">Mercurial has a powerful web interface that provides several
   14.22        useful capabilities.</para>
   14.23  
   14.24 -    <para>For interactive use, the web interface lets you browse a
   14.25 +    <para id="x_44c">For interactive use, the web interface lets you browse a
   14.26        single repository or a collection of repositories.  You can view
   14.27        the history of a repository, examine each change (comments and
   14.28        diffs), and view the contents of each directory and file.</para>
   14.29  
   14.30 -    <para>Also for human consumption, the web interface provides an
   14.31 +    <para id="x_44d">Also for human consumption, the web interface provides an
   14.32        RSS feed of the changes in a repository.  This lets you
   14.33        <quote>subscribe</quote> to a repository using your favourite
   14.34        feed reader, and be automatically notified of activity in that
   14.35 @@ -31,35 +31,35 @@
   14.36        configuration on the part of whoever is serving the
   14.37        repository.</para>
   14.38  
   14.39 -    <para>The web interface also lets remote users clone a repository,
   14.40 +    <para id="x_44e">The web interface also lets remote users clone a repository,
   14.41        pull changes from it, and (when the server is configured to
   14.42        permit it) push changes back to it.  Mercurial's HTTP tunneling
   14.43        protocol aggressively compresses data, so that it works
   14.44        efficiently even over low-bandwidth network connections.</para>
   14.45  
   14.46 -    <para>The easiest way to get started with the web interface is to
   14.47 +    <para id="x_44f">The easiest way to get started with the web interface is to
   14.48        use your web browser to visit an existing repository, such as
   14.49        the master Mercurial repository at <ulink
   14.50  	url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
   14.51  
   14.52 -    <para>If you're interested in providing a web interface to your
   14.53 -      own repositories, Mercurial provides two ways to do this.  The
   14.54 -      first is using the <command role="hg-cmd">hg serve</command>
   14.55 -      command, which is best suited to short-term
   14.56 -      <quote>lightweight</quote> serving.  See section <xref
   14.57 -	linkend="sec.collab.serve"/> below for details of how to use
   14.58 +    <para id="x_450">If you're interested in providing a web interface
   14.59 +      to your own repositories, Mercurial provides two ways to do
   14.60 +      this.  The first is using the <command role="hg-cmd">hg
   14.61 +	serve</command> command, which is best suited to short-term
   14.62 +      <quote>lightweight</quote> serving.  See <xref
   14.63 +	linkend="sec:collab:serve"/> below for details of how to use
   14.64        this command.  If you have a long-lived repository that you'd
   14.65        like to make permanently available, Mercurial has built-in
   14.66        support for the CGI (Common Gateway Interface) standard, which
   14.67 -      all common web servers support.  See section <xref
   14.68 -	linkend="sec.collab.cgi"/> for details of CGI
   14.69 +      all common web servers support.  See <xref
   14.70 +	linkend="sec:collab:cgi"/> for details of CGI
   14.71        configuration.</para>
   14.72  
   14.73    </sect1>
   14.74    <sect1>
   14.75      <title>Collaboration models</title>
   14.76  
   14.77 -    <para>With a suitably flexible tool, making decisions about
   14.78 +    <para id="x_451">With a suitably flexible tool, making decisions about
   14.79        workflow is much more of a social engineering challenge than a
   14.80        technical one. Mercurial imposes few limitations on how you can
   14.81        structure the flow of work in a project, so it's up to you and
   14.82 @@ -69,13 +69,13 @@
   14.83      <sect2>
   14.84        <title>Factors to keep in mind</title>
   14.85  
   14.86 -      <para>The most important aspect of any model that you must keep
   14.87 +      <para id="x_452">The most important aspect of any model that you must keep
   14.88  	in mind is how well it matches the needs and capabilities of
   14.89  	the people who will be using it.  This might seem
   14.90  	self-evident; even so, you still can't afford to forget it for
   14.91  	a moment.</para>
   14.92  
   14.93 -      <para>I once put together a workflow model that seemed to make
   14.94 +      <para id="x_453">I once put together a workflow model that seemed to make
   14.95  	perfect sense to me, but that caused a considerable amount of
   14.96  	consternation and strife within my development team.  In spite
   14.97  	of my attempts to explain why we needed a complex set of
   14.98 @@ -85,7 +85,7 @@
   14.99  	operating under, or face the consequences of those constraints
  14.100  	in the details of the model that I was advocating.</para>
  14.101  
  14.102 -      <para>Don't sweep foreseeable social or technical problems under
  14.103 +      <para id="x_454">Don't sweep foreseeable social or technical problems under
  14.104  	the rug. Whatever scheme you put into effect, you should plan
  14.105  	for mistakes and problem scenarios.  Consider adding automated
  14.106  	machinery to prevent, or quickly recover from, trouble that
  14.107 @@ -101,12 +101,12 @@
  14.108      <sect2>
  14.109        <title>Informal anarchy</title>
  14.110  
  14.111 -      <para>I wouldn't suggest an <quote>anything goes</quote>
  14.112 +      <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
  14.113  	approach as something sustainable, but it's a model that's
  14.114  	easy to grasp, and it works perfectly well in a few unusual
  14.115  	situations.</para>
  14.116  
  14.117 -      <para>As one example, many projects have a loose-knit group of
  14.118 +      <para id="x_456">As one example, many projects have a loose-knit group of
  14.119  	collaborators who rarely physically meet each other.  Some
  14.120  	groups like to overcome the isolation of working at a distance
  14.121  	by organising occasional <quote>sprints</quote>.  In a sprint,
  14.122 @@ -115,21 +115,21 @@
  14.123  	place) and spend several days more or less locked in there,
  14.124  	hacking intensely on a handful of projects.</para>
  14.125  
  14.126 -      <para>A sprint is the perfect place to use the <command
  14.127 -	  role="hg-cmd">hg serve</command> command, since <command
  14.128 -	  role="hg-cmd">hg serve</command> does not require any fancy
  14.129 -	server infrastructure.  You can get started with <command
  14.130 -	  role="hg-cmd">hg serve</command> in moments, by reading
  14.131 -	section <xref linkend="sec.collab.serve"/> below.  Then simply
  14.132 -	tell
  14.133 -	the person next to you that you're running a server, send the
  14.134 -	URL to them in an instant message, and you immediately have a
  14.135 -	quick-turnaround way to work together.  They can type your URL
  14.136 -	into their web browser and quickly review your changes; or
  14.137 -	they can pull a bugfix from you and verify it; or they can
  14.138 -	clone a branch containing a new feature and try it out.</para>
  14.139 -
  14.140 -      <para>The charm, and the problem, with doing things in an ad hoc
  14.141 +      <para id="x_457">A sprint is the perfect place to use the
  14.142 +	<command role="hg-cmd">hg serve</command> command, since
  14.143 +	<command role="hg-cmd">hg serve</command> does not require any
  14.144 +	fancy server infrastructure.  You can get started with
  14.145 +	<command role="hg-cmd">hg serve</command> in moments, by
  14.146 +	reading <xref linkend="sec:collab:serve"/> below.  Then simply
  14.147 +	tell the person next to you that you're running a server, send
  14.148 +	the URL to them in an instant message, and you immediately
  14.149 +	have a quick-turnaround way to work together.  They can type
  14.150 +	your URL into their web browser and quickly review your
  14.151 +	changes; or they can pull a bugfix from you and verify it; or
  14.152 +	they can clone a branch containing a new feature and try it
  14.153 +	out.</para>
  14.154 +
  14.155 +      <para id="x_458">The charm, and the problem, with doing things in an ad hoc
  14.156  	fashion like this is that only people who know about your
  14.157  	changes, and where they are, can see them.  Such an informal
  14.158  	approach simply doesn't scale beyond a handful people, because
  14.159 @@ -140,18 +140,18 @@
  14.160      <sect2>
  14.161        <title>A single central repository</title>
  14.162  
  14.163 -      <para>For smaller projects migrating from a centralised revision
  14.164 +      <para id="x_459">For smaller projects migrating from a centralised revision
  14.165  	control tool, perhaps the easiest way to get started is to
  14.166  	have changes flow through a single shared central repository.
  14.167  	This is also the most common <quote>building block</quote> for
  14.168  	more ambitious workflow schemes.</para>
  14.169  
  14.170 -      <para>Contributors start by cloning a copy of this repository.
  14.171 +      <para id="x_45a">Contributors start by cloning a copy of this repository.
  14.172  	They can pull changes from it whenever they need to, and some
  14.173  	(perhaps all) developers have permission to push a change back
  14.174  	when they're ready for other people to see it.</para>
  14.175  
  14.176 -      <para>Under this model, it can still often make sense for people
  14.177 +      <para id="x_45b">Under this model, it can still often make sense for people
  14.178  	to pull changes directly from each other, without going
  14.179  	through the central repository.  Consider a case in which I
  14.180  	have a tentative bug fix, but I am worried that if I were to
  14.181 @@ -162,22 +162,21 @@
  14.182  	lets us put off publishing the potentially unsafe change until
  14.183  	it has had a little testing.</para>
  14.184  
  14.185 -      <para>In this kind of scenario, people usually use the
  14.186 -	<command>ssh</command> protocol to securely push changes to
  14.187 -	the central repository, as documented in section <xref
  14.188 -	  linkend="sec.collab.ssh"/>.  It's also
  14.189 -	usual to publish a read-only copy of the repository over HTTP
  14.190 -	using CGI, as in section <xref linkend="sec.collab.cgi"/>.
  14.191 -	Publishing over HTTP
  14.192 -	satisfies the needs of people who don't have push access, and
  14.193 -	those who want to use web browsers to browse the repository's
  14.194 -	history.</para>
  14.195 +      <para id="x_45c">In this kind of scenario, people usually use
  14.196 +	the <command>ssh</command> protocol to securely push changes
  14.197 +	to the central repository, as documented in <xref
  14.198 +	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
  14.199 +	read-only copy of the repository over HTTP using CGI, as in
  14.200 +	<xref linkend="sec:collab:cgi"/>. Publishing
  14.201 +	over HTTP satisfies the needs of people who don't have push
  14.202 +	access, and those who want to use web browsers to browse the
  14.203 +	repository's history.</para>
  14.204  
  14.205      </sect2>
  14.206      <sect2>
  14.207        <title>Working with multiple branches</title>
  14.208  
  14.209 -      <para>Projects of any significant size naturally tend to make
  14.210 +      <para id="x_45d">Projects of any significant size naturally tend to make
  14.211  	progress on several fronts simultaneously.  In the case of
  14.212  	software, it's common for a project to go through periodic
  14.213  	official releases.  A release might then go into
  14.214 @@ -190,7 +189,7 @@
  14.215  	different directions in which development is
  14.216  	proceeding.</para>
  14.217  
  14.218 -      <para>Mercurial is particularly well suited to managing a number
  14.219 +      <para id="x_45e">Mercurial is particularly well suited to managing a number
  14.220  	of simultaneous, but not identical, branches.  Each
  14.221  	<quote>development direction</quote> can live in its own
  14.222  	central repository, and you can merge changes from one to
  14.223 @@ -199,27 +198,27 @@
  14.224  	branch will never affect a stable branch unless someone
  14.225  	explicitly merges those changes in.</para>
  14.226  
  14.227 -      <para>Here's an example of how this can work in practice.  Let's
  14.228 +      <para id="x_45f">Here's an example of how this can work in practice.  Let's
  14.229  	say you have one <quote>main branch</quote> on a central
  14.230  	server.</para>
  14.231  
  14.232        &interaction.branching.init;
  14.233  
  14.234 -      <para>People clone it, make changes locally, test them, and push
  14.235 +      <para id="x_460">People clone it, make changes locally, test them, and push
  14.236  	them back.</para>
  14.237  
  14.238 -      <para>Once the main branch reaches a release milestone, you can
  14.239 +      <para id="x_461">Once the main branch reaches a release milestone, you can
  14.240  	use the <command role="hg-cmd">hg tag</command> command to
  14.241  	give a permanent name to the milestone revision.</para>
  14.242  
  14.243  	&interaction.branching.tag;
  14.244  
  14.245 -      <para>Let's say some ongoing
  14.246 +      <para id="x_462">Let's say some ongoing
  14.247  	development occurs on the main branch.</para>
  14.248  
  14.249        &interaction.branching.main;
  14.250  
  14.251 -      <para>Using the tag that was recorded at the milestone, people
  14.252 +      <para id="x_463">Using the tag that was recorded at the milestone, people
  14.253  	who clone that repository at any time in the future can use
  14.254  	<command role="hg-cmd">hg update</command> to get a copy of
  14.255  	the working directory exactly as it was when that tagged
  14.256 @@ -227,26 +226,26 @@
  14.257  
  14.258        &interaction.branching.update;
  14.259  
  14.260 -      <para>In addition, immediately after the main branch is tagged,
  14.261 +      <para id="x_464">In addition, immediately after the main branch is tagged,
  14.262  	someone can then clone the main branch on the server to a new
  14.263  	<quote>stable</quote> branch, also on the server.</para>
  14.264  
  14.265        &interaction.branching.clone;
  14.266  
  14.267 -      <para>Someone who needs to make a change to the stable branch
  14.268 +      <para id="x_465">Someone who needs to make a change to the stable branch
  14.269  	can then clone <emphasis>that</emphasis> repository, make
  14.270  	their changes, commit, and push their changes back there.</para>
  14.271  
  14.272        &interaction.branching.stable;
  14.273  
  14.274 -      <para>Because Mercurial repositories are independent, and
  14.275 +      <para id="x_466">Because Mercurial repositories are independent, and
  14.276  	Mercurial doesn't move changes around automatically, the
  14.277  	stable and main branches are <emphasis>isolated</emphasis>
  14.278  	from each other.  The changes that you made on the main branch
  14.279  	don't <quote>leak</quote> to the stable branch, and vice
  14.280  	versa.</para>
  14.281  
  14.282 -      <para>You'll often want all of your bugfixes on the stable
  14.283 +      <para id="x_467">You'll often want all of your bugfixes on the stable
  14.284  	branch to show up on the main branch, too.  Rather than
  14.285  	rewrite a bugfix on the main branch, you can simply pull and
  14.286  	merge changes from the stable to the main branch, and
  14.287 @@ -254,7 +253,7 @@
  14.288  
  14.289  	&interaction.branching.merge;
  14.290  
  14.291 -      <para>The main branch will still contain changes that are not on
  14.292 +      <para id="x_468">The main branch will still contain changes that are not on
  14.293  	the stable branch, but it will also contain all of the
  14.294  	bugfixes from the stable branch.  The stable branch remains
  14.295  	unaffected by these changes.</para>
  14.296 @@ -263,24 +262,22 @@
  14.297      <sect2>
  14.298        <title>Feature branches</title>
  14.299  
  14.300 -      <para>For larger projects, an effective way to manage change is
  14.301 +      <para id="x_469">For larger projects, an effective way to manage change is
  14.302  	to break up a team into smaller groups.  Each group has a
  14.303  	shared branch of its own, cloned from a single
  14.304  	<quote>master</quote> branch used by the entire project.
  14.305  	People working on an individual branch are typically quite
  14.306  	isolated from developments on other branches.</para>
  14.307  
  14.308 -      <informalfigure id="fig.collab.feature-branches">
  14.309 -        <mediaobject>
  14.310 -          <imageobject><imagedata fileref="images/feature-branches.png"/>
  14.311 -          </imageobject>
  14.312 -          <textobject><phrase>XXX add text</phrase></textobject>
  14.313 -          <caption><para id="fig.collab.feature-branches.caption">Feature
  14.314 -            branches</para></caption>
  14.315 -        </mediaobject>
  14.316 -      </informalfigure>
  14.317 -
  14.318 -      <para>When a particular feature is deemed to be in suitable
  14.319 +      <figure id="fig:collab:feature-branches">
  14.320 +	<title>Feature branches</title>
  14.321 +	<mediaobject>
  14.322 +	  <imageobject><imagedata imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
  14.323 +	  <textobject><phrase>XXX add text</phrase></textobject>
  14.324 +	</mediaobject>
  14.325 +      </figure>
  14.326 +
  14.327 +      <para id="x_46b">When a particular feature is deemed to be in suitable
  14.328  	shape, someone on that feature team pulls and merges from the
  14.329  	master branch into the feature branch, then pushes back up to
  14.330  	the master branch.</para>
  14.331 @@ -289,12 +286,12 @@
  14.332      <sect2>
  14.333        <title>The release train</title>
  14.334  
  14.335 -      <para>Some projects are organised on a <quote>train</quote>
  14.336 +      <para id="x_46c">Some projects are organised on a <quote>train</quote>
  14.337  	basis: a release is scheduled to happen every few months, and
  14.338  	whatever features are ready when the <quote>train</quote> is
  14.339  	ready to leave are allowed in.</para>
  14.340  
  14.341 -      <para>This model resembles working with feature branches.  The
  14.342 +      <para id="x_46d">This model resembles working with feature branches.  The
  14.343  	difference is that when a feature branch misses a train,
  14.344  	someone on the feature team pulls and merges the changes that
  14.345  	went out on that train release into the feature branch, and
  14.346 @@ -305,7 +302,7 @@
  14.347      <sect2>
  14.348        <title>The Linux kernel model</title>
  14.349  
  14.350 -      <para>The development of the Linux kernel has a shallow
  14.351 +      <para id="x_46e">The development of the Linux kernel has a shallow
  14.352  	hierarchical structure, surrounded by a cloud of apparent
  14.353  	chaos.  Because most Linux developers use
  14.354  	<command>git</command>, a distributed revision control tool
  14.355 @@ -313,14 +310,14 @@
  14.356  	describe the way work flows in that environment; if you like
  14.357  	the ideas, the approach translates well across tools.</para>
  14.358  
  14.359 -      <para>At the center of the community sits Linus Torvalds, the
  14.360 +      <para id="x_46f">At the center of the community sits Linus Torvalds, the
  14.361  	creator of Linux.  He publishes a single source repository
  14.362  	that is considered the <quote>authoritative</quote> current
  14.363  	tree by the entire developer community. Anyone can clone
  14.364  	Linus's tree, but he is very choosy about whose trees he pulls
  14.365  	from.</para>
  14.366  
  14.367 -      <para>Linus has a number of <quote>trusted lieutenants</quote>.
  14.368 +      <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
  14.369  	As a general rule, he pulls whatever changes they publish, in
  14.370  	most cases without even reviewing those changes.  Some of
  14.371  	those lieutenants are generally agreed to be
  14.372 @@ -332,7 +329,7 @@
  14.373  	If the maintainer reviews their changes and agrees to take
  14.374  	them, they'll pass them along to Linus in due course.</para>
  14.375  
  14.376 -      <para>Individual lieutenants have their own approaches to
  14.377 +      <para id="x_471">Individual lieutenants have their own approaches to
  14.378  	reviewing, accepting, and publishing changes; and for deciding
  14.379  	when to feed them to Linus.  In addition, there are several
  14.380  	well known branches that people use for different purposes.
  14.381 @@ -343,14 +340,14 @@
  14.382  	that they are about to feed upstream; and so on.  Others just
  14.383  	publish a single tree.</para>
  14.384  
  14.385 -      <para>This model has two notable features.  The first is that
  14.386 +      <para id="x_472">This model has two notable features.  The first is that
  14.387  	it's <quote>pull only</quote>.  You have to ask, convince, or
  14.388  	beg another developer to take a change from you, because there
  14.389  	are almost no trees to which more than one person can push,
  14.390  	and there's no way to push changes into a tree that someone
  14.391  	else controls.</para>
  14.392  
  14.393 -      <para>The second is that it's based on reputation and acclaim.
  14.394 +      <para id="x_473">The second is that it's based on reputation and acclaim.
  14.395  	If you're an unknown, Linus will probably ignore changes from
  14.396  	you without even responding.  But a subsystem maintainer will
  14.397  	probably review them, and will likely take them if they pass
  14.398 @@ -361,14 +358,14 @@
  14.399  	Linus hasn't yet accepted, people with similar interests may
  14.400  	pull your changes regularly to keep up with your work.</para>
  14.401  
  14.402 -      <para>Reputation and acclaim don't necessarily cross subsystem
  14.403 +      <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
  14.404  	or <quote>people</quote> boundaries.  If you're a respected
  14.405  	but specialised storage hacker, and you try to fix a
  14.406  	networking bug, that change will receive a level of scrutiny
  14.407  	from a network maintainer comparable to a change from a
  14.408  	complete stranger.</para>
  14.409  
  14.410 -      <para>To people who come from more orderly project backgrounds,
  14.411 +      <para id="x_475">To people who come from more orderly project backgrounds,
  14.412  	the comparatively chaotic Linux kernel development process
  14.413  	often seems completely insane.  It's subject to the whims of
  14.414  	individuals; people make sweeping changes whenever they deem
  14.415 @@ -380,13 +377,13 @@
  14.416      <sect2>
  14.417        <title>Pull-only versus shared-push collaboration</title>
  14.418  
  14.419 -      <para>A perpetual source of heat in the open source community is
  14.420 +      <para id="x_476">A perpetual source of heat in the open source community is
  14.421  	whether a development model in which people only ever pull
  14.422  	changes from others is <quote>better than</quote> one in which
  14.423  	multiple people can push changes to a shared
  14.424  	repository.</para>
  14.425  
  14.426 -      <para>Typically, the backers of the shared-push model use tools
  14.427 +      <para id="x_477">Typically, the backers of the shared-push model use tools
  14.428  	that actively enforce this approach.  If you're using a
  14.429  	centralised revision control tool such as Subversion, there's
  14.430  	no way to make a choice over which model you'll use: the tool
  14.431 @@ -394,7 +391,7 @@
  14.432  	you'll have to roll your own approach on top (such as applying
  14.433  	a patch by hand).</para>
  14.434  
  14.435 -      <para>A good distributed revision control tool, such as
  14.436 +      <para id="x_478">A good distributed revision control tool, such as
  14.437  	Mercurial, will support both models.  You and your
  14.438  	collaborators can then structure how you work together based
  14.439  	on your own needs and preferences, not on what contortions
  14.440 @@ -404,34 +401,34 @@
  14.441      <sect2>
  14.442        <title>Where collaboration meets branch management</title>
  14.443  
  14.444 -      <para>Once you and your team set up some shared repositories and
  14.445 -	start propagating changes back and forth between local and
  14.446 -	shared repos, you begin to face a related, but slightly
  14.447 -	different challenge: that of managing the multiple directions
  14.448 -	in which your team may be moving at once.  Even though this
  14.449 -	subject is intimately related to how your team collaborates,
  14.450 -	it's dense enough to merit treatment of its own, in chapter
  14.451 -	<xref linkend="chap.branch"/>.</para>
  14.452 +      <para id="x_479">Once you and your team set up some shared
  14.453 +	repositories and start propagating changes back and forth
  14.454 +	between local and shared repos, you begin to face a related,
  14.455 +	but slightly different challenge: that of managing the
  14.456 +	multiple directions in which your team may be moving at once.
  14.457 +	Even though this subject is intimately related to how your
  14.458 +	team collaborates, it's dense enough to merit treatment of its
  14.459 +	own, in <xref linkend="chap:branch"/>.</para>
  14.460  
  14.461      </sect2>
  14.462    </sect1>
  14.463    <sect1>
  14.464      <title>The technical side of sharing</title>
  14.465  
  14.466 -    <para>The remainder of this chapter is devoted to the question of
  14.467 +    <para id="x_47a">The remainder of this chapter is devoted to the question of
  14.468        serving data to your collaborators.</para>
  14.469  
  14.470    </sect1>
  14.471 -  <sect1 id="sec.collab.serve">
  14.472 +  <sect1 id="sec:collab:serve">
  14.473      <title>Informal sharing with <command role="hg-cmd">hg
  14.474  	serve</command></title>
  14.475  
  14.476 -    <para>Mercurial's <command role="hg-cmd">hg serve</command>
  14.477 +    <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command>
  14.478        command is wonderfully suited to small, tight-knit, and
  14.479        fast-paced group environments.  It also provides a great way to
  14.480        get a feel for using Mercurial commands over a network.</para>
  14.481  
  14.482 -    <para>Run <command role="hg-cmd">hg serve</command> inside a
  14.483 +    <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a
  14.484        repository, and in under a second it will bring up a specialised
  14.485        HTTP server; this will accept connections from any client, and
  14.486        serve up data for that repository until you terminate it.
  14.487 @@ -442,24 +439,24 @@
  14.488        on a laptop is likely to look something like
  14.489        <literal>http://my-laptop.local:8000/</literal>.</para>
  14.490  
  14.491 -    <para>The <command role="hg-cmd">hg serve</command> command is
  14.492 +    <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is
  14.493        <emphasis>not</emphasis> a general-purpose web server. It can do
  14.494        only two things:</para>
  14.495      <itemizedlist>
  14.496 -      <listitem><para>Allow people to browse the history of the
  14.497 +      <listitem><para id="x_47e">Allow people to browse the history of the
  14.498  	  repository it's serving, from their normal web
  14.499  	  browsers.</para>
  14.500        </listitem>
  14.501 -      <listitem><para>Speak Mercurial's wire protocol, so that people
  14.502 +      <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
  14.503  	  can <command role="hg-cmd">hg clone</command> or <command
  14.504  	    role="hg-cmd">hg pull</command> changes from that
  14.505  	  repository.</para>
  14.506        </listitem></itemizedlist>
  14.507 -    <para>In particular, <command role="hg-cmd">hg serve</command>
  14.508 +    <para id="x_480">In particular, <command role="hg-cmd">hg serve</command>
  14.509        won't allow remote users to <emphasis>modify</emphasis> your
  14.510        repository.  It's intended for read-only use.</para>
  14.511  
  14.512 -    <para>If you're getting started with Mercurial, there's nothing to
  14.513 +    <para id="x_481">If you're getting started with Mercurial, there's nothing to
  14.514        prevent you from using <command role="hg-cmd">hg serve</command>
  14.515        to serve up a repository on your own computer, then use commands
  14.516        like <command role="hg-cmd">hg clone</command>, <command
  14.517 @@ -471,13 +468,13 @@
  14.518      <sect2>
  14.519        <title>A few things to keep in mind</title>
  14.520  
  14.521 -      <para>Because it provides unauthenticated read access to all
  14.522 +      <para id="x_482">Because it provides unauthenticated read access to all
  14.523  	clients, you should only use <command role="hg-cmd">hg
  14.524  	  serve</command> in an environment where you either don't
  14.525  	care, or have complete control over, who can access your
  14.526  	network and pull data from your repository.</para>
  14.527  
  14.528 -      <para>The <command role="hg-cmd">hg serve</command> command
  14.529 +      <para id="x_483">The <command role="hg-cmd">hg serve</command> command
  14.530  	knows nothing about any firewall software you might have
  14.531  	installed on your system or network.  It cannot detect or
  14.532  	control your firewall software.  If other people are unable to
  14.533 @@ -486,13 +483,13 @@
  14.534  	(<emphasis>after</emphasis> you make sure that they're using
  14.535  	the correct URL) is check your firewall configuration.</para>
  14.536  
  14.537 -      <para>By default, <command role="hg-cmd">hg serve</command>
  14.538 +      <para id="x_484">By default, <command role="hg-cmd">hg serve</command>
  14.539  	listens for incoming connections on port 8000.  If another
  14.540  	process is already listening on the port you want to use, you
  14.541  	can specify a different port to listen on using the <option
  14.542  	  role="hg-opt-serve">-p</option> option.</para>
  14.543  
  14.544 -      <para>Normally, when <command role="hg-cmd">hg serve</command>
  14.545 +      <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command>
  14.546  	starts, it prints no output, which can be a bit unnerving.  If
  14.547  	you'd like to confirm that it is indeed running correctly, and
  14.548  	find out what URL you should send to your collaborators, start
  14.549 @@ -501,59 +498,59 @@
  14.550  
  14.551      </sect2>
  14.552    </sect1>
  14.553 -  <sect1 id="sec.collab.ssh">
  14.554 +  <sect1 id="sec:collab:ssh">
  14.555      <title>Using the Secure Shell (ssh) protocol</title>
  14.556  
  14.557 -    <para>You can pull and push changes securely over a network
  14.558 +    <para id="x_486">You can pull and push changes securely over a network
  14.559        connection using the Secure Shell (<literal>ssh</literal>)
  14.560        protocol.  To use this successfully, you may have to do a little
  14.561        bit of configuration on the client or server sides.</para>
  14.562  
  14.563 -    <para>If you're not familiar with ssh, it's a network protocol
  14.564 +    <para id="x_487">If you're not familiar with ssh, it's a network protocol
  14.565        that lets you securely communicate with another computer.  To
  14.566        use it with Mercurial, you'll be setting up one or more user
  14.567        accounts on a server so that remote users can log in and execute
  14.568        commands.</para>
  14.569  
  14.570 -    <para>(If you <emphasis>are</emphasis> familiar with ssh, you'll
  14.571 +    <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
  14.572        probably find some of the material that follows to be elementary
  14.573        in nature.)</para>
  14.574  
  14.575      <sect2>
  14.576        <title>How to read and write ssh URLs</title>
  14.577  
  14.578 -      <para>An ssh URL tends to look like this:</para>
  14.579 +      <para id="x_489">An ssh URL tends to look like this:</para>
  14.580        <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
  14.581        <orderedlist>
  14.582 -	<listitem><para>The <quote><literal>ssh://</literal></quote>
  14.583 +	<listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote>
  14.584  	    part tells Mercurial to use the ssh protocol.</para>
  14.585  	</listitem>
  14.586 -	<listitem><para>The <quote><literal>bos@</literal></quote>
  14.587 +	<listitem><para id="x_48b">The <quote><literal>bos@</literal></quote>
  14.588  	    component indicates what username to log into the server
  14.589  	    as.  You can leave this out if the remote username is the
  14.590  	    same as your local username.</para>
  14.591  	</listitem>
  14.592 -	<listitem><para>The
  14.593 +	<listitem><para id="x_48c">The
  14.594  	    <quote><literal>hg.serpentine.com</literal></quote> gives
  14.595  	    the hostname of the server to log into.</para>
  14.596  	</listitem>
  14.597 -	<listitem><para>The <quote>:22</quote> identifies the port
  14.598 +	<listitem><para id="x_48d">The <quote>:22</quote> identifies the port
  14.599  	    number to connect to the server on.  The default port is
  14.600  	    22, so you only need to specify a colon and port number if
  14.601  	    you're <emphasis>not</emphasis> using port 22.</para>
  14.602  	</listitem>
  14.603 -	<listitem><para>The remainder of the URL is the local path to
  14.604 +	<listitem><para id="x_48e">The remainder of the URL is the local path to
  14.605  	    the repository on the server.</para>
  14.606  	</listitem></orderedlist>
  14.607  
  14.608 -      <para>There's plenty of scope for confusion with the path
  14.609 +      <para id="x_48f">There's plenty of scope for confusion with the path
  14.610  	component of ssh URLs, as there is no standard way for tools
  14.611  	to interpret it.  Some programs behave differently than others
  14.612  	when dealing with these paths. This isn't an ideal situation,
  14.613  	but it's unlikely to change.  Please read the following
  14.614  	paragraphs carefully.</para>
  14.615  
  14.616 -      <para>Mercurial treats the path to a repository on the server as
  14.617 +      <para id="x_490">Mercurial treats the path to a repository on the server as
  14.618  	relative to the remote user's home directory.  For example, if
  14.619  	user <literal>foo</literal> on the server has a home directory
  14.620  	of <filename class="directory">/home/foo</filename>, then an
  14.621 @@ -562,13 +559,13 @@
  14.622  	refers to the directory <filename
  14.623  	  class="directory">/home/foo/bar</filename>.</para>
  14.624  
  14.625 -      <para>If you want to specify a path relative to another user's
  14.626 +      <para id="x_491">If you want to specify a path relative to another user's
  14.627  	home directory, you can use a path that starts with a tilde
  14.628  	character followed by the user's name (let's call them
  14.629  	<literal>otheruser</literal>), like this.</para>
  14.630        <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
  14.631  
  14.632 -      <para>And if you really want to specify an
  14.633 +      <para id="x_492">And if you really want to specify an
  14.634  	<emphasis>absolute</emphasis> path on the server, begin the
  14.635  	path component with two slashes, as in this example.</para>
  14.636        <programlisting>ssh://server//absolute/path</programlisting>
  14.637 @@ -577,7 +574,7 @@
  14.638      <sect2>
  14.639        <title>Finding an ssh client for your system</title>
  14.640  
  14.641 -      <para>Almost every Unix-like system comes with OpenSSH
  14.642 +      <para id="x_493">Almost every Unix-like system comes with OpenSSH
  14.643  	preinstalled.  If you're using such a system, run
  14.644  	<literal>which ssh</literal> to find out if the
  14.645  	<command>ssh</command> command is installed (it's usually in
  14.646 @@ -585,17 +582,17 @@
  14.647  	unlikely event that it isn't present, take a look at your
  14.648  	system documentation to figure out how to install it.</para>
  14.649  
  14.650 -      <para>On Windows, you'll first need to download a suitable ssh
  14.651 +      <para id="x_494">On Windows, you'll first need to download a suitable ssh
  14.652  	client.  There are two alternatives.</para>
  14.653        <itemizedlist>
  14.654 -	<listitem><para>Simon Tatham's excellent PuTTY package
  14.655 +	<listitem><para id="x_495">Simon Tatham's excellent PuTTY package
  14.656  	    <citation>web:putty</citation> provides a complete suite
  14.657  	    of ssh client commands.</para>
  14.658  	</listitem>
  14.659 -	<listitem><para>If you have a high tolerance for pain, you can
  14.660 +	<listitem><para id="x_496">If you have a high tolerance for pain, you can
  14.661  	    use the Cygwin port of OpenSSH.</para>
  14.662  	</listitem></itemizedlist>
  14.663 -      <para>In either case, you'll need to edit your <filename
  14.664 +      <para id="x_497">In either case, you'll need to edit your <filename
  14.665        role="special">hg.ini</filename> file to
  14.666  	tell Mercurial where to find the actual client command.  For
  14.667  	example, if you're using PuTTY, you'll need to use the
  14.668 @@ -605,7 +602,7 @@
  14.669  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"</programlisting>
  14.670  
  14.671        <note>
  14.672 -	<para>  The path to <command>plink</command> shouldn't contain
  14.673 +	<para id="x_498">  The path to <command>plink</command> shouldn't contain
  14.674  	  any whitespace characters, or Mercurial may not be able to
  14.675  	  run it correctly (so putting it in <filename
  14.676  	    class="directory">C:\Program Files</filename> is probably
  14.677 @@ -616,7 +613,7 @@
  14.678      <sect2>
  14.679        <title>Generating a key pair</title>
  14.680  
  14.681 -      <para>To avoid the need to repetitively type a password every
  14.682 +      <para id="x_499">To avoid the need to repetitively type a password every
  14.683  	time you need to use your ssh client, I recommend generating a
  14.684  	key pair.  On a Unix-like system, the
  14.685  	<command>ssh-keygen</command> command will do the trick. On
  14.686 @@ -624,13 +621,13 @@
  14.687  	<command>puttygen</command> command is what you'll
  14.688  	need.</para>
  14.689  
  14.690 -      <para>When you generate a key pair, it's usually
  14.691 +      <para id="x_49a">When you generate a key pair, it's usually
  14.692  	<emphasis>highly</emphasis> advisable to protect it with a
  14.693  	passphrase.  (The only time that you might not want to do this
  14.694  	is when you're using the ssh protocol for automated tasks on a
  14.695  	secure network.)</para>
  14.696  
  14.697 -      <para>Simply generating a key pair isn't enough, however.
  14.698 +      <para id="x_49b">Simply generating a key pair isn't enough, however.
  14.699  	You'll need to add the public key to the set of authorised
  14.700  	keys for whatever user you're logging in remotely as.  For
  14.701  	servers using OpenSSH (the vast majority), this will mean
  14.702 @@ -639,7 +636,7 @@
  14.703  	  role="special" class="directory">.ssh</filename>
  14.704  	directory.</para>
  14.705  
  14.706 -      <para>On a Unix-like system, your public key will have a
  14.707 +      <para id="x_49c">On a Unix-like system, your public key will have a
  14.708  	<filename>.pub</filename> extension.  If you're using
  14.709  	<command>puttygen</command> on Windows, you can save the
  14.710  	public key to a file of your choosing, or paste it from the
  14.711 @@ -650,7 +647,7 @@
  14.712      <sect2>
  14.713        <title>Using an authentication agent</title>
  14.714  
  14.715 -      <para>An authentication agent is a daemon that stores
  14.716 +      <para id="x_49d">An authentication agent is a daemon that stores
  14.717  	passphrases in memory (so it will forget passphrases if you
  14.718  	log out and log back in again). An ssh client will notice if
  14.719  	it's running, and query it for a passphrase.  If there's no
  14.720 @@ -659,14 +656,14 @@
  14.721  	every time Mercurial tries to communicate with a server on
  14.722  	your behalf (e.g. whenever you pull or push changes).</para>
  14.723  
  14.724 -      <para>The downside of storing passphrases in an agent is that
  14.725 +      <para id="x_49e">The downside of storing passphrases in an agent is that
  14.726  	it's possible for a well-prepared attacker to recover the
  14.727  	plain text of your passphrases, in some cases even if your
  14.728  	system has been power-cycled. You should make your own
  14.729  	judgment as to whether this is an acceptable risk.  It
  14.730  	certainly saves a lot of repeated typing.</para>
  14.731  
  14.732 -      <para>On Unix-like systems, the agent is called
  14.733 +      <para id="x_49f">On Unix-like systems, the agent is called
  14.734  	<command>ssh-agent</command>, and it's often run automatically
  14.735  	for you when you log in.  You'll need to use the
  14.736  	<command>ssh-add</command> command to add passphrases to the
  14.737 @@ -679,7 +676,7 @@
  14.738      <sect2>
  14.739        <title>Configuring the server side properly</title>
  14.740  
  14.741 -      <para>Because ssh can be fiddly to set up if you're new to it,
  14.742 +      <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
  14.743  	there's a variety of things that can go wrong.  Add Mercurial
  14.744  	on top, and there's plenty more scope for head-scratching.
  14.745  	Most of these potential problems occur on the server side, not
  14.746 @@ -687,7 +684,7 @@
  14.747  	configuration working, it will usually continue to work
  14.748  	indefinitely.</para>
  14.749  
  14.750 -      <para>Before you try using Mercurial to talk to an ssh server,
  14.751 +      <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
  14.752  	it's best to make sure that you can use the normal
  14.753  	<command>ssh</command> or <command>putty</command> command to
  14.754  	talk to the server first.  If you run into problems with using
  14.755 @@ -698,29 +695,29 @@
  14.756  	<emphasis>before</emphasis> you worry about whether there's a
  14.757  	problem with Mercurial.</para>
  14.758  
  14.759 -      <para>The first thing to be sure of on the server side is that
  14.760 +      <para id="x_4a2">The first thing to be sure of on the server side is that
  14.761  	you can actually log in from another machine at all.  If you
  14.762  	can't use <command>ssh</command> or <command>putty</command>
  14.763  	to log in, the error message you get may give you a few hints
  14.764  	as to what's wrong.  The most common problems are as
  14.765  	follows.</para>
  14.766        <itemizedlist>
  14.767 -	<listitem><para>If you get a <quote>connection refused</quote>
  14.768 +	<listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
  14.769  	    error, either there isn't an SSH daemon running on the
  14.770  	    server at all, or it's inaccessible due to firewall
  14.771  	    configuration.</para>
  14.772  	</listitem>
  14.773 -	<listitem><para>If you get a <quote>no route to host</quote>
  14.774 +	<listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
  14.775  	    error, you either have an incorrect address for the server
  14.776  	    or a seriously locked down firewall that won't admit its
  14.777  	    existence at all.</para>
  14.778  	</listitem>
  14.779 -	<listitem><para>If you get a <quote>permission denied</quote>
  14.780 +	<listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
  14.781  	    error, you may have mistyped the username on the server,
  14.782  	    or you could have mistyped your key's passphrase or the
  14.783  	    remote user's password.</para>
  14.784  	</listitem></itemizedlist>
  14.785 -      <para>In summary, if you're having trouble talking to the
  14.786 +      <para id="x_4a6">In summary, if you're having trouble talking to the
  14.787  	server's ssh daemon, first make sure that one is running at
  14.788  	all.  On many systems it will be installed, but disabled, by
  14.789  	default.  Once you're done with this step, you should then
  14.790 @@ -730,23 +727,23 @@
  14.791  	for misconfiguration until you've checked these two
  14.792  	first.</para>
  14.793  
  14.794 -      <para>If you're using an authentication agent on the client side
  14.795 +      <para id="x_4a7">If you're using an authentication agent on the client side
  14.796  	to store passphrases for your keys, you ought to be able to
  14.797  	log into the server without being prompted for a passphrase or
  14.798  	a password.  If you're prompted for a passphrase, there are a
  14.799  	few possible culprits.</para>
  14.800        <itemizedlist>
  14.801 -	<listitem><para>You might have forgotten to use
  14.802 +	<listitem><para id="x_4a8">You might have forgotten to use
  14.803  	    <command>ssh-add</command> or <command>pageant</command>
  14.804  	    to store the passphrase.</para>
  14.805  	</listitem>
  14.806 -	<listitem><para>You might have stored the passphrase for the
  14.807 +	<listitem><para id="x_4a9">You might have stored the passphrase for the
  14.808  	    wrong key.</para>
  14.809  	</listitem></itemizedlist>
  14.810 -      <para>If you're being prompted for the remote user's password,
  14.811 +      <para id="x_4aa">If you're being prompted for the remote user's password,
  14.812  	there are another few possible problems to check.</para>
  14.813        <itemizedlist>
  14.814 -	<listitem><para>Either the user's home directory or their
  14.815 +	<listitem><para id="x_4ab">Either the user's home directory or their
  14.816  	    <filename role="special" class="directory">.ssh</filename>
  14.817  	    directory might have excessively liberal permissions.  As
  14.818  	    a result, the ssh daemon will not trust or read their
  14.819 @@ -755,19 +752,19 @@
  14.820  	      role="special" class="directory">.ssh</filename>
  14.821  	    directory will often cause this symptom.</para>
  14.822  	</listitem>
  14.823 -	<listitem><para>The user's <filename
  14.824 +	<listitem><para id="x_4ac">The user's <filename
  14.825  	      role="special">authorized_keys</filename> file may have
  14.826  	    a problem. If anyone other than the user owns or can write
  14.827  	    to that file, the ssh daemon will not trust or read
  14.828  	    it.</para>
  14.829  	</listitem></itemizedlist>
  14.830  
  14.831 -      <para>In the ideal world, you should be able to run the
  14.832 +      <para id="x_4ad">In the ideal world, you should be able to run the
  14.833  	following command successfully, and it should print exactly
  14.834  	one line of output, the current date and time.</para>
  14.835        <programlisting>ssh myserver date</programlisting>
  14.836  
  14.837 -      <para>If, on your server, you have login scripts that print
  14.838 +      <para id="x_4ae">If, on your server, you have login scripts that print
  14.839  	banners or other junk even when running non-interactive
  14.840  	commands like this, you should fix them before you continue,
  14.841  	so that they only print output if they're run interactively.
  14.842 @@ -781,43 +778,43 @@
  14.843  	shell is to check the return code from the command
  14.844  	<literal>tty -s</literal>.)</para>
  14.845  
  14.846 -      <para>Once you've verified that plain old ssh is working with
  14.847 +      <para id="x_4af">Once you've verified that plain old ssh is working with
  14.848  	your server, the next step is to ensure that Mercurial runs on
  14.849  	the server.  The following command should run
  14.850  	successfully:</para>
  14.851  
  14.852        <programlisting>ssh myserver hg version</programlisting>
  14.853  
  14.854 -      <para>If you see an error message instead of normal <command
  14.855 +      <para id="x_4b0">If you see an error message instead of normal <command
  14.856  	  role="hg-cmd">hg version</command> output, this is usually
  14.857  	because you haven't installed Mercurial to <filename
  14.858  	  class="directory">/usr/bin</filename>.  Don't worry if this
  14.859  	is the case; you don't need to do that.  But you should check
  14.860  	for a few possible problems.</para>
  14.861        <itemizedlist>
  14.862 -	<listitem><para>Is Mercurial really installed on the server at
  14.863 +	<listitem><para id="x_4b1">Is Mercurial really installed on the server at
  14.864  	    all?  I know this sounds trivial, but it's worth
  14.865  	    checking!</para>
  14.866  	</listitem>
  14.867 -	<listitem><para>Maybe your shell's search path (usually set
  14.868 +	<listitem><para id="x_4b2">Maybe your shell's search path (usually set
  14.869  	    via the <envar>PATH</envar> environment variable) is
  14.870  	    simply misconfigured.</para>
  14.871  	</listitem>
  14.872 -	<listitem><para>Perhaps your <envar>PATH</envar> environment
  14.873 +	<listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
  14.874  	    variable is only being set to point to the location of the
  14.875  	    <command>hg</command> executable if the login session is
  14.876  	    interactive.  This can happen if you're setting the path
  14.877  	    in the wrong shell login script.  See your shell's
  14.878  	    documentation for details.</para>
  14.879  	</listitem>
  14.880 -	<listitem><para>The <envar>PYTHONPATH</envar> environment
  14.881 +	<listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
  14.882  	    variable may need to contain the path to the Mercurial
  14.883  	    Python modules.  It might not be set at all; it could be
  14.884  	    incorrect; or it may be set only if the login is
  14.885  	    interactive.</para>
  14.886  	</listitem></itemizedlist>
  14.887  
  14.888 -      <para>If you can run <command role="hg-cmd">hg version</command>
  14.889 +      <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
  14.890  	over an ssh connection, well done! You've got the server and
  14.891  	client sorted out.  You should now be able to use Mercurial to
  14.892  	access repositories hosted by that username on that server.
  14.893 @@ -829,19 +826,19 @@
  14.894      <sect2>
  14.895        <title>Using compression with ssh</title>
  14.896  
  14.897 -      <para>Mercurial does not compress data when it uses the ssh
  14.898 +      <para id="x_4b6">Mercurial does not compress data when it uses the ssh
  14.899  	protocol, because the ssh protocol can transparently compress
  14.900  	data.  However, the default behaviour of ssh clients is
  14.901  	<emphasis>not</emphasis> to request compression.</para>
  14.902  
  14.903 -      <para>Over any network other than a fast LAN (even a wireless
  14.904 +      <para id="x_4b7">Over any network other than a fast LAN (even a wireless
  14.905  	network), using compression is likely to significantly speed
  14.906  	up Mercurial's network operations.  For example, over a WAN,
  14.907  	someone measured compression as reducing the amount of time
  14.908  	required to clone a particularly large repository from 51
  14.909  	minutes to 17 minutes.</para>
  14.910  
  14.911 -      <para>Both <command>ssh</command> and <command>plink</command>
  14.912 +      <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
  14.913  	accept a <option role="cmd-opt-ssh">-C</option> option which
  14.914  	turns on compression.  You can easily edit your <filename
  14.915  	  role="special">~/.hgrc</filename> to enable compression for
  14.916 @@ -849,7 +846,7 @@
  14.917        <programlisting>[ui]
  14.918  ssh = ssh -C</programlisting>
  14.919  
  14.920 -      <para>If you use <command>ssh</command>, you can configure it to
  14.921 +      <para id="x_4b9">If you use <command>ssh</command>, you can configure it to
  14.922  	always use compression when talking to your server.  To do
  14.923  	this, edit your <filename
  14.924  	  role="special">.ssh/config</filename> file (which may not
  14.925 @@ -857,7 +854,7 @@
  14.926        <programlisting>Host hg
  14.927    Compression yes
  14.928    HostName hg.example.com</programlisting>
  14.929 -      <para>This defines an alias, <literal>hg</literal>.  When you
  14.930 +      <para id="x_4ba">This defines an alias, <literal>hg</literal>.  When you
  14.931  	use it on the <command>ssh</command> command line or in a
  14.932  	Mercurial <literal>ssh</literal>-protocol URL, it will cause
  14.933  	<command>ssh</command> to connect to
  14.934 @@ -867,20 +864,20 @@
  14.935  
  14.936      </sect2>
  14.937    </sect1>
  14.938 -  <sect1 id="sec.collab.cgi">
  14.939 +  <sect1 id="sec:collab:cgi">
  14.940      <title>Serving over HTTP using CGI</title>
  14.941  
  14.942 -    <para>Depending on how ambitious you are, configuring Mercurial's
  14.943 +    <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
  14.944        CGI interface can take anything from a few moments to several
  14.945        hours.</para>
  14.946  
  14.947 -    <para>We'll begin with the simplest of examples, and work our way
  14.948 +    <para id="x_4bc">We'll begin with the simplest of examples, and work our way
  14.949        towards a more complex configuration.  Even for the most basic
  14.950        case, you're almost certainly going to need to read and modify
  14.951        your web server's configuration.</para>
  14.952  
  14.953      <note>
  14.954 -      <para>  Configuring a web server is a complex, fiddly, and
  14.955 +      <para id="x_4bd">  Configuring a web server is a complex, fiddly, and
  14.956  	highly system-dependent activity.  I can't possibly give you
  14.957  	instructions that will cover anything like all of the cases
  14.958  	you will encounter. Please use your discretion and judgment in
  14.959 @@ -892,25 +889,25 @@
  14.960      <sect2>
  14.961        <title>Web server configuration checklist</title>
  14.962  
  14.963 -      <para>Before you continue, do take a few moments to check a few
  14.964 +      <para id="x_4be">Before you continue, do take a few moments to check a few
  14.965  	aspects of your system's setup.</para>
  14.966  
  14.967        <orderedlist>
  14.968 -	<listitem><para>Do you have a web server installed at all?
  14.969 +	<listitem><para id="x_4bf">Do you have a web server installed at all?
  14.970  	    Mac OS X ships with Apache, but many other systems may not
  14.971  	    have a web server installed.</para>
  14.972  	</listitem>
  14.973 -	<listitem><para>If you have a web server installed, is it
  14.974 +	<listitem><para id="x_4c0">If you have a web server installed, is it
  14.975  	    actually running?  On most systems, even if one is
  14.976  	    present, it will be disabled by default.</para>
  14.977  	</listitem>
  14.978 -	<listitem><para>Is your server configured to allow you to run
  14.979 +	<listitem><para id="x_4c1">Is your server configured to allow you to run
  14.980  	    CGI programs in the directory where you plan to do so?
  14.981  	    Most servers default to explicitly disabling the ability
  14.982  	    to run CGI programs.</para>
  14.983  	</listitem></orderedlist>
  14.984  
  14.985 -      <para>If you don't have a web server installed, and don't have
  14.986 +      <para id="x_4c2">If you don't have a web server installed, and don't have
  14.987  	substantial experience configuring Apache, you should consider
  14.988  	using the <literal>lighttpd</literal> web server instead of
  14.989  	Apache.  Apache has a well-deserved reputation for baroque and
  14.990 @@ -925,7 +922,7 @@
  14.991      <sect2>
  14.992        <title>Basic CGI configuration</title>
  14.993  
  14.994 -      <para>On Unix-like systems, it's common for users to have a
  14.995 +      <para id="x_4c3">On Unix-like systems, it's common for users to have a
  14.996  	subdirectory named something like <filename
  14.997  	  class="directory">public_html</filename> in their home
  14.998  	directory, from which they can serve up web pages.  A file
  14.999 @@ -933,19 +930,19 @@
 14.1000  	accessible at a URL of the form
 14.1001  	<literal>http://www.example.com/username/foo</literal>.</para>
 14.1002  
 14.1003 -      <para>To get started, find the <filename
 14.1004 +      <para id="x_4c4">To get started, find the <filename
 14.1005  	  role="special">hgweb.cgi</filename> script that should be
 14.1006  	present in your Mercurial installation.  If you can't quickly
 14.1007  	find a local copy on your system, simply download one from the
 14.1008  	master Mercurial repository at <ulink
 14.1009  	  url="http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>.</para>
 14.1010  
 14.1011 -      <para>You'll need to copy this script into your <filename
 14.1012 +      <para id="x_4c5">You'll need to copy this script into your <filename
 14.1013  	  class="directory">public_html</filename> directory, and
 14.1014  	ensure that it's executable.</para>
 14.1015        <programlisting>cp .../hgweb.cgi ~/public_html
 14.1016  chmod 755 ~/public_html/hgweb.cgi</programlisting>
 14.1017 -      <para>The <literal>755</literal> argument to
 14.1018 +      <para id="x_4c6">The <literal>755</literal> argument to
 14.1019  	<command>chmod</command> is a little more general than just
 14.1020  	making the script executable: it ensures that the script is
 14.1021  	executable by anyone, and that <quote>group</quote> and
 14.1022 @@ -958,11 +955,11 @@
 14.1023  	must not be writable by others.</para>
 14.1024        <programlisting>chmod 755 ~/public_html</programlisting>
 14.1025  
 14.1026 -      <sect3 id="sec.collab.wtf">
 14.1027 +      <sect3 id="sec:collab:wtf">
 14.1028  	<title>What could <emphasis>possibly</emphasis> go
 14.1029  	  wrong?</title>
 14.1030  
 14.1031 -	<para>Once you've copied the CGI script into place, go into a
 14.1032 +	<para id="x_4c7">Once you've copied the CGI script into place, go into a
 14.1033  	  web browser, and try to open the URL <ulink
 14.1034  	    url="http://myhostname/
 14.1035  	    myuser/hgweb.cgi">http://myhostname/
 14.1036 @@ -976,7 +973,7 @@
 14.1037  	  fresh installation of Apache, and a user account that I
 14.1038  	  created specially to perform this exercise.</para>
 14.1039  
 14.1040 -	<para>Your web server may have per-user directories disabled.
 14.1041 +	<para id="x_4c8">Your web server may have per-user directories disabled.
 14.1042  	  If you're using Apache, search your config file for a
 14.1043  	  <literal>UserDir</literal> directive.  If there's none
 14.1044  	  present, per-user directories will be disabled.  If one
 14.1045 @@ -987,7 +984,7 @@
 14.1046  	  directory, for example <filename
 14.1047  	    class="directory">public_html</filename>.</para>
 14.1048  
 14.1049 -	<para>Your file access permissions may be too restrictive.
 14.1050 +	<para id="x_4c9">Your file access permissions may be too restrictive.
 14.1051  	  The web server must be able to traverse your home directory
 14.1052  	  and directories under your <filename
 14.1053  	    class="directory">public_html</filename> directory, and
 14.1054 @@ -997,34 +994,34 @@
 14.1055  find ~/public_html -type d -print0 | xargs -0r chmod 755
 14.1056  find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
 14.1057  
 14.1058 -	<para>The other possibility with permissions is that you might
 14.1059 +	<para id="x_4ca">The other possibility with permissions is that you might
 14.1060  	  get a completely empty window when you try to load the
 14.1061  	  script.  In this case, it's likely that your access
 14.1062  	  permissions are <emphasis>too permissive</emphasis>.  Apache's
 14.1063  	  <literal>suexec</literal> subsystem won't execute a script
 14.1064  	  that's group- or world-writable, for example.</para>
 14.1065  
 14.1066 -	<para>Your web server may be configured to disallow execution
 14.1067 +	<para id="x_4cb">Your web server may be configured to disallow execution
 14.1068  	  of CGI programs in your per-user web directory.  Here's
 14.1069  	  Apache's default per-user configuration from my Fedora
 14.1070  	  system.</para>
 14.1071  
 14.1072 -	<programlisting><![CDATA[&ch06-apache-config.lst;]]></programlisting>
 14.1073 -
 14.1074 -	<para>If you find a similar-looking
 14.1075 +	&ch06-apache-config.lst;
 14.1076 +
 14.1077 +	<para id="x_4cc">If you find a similar-looking
 14.1078  	  <literal>Directory</literal> group in your Apache
 14.1079  	  configuration, the directive to look at inside it is
 14.1080  	  <literal>Options</literal>. Add <literal>ExecCGI</literal>
 14.1081  	  to the end of this list if it's missing, and restart the web
 14.1082  	  server.</para>
 14.1083  
 14.1084 -	<para>If you find that Apache serves you the text of the CGI
 14.1085 +	<para id="x_4cd">If you find that Apache serves you the text of the CGI
 14.1086  	  script instead of executing it, you may need to either
 14.1087  	  uncomment (if already present) or add a directive like
 14.1088  	  this.</para>
 14.1089  	<programlisting>AddHandler cgi-script .cgi</programlisting>
 14.1090  
 14.1091 -	<para>The next possibility is that you might be served with a
 14.1092 +	<para id="x_4ce">The next possibility is that you might be served with a
 14.1093  	  colourful Python backtrace claiming that it can't import a
 14.1094  	  <literal>mercurial</literal>-related module.  This is
 14.1095  	  actually progress!  The server is now capable of executing
 14.1096 @@ -1038,7 +1035,7 @@
 14.1097  	  directions inside it to correctly set your
 14.1098  	  <envar>PYTHONPATH</envar> environment variable.</para>
 14.1099  
 14.1100 -	<para>Finally, you are <emphasis>certain</emphasis> to by
 14.1101 +	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to by
 14.1102  	  served with another colourful Python backtrace: this one
 14.1103  	  will complain that it can't find <filename
 14.1104  	    class="directory">/path/to/repository</filename>.  Edit
 14.1105 @@ -1048,7 +1045,7 @@
 14.1106  	  with the complete path to the repository you want to serve
 14.1107  	  up.</para>
 14.1108  
 14.1109 -	<para>At this point, when you try to reload the page, you
 14.1110 +	<para id="x_4d0">At this point, when you try to reload the page, you
 14.1111  	  should be presented with a nice HTML view of your
 14.1112  	  repository's history.  Whew!</para>
 14.1113  
 14.1114 @@ -1056,7 +1053,7 @@
 14.1115        <sect3>
 14.1116  	<title>Configuring lighttpd</title>
 14.1117  
 14.1118 -	<para>To be exhaustive in my experiments, I tried configuring
 14.1119 +	<para id="x_4d1">To be exhaustive in my experiments, I tried configuring
 14.1120  	  the increasingly popular <literal>lighttpd</literal> web
 14.1121  	  server to serve the same repository as I described with
 14.1122  	  Apache above.  I had already overcome all of the problems I
 14.1123 @@ -1066,7 +1063,7 @@
 14.1124  	    role="special">hgweb.cgi</filename> script was properly
 14.1125  	  edited.</para>
 14.1126  
 14.1127 -	<para>Once I had Apache running, getting
 14.1128 +	<para id="x_4d2">Once I had Apache running, getting
 14.1129  	  <literal>lighttpd</literal> to serve the repository was a
 14.1130  	  snap (in other words, even if you're trying to use
 14.1131  	  <literal>lighttpd</literal>, you should read the Apache
 14.1132 @@ -1078,7 +1075,7 @@
 14.1133  	  end of the config file, to configure these modules.</para>
 14.1134  	<programlisting>userdir.path = "public_html"
 14.1135  cgi.assign = (".cgi" =&gt; "" )</programlisting>
 14.1136 -	<para>With this done, <literal>lighttpd</literal> ran
 14.1137 +	<para id="x_4d3">With this done, <literal>lighttpd</literal> ran
 14.1138  	  immediately for me.  If I had configured
 14.1139  	  <literal>lighttpd</literal> before Apache, I'd almost
 14.1140  	  certainly have run into many of the same system-level
 14.1141 @@ -1093,7 +1090,7 @@
 14.1142      <sect2>
 14.1143        <title>Sharing multiple repositories with one CGI script</title>
 14.1144  
 14.1145 -      <para>The <filename role="special">hgweb.cgi</filename> script
 14.1146 +      <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
 14.1147  	only lets you publish a single repository, which is an
 14.1148  	annoying restriction.  If you want to publish more than one
 14.1149  	without wracking yourself with multiple copies of the same
 14.1150 @@ -1101,7 +1098,7 @@
 14.1151  	the <filename role="special">hgwebdir.cgi</filename>
 14.1152  	script.</para>
 14.1153  
 14.1154 -      <para>The procedure to configure <filename
 14.1155 +      <para id="x_4d5">The procedure to configure <filename
 14.1156  	  role="special">hgwebdir.cgi</filename> is only a little more
 14.1157  	involved than for <filename
 14.1158  	  role="special">hgweb.cgi</filename>.  First, you must obtain
 14.1159 @@ -1109,21 +1106,23 @@
 14.1160  	download a copy from the master Mercurial repository at <ulink
 14.1161  	  url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.</para>
 14.1162  
 14.1163 -      <para>You'll need to copy this script into your <filename
 14.1164 +      <para id="x_4d6">You'll need to copy this script into your <filename
 14.1165  	  class="directory">public_html</filename> directory, and
 14.1166  	ensure that it's executable.</para>
 14.1167 +
 14.1168        <programlisting>cp .../hgwebdir.cgi ~/public_html
 14.1169  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
 14.1170 -      <para>With basic configuration out of the way, try to visit
 14.1171 -	<ulink url="http://myhostname/
 14.1172 +
 14.1173 +      <para id="x_4d7">With basic configuration out of the way, try to
 14.1174 +	visit <ulink url="http://myhostname/
 14.1175  	  myuser/hgwebdir.cgi">http://myhostname/
 14.1176  	  myuser/hgwebdir.cgi</ulink> in your browser.  It should
 14.1177  	display an empty list of repositories.  If you get a blank
 14.1178  	window or error message, try walking through the list of
 14.1179 -	potential problems in section <xref
 14.1180 -	  linkend="sec.collab.wtf"/>.</para>
 14.1181 -
 14.1182 -      <para>The <filename role="special">hgwebdir.cgi</filename>
 14.1183 +	potential problems in <xref
 14.1184 +	  linkend="sec:collab:wtf"/>.</para>
 14.1185 +
 14.1186 +      <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
 14.1187  	script relies on an external configuration file.  By default,
 14.1188  	it searches for a file named <filename
 14.1189  	  role="special">hgweb.config</filename> in the same directory
 14.1190 @@ -1133,7 +1132,7 @@
 14.1191  	<literal>ConfigParser</literal>
 14.1192  	<citation>web:configparser</citation> module.</para>
 14.1193  
 14.1194 -      <para>The easiest way to configure <filename
 14.1195 +      <para id="x_4d9">The easiest way to configure <filename
 14.1196  	  role="special">hgwebdir.cgi</filename> is with a section
 14.1197  	named <literal>collections</literal>.  This will automatically
 14.1198  	publish <emphasis>every</emphasis> repository under the
 14.1199 @@ -1141,7 +1140,7 @@
 14.1200  	this:</para>
 14.1201        <programlisting>[collections]
 14.1202  /my/root = /my/root</programlisting>
 14.1203 -      <para>Mercurial interprets this by looking at the directory name
 14.1204 +      <para id="x_4da">Mercurial interprets this by looking at the directory name
 14.1205  	on the <emphasis>right</emphasis> hand side of the
 14.1206  	<quote><literal>=</literal></quote> sign; finding repositories
 14.1207  	in that directory hierarchy; and using the text on the
 14.1208 @@ -1150,7 +1149,7 @@
 14.1209  	remaining component of a path after this stripping has
 14.1210  	occurred is called a <quote>virtual path</quote>.</para>
 14.1211  
 14.1212 -      <para>Given the example above, if we have a repository whose
 14.1213 +      <para id="x_4db">Given the example above, if we have a repository whose
 14.1214  	local path is <filename
 14.1215  	  class="directory">/my/root/this/repo</filename>, the CGI
 14.1216  	script will strip the leading <filename
 14.1217 @@ -1164,7 +1163,7 @@
 14.1218  	  myuser/hgwebdir.cgi/this/repo">http://myhostname/
 14.1219  	  myuser/hgwebdir.cgi/this/repo</ulink>.</para>
 14.1220  
 14.1221 -      <para>If we replace <filename
 14.1222 +      <para id="x_4dc">If we replace <filename
 14.1223  	  class="directory">/my/root</filename> on the left hand side
 14.1224  	of this example with <filename
 14.1225  	  class="directory">/my</filename>, then <filename
 14.1226 @@ -1174,13 +1173,13 @@
 14.1227  	  class="directory">root/this/repo</filename> instead of
 14.1228  	<filename class="directory">this/repo</filename>.</para>
 14.1229  
 14.1230 -      <para>The <filename role="special">hgwebdir.cgi</filename>
 14.1231 +      <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
 14.1232  	script will recursively search each directory listed in the
 14.1233  	<literal>collections</literal> section of its configuration
 14.1234  	file, but it will <literal>not</literal> recurse into the
 14.1235  	repositories it finds.</para>
 14.1236  
 14.1237 -      <para>The <literal>collections</literal> mechanism makes it easy
 14.1238 +      <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
 14.1239  	to publish many repositories in a <quote>fire and
 14.1240  	  forget</quote> manner.  You only need to set up the CGI
 14.1241  	script and configuration file one time.  Afterwards, you can
 14.1242 @@ -1193,7 +1192,7 @@
 14.1243  	<title>Explicitly specifying which repositories to
 14.1244  	  publish</title>
 14.1245  
 14.1246 -	<para>In addition to the <literal>collections</literal>
 14.1247 +	<para id="x_4df">In addition to the <literal>collections</literal>
 14.1248  	  mechanism, the <filename
 14.1249  	    role="special">hgwebdir.cgi</filename> script allows you
 14.1250  	  to publish a specific list of repositories.  To do so,
 14.1251 @@ -1202,20 +1201,20 @@
 14.1252  	<programlisting>[paths]
 14.1253  repo1 = /my/path/to/some/repo
 14.1254  repo2 = /some/path/to/another</programlisting>
 14.1255 -	<para>In this case, the virtual path (the component that will
 14.1256 +	<para id="x_4e0">In this case, the virtual path (the component that will
 14.1257  	  appear in a URL) is on the left hand side of each
 14.1258  	  definition, while the path to the repository is on the
 14.1259  	  right.  Notice that there does not need to be any
 14.1260  	  relationship between the virtual path you choose and the
 14.1261  	  location of a repository in your filesystem.</para>
 14.1262  
 14.1263 -	<para>If you wish, you can use both the
 14.1264 +	<para id="x_4e1">If you wish, you can use both the
 14.1265  	  <literal>collections</literal> and <literal>paths</literal>
 14.1266  	  mechanisms simultaneously in a single configuration
 14.1267  	  file.</para>
 14.1268  
 14.1269  	<note>
 14.1270 -	  <para>  If multiple repositories have the same virtual path,
 14.1271 +	  <para id="x_4e2">  If multiple repositories have the same virtual path,
 14.1272  	    <filename role="special">hgwebdir.cgi</filename> will not
 14.1273  	    report an error.  Instead, it will behave
 14.1274  	    unpredictably.</para>
 14.1275 @@ -1226,12 +1225,12 @@
 14.1276      <sect2>
 14.1277        <title>Downloading source archives</title>
 14.1278  
 14.1279 -      <para>Mercurial's web interface lets users download an archive
 14.1280 +      <para id="x_4e3">Mercurial's web interface lets users download an archive
 14.1281  	of any revision.  This archive will contain a snapshot of the
 14.1282  	working directory as of that revision, but it will not contain
 14.1283  	a copy of the repository data.</para>
 14.1284  
 14.1285 -      <para>By default, this feature is not enabled.  To enable it,
 14.1286 +      <para id="x_4e4">By default, this feature is not enabled.  To enable it,
 14.1287  	you'll need to add an <envar
 14.1288  	  role="rc-item-web">allow_archive</envar> item to the
 14.1289  	<literal role="rc-web">web</literal> section of your <filename
 14.1290 @@ -1241,7 +1240,7 @@
 14.1291      <sect2>
 14.1292        <title>Web configuration options</title>
 14.1293  
 14.1294 -      <para>Mercurial's web interfaces (the <command role="hg-cmd">hg
 14.1295 +      <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
 14.1296  	  serve</command> command, and the <filename
 14.1297  	  role="special">hgweb.cgi</filename> and <filename
 14.1298  	  role="special">hgwebdir.cgi</filename> scripts) have a
 14.1299 @@ -1249,7 +1248,7 @@
 14.1300  	belong in a section named <literal
 14.1301  	  role="rc-web">web</literal>.</para>
 14.1302        <itemizedlist>
 14.1303 -	<listitem><para><envar
 14.1304 +	<listitem><para id="x_4e6"><envar
 14.1305  	      role="rc-item-web">allow_archive</envar>: Determines
 14.1306  	    which (if any) archive download mechanisms Mercurial
 14.1307  	    supports.  If you enable this feature, users of the web
 14.1308 @@ -1258,30 +1257,30 @@
 14.1309  	    archive feature, this item must take the form of a
 14.1310  	    sequence of words drawn from the list below.</para>
 14.1311  	  <itemizedlist>
 14.1312 -	    <listitem><para><literal>bz2</literal>: A
 14.1313 +	    <listitem><para id="x_4e7"><literal>bz2</literal>: A
 14.1314  		<command>tar</command> archive, compressed using
 14.1315  		<literal>bzip2</literal> compression.  This has the
 14.1316  		best compression ratio, but uses the most CPU time on
 14.1317  		the server.</para>
 14.1318  	    </listitem>
 14.1319 -	    <listitem><para><literal>gz</literal>: A
 14.1320 +	    <listitem><para id="x_4e8"><literal>gz</literal>: A
 14.1321  		<command>tar</command> archive, compressed using
 14.1322  		<literal>gzip</literal> compression.</para>
 14.1323  	    </listitem>
 14.1324 -	    <listitem><para><literal>zip</literal>: A
 14.1325 +	    <listitem><para id="x_4e9"><literal>zip</literal>: A
 14.1326  		<command>zip</command> archive, compressed using LZW
 14.1327  		compression.  This format has the worst compression
 14.1328  		ratio, but is widely used in the Windows world.</para>
 14.1329  	    </listitem>
 14.1330  	  </itemizedlist>
 14.1331 -	  <para>  If you provide an empty list, or don't have an
 14.1332 +	  <para id="x_4ea">  If you provide an empty list, or don't have an
 14.1333  	    <envar role="rc-item-web">allow_archive</envar> entry at
 14.1334  	    all, this feature will be disabled.  Here is an example of
 14.1335  	    how to enable all three supported formats.</para>
 14.1336  	  <programlisting>[web]
 14.1337  allow_archive = bz2 gz zip</programlisting>
 14.1338  	</listitem>
 14.1339 -	<listitem><para><envar role="rc-item-web">allowpull</envar>:
 14.1340 +	<listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
 14.1341  	    Boolean.  Determines whether the web interface allows
 14.1342  	    remote users to <command role="hg-cmd">hg pull</command>
 14.1343  	    and <command role="hg-cmd">hg clone</command> this
 14.1344 @@ -1290,7 +1289,7 @@
 14.1345  	    <quote>human-oriented</quote> portion of the web interface
 14.1346  	    is available.</para>
 14.1347  	</listitem>
 14.1348 -	<listitem><para><envar role="rc-item-web">contact</envar>:
 14.1349 +	<listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
 14.1350  	    String.  A free-form (but preferably brief) string
 14.1351  	    identifying the person or group in charge of the
 14.1352  	    repository.  This often contains the name and email
 14.1353 @@ -1301,38 +1300,39 @@
 14.1354  	      role="special">~/.hgrc</filename> if every repository
 14.1355  	    has a single maintainer.</para>
 14.1356  	</listitem>
 14.1357 -	<listitem><para><envar role="rc-item-web">maxchanges</envar>:
 14.1358 +	<listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
 14.1359  	    Integer.  The default maximum number of changesets to
 14.1360  	    display in a single page of output.</para>
 14.1361  	</listitem>
 14.1362 -	<listitem><para><envar role="rc-item-web">maxfiles</envar>:
 14.1363 +	<listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
 14.1364  	    Integer.  The default maximum number of modified files to
 14.1365  	    display in a single page of output.</para>
 14.1366  	</listitem>
 14.1367 -	<listitem><para><envar role="rc-item-web">stripes</envar>:
 14.1368 +	<listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
 14.1369  	    Integer.  If the web interface displays alternating
 14.1370  	    <quote>stripes</quote> to make it easier to visually align
 14.1371  	    rows when you are looking at a table, this number controls
 14.1372  	    the number of rows in each stripe.</para>
 14.1373  	</listitem>
 14.1374 -	<listitem><para><envar role="rc-item-web">style</envar>:
 14.1375 -	    Controls the template Mercurial uses to display the web
 14.1376 -	    interface.  Mercurial ships with two web templates, named
 14.1377 +	<listitem><para id="x_4f0"><envar
 14.1378 +	      role="rc-item-web">style</envar>: Controls the template
 14.1379 +	    Mercurial uses to display the web interface.  Mercurial
 14.1380 +	    ships with two web templates, named
 14.1381  	    <literal>default</literal> and <literal>gitweb</literal>
 14.1382  	    (the latter is much more visually attractive).  You can
 14.1383 -	    also specify a custom template of your own; see chapter
 14.1384 -	    <xref linkend="chap.template"/> for details.
 14.1385 -	    Here, you can see how to enable the
 14.1386 -	    <literal>gitweb</literal> style.</para>
 14.1387 +	    also specify a custom template of your own; see 
 14.1388 +	    <xref linkend="chap:template"/> for details. Here, you can
 14.1389 +	    see how to enable the <literal>gitweb</literal>
 14.1390 +	    style.</para>
 14.1391  	  <programlisting>[web]
 14.1392  style = gitweb</programlisting>
 14.1393  	</listitem>
 14.1394 -	<listitem><para><envar role="rc-item-web">templates</envar>:
 14.1395 +	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
 14.1396  	    Path.  The directory in which to search for template
 14.1397  	    files.  By default, Mercurial searches in the directory in
 14.1398  	    which it was installed.</para>
 14.1399  	</listitem></itemizedlist>
 14.1400 -      <para>If you are using <filename
 14.1401 +      <para id="x_4f2">If you are using <filename
 14.1402  	  role="special">hgwebdir.cgi</filename>, you can place a few
 14.1403  	configuration items in a <literal role="rc-web">web</literal>
 14.1404  	section of the <filename
 14.1405 @@ -1345,17 +1345,17 @@
 14.1406        <sect3>
 14.1407  	<title>Options specific to an individual repository</title>
 14.1408  
 14.1409 -	<para>A few <literal role="rc-web">web</literal> configuration
 14.1410 +	<para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
 14.1411  	  items ought to be placed in a repository's local <filename
 14.1412  	    role="special">.hg/hgrc</filename>, rather than a user's
 14.1413  	  or global <filename role="special">~/.hgrc</filename>.</para>
 14.1414  	<itemizedlist>
 14.1415 -	  <listitem><para><envar
 14.1416 +	  <listitem><para id="x_4f4"><envar
 14.1417  		role="rc-item-web">description</envar>: String.  A
 14.1418  	      free-form (but preferably brief) string that describes
 14.1419  	      the contents or purpose of the repository.</para>
 14.1420  	  </listitem>
 14.1421 -	  <listitem><para><envar role="rc-item-web">name</envar>:
 14.1422 +	  <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
 14.1423  	      String.  The name to use for the repository in the web
 14.1424  	      interface.  This overrides the default name, which is
 14.1425  	      the last component of the repository's path.</para>
 14.1426 @@ -1366,13 +1366,13 @@
 14.1427  	<title>Options specific to the <command role="hg-cmd">hg
 14.1428  	    serve</command> command</title>
 14.1429  
 14.1430 -	<para>Some of the items in the <literal
 14.1431 +	<para id="x_4f6">Some of the items in the <literal
 14.1432  	    role="rc-web">web</literal> section of a <filename
 14.1433  	    role="special">~/.hgrc</filename> file are only for use
 14.1434  	  with the <command role="hg-cmd">hg serve</command>
 14.1435  	  command.</para>
 14.1436  	<itemizedlist>
 14.1437 -	  <listitem><para><envar role="rc-item-web">accesslog</envar>:
 14.1438 +	  <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
 14.1439  	      Path.  The name of a file into which to write an access
 14.1440  	      log.  By default, the <command role="hg-cmd">hg
 14.1441  		serve</command> command writes this information to
 14.1442 @@ -1380,22 +1380,22 @@
 14.1443  	      in the standard <quote>combined</quote> file format used
 14.1444  	      by almost all web servers.</para>
 14.1445  	  </listitem>
 14.1446 -	  <listitem><para><envar role="rc-item-web">address</envar>:
 14.1447 +	  <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
 14.1448  	      String.  The local address on which the server should
 14.1449  	      listen for incoming connections.  By default, the server
 14.1450  	      listens on all addresses.</para>
 14.1451  	  </listitem>
 14.1452 -	  <listitem><para><envar role="rc-item-web">errorlog</envar>:
 14.1453 +	  <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
 14.1454  	      Path.  The name of a file into which to write an error
 14.1455  	      log.  By default, the <command role="hg-cmd">hg
 14.1456  		serve</command> command writes this information to
 14.1457  	      standard error, not to a file.</para>
 14.1458  	  </listitem>
 14.1459 -	  <listitem><para><envar role="rc-item-web">ipv6</envar>:
 14.1460 +	  <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
 14.1461  	      Boolean.  Whether to use the IPv6 protocol. By default,
 14.1462  	      IPv6 is not used.</para>
 14.1463  	  </listitem>
 14.1464 -	  <listitem><para><envar role="rc-item-web">port</envar>:
 14.1465 +	  <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
 14.1466  	      Integer.  The TCP port number on which the server should
 14.1467  	      listen.  The default port number used is 8000.</para>
 14.1468  	  </listitem></itemizedlist>
 14.1469 @@ -1406,14 +1406,14 @@
 14.1470  	    role="special">~/.hgrc</filename> file to add <literal
 14.1471  	    role="rc-web">web</literal> items to</title>
 14.1472  
 14.1473 -	<para>It is important to remember that a web server like
 14.1474 +	<para id="x_4fc">It is important to remember that a web server like
 14.1475  	  Apache or <literal>lighttpd</literal> will run under a user
 14.1476  	  ID that is different to yours. CGI scripts run by your
 14.1477  	  server, such as <filename
 14.1478  	    role="special">hgweb.cgi</filename>, will usually also run
 14.1479  	  under that user ID.</para>
 14.1480  
 14.1481 -	<para>If you add <literal role="rc-web">web</literal> items to
 14.1482 +	<para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
 14.1483  	  your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
 14.1484  	  <filename role="special">~/.hgrc</filename> file.  Those
 14.1485  	  settings will thus only affect the behaviour of the <command

    15.1 --- a/en/ch06-filenames.xml	Fri Mar 20 17:17:55 2009 +0800
    15.2 +++ b/en/ch06-filenames.xml	Mon Mar 30 16:23:33 2009 +0800
    15.3 @@ -1,6 +1,6 @@
    15.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    15.5  
    15.6 -<chapter id="chap.names">
    15.7 +<chapter id="chap:names">
    15.8    <?dbhtml filename="file-names-and-pattern-matching.html"?>
    15.9    <title>File names and pattern matching</title>
   15.10  
   15.11 @@ -274,7 +274,7 @@
   15.12      <para id="x_569">XXX.</para>
   15.13  
   15.14    </sect1>
   15.15 -  <sect1 id="sec.names.case">
   15.16 +  <sect1 id="sec:names:case">
   15.17      <title>Case sensitivity</title>
   15.18  
   15.19      <para id="x_56a">If you're working in a mixed development environment that

    16.1 --- a/en/ch07-branch.xml	Fri Mar 20 17:17:55 2009 +0800
    16.2 +++ b/en/ch07-branch.xml	Mon Mar 30 16:23:33 2009 +0800
    16.3 @@ -1,6 +1,6 @@
    16.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    16.5  
    16.6 -<chapter id="chap.branch">
    16.7 +<chapter id="chap:branch">
    16.8    <?dbhtml filename="managing-releases-and-branchy-development.html"?>
    16.9    <title>Managing releases and branchy development</title>
   16.10  

    17.1 --- a/en/ch08-undo.xml	Fri Mar 20 17:17:55 2009 +0800
    17.2 +++ b/en/ch08-undo.xml	Mon Mar 30 16:23:33 2009 +0800
    17.3 @@ -1,10 +1,10 @@
    17.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    17.5  
    17.6 -<chapter id="chap.undo">
    17.7 +<chapter id="chap:undo">
    17.8    <?dbhtml filename="finding-and-fixing-mistakes.html"?>
    17.9    <title>Finding and fixing mistakes</title>
   17.10  
   17.11 -  <para>To err might be human, but to really handle the consequences
   17.12 +  <para id="x_d2">To err might be human, but to really handle the consequences
   17.13      well takes a top-notch revision control system.  In this chapter,
   17.14      we'll discuss some of the techniques you can use when you find
   17.15      that a problem has crept into your project.  Mercurial has some
   17.16 @@ -17,7 +17,7 @@
   17.17      <sect2>
   17.18        <title>The accidental commit</title>
   17.19  
   17.20 -      <para>I have the occasional but persistent problem of typing
   17.21 +      <para id="x_d3">I have the occasional but persistent problem of typing
   17.22  	rather more quickly than I can think, which sometimes results
   17.23  	in me committing a changeset that is either incomplete or
   17.24  	plain wrong.  In my case, the usual kind of incomplete
   17.25 @@ -27,33 +27,33 @@
   17.26  	less annoying.</para>
   17.27  
   17.28      </sect2>
   17.29 -    <sect2 id="sec.undo.rollback">
   17.30 +    <sect2 id="sec:undo:rollback">
   17.31        <title>Rolling back a transaction</title>
   17.32  
   17.33 -      <para>In section <xref linkend="sec.concepts.txn"/>, I mentioned
   17.34 -	that Mercurial treats each modification of a repository as a
   17.35 -	<emphasis>transaction</emphasis>.  Every time you commit a
   17.36 -	changeset or pull changes from another repository, Mercurial
   17.37 -	remembers what you did.  You can undo, or <emphasis>roll
   17.38 -	  back</emphasis>, exactly one of these actions using the
   17.39 -	<command role="hg-cmd">hg rollback</command> command.  (See
   17.40 -	section <xref linkend="sec.undo.rollback-after-push"/> for an
   17.41 -	important caveat about the use of this command.)</para>
   17.42 -
   17.43 -      <para>Here's a mistake that I often find myself making:
   17.44 +      <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I
   17.45 +	mentioned that Mercurial treats each modification of a
   17.46 +	repository as a <emphasis>transaction</emphasis>.  Every time
   17.47 +	you commit a changeset or pull changes from another
   17.48 +	repository, Mercurial remembers what you did.  You can undo,
   17.49 +	or <emphasis>roll back</emphasis>, exactly one of these
   17.50 +	actions using the <command role="hg-cmd">hg rollback</command>
   17.51 +	command.  (See <xref linkend="sec:undo:rollback-after-push"/>
   17.52 +	for an important caveat about the use of this command.)</para>
   17.53 +
   17.54 +      <para id="x_d5">Here's a mistake that I often find myself making:
   17.55  	committing a change in which I've created a new file, but
   17.56  	forgotten to <command role="hg-cmd">hg add</command>
   17.57  	it.</para>
   17.58  
   17.59        &interaction.rollback.commit;
   17.60  
   17.61 -      <para>Looking at the output of <command role="hg-cmd">hg
   17.62 +      <para id="x_d6">Looking at the output of <command role="hg-cmd">hg
   17.63  	  status</command> after the commit immediately confirms the
   17.64  	error.</para>
   17.65  
   17.66        &interaction.rollback.status;
   17.67  
   17.68 -      <para>The commit captured the changes to the file
   17.69 +      <para id="x_d7">The commit captured the changes to the file
   17.70  	<filename>a</filename>, but not the new file
   17.71  	<filename>b</filename>.  If I were to push this changeset to a
   17.72  	repository that I shared with a colleague, the chances are
   17.73 @@ -62,14 +62,14 @@
   17.74  	repository when they pulled my changes.  I would thus become
   17.75  	the object of some indignation.</para>
   17.76  
   17.77 -      <para>However, luck is with me&emdash;I've caught my error
   17.78 +      <para id="x_d8">However, luck is with me&emdash;I've caught my error
   17.79  	before I pushed the changeset.  I use the <command
   17.80  	  role="hg-cmd">hg rollback</command> command, and Mercurial
   17.81  	makes that last changeset vanish.</para>
   17.82  
   17.83        &interaction.rollback.rollback;
   17.84  
   17.85 -      <para>Notice that the changeset is no longer present in the
   17.86 +      <para id="x_d9">Notice that the changeset is no longer present in the
   17.87  	repository's history, and the working directory once again
   17.88  	thinks that the file <filename>a</filename> is modified.  The
   17.89  	commit and rollback have left the working directory exactly as
   17.90 @@ -84,14 +84,14 @@
   17.91      <sect2>
   17.92        <title>The erroneous pull</title>
   17.93  
   17.94 -      <para>It's common practice with Mercurial to maintain separate
   17.95 +      <para id="x_da">It's common practice with Mercurial to maintain separate
   17.96  	development branches of a project in different repositories.
   17.97  	Your development team might have one shared repository for
   17.98  	your project's <quote>0.9</quote> release, and another,
   17.99  	containing different changes, for the <quote>1.0</quote>
  17.100  	release.</para>
  17.101  
  17.102 -      <para>Given this, you can imagine that the consequences could be
  17.103 +      <para id="x_db">Given this, you can imagine that the consequences could be
  17.104  	messy if you had a local <quote>0.9</quote> repository, and
  17.105  	accidentally pulled changes from the shared <quote>1.0</quote>
  17.106  	repository into it.  At worst, you could be paying
  17.107 @@ -103,7 +103,7 @@
  17.108  	see it pull a suspiciously large number of changes into the
  17.109  	repository.</para>
  17.110  
  17.111 -      <para>The <command role="hg-cmd">hg rollback</command> command
  17.112 +      <para id="x_dc">The <command role="hg-cmd">hg rollback</command> command
  17.113  	will work nicely to expunge all of the changesets that you
  17.114  	just pulled.  Mercurial groups all changes from one <command
  17.115  	  role="hg-cmd">hg pull</command> into a single transaction,
  17.116 @@ -111,10 +111,10 @@
  17.117  	need to undo this mistake.</para>
  17.118  
  17.119      </sect2>
  17.120 -    <sect2 id="sec.undo.rollback-after-push">
  17.121 +    <sect2 id="sec:undo:rollback-after-push">
  17.122        <title>Rolling back is useless once you've pushed</title>
  17.123  
  17.124 -      <para>The value of the <command role="hg-cmd">hg
  17.125 +      <para id="x_dd">The value of the <command role="hg-cmd">hg
  17.126  	  rollback</command> command drops to zero once you've pushed
  17.127  	your changes to another repository.  Rolling back a change
  17.128  	makes it disappear entirely, but <emphasis>only</emphasis> in
  17.129 @@ -123,7 +123,7 @@
  17.130  	eliminates history, there's no way for the disappearance of a
  17.131  	change to propagate between repositories.</para>
  17.132  
  17.133 -      <para>If you've pushed a change to another
  17.134 +      <para id="x_de">If you've pushed a change to another
  17.135  	repository&emdash;particularly if it's a shared
  17.136  	repository&emdash;it has essentially <quote>escaped into the
  17.137  	  wild,</quote> and you'll have to recover from your mistake
  17.138 @@ -132,7 +132,7 @@
  17.139  	you pushed to, is that the changeset will reappear in your
  17.140  	repository.</para>
  17.141  
  17.142 -      <para>(If you absolutely know for sure that the change you want
  17.143 +      <para id="x_df">(If you absolutely know for sure that the change you want
  17.144  	to roll back is the most recent change in the repository that
  17.145  	you pushed to, <emphasis>and</emphasis> you know that nobody
  17.146  	else could have pulled it from that repository, you can roll
  17.147 @@ -146,7 +146,7 @@
  17.148      <sect2>
  17.149        <title>You can only roll back once</title>
  17.150  
  17.151 -      <para>Mercurial stores exactly one transaction in its
  17.152 +      <para id="x_e0">Mercurial stores exactly one transaction in its
  17.153  	transaction log; that transaction is the most recent one that
  17.154  	occurred in the repository. This means that you can only roll
  17.155  	back one transaction.  If you expect to be able to roll back
  17.156 @@ -155,7 +155,7 @@
  17.157  
  17.158        &interaction.rollback.twice;
  17.159  
  17.160 -      <para>Once you've rolled back one transaction in a repository,
  17.161 +      <para id="x_e1">Once you've rolled back one transaction in a repository,
  17.162  	you can't roll back again in that repository until you perform
  17.163  	another commit or pull.</para>
  17.164  
  17.165 @@ -164,7 +164,7 @@
  17.166    <sect1>
  17.167      <title>Reverting the mistaken change</title>
  17.168  
  17.169 -    <para>If you make a modification to a file, and decide that you
  17.170 +    <para id="x_e2">If you make a modification to a file, and decide that you
  17.171        really didn't want to change the file at all, and you haven't
  17.172        yet committed your changes, the <command role="hg-cmd">hg
  17.173  	revert</command> command is the one you'll need.  It looks at
  17.174 @@ -173,57 +173,57 @@
  17.175        changeset. (That's a long-winded way of saying that, in the
  17.176        normal case, it undoes your modifications.)</para>
  17.177  
  17.178 -    <para>Let's illustrate how the <command role="hg-cmd">hg
  17.179 +    <para id="x_e3">Let's illustrate how the <command role="hg-cmd">hg
  17.180  	revert</command> command works with yet another small example.
  17.181        We'll begin by modifying a file that Mercurial is already
  17.182        tracking.</para>
  17.183  
  17.184      &interaction.daily.revert.modify;
  17.185  
  17.186 -    <para>If we don't
  17.187 +    <para id="x_e4">If we don't
  17.188        want that change, we can simply <command role="hg-cmd">hg
  17.189  	revert</command> the file.</para>
  17.190  
  17.191        &interaction.daily.revert.unmodify;
  17.192  
  17.193 -    <para>The <command role="hg-cmd">hg revert</command> command
  17.194 +    <para id="x_e5">The <command role="hg-cmd">hg revert</command> command
  17.195        provides us with an extra degree of safety by saving our
  17.196        modified file with a <filename>.orig</filename>
  17.197        extension.</para>
  17.198  
  17.199      &interaction.daily.revert.status;
  17.200  
  17.201 -    <para>Here is a summary of the cases that the <command
  17.202 +    <para id="x_e6">Here is a summary of the cases that the <command
  17.203  	role="hg-cmd">hg revert</command> command can deal with.  We
  17.204        will describe each of these in more detail in the section that
  17.205        follows.</para>
  17.206      <itemizedlist>
  17.207 -      <listitem><para>If you modify a file, it will restore the file
  17.208 +      <listitem><para id="x_e7">If you modify a file, it will restore the file
  17.209  	  to its unmodified state.</para>
  17.210        </listitem>
  17.211 -      <listitem><para>If you <command role="hg-cmd">hg add</command> a
  17.212 +      <listitem><para id="x_e8">If you <command role="hg-cmd">hg add</command> a
  17.213  	  file, it will undo the <quote>added</quote> state of the
  17.214  	  file, but leave the file itself untouched.</para>
  17.215        </listitem>
  17.216 -      <listitem><para>If you delete a file without telling Mercurial,
  17.217 +      <listitem><para id="x_e9">If you delete a file without telling Mercurial,
  17.218  	  it will restore the file to its unmodified contents.</para>
  17.219        </listitem>
  17.220 -      <listitem><para>If you use the <command role="hg-cmd">hg
  17.221 +      <listitem><para id="x_ea">If you use the <command role="hg-cmd">hg
  17.222  	    remove</command> command to remove a file, it will undo
  17.223  	  the <quote>removed</quote> state of the file, and restore
  17.224  	  the file to its unmodified contents.</para>
  17.225        </listitem></itemizedlist>
  17.226  
  17.227 -    <sect2 id="sec.undo.mgmt">
  17.228 +    <sect2 id="sec:undo:mgmt">
  17.229        <title>File management errors</title>
  17.230  
  17.231 -      <para>The <command role="hg-cmd">hg revert</command> command is
  17.232 +      <para id="x_eb">The <command role="hg-cmd">hg revert</command> command is
  17.233  	useful for more than just modified files.  It lets you reverse
  17.234  	the results of all of Mercurial's file management
  17.235  	commands&emdash;<command role="hg-cmd">hg add</command>,
  17.236  	<command role="hg-cmd">hg remove</command>, and so on.</para>
  17.237  
  17.238 -      <para>If you <command role="hg-cmd">hg add</command> a file,
  17.239 +      <para id="x_ec">If you <command role="hg-cmd">hg add</command> a file,
  17.240  	then decide that in fact you don't want Mercurial to track it,
  17.241  	use <command role="hg-cmd">hg revert</command> to undo the
  17.242  	add.  Don't worry; Mercurial will not modify the file in any
  17.243 @@ -231,7 +231,7 @@
  17.244  
  17.245        &interaction.daily.revert.add;
  17.246  
  17.247 -      <para>Similarly, if you ask Mercurial to <command
  17.248 +      <para id="x_ed">Similarly, if you ask Mercurial to <command
  17.249  	  role="hg-cmd">hg remove</command> a file, you can use
  17.250  	<command role="hg-cmd">hg revert</command> to restore it to
  17.251  	the contents it had as of the parent of the working directory.
  17.252 @@ -242,7 +242,7 @@
  17.253  
  17.254        &interaction.daily.revert.missing;
  17.255  
  17.256 -      <para>If you revert a <command role="hg-cmd">hg copy</command>,
  17.257 +      <para id="x_ee">If you revert a <command role="hg-cmd">hg copy</command>,
  17.258  	the copied-to file remains in your working directory
  17.259  	afterwards, untracked.  Since a copy doesn't affect the
  17.260  	copied-from file in any way, Mercurial doesn't do anything
  17.261 @@ -253,7 +253,7 @@
  17.262        <sect3>
  17.263  	<title>A slightly special case: reverting a rename</title>
  17.264  
  17.265 -	<para>If you <command role="hg-cmd">hg rename</command> a
  17.266 +	<para id="x_ef">If you <command role="hg-cmd">hg rename</command> a
  17.267  	  file, there is one small detail that you should remember.
  17.268  	  When you <command role="hg-cmd">hg revert</command> a
  17.269  	  rename, it's not enough to provide the name of the
  17.270 @@ -261,7 +261,7 @@
  17.271  
  17.272  	&interaction.daily.revert.rename;
  17.273  
  17.274 -	<para>As you can see from the output of <command
  17.275 +	<para id="x_f0">As you can see from the output of <command
  17.276  	    role="hg-cmd">hg status</command>, the renamed-to file is
  17.277  	  no longer identified as added, but the
  17.278  	  renamed-<emphasis>from</emphasis> file is still removed!
  17.279 @@ -270,22 +270,22 @@
  17.280  
  17.281  	&interaction.daily.revert.rename-orig;
  17.282  
  17.283 -	<para>So remember, to revert a <command role="hg-cmd">hg
  17.284 +	<para id="x_f1">So remember, to revert a <command role="hg-cmd">hg
  17.285  	    rename</command>, you must provide
  17.286  	  <emphasis>both</emphasis> the source and destination
  17.287  	  names.</para>
  17.288  
  17.289 -	<para>% TODO: the output doesn't look like it will be
  17.290 +	<para id="x_f2">% TODO: the output doesn't look like it will be
  17.291  	  removed!</para>
  17.292  
  17.293 -	<para>(By the way, if you rename a file, then modify the
  17.294 +	<para id="x_f3">(By the way, if you rename a file, then modify the
  17.295  	  renamed-to file, then revert both components of the rename,
  17.296  	  when Mercurial restores the file that was removed as part of
  17.297  	  the rename, it will be unmodified. If you need the
  17.298  	  modifications in the renamed-to file to show up in the
  17.299  	  renamed-from file, don't forget to copy them over.)</para>
  17.300  
  17.301 -	<para>These fiddly aspects of reverting a rename arguably
  17.302 +	<para id="x_f4">These fiddly aspects of reverting a rename arguably
  17.303  	  constitute a small bug in Mercurial.</para>
  17.304  
  17.305        </sect3>
  17.306 @@ -294,24 +294,24 @@
  17.307    <sect1>
  17.308      <title>Dealing with committed changes</title>
  17.309  
  17.310 -    <para>Consider a case where you have committed a change $a$, and
  17.311 +    <para id="x_f5">Consider a case where you have committed a change $a$, and
  17.312        another change $b$ on top of it; you then realise that change
  17.313        $a$ was incorrect.  Mercurial lets you <quote>back out</quote>
  17.314        an entire changeset automatically, and building blocks that let
  17.315        you reverse part of a changeset by hand.</para>
  17.316  
  17.317 -    <para>Before you read this section, here's something to keep in
  17.318 -      mind: the <command role="hg-cmd">hg backout</command> command
  17.319 -      undoes changes by <emphasis>adding</emphasis> history, not by
  17.320 -      modifying or erasing it.  It's the right tool to use if you're
  17.321 -      fixing bugs, but not if you're trying to undo some change that
  17.322 -      has catastrophic consequences.  To deal with those, see section
  17.323 -      <xref linkend="sec.undo.aaaiiieee"/>.</para>
  17.324 +    <para id="x_f6">Before you read this section, here's something to
  17.325 +      keep in mind: the <command role="hg-cmd">hg backout</command>
  17.326 +      command undoes changes by <emphasis>adding</emphasis> history,
  17.327 +      not by modifying or erasing it.  It's the right tool to use if
  17.328 +      you're fixing bugs, but not if you're trying to undo some change
  17.329 +      that has catastrophic consequences.  To deal with those, see
  17.330 +      <xref linkend="sec:undo:aaaiiieee"/>.</para>
  17.331  
  17.332      <sect2>
  17.333        <title>Backing out a changeset</title>
  17.334  
  17.335 -      <para>The <command role="hg-cmd">hg backout</command> command
  17.336 +      <para id="x_f7">The <command role="hg-cmd">hg backout</command> command
  17.337  	lets you <quote>undo</quote> the effects of an entire
  17.338  	changeset in an automated fashion.  Because Mercurial's
  17.339  	history is immutable, this command <emphasis>does
  17.340 @@ -320,14 +320,14 @@
  17.341  	<emphasis>reverses</emphasis> the effect of the to-be-undone
  17.342  	changeset.</para>
  17.343  
  17.344 -      <para>The operation of the <command role="hg-cmd">hg
  17.345 +      <para id="x_f8">The operation of the <command role="hg-cmd">hg
  17.346  	  backout</command> command is a little intricate, so let's
  17.347  	illustrate it with some examples.  First, we'll create a
  17.348  	repository with some simple changes.</para>
  17.349  
  17.350        &interaction.backout.init;
  17.351  
  17.352 -      <para>The <command role="hg-cmd">hg backout</command> command
  17.353 +      <para id="x_f9">The <command role="hg-cmd">hg backout</command> command
  17.354  	takes a single changeset ID as its argument; this is the
  17.355  	changeset to back out.  Normally, <command role="hg-cmd">hg
  17.356  	  backout</command> will drop you into a text editor to write
  17.357 @@ -340,12 +340,12 @@
  17.358      <sect2>
  17.359        <title>Backing out the tip changeset</title>
  17.360  
  17.361 -      <para>We're going to start by backing out the last changeset we
  17.362 +      <para id="x_fa">We're going to start by backing out the last changeset we
  17.363  	committed.</para>
  17.364  
  17.365        &interaction.backout.simple;
  17.366  
  17.367 -      <para>You can see that the second line from
  17.368 +      <para id="x_fb">You can see that the second line from
  17.369  	<filename>myfile</filename> is no longer present.  Taking a
  17.370  	look at the output of <command role="hg-cmd">hg log</command>
  17.371  	gives us an idea of what the <command role="hg-cmd">hg
  17.372 @@ -353,51 +353,45 @@
  17.373  	&interaction.backout.simple.log; Notice that the new changeset
  17.374  	that <command role="hg-cmd">hg backout</command> has created
  17.375  	is a child of the changeset we backed out.  It's easier to see
  17.376 -	this in figure <xref
  17.377 -	  endterm="fig.undo.backout.caption" linkend="fig.undo.backout"/>,
  17.378 -	which presents a graphical
  17.379 -	view of the change history.  As you can see, the history is
  17.380 -	nice and linear.</para>
  17.381 -
  17.382 -      <informalfigure id="fig.undo.backout">
  17.383 -        <mediaobject>
  17.384 -          <imageobject><imagedata fileref="images/undo-simple.png"/>
  17.385 -          </imageobject>
  17.386 -          <textobject><phrase>XXX add text</phrase></textobject>
  17.387 -          <caption><para id="fig.undo.backout.caption">Backing out
  17.388 -            a change using the 
  17.389 -            <command role="hg-cmd">hg backout</command>
  17.390 -            command</para></caption>
  17.391 -      </mediaobject>
  17.392 -      </informalfigure>
  17.393 +	this in <xref linkend="fig:undo:backout"/>, which presents a
  17.394 +	graphical view of the change history.  As you can see, the
  17.395 +	history is nice and linear.</para>
  17.396 +
  17.397 +      <figure id="fig:undo:backout">
  17.398 +	<title>Backing out a change using the <command
  17.399 +	    role="hg-cmd">hg backout</command> command</title>
  17.400 +	<mediaobject>
  17.401 +	  <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject>
  17.402 +	  <textobject><phrase>XXX add text</phrase></textobject>
  17.403 +	</mediaobject>
  17.404 +      </figure>
  17.405  
  17.406      </sect2>
  17.407      <sect2>
  17.408        <title>Backing out a non-tip change</title>
  17.409  
  17.410 -      <para>If you want to back out a change other than the last one
  17.411 +      <para id="x_fd">If you want to back out a change other than the last one
  17.412  	you committed, pass the <option
  17.413  	  role="hg-opt-backout">--merge</option> option to the
  17.414  	<command role="hg-cmd">hg backout</command> command.</para>
  17.415  
  17.416        &interaction.backout.non-tip.clone;
  17.417  
  17.418 -      <para>This makes backing out any changeset a
  17.419 +      <para id="x_fe">This makes backing out any changeset a
  17.420  	<quote>one-shot</quote> operation that's usually simple and
  17.421  	fast.</para>
  17.422  
  17.423        &interaction.backout.non-tip.backout;
  17.424  
  17.425 -      <para>If you take a look at the contents of
  17.426 +      <para id="x_ff">If you take a look at the contents of
  17.427  	<filename>myfile</filename> after the backout finishes, you'll
  17.428  	see that the first and third changes are present, but not the
  17.429  	second.</para>
  17.430  
  17.431        &interaction.backout.non-tip.cat;
  17.432  
  17.433 -      <para>As the graphical history in figure <xref
  17.434 -	  endterm="fig.undo.backout-non-tip.caption"
  17.435 -	  linkend="fig.undo.backout-non-tip"/> illustrates, Mercurial
  17.436 +      <para id="x_100">As the graphical history in <xref
  17.437 +	  linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial
  17.438  	actually commits <emphasis>two</emphasis> changes in this kind
  17.439  	of situation (the box-shaped nodes are the ones that Mercurial
  17.440  	commits automatically).  Before Mercurial begins the backout
  17.441 @@ -407,21 +401,19 @@
  17.442  	the previous parent of the working directory, and commits the
  17.443  	result of the merge.</para>
  17.444  
  17.445 -      <para>% TODO: to me it looks like mercurial doesn't commit the
  17.446 +      <para id="x_101">% TODO: to me it looks like mercurial doesn't commit the
  17.447  	second merge automatically!</para>
  17.448  
  17.449 -      <informalfigure id="fig.undo.backout-non-tip">
  17.450 -        <mediaobject>
  17.451 -          <imageobject><imagedata fileref="images/undo-non-tip.png"/>
  17.452 -          </imageobject>
  17.453 -          <textobject><phrase>XXX add text</phrase></textobject>
  17.454 -          <caption><para id="fig.undo.backout-non-tip.caption">Automated
  17.455 -            backout of a non-tip change using the
  17.456 -            <command role="hg-cmd">hg backout</command> command</para></caption>
  17.457 -        </mediaobject>
  17.458 -      </informalfigure>
  17.459 -
  17.460 -      <para>The result is that you end up <quote>back where you
  17.461 +      <figure id="fig:undo:backout-non-tip">
  17.462 +	<title>Automated backout of a non-tip change using the
  17.463 +	  <command role="hg-cmd">hg backout</command> command</title>
  17.464 +	<mediaobject>
  17.465 +	  <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject>
  17.466 +	  <textobject><phrase>XXX add text</phrase></textobject>
  17.467 +	</mediaobject>
  17.468 +      </figure>
  17.469 +
  17.470 +      <para id="x_103">The result is that you end up <quote>back where you
  17.471  	  were</quote>, only with some extra history that undoes the
  17.472  	effect of the changeset you wanted to back out.</para>
  17.473  
  17.474 @@ -429,7 +421,7 @@
  17.475  	<title>Always use the <option
  17.476  	    role="hg-opt-backout">--merge</option> option</title>
  17.477  
  17.478 -	<para>In fact, since the <option
  17.479 +	<para id="x_104">In fact, since the <option
  17.480  	    role="hg-opt-backout">--merge</option> option will do the
  17.481  	  <quote>right thing</quote> whether or not the changeset
  17.482  	  you're backing out is the tip (i.e. it won't try to merge if
  17.483 @@ -442,7 +434,7 @@
  17.484      <sect2>
  17.485        <title>Gaining more control of the backout process</title>
  17.486  
  17.487 -      <para>While I've recommended that you always use the <option
  17.488 +      <para id="x_105">While I've recommended that you always use the <option
  17.489  	  role="hg-opt-backout">--merge</option> option when backing
  17.490  	out a change, the <command role="hg-cmd">hg backout</command>
  17.491  	command lets you decide how to merge a backout changeset.
  17.492 @@ -455,13 +447,13 @@
  17.493  
  17.494        &interaction.backout.manual.clone;
  17.495  
  17.496 -      <para>As with our
  17.497 +      <para id="x_106">As with our
  17.498  	earlier example, We'll commit a third changeset, then back out
  17.499  	its parent, and see what happens.</para>
  17.500  
  17.501        &interaction.backout.manual.backout;
  17.502  
  17.503 -      <para>Our new changeset is again a descendant of the changeset
  17.504 +      <para id="x_107">Our new changeset is again a descendant of the changeset
  17.505  	we backout out; it's thus a new head, <emphasis>not</emphasis>
  17.506  	a descendant of the changeset that was the tip.  The <command
  17.507  	  role="hg-cmd">hg backout</command> command was quite
  17.508 @@ -469,38 +461,35 @@
  17.509  
  17.510        &interaction.backout.manual.log;
  17.511  
  17.512 -      <para>Again, it's easier to see what has happened by looking at
  17.513 -	a graph of the revision history, in figure <xref
  17.514 -	  endterm="fig.undo.backout-manual.caption"
  17.515 -	  linkend="fig.undo.backout-manual"/>.  This makes it clear
  17.516 +      <para id="x_108">Again, it's easier to see what has happened by looking at
  17.517 +	a graph of the revision history, in <xref
  17.518 +	  linkend="fig:undo:backout-manual"/>.  This makes it clear
  17.519  	that when we use <command role="hg-cmd">hg backout</command>
  17.520  	to back out a change other than the tip, Mercurial adds a new
  17.521  	head to the repository (the change it committed is
  17.522  	box-shaped).</para>
  17.523  
  17.524 -      <informalfigure id="fig.undo.backout-manual">
  17.525 -        <mediaobject>
  17.526 -          <imageobject><imagedata fileref="images/undo-manual.png"/>
  17.527 -          </imageobject>
  17.528 -          <textobject><phrase>XXX add text</phrase></textobject>
  17.529 -          <caption><para id="fig.undo.backout-manual.caption">Backing out a
  17.530 -            change using the <command role="hg-cmd">hg backout</command>
  17.531 -            command</para></caption>
  17.532 -        </mediaobject>
  17.533 -      </informalfigure>
  17.534 -
  17.535 -      <para>After the <command role="hg-cmd">hg backout</command>
  17.536 +      <figure id="fig:undo:backout-manual">
  17.537 +	<title>Backing out a change using the <command
  17.538 +	    role="hg-cmd">hg backout</command> command</title>
  17.539 +	<mediaobject>
  17.540 +	  <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject>
  17.541 +	  <textobject><phrase>XXX add text</phrase></textobject>
  17.542 +	</mediaobject>
  17.543 +      </figure>
  17.544 +
  17.545 +      <para id="x_10a">After the <command role="hg-cmd">hg backout</command>
  17.546  	command has completed, it leaves the new
  17.547  	<quote>backout</quote> changeset as the parent of the working
  17.548  	directory.</para>
  17.549  
  17.550        &interaction.backout.manual.parents;
  17.551  
  17.552 -      <para>Now we have two isolated sets of changes.</para>
  17.553 +      <para id="x_10b">Now we have two isolated sets of changes.</para>
  17.554  
  17.555        &interaction.backout.manual.heads;
  17.556  
  17.557 -      <para>Let's think about what we expect to see as the contents of
  17.558 +      <para id="x_10c">Let's think about what we expect to see as the contents of
  17.559  	<filename>myfile</filename> now.  The first change should be
  17.560  	present, because we've never backed it out.  The second change
  17.561  	should be missing, as that's the change we backed out.  Since
  17.562 @@ -510,68 +499,65 @@
  17.563  
  17.564        &interaction.backout.manual.cat;
  17.565  
  17.566 -      <para>To get the third change back into the file, we just do a
  17.567 +      <para id="x_10d">To get the third change back into the file, we just do a
  17.568  	normal merge of our two heads.</para>
  17.569  
  17.570        &interaction.backout.manual.merge;
  17.571  
  17.572 -      <para>Afterwards, the graphical history of our repository looks
  17.573 -	like figure
  17.574 -	<xref endterm="fig.undo.backout-manual-merge.caption"
  17.575 -	  linkend="fig.undo.backout-manual-merge"/>.</para>
  17.576 -
  17.577 -      <informalfigure id="fig.undo.backout-manual-merge">
  17.578 -        <mediaobject>
  17.579 -          <imageobject><imagedata fileref="images/undo-manual-merge.png"/>
  17.580 -          </imageobject>
  17.581 -          <textobject><phrase>XXX add text</phrase></textobject>
  17.582 -          <caption><para id="fig.undo.backout-manual-merge.caption">Manually
  17.583 -            merging a backout change</para></caption>
  17.584 -        </mediaobject>
  17.585 -      </informalfigure>
  17.586 +      <para id="x_10e">Afterwards, the graphical history of our
  17.587 +	repository looks like
  17.588 +	<xref linkend="fig:undo:backout-manual-merge"/>.</para>
  17.589 +
  17.590 +      <figure id="fig:undo:backout-manual-merge">
  17.591 +	<title>Manually merging a backout change</title>
  17.592 +	<mediaobject>
  17.593 +	  <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject>
  17.594 +	  <textobject><phrase>XXX add text</phrase></textobject>
  17.595 +	</mediaobject>
  17.596 +      </figure>
  17.597  
  17.598      </sect2>
  17.599      <sect2>
  17.600        <title>Why <command role="hg-cmd">hg backout</command> works as
  17.601  	it does</title>
  17.602  
  17.603 -      <para>Here's a brief description of how the <command
  17.604 +      <para id="x_110">Here's a brief description of how the <command
  17.605  	  role="hg-cmd">hg backout</command> command works.</para>
  17.606        <orderedlist>
  17.607 -	<listitem><para>It ensures that the working directory is
  17.608 +	<listitem><para id="x_111">It ensures that the working directory is
  17.609  	    <quote>clean</quote>, i.e. that the output of <command
  17.610  	      role="hg-cmd">hg status</command> would be empty.</para>
  17.611  	</listitem>
  17.612 -	<listitem><para>It remembers the current parent of the working
  17.613 +	<listitem><para id="x_112">It remembers the current parent of the working
  17.614  	    directory.  Let's call this changeset
  17.615  	    <literal>orig</literal></para>
  17.616  	</listitem>
  17.617 -	<listitem><para>It does the equivalent of a <command
  17.618 +	<listitem><para id="x_113">It does the equivalent of a <command
  17.619  	      role="hg-cmd">hg update</command> to sync the working
  17.620  	    directory to the changeset you want to back out.  Let's
  17.621  	    call this changeset <literal>backout</literal></para>
  17.622  	</listitem>
  17.623 -	<listitem><para>It finds the parent of that changeset.  Let's
  17.624 +	<listitem><para id="x_114">It finds the parent of that changeset.  Let's
  17.625  	    call that changeset <literal>parent</literal>.</para>
  17.626  	</listitem>
  17.627 -	<listitem><para>For each file that the
  17.628 +	<listitem><para id="x_115">For each file that the
  17.629  	    <literal>backout</literal> changeset affected, it does the
  17.630  	    equivalent of a <command role="hg-cmd">hg revert -r
  17.631  	      parent</command> on that file, to restore it to the
  17.632  	    contents it had before that changeset was
  17.633  	    committed.</para>
  17.634  	</listitem>
  17.635 -	<listitem><para>It commits the result as a new changeset.
  17.636 +	<listitem><para id="x_116">It commits the result as a new changeset.
  17.637  	    This changeset has <literal>backout</literal> as its
  17.638  	    parent.</para>
  17.639  	</listitem>
  17.640 -	<listitem><para>If you specify <option
  17.641 +	<listitem><para id="x_117">If you specify <option
  17.642  	      role="hg-opt-backout">--merge</option> on the command
  17.643  	    line, it merges with <literal>orig</literal>, and commits
  17.644  	    the result of the merge.</para>
  17.645  	</listitem></orderedlist>
  17.646  
  17.647 -      <para>An alternative way to implement the <command
  17.648 +      <para id="x_118">An alternative way to implement the <command
  17.649  	  role="hg-cmd">hg backout</command> command would be to
  17.650  	<command role="hg-cmd">hg export</command> the
  17.651  	to-be-backed-out changeset as a diff, then use the <option
  17.652 @@ -581,21 +567,21 @@
  17.653  	sounds much simpler, but it would not work nearly as
  17.654  	well.</para>
  17.655  
  17.656 -      <para>The reason that <command role="hg-cmd">hg
  17.657 +      <para id="x_119">The reason that <command role="hg-cmd">hg
  17.658  	  backout</command> does an update, a commit, a merge, and
  17.659  	another commit is to give the merge machinery the best chance
  17.660  	to do a good job when dealing with all the changes
  17.661  	<emphasis>between</emphasis> the change you're backing out and
  17.662  	the current tip.</para>
  17.663  
  17.664 -      <para>If you're backing out a changeset that's 100 revisions
  17.665 +      <para id="x_11a">If you're backing out a changeset that's 100 revisions
  17.666  	back in your project's history, the chances that the
  17.667  	<command>patch</command> command will be able to apply a
  17.668  	reverse diff cleanly are not good, because intervening changes
  17.669  	are likely to have <quote>broken the context</quote> that
  17.670  	<command>patch</command> uses to determine whether it can
  17.671  	apply a patch (if this sounds like gibberish, see <xref
  17.672 -	  linkend="sec.mq.patch"/> for a
  17.673 +	  linkend="sec:mq:patch"/> for a
  17.674  	discussion of the <command>patch</command> command).  Also,
  17.675  	Mercurial's merge machinery will handle files and directories
  17.676  	being renamed, permission changes, and modifications to binary
  17.677 @@ -604,16 +590,16 @@
  17.678  
  17.679      </sect2>
  17.680    </sect1>
  17.681 -  <sect1 id="sec.undo.aaaiiieee">
  17.682 +  <sect1 id="sec:undo:aaaiiieee">
  17.683      <title>Changes that should never have been</title>
  17.684  
  17.685 -    <para>Most of the time, the <command role="hg-cmd">hg
  17.686 +    <para id="x_11b">Most of the time, the <command role="hg-cmd">hg
  17.687  	backout</command> command is exactly what you need if you want
  17.688        to undo the effects of a change.  It leaves a permanent record
  17.689        of exactly what you did, both when committing the original
  17.690        changeset and when you cleaned up after it.</para>
  17.691  
  17.692 -    <para>On rare occasions, though, you may find that you've
  17.693 +    <para id="x_11c">On rare occasions, though, you may find that you've
  17.694        committed a change that really should not be present in the
  17.695        repository at all.  For example, it would be very unusual, and
  17.696        usually considered a mistake, to commit a software project's
  17.697 @@ -622,21 +608,21 @@
  17.698        so they increase the size of the repository and the amount of
  17.699        time it takes to clone or pull changes.</para>
  17.700  
  17.701 -    <para>Before I discuss the options that you have if you commit a
  17.702 +    <para id="x_11d">Before I discuss the options that you have if you commit a
  17.703        <quote>brown paper bag</quote> change (the kind that's so bad
  17.704        that you want to pull a brown paper bag over your head), let me
  17.705        first discuss some approaches that probably won't work.</para>
  17.706  
  17.707 -    <para>Since Mercurial treats history as accumulative&emdash;every
  17.708 -      change builds on top of all changes that preceded it&emdash;you
  17.709 -      generally can't just make disastrous changes disappear.  The one
  17.710 -      exception is when you've just committed a change, and it hasn't
  17.711 -      been pushed or pulled into another repository.  That's when you
  17.712 -      can safely use the <command role="hg-cmd">hg rollback</command>
  17.713 -      command, as I detailed in section <xref
  17.714 -	linkend="sec.undo.rollback"/>.</para>
  17.715 -
  17.716 -    <para>After you've pushed a bad change to another repository, you
  17.717 +    <para id="x_11e">Since Mercurial treats history as
  17.718 +      accumulative&emdash;every change builds on top of all changes
  17.719 +      that preceded it&emdash;you generally can't just make disastrous
  17.720 +      changes disappear.  The one exception is when you've just
  17.721 +      committed a change, and it hasn't been pushed or pulled into
  17.722 +      another repository.  That's when you can safely use the <command
  17.723 +	role="hg-cmd">hg rollback</command> command, as I detailed in
  17.724 +      <xref linkend="sec:undo:rollback"/>.</para>
  17.725 +
  17.726 +    <para id="x_11f">After you've pushed a bad change to another repository, you
  17.727        <emphasis>could</emphasis> still use <command role="hg-cmd">hg
  17.728  	rollback</command> to make your local copy of the change
  17.729        disappear, but it won't have the consequences you want.  The
  17.730 @@ -644,7 +630,7 @@
  17.731        will reappear in your local repository the next time you
  17.732        pull.</para>
  17.733  
  17.734 -    <para>If a situation like this arises, and you know which
  17.735 +    <para id="x_120">If a situation like this arises, and you know which
  17.736        repositories your bad change has propagated into, you can
  17.737        <emphasis>try</emphasis> to get rid of the changeefrom
  17.738        <emphasis>every</emphasis> one of those repositories.  This is,
  17.739 @@ -652,13 +638,13 @@
  17.740        single repository while you're expunging, the change is still
  17.741        <quote>in the wild</quote>, and could propagate further.</para>
  17.742  
  17.743 -    <para>If you've committed one or more changes
  17.744 +    <para id="x_121">If you've committed one or more changes
  17.745        <emphasis>after</emphasis> the change that you'd like to see
  17.746        disappear, your options are further reduced. Mercurial doesn't
  17.747        provide a way to <quote>punch a hole</quote> in history, leaving
  17.748        changesets intact.</para>
  17.749  
  17.750 -    <para>XXX This needs filling out.  The
  17.751 +    <para id="x_122">XXX This needs filling out.  The
  17.752        <literal>hg-replay</literal> script in the
  17.753        <literal>examples</literal> directory works, but doesn't handle
  17.754        merge changesets.  Kind of an important omission.</para>
  17.755 @@ -667,15 +653,15 @@
  17.756        <title>Protect yourself from <quote>escaped</quote>
  17.757  	changes</title>
  17.758  
  17.759 -      <para>If you've committed some changes to your local repository
  17.760 +      <para id="x_123">If you've committed some changes to your local repository
  17.761  	and they've been pushed or pulled somewhere else, this isn't
  17.762  	necessarily a disaster.  You can protect yourself ahead of
  17.763  	time against some classes of bad changeset.  This is
  17.764  	particularly easy if your team usually pulls changes from a
  17.765  	central repository.</para>
  17.766  
  17.767 -      <para>By configuring some hooks on that repository to validate
  17.768 -	incoming changesets (see chapter <xref linkend="chap.hook"/>),
  17.769 +      <para id="x_124">By configuring some hooks on that repository to validate
  17.770 +	incoming changesets (see chapter <xref linkend="chap:hook"/>),
  17.771  	you can
  17.772  	automatically prevent some kinds of bad changeset from being
  17.773  	pushed to the central repository at all.  With such a
  17.774 @@ -684,23 +670,23 @@
  17.775  	propagate into the central repository.  Better yet, this
  17.776  	happens without any need for explicit intervention.</para>
  17.777  
  17.778 -      <para>For instance, an incoming change hook that verifies that a
  17.779 +      <para id="x_125">For instance, an incoming change hook that verifies that a
  17.780  	changeset will actually compile can prevent people from
  17.781  	inadvertantly <quote>breaking the build</quote>.</para>
  17.782  
  17.783      </sect2>
  17.784    </sect1>
  17.785 -  <sect1 id="sec.undo.bisect">
  17.786 +  <sect1 id="sec:undo:bisect">
  17.787      <title>Finding the source of a bug</title>
  17.788  
  17.789 -    <para>While it's all very well to be able to back out a changeset
  17.790 +    <para id="x_126">While it's all very well to be able to back out a changeset
  17.791        that introduced a bug, this requires that you know which
  17.792        changeset to back out.  Mercurial provides an invaluable
  17.793        command, called <command role="hg-cmd">hg bisect</command>, that
  17.794        helps you to automate this process and accomplish it very
  17.795        efficiently.</para>
  17.796  
  17.797 -    <para>The idea behind the <command role="hg-cmd">hg
  17.798 +    <para id="x_127">The idea behind the <command role="hg-cmd">hg
  17.799  	bisect</command> command is that a changeset has introduced
  17.800        some change of behaviour that you can identify with a simple
  17.801        binary test.  You don't know which piece of code introduced the
  17.802 @@ -709,41 +695,41 @@
  17.803        test to direct its search for the changeset that introduced the
  17.804        code that caused the bug.</para>
  17.805  
  17.806 -    <para>Here are a few scenarios to help you understand how you
  17.807 +    <para id="x_128">Here are a few scenarios to help you understand how you
  17.808        might apply this command.</para>
  17.809      <itemizedlist>
  17.810 -      <listitem><para>The most recent version of your software has a
  17.811 +      <listitem><para id="x_129">The most recent version of your software has a
  17.812  	  bug that you remember wasn't present a few weeks ago, but
  17.813  	  you don't know when it was introduced.  Here, your binary
  17.814  	  test checks for the presence of that bug.</para>
  17.815        </listitem>
  17.816 -      <listitem><para>You fixed a bug in a rush, and now it's time to
  17.817 +      <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to
  17.818  	  close the entry in your team's bug database.  The bug
  17.819  	  database requires a changeset ID when you close an entry,
  17.820  	  but you don't remember which changeset you fixed the bug in.
  17.821  	  Once again, your binary test checks for the presence of the
  17.822  	  bug.</para>
  17.823        </listitem>
  17.824 -      <listitem><para>Your software works correctly, but runs 15%
  17.825 +      <listitem><para id="x_12b">Your software works correctly, but runs 15%
  17.826  	  slower than the last time you measured it.  You want to know
  17.827  	  which changeset introduced the performance regression.  In
  17.828  	  this case, your binary test measures the performance of your
  17.829  	  software, to see whether it's <quote>fast</quote> or
  17.830  	  <quote>slow</quote>.</para>
  17.831        </listitem>
  17.832 -      <listitem><para>The sizes of the components of your project that
  17.833 +      <listitem><para id="x_12c">The sizes of the components of your project that
  17.834  	  you ship exploded recently, and you suspect that something
  17.835  	  changed in the way you build your project.</para>
  17.836        </listitem></itemizedlist>
  17.837  
  17.838 -    <para>From these examples, it should be clear that the <command
  17.839 +    <para id="x_12d">From these examples, it should be clear that the <command
  17.840  	role="hg-cmd">hg bisect</command> command is not useful only
  17.841        for finding the sources of bugs.  You can use it to find any
  17.842        <quote>emergent property</quote> of a repository (anything that
  17.843        you can't find from a simple text search of the files in the
  17.844        tree) for which you can write a binary test.</para>
  17.845  
  17.846 -    <para>We'll introduce a little bit of terminology here, just to
  17.847 +    <para id="x_12e">We'll introduce a little bit of terminology here, just to
  17.848        make it clear which parts of the search process are your
  17.849        responsibility, and which are Mercurial's.  A
  17.850        <emphasis>test</emphasis> is something that
  17.851 @@ -756,7 +742,7 @@
  17.852  	the <command role="hg-cmd">hg bisect</command>
  17.853  	command</quote>.</para>
  17.854  
  17.855 -    <para>One simple way to automate the searching process would be
  17.856 +    <para id="x_12f">One simple way to automate the searching process would be
  17.857        simply to probe every changeset.  However, this scales poorly.
  17.858        If it took ten minutes to test a single changeset, and you had
  17.859        10,000 changesets in your repository, the exhaustive approach
  17.860 @@ -766,7 +752,7 @@
  17.861        your search to those, you'd still be looking at over 40 hours to
  17.862        find the changeset that introduced your bug.</para>
  17.863  
  17.864 -    <para>What the <command role="hg-cmd">hg bisect</command> command
  17.865 +    <para id="x_130">What the <command role="hg-cmd">hg bisect</command> command
  17.866        does is use its knowledge of the <quote>shape</quote> of your
  17.867        project's revision history to perform a search in time
  17.868        proportional to the <emphasis>logarithm</emphasis> of the number
  17.869 @@ -777,7 +763,7 @@
  17.870        Limit your search to the last hundred changesets, and it will
  17.871        take only about an hour (roughly seven tests).</para>
  17.872  
  17.873 -    <para>The <command role="hg-cmd">hg bisect</command> command is
  17.874 +    <para id="x_131">The <command role="hg-cmd">hg bisect</command> command is
  17.875        aware of the <quote>branchy</quote> nature of a Mercurial
  17.876        project's revision history, so it has no problems dealing with
  17.877        branches, merges, or multiple heads in a repository.  It can
  17.878 @@ -788,24 +774,24 @@
  17.879        <title>Using the <command role="hg-cmd">hg bisect</command>
  17.880  	command</title>
  17.881  
  17.882 -      <para>Here's an example of <command role="hg-cmd">hg
  17.883 +      <para id="x_132">Here's an example of <command role="hg-cmd">hg
  17.884  	  bisect</command> in action.</para>
  17.885  
  17.886        <note>
  17.887 -	<para>  In versions 0.9.5 and earlier of Mercurial, <command
  17.888 +	<para id="x_133">  In versions 0.9.5 and earlier of Mercurial, <command
  17.889  	    role="hg-cmd">hg bisect</command> was not a core command:
  17.890  	  it was distributed with Mercurial as an extension. This
  17.891  	  section describes the built-in command, not the old
  17.892  	  extension.</para>
  17.893        </note>
  17.894  
  17.895 -      <para>Now let's create a repository, so that we can try out the
  17.896 +      <para id="x_134">Now let's create a repository, so that we can try out the
  17.897  	<command role="hg-cmd">hg bisect</command> command in
  17.898  	isolation.</para>
  17.899  
  17.900        &interaction.bisect.init;
  17.901  
  17.902 -      <para>We'll simulate a project that has a bug in it in a
  17.903 +      <para id="x_135">We'll simulate a project that has a bug in it in a
  17.904  	simple-minded way: create trivial changes in a loop, and
  17.905  	nominate one specific change that will have the
  17.906  	<quote>bug</quote>.  This loop creates 35 changesets, each
  17.907 @@ -815,44 +801,44 @@
  17.908  
  17.909        &interaction.bisect.commits;
  17.910  
  17.911 -      <para>The next thing that we'd like to do is figure out how to
  17.912 +      <para id="x_136">The next thing that we'd like to do is figure out how to
  17.913  	use the <command role="hg-cmd">hg bisect</command> command.
  17.914  	We can use Mercurial's normal built-in help mechanism for
  17.915  	this.</para>
  17.916  
  17.917        &interaction.bisect.help;
  17.918  
  17.919 -      <para>The <command role="hg-cmd">hg bisect</command> command
  17.920 +      <para id="x_137">The <command role="hg-cmd">hg bisect</command> command
  17.921  	works in steps.  Each step proceeds as follows.</para>
  17.922        <orderedlist>
  17.923 -	<listitem><para>You run your binary test.</para>
  17.924 +	<listitem><para id="x_138">You run your binary test.</para>
  17.925  	  <itemizedlist>
  17.926 -	    <listitem><para>If the test succeeded, you tell <command
  17.927 +	    <listitem><para id="x_139">If the test succeeded, you tell <command
  17.928  		  role="hg-cmd">hg bisect</command> by running the
  17.929  		<command role="hg-cmd">hg bisect good</command>
  17.930  		command.</para>
  17.931  	    </listitem>
  17.932 -	    <listitem><para>If it failed, run the <command
  17.933 +	    <listitem><para id="x_13a">If it failed, run the <command
  17.934  		  role="hg-cmd">hg bisect bad</command>
  17.935  		command.</para></listitem></itemizedlist>
  17.936  	</listitem>
  17.937 -	<listitem><para>The command uses your information to decide
  17.938 +	<listitem><para id="x_13b">The command uses your information to decide
  17.939  	    which changeset to test next.</para>
  17.940  	</listitem>
  17.941 -	<listitem><para>It updates the working directory to that
  17.942 +	<listitem><para id="x_13c">It updates the working directory to that
  17.943  	    changeset, and the process begins again.</para>
  17.944  	</listitem></orderedlist>
  17.945 -      <para>The process ends when <command role="hg-cmd">hg
  17.946 +      <para id="x_13d">The process ends when <command role="hg-cmd">hg
  17.947  	  bisect</command> identifies a unique changeset that marks
  17.948  	the point where your test transitioned from
  17.949  	<quote>succeeding</quote> to <quote>failing</quote>.</para>
  17.950  
  17.951 -      <para>To start the search, we must run the <command
  17.952 +      <para id="x_13e">To start the search, we must run the <command
  17.953  	  role="hg-cmd">hg bisect --reset</command> command.</para>
  17.954  
  17.955        &interaction.bisect.search.init;
  17.956  
  17.957 -      <para>In our case, the binary test we use is simple: we check to
  17.958 +      <para id="x_13f">In our case, the binary test we use is simple: we check to
  17.959  	see if any file in the repository contains the string <quote>i
  17.960  	  have a gub</quote>.  If it does, this changeset contains the
  17.961  	change that <quote>caused the bug</quote>.  By convention, a
  17.962 @@ -860,14 +846,14 @@
  17.963  	<quote>bad</quote>, while one that doesn't is
  17.964  	<quote>good</quote>.</para>
  17.965  
  17.966 -      <para>Most of the time, the revision to which the working
  17.967 +      <para id="x_140">Most of the time, the revision to which the working
  17.968  	directory is synced (usually the tip) already exhibits the
  17.969  	problem introduced by the buggy change, so we'll mark it as
  17.970  	<quote>bad</quote>.</para>
  17.971  
  17.972        &interaction.bisect.search.bad-init;
  17.973  
  17.974 -      <para>Our next task is to nominate a changeset that we know
  17.975 +      <para id="x_141">Our next task is to nominate a changeset that we know
  17.976  	<emphasis>doesn't</emphasis> have the bug; the <command
  17.977  	  role="hg-cmd">hg bisect</command> command will
  17.978  	<quote>bracket</quote> its search between the first pair of
  17.979 @@ -877,38 +863,38 @@
  17.980  
  17.981        &interaction.bisect.search.good-init;
  17.982  
  17.983 -      <para>Notice that this command printed some output.</para>
  17.984 +      <para id="x_142">Notice that this command printed some output.</para>
  17.985        <itemizedlist>
  17.986 -	<listitem><para>It told us how many changesets it must
  17.987 +	<listitem><para id="x_143">It told us how many changesets it must
  17.988  	    consider before it can identify the one that introduced
  17.989  	    the bug, and how many tests that will require.</para>
  17.990  	</listitem>
  17.991 -	<listitem><para>It updated the working directory to the next
  17.992 +	<listitem><para id="x_144">It updated the working directory to the next
  17.993  	    changeset to test, and told us which changeset it's
  17.994  	    testing.</para>
  17.995  	</listitem></itemizedlist>
  17.996  
  17.997 -      <para>We now run our test in the working directory.  We use the
  17.998 +      <para id="x_145">We now run our test in the working directory.  We use the
  17.999  	<command>grep</command> command to see if our
 17.1000  	<quote>bad</quote> file is present in the working directory.
 17.1001  	If it is, this revision is bad; if not, this revision is good.
 17.1002  	&interaction.bisect.search.step1;</para>
 17.1003  
 17.1004 -      <para>This test looks like a perfect candidate for automation,
 17.1005 +      <para id="x_146">This test looks like a perfect candidate for automation,
 17.1006  	so let's turn it into a shell function.</para>
 17.1007        &interaction.bisect.search.mytest;
 17.1008  
 17.1009 -      <para>We can now run an entire test step with a single command,
 17.1010 +      <para id="x_147">We can now run an entire test step with a single command,
 17.1011  	<literal>mytest</literal>.</para>
 17.1012  
 17.1013        &interaction.bisect.search.step2;
 17.1014  
 17.1015 -      <para>A few more invocations of our canned test step command,
 17.1016 +      <para id="x_148">A few more invocations of our canned test step command,
 17.1017  	and we're done.</para>
 17.1018  
 17.1019        &interaction.bisect.search.rest;
 17.1020  
 17.1021 -      <para>Even though we had 40 changesets to search through, the
 17.1022 +      <para id="x_149">Even though we had 40 changesets to search through, the
 17.1023  	<command role="hg-cmd">hg bisect</command> command let us find
 17.1024  	the changeset that introduced our <quote>bug</quote> with only
 17.1025  	five tests.  Because the number of tests that the <command
 17.1026 @@ -921,7 +907,7 @@
 17.1027      <sect2>
 17.1028        <title>Cleaning up after your search</title>
 17.1029  
 17.1030 -      <para>When you're finished using the <command role="hg-cmd">hg
 17.1031 +      <para id="x_14a">When you're finished using the <command role="hg-cmd">hg
 17.1032  	  bisect</command> command in a repository, you can use the
 17.1033  	<command role="hg-cmd">hg bisect reset</command> command to
 17.1034  	drop the information it was using to drive your search.  The
 17.1035 @@ -941,7 +927,7 @@
 17.1036      <sect2>
 17.1037        <title>Give consistent input</title>
 17.1038  
 17.1039 -      <para>The <command role="hg-cmd">hg bisect</command> command
 17.1040 +      <para id="x_14b">The <command role="hg-cmd">hg bisect</command> command
 17.1041  	requires that you correctly report the result of every test
 17.1042  	you perform.  If you tell it that a test failed when it really
 17.1043  	succeeded, it <emphasis>might</emphasis> be able to detect the
 17.1044 @@ -955,7 +941,7 @@
 17.1045      <sect2>
 17.1046        <title>Automate as much as possible</title>
 17.1047  
 17.1048 -      <para>When I started using the <command role="hg-cmd">hg
 17.1049 +      <para id="x_14c">When I started using the <command role="hg-cmd">hg
 17.1050  	  bisect</command> command, I tried a few times to run my
 17.1051  	tests by hand, on the command line.  This is an approach that
 17.1052  	I, at least, am not suited to.  After a few tries, I found
 17.1053 @@ -963,7 +949,7 @@
 17.1054  	my searches several times before finally getting correct
 17.1055  	results.</para>
 17.1056  
 17.1057 -      <para>My initial problems with driving the <command
 17.1058 +      <para id="x_14d">My initial problems with driving the <command
 17.1059  	  role="hg-cmd">hg bisect</command> command by hand occurred
 17.1060  	even with simple searches on small repositories; if the
 17.1061  	problem you're looking for is more subtle, or the number of
 17.1062 @@ -972,14 +958,14 @@
 17.1063  	the search is much higher.  Once I started automating my
 17.1064  	tests, I had much better results.</para>
 17.1065  
 17.1066 -      <para>The key to automated testing is twofold:</para>
 17.1067 +      <para id="x_14e">The key to automated testing is twofold:</para>
 17.1068        <itemizedlist>
 17.1069 -	<listitem><para>always test for the same symptom, and</para>
 17.1070 -	</listitem>
 17.1071 -	<listitem><para>always feed consistent input to the <command
 17.1072 +	<listitem><para id="x_14f">always test for the same symptom, and</para>
 17.1073 +	</listitem>
 17.1074 +	<listitem><para id="x_150">always feed consistent input to the <command
 17.1075  	      role="hg-cmd">hg bisect</command> command.</para>
 17.1076  	</listitem></itemizedlist>
 17.1077 -      <para>In my tutorial example above, the <command>grep</command>
 17.1078 +      <para id="x_151">In my tutorial example above, the <command>grep</command>
 17.1079  	command tests for the symptom, and the <literal>if</literal>
 17.1080  	statement takes the result of this check and ensures that we
 17.1081  	always feed the same input to the <command role="hg-cmd">hg
 17.1082 @@ -991,21 +977,21 @@
 17.1083      <sect2>
 17.1084        <title>Check your results</title>
 17.1085  
 17.1086 -      <para>Because the output of a <command role="hg-cmd">hg
 17.1087 +      <para id="x_152">Because the output of a <command role="hg-cmd">hg
 17.1088  	  bisect</command> search is only as good as the input you
 17.1089  	give it, don't take the changeset it reports as the absolute
 17.1090  	truth.  A simple way to cross-check its report is to manually
 17.1091  	run your test at each of the following changesets:</para>
 17.1092        <itemizedlist>
 17.1093 -	<listitem><para>The changeset that it reports as the first bad
 17.1094 +	<listitem><para id="x_153">The changeset that it reports as the first bad
 17.1095  	    revision.  Your test should still report this as
 17.1096  	    bad.</para>
 17.1097  	</listitem>
 17.1098 -	<listitem><para>The parent of that changeset (either parent,
 17.1099 +	<listitem><para id="x_154">The parent of that changeset (either parent,
 17.1100  	    if it's a merge). Your test should report this changeset
 17.1101  	    as good.</para>
 17.1102  	</listitem>
 17.1103 -	<listitem><para>A child of that changeset.  Your test should
 17.1104 +	<listitem><para id="x_155">A child of that changeset.  Your test should
 17.1105  	    report this changeset as bad.</para>
 17.1106  	</listitem></itemizedlist>
 17.1107  
 17.1108 @@ -1013,7 +999,7 @@
 17.1109      <sect2>
 17.1110        <title>Beware interference between bugs</title>
 17.1111  
 17.1112 -      <para>It's possible that your search for one bug could be
 17.1113 +      <para id="x_156">It's possible that your search for one bug could be
 17.1114  	disrupted by the presence of another.  For example, let's say
 17.1115  	your software crashes at revision 100, and worked correctly at
 17.1116  	revision 50.  Unknown to you, someone else introduced a
 17.1117 @@ -1021,7 +1007,7 @@
 17.1118  	revision 80.  This could distort your results in one of
 17.1119  	several ways.</para>
 17.1120  
 17.1121 -      <para>It is possible that this other bug completely
 17.1122 +      <para id="x_157">It is possible that this other bug completely
 17.1123  	<quote>masks</quote> yours, which is to say that it occurs
 17.1124  	before your bug has a chance to manifest itself.  If you can't
 17.1125  	avoid that other bug (for example, it prevents your project
 17.1126 @@ -1031,14 +1017,14 @@
 17.1127  	you can mark a changeset as untested by running <command
 17.1128  	  role="hg-cmd">hg bisect --skip</command>.</para>
 17.1129  
 17.1130 -      <para>A different problem could arise if your test for a bug's
 17.1131 +      <para id="x_158">A different problem could arise if your test for a bug's
 17.1132  	presence is not specific enough.  If you check for <quote>my
 17.1133  	  program crashes</quote>, then both your crashing bug and an
 17.1134  	unrelated crashing bug that masks it will look like the same
 17.1135  	thing, and mislead <command role="hg-cmd">hg
 17.1136  	  bisect</command>.</para>
 17.1137  
 17.1138 -      <para>Another useful situation in which to use <command
 17.1139 +      <para id="x_159">Another useful situation in which to use <command
 17.1140  	  role="hg-cmd">hg bisect --skip</command> is if you can't
 17.1141  	test a revision because your project was in a broken and hence
 17.1142  	untestable state at that revision, perhaps because someone
 17.1143 @@ -1049,7 +1035,7 @@
 17.1144      <sect2>
 17.1145        <title>Bracket your search lazily</title>
 17.1146  
 17.1147 -      <para>Choosing the first <quote>good</quote> and
 17.1148 +      <para id="x_15a">Choosing the first <quote>good</quote> and
 17.1149  	<quote>bad</quote> changesets that will mark the end points of
 17.1150  	your search is often easy, but it bears a little discussion
 17.1151  	nevertheless.  From the perspective of <command
 17.1152 @@ -1057,7 +1043,7 @@
 17.1153  	changeset is conventionally <quote>bad</quote>, and the older
 17.1154  	changeset is <quote>good</quote>.</para>
 17.1155  
 17.1156 -      <para>If you're having trouble remembering when a suitable
 17.1157 +      <para id="x_15b">If you're having trouble remembering when a suitable
 17.1158  	<quote>good</quote> change was, so that you can tell <command
 17.1159  	  role="hg-cmd">hg bisect</command>, you could do worse than
 17.1160  	testing changesets at random.  Just remember to eliminate
 17.1161 @@ -1066,7 +1052,7 @@
 17.1162  	where another problem masks the bug (as I discussed
 17.1163  	above).</para>
 17.1164  
 17.1165 -      <para>Even if you end up <quote>early</quote> by thousands of
 17.1166 +      <para id="x_15c">Even if you end up <quote>early</quote> by thousands of
 17.1167  	changesets or months of history, you will only add a handful
 17.1168  	of tests to the total number that <command role="hg-cmd">hg
 17.1169  	  bisect</command> must perform, thanks to its logarithmic

    18.1 --- a/en/ch09-hook.xml	Fri Mar 20 17:17:55 2009 +0800
    18.2 +++ b/en/ch09-hook.xml	Mon Mar 30 16:23:33 2009 +0800
    18.3 @@ -1,15 +1,15 @@
    18.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    18.5  
    18.6 -<chapter id="chap.hook">
    18.7 +<chapter id="chap:hook">
    18.8    <?dbhtml filename="handling-repository-events-with-hooks.html"?>
    18.9    <title>Handling repository events with hooks</title>
   18.10  
   18.11 -  <para>Mercurial offers a powerful mechanism to let you perform
   18.12 +  <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform
   18.13      automated actions in response to events that occur in a
   18.14      repository.  In some cases, you can even control Mercurial's
   18.15      response to those events.</para>
   18.16  
   18.17 -  <para>The name Mercurial uses for one of these actions is a
   18.18 +  <para id="x_1e7">The name Mercurial uses for one of these actions is a
   18.19      <emphasis>hook</emphasis>. Hooks are called
   18.20      <quote>triggers</quote> in some revision control systems, but the
   18.21      two names refer to the same idea.</para>
   18.22 @@ -17,49 +17,49 @@
   18.23    <sect1>
   18.24      <title>An overview of hooks in Mercurial</title>
   18.25  
   18.26 -    <para>Here is a brief list of the hooks that Mercurial supports.
   18.27 -      We will revisit each of these hooks in more detail later, in
   18.28 -      section <xref linkend="sec.hook.ref"/>.</para>
   18.29 +    <para id="x_1e8">Here is a brief list of the hooks that Mercurial
   18.30 +      supports. We will revisit each of these hooks in more detail
   18.31 +      later, in <xref linkend="sec:hook:ref"/>.</para>
   18.32  
   18.33      <itemizedlist>
   18.34 -      <listitem><para><literal role="hook">changegroup</literal>: This
   18.35 +      <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This
   18.36  	  is run after a group of changesets has been brought into the
   18.37  	  repository from elsewhere.</para>
   18.38        </listitem>
   18.39 -      <listitem><para><literal role="hook">commit</literal>: This is
   18.40 +      <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is
   18.41  	  run after a new changeset has been created in the local
   18.42  	  repository.</para>
   18.43        </listitem>
   18.44 -      <listitem><para><literal role="hook">incoming</literal>: This is
   18.45 +      <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is
   18.46  	  run once for each new changeset that is brought into the
   18.47  	  repository from elsewhere.  Notice the difference from
   18.48  	  <literal role="hook">changegroup</literal>, which is run
   18.49  	  once per <emphasis>group</emphasis> of changesets brought
   18.50  	  in.</para>
   18.51        </listitem>
   18.52 -      <listitem><para><literal role="hook">outgoing</literal>: This is
   18.53 +      <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is
   18.54  	  run after a group of changesets has been transmitted from
   18.55  	  this repository.</para>
   18.56        </listitem>
   18.57 -      <listitem><para><literal role="hook">prechangegroup</literal>:
   18.58 +      <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>:
   18.59  	  This is run before starting to bring a group of changesets
   18.60  	  into the repository.
   18.61  	</para>
   18.62        </listitem>
   18.63 -      <listitem><para><literal role="hook">precommit</literal>:
   18.64 +      <listitem><para id="x_1ee"><literal role="hook">precommit</literal>:
   18.65  	  Controlling. This is run before starting a commit.
   18.66  	</para>
   18.67        </listitem>
   18.68 -      <listitem><para><literal role="hook">preoutgoing</literal>:
   18.69 +      <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>:
   18.70  	  Controlling. This is run before starting to transmit a group
   18.71  	  of changesets from this repository.
   18.72  	</para>
   18.73        </listitem>
   18.74 -      <listitem><para><literal role="hook">pretag</literal>:
   18.75 +      <listitem><para id="x_1f0"><literal role="hook">pretag</literal>:
   18.76  	  Controlling. This is run before creating a tag.
   18.77  	</para>
   18.78        </listitem>
   18.79 -      <listitem><para><literal
   18.80 +      <listitem><para id="x_1f1"><literal
   18.81  	    role="hook">pretxnchangegroup</literal>: Controlling. This
   18.82  	  is run after a group of changesets has been brought into the
   18.83  	  local repository from another, but before the transaction
   18.84 @@ -67,27 +67,27 @@
   18.85  	  repository.
   18.86  	</para>
   18.87        </listitem>
   18.88 -      <listitem><para><literal role="hook">pretxncommit</literal>:
   18.89 +      <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>:
   18.90  	  Controlling. This is run after a new changeset has been
   18.91  	  created in the local repository, but before the transaction
   18.92  	  completes that will make it permanent.
   18.93  	</para>
   18.94        </listitem>
   18.95 -      <listitem><para><literal role="hook">preupdate</literal>:
   18.96 +      <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>:
   18.97  	  Controlling. This is run before starting an update or merge
   18.98  	  of the working directory.
   18.99  	</para>
  18.100        </listitem>
  18.101 -      <listitem><para><literal role="hook">tag</literal>: This is run
  18.102 +      <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run
  18.103  	  after a tag is created.
  18.104  	</para>
  18.105        </listitem>
  18.106 -      <listitem><para><literal role="hook">update</literal>: This is
  18.107 +      <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is
  18.108  	  run after an update or merge of the working directory has
  18.109  	  finished.
  18.110  	</para>
  18.111        </listitem></itemizedlist>
  18.112 -    <para>Each of the hooks whose description begins with the word
  18.113 +    <para id="x_1f6">Each of the hooks whose description begins with the word
  18.114        <quote>Controlling</quote> has the ability to determine whether
  18.115        an activity can proceed.  If the hook succeeds, the activity may
  18.116        proceed; if it fails, the activity is either not permitted or
  18.117 @@ -101,7 +101,7 @@
  18.118      <sect2>
  18.119        <title>Hooks are run with your privileges</title>
  18.120  
  18.121 -      <para>When you run a Mercurial command in a repository, and the
  18.122 +      <para id="x_1f7">When you run a Mercurial command in a repository, and the
  18.123  	command causes a hook to run, that hook runs on
  18.124  	<emphasis>your</emphasis> system, under
  18.125  	<emphasis>your</emphasis> user account, with
  18.126 @@ -112,14 +112,14 @@
  18.127  	it does.
  18.128        </para>
  18.129  
  18.130 -      <para>In some cases, you may be exposed to hooks that you did
  18.131 +      <para id="x_1f8">In some cases, you may be exposed to hooks that you did
  18.132  	not install yourself.  If you work with Mercurial on an
  18.133  	unfamiliar system, Mercurial will run hooks defined in that
  18.134  	system's global <filename role="special">~/.hgrc</filename>
  18.135  	file.
  18.136        </para>
  18.137  
  18.138 -      <para>If you are working with a repository owned by another
  18.139 +      <para id="x_1f9">If you are working with a repository owned by another
  18.140  	user, Mercurial can run hooks defined in that user's
  18.141  	repository, but it will still run them as <quote>you</quote>.
  18.142  	For example, if you <command role="hg-cmd">hg pull</command>
  18.143 @@ -131,7 +131,7 @@
  18.144        </para>
  18.145  
  18.146        <note>
  18.147 -	<para>  This only applies if you are pulling from a repository
  18.148 +	<para id="x_1fa">  This only applies if you are pulling from a repository
  18.149  	  on a local or network filesystem.  If you're pulling over
  18.150  	  http or ssh, any <literal role="hook">outgoing</literal>
  18.151  	  hook will run under whatever account is executing the server
  18.152 @@ -139,7 +139,7 @@
  18.153  	</para>
  18.154        </note>
  18.155  
  18.156 -      <para>XXX To see what hooks are defined in a repository, use the
  18.157 +      <para id="x_1fb">XXX To see what hooks are defined in a repository, use the
  18.158  	<command role="hg-cmd">hg config hooks</command> command.  If
  18.159  	you are working in one repository, but talking to another that
  18.160  	you do not own (e.g. using <command role="hg-cmd">hg
  18.161 @@ -152,27 +152,27 @@
  18.162      <sect2>
  18.163        <title>Hooks do not propagate</title>
  18.164  
  18.165 -      <para>In Mercurial, hooks are not revision controlled, and do
  18.166 +      <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do
  18.167  	not propagate when you clone, or pull from, a repository.  The
  18.168  	reason for this is simple: a hook is a completely arbitrary
  18.169  	piece of executable code.  It runs under your user identity,
  18.170  	with your privilege level, on your machine.
  18.171        </para>
  18.172  
  18.173 -      <para>It would be extremely reckless for any distributed
  18.174 +      <para id="x_1fd">It would be extremely reckless for any distributed
  18.175  	revision control system to implement revision-controlled
  18.176  	hooks, as this would offer an easily exploitable way to
  18.177  	subvert the accounts of users of the revision control system.
  18.178        </para>
  18.179  
  18.180 -      <para>Since Mercurial does not propagate hooks, if you are
  18.181 +      <para id="x_1fe">Since Mercurial does not propagate hooks, if you are
  18.182  	collaborating with other people on a common project, you
  18.183  	should not assume that they are using the same Mercurial hooks
  18.184  	as you are, or that theirs are correctly configured.  You
  18.185  	should document the hooks you expect people to use.
  18.186        </para>
  18.187  
  18.188 -      <para>In a corporate intranet, this is somewhat easier to
  18.189 +      <para id="x_1ff">In a corporate intranet, this is somewhat easier to
  18.190  	control, as you can for example provide a
  18.191  	<quote>standard</quote> installation of Mercurial on an NFS
  18.192  	filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will
  18.193 @@ -183,12 +183,12 @@
  18.194      <sect2>
  18.195        <title>Hooks can be overridden</title>
  18.196  
  18.197 -      <para>Mercurial allows you to override a hook definition by
  18.198 +      <para id="x_200">Mercurial allows you to override a hook definition by
  18.199  	redefining the hook.  You can disable it by setting its value
  18.200  	to the empty string, or change its behaviour as you wish.
  18.201        </para>
  18.202  
  18.203 -      <para>If you deploy a system- or site-wide <filename
  18.204 +      <para id="x_201">If you deploy a system- or site-wide <filename
  18.205  	  role="special">~/.hgrc</filename> file that defines some
  18.206  	hooks, you should thus understand that your users can disable
  18.207  	or override those hooks.
  18.208 @@ -198,7 +198,7 @@
  18.209      <sect2>
  18.210        <title>Ensuring that critical hooks are run</title>
  18.211  
  18.212 -      <para>Sometimes you may want to enforce a policy that you do not
  18.213 +      <para id="x_202">Sometimes you may want to enforce a policy that you do not
  18.214  	want others to be able to work around.  For example, you may
  18.215  	have a requirement that every changeset must pass a rigorous
  18.216  	set of tests.  Defining this requirement via a hook in a
  18.217 @@ -207,13 +207,13 @@
  18.218  	can subvert it at will by overriding the hook.
  18.219        </para>
  18.220  
  18.221 -      <para>Instead, you can set up your policies for use of Mercurial
  18.222 +      <para id="x_203">Instead, you can set up your policies for use of Mercurial
  18.223  	so that people are expected to propagate changes through a
  18.224  	well-known <quote>canonical</quote> server that you have
  18.225  	locked down and configured appropriately.
  18.226        </para>
  18.227  
  18.228 -      <para>One way to do this is via a combination of social
  18.229 +      <para id="x_204">One way to do this is via a combination of social
  18.230  	engineering and technology.  Set up a restricted-access
  18.231  	account; users can push changes over the network to
  18.232  	repositories managed by this account, but they cannot log into
  18.233 @@ -222,7 +222,7 @@
  18.234  	they want.
  18.235        </para>
  18.236  
  18.237 -      <para>When someone pushes a changeset to the server that
  18.238 +      <para id="x_205">When someone pushes a changeset to the server that
  18.239  	everyone pulls from, the server will test the changeset before
  18.240  	it accepts it as permanent, and reject it if it fails to pass
  18.241  	the test suite.  If people only pull changes from this
  18.242 @@ -236,19 +236,19 @@
  18.243      <title>Care with <literal>pretxn</literal> hooks in a
  18.244        shared-access repository</title>
  18.245  
  18.246 -    <para>If you want to use hooks to do some automated work in a
  18.247 +    <para id="x_206">If you want to use hooks to do some automated work in a
  18.248        repository that a number of people have shared access to, you
  18.249        need to be careful in how you do this.
  18.250      </para>
  18.251  
  18.252 -    <para>Mercurial only locks a repository when it is writing to the
  18.253 +    <para id="x_207">Mercurial only locks a repository when it is writing to the
  18.254        repository, and only the parts of Mercurial that write to the
  18.255        repository pay attention to locks.  Write locks are necessary to
  18.256        prevent multiple simultaneous writers from scribbling on each
  18.257        other's work, corrupting the repository.
  18.258      </para>
  18.259  
  18.260 -    <para>Because Mercurial is careful with the order in which it
  18.261 +    <para id="x_208">Because Mercurial is careful with the order in which it
  18.262        reads and writes data, it does not need to acquire a lock when
  18.263        it wants to read data from the repository.  The parts of
  18.264        Mercurial that read from the repository never pay attention to
  18.265 @@ -256,14 +256,14 @@
  18.266        performance and concurrency.
  18.267      </para>
  18.268  
  18.269 -    <para>With great performance comes a trade-off, though, one which
  18.270 +    <para id="x_209">With great performance comes a trade-off, though, one which
  18.271        has the potential to cause you trouble unless you're aware of
  18.272        it.  To describe this requires a little detail about how
  18.273        Mercurial adds changesets to a repository and reads those
  18.274        changes.
  18.275      </para>
  18.276  
  18.277 -    <para>When Mercurial <emphasis>writes</emphasis> metadata, it
  18.278 +    <para id="x_20a">When Mercurial <emphasis>writes</emphasis> metadata, it
  18.279        writes it straight into the destination file.  It writes file
  18.280        data first, then manifest data (which contains pointers to the
  18.281        new file data), then changelog data (which contains pointers to
  18.282 @@ -274,13 +274,13 @@
  18.283        before the transaction began.
  18.284      </para>
  18.285  
  18.286 -    <para>When Mercurial <emphasis>reads</emphasis> metadata, it reads
  18.287 +    <para id="x_20b">When Mercurial <emphasis>reads</emphasis> metadata, it reads
  18.288        the changelog first, then everything else.  Since a reader will
  18.289        only access parts of the manifest or file metadata that it can
  18.290        see in the changelog, it can never see partially written data.
  18.291      </para>
  18.292  
  18.293 -    <para>Some controlling hooks (<literal
  18.294 +    <para id="x_20c">Some controlling hooks (<literal
  18.295  	role="hook">pretxncommit</literal> and <literal
  18.296  	role="hook">pretxnchangegroup</literal>) run when a
  18.297        transaction is almost complete. All of the metadata has been
  18.298 @@ -288,7 +288,7 @@
  18.299        cause the newly-written data to disappear.
  18.300      </para>
  18.301  
  18.302 -    <para>If one of these hooks runs for long, it opens a window of
  18.303 +    <para id="x_20d">If one of these hooks runs for long, it opens a window of
  18.304        time during which a reader can see the metadata for changesets
  18.305        that are not yet permanent, and should not be thought of as
  18.306        <quote>really there</quote>.  The longer the hook runs, the
  18.307 @@ -298,7 +298,7 @@
  18.308      <sect2>
  18.309        <title>The problem illustrated</title>
  18.310  
  18.311 -      <para>In principle, a good use for the <literal
  18.312 +      <para id="x_20e">In principle, a good use for the <literal
  18.313  	  role="hook">pretxnchangegroup</literal> hook would be to
  18.314  	automatically build and test incoming changes before they are
  18.315  	accepted into a central repository.  This could let you
  18.316 @@ -309,7 +309,7 @@
  18.317  	potentially breaking their build.
  18.318        </para>
  18.319  
  18.320 -      <para>The safest technological answer to this challenge is to
  18.321 +      <para id="x_20f">The safest technological answer to this challenge is to
  18.322  	set up such a <quote>gatekeeper</quote> repository as
  18.323  	<emphasis>unidirectional</emphasis>.  Let it take changes
  18.324  	pushed in from the outside, but do not allow anyone to pull
  18.325 @@ -321,7 +321,7 @@
  18.326  	<emphasis>can</emphasis> pull from.
  18.327        </para>
  18.328  
  18.329 -      <para>In practice, putting a centralised bottleneck like this in
  18.330 +      <para id="x_210">In practice, putting a centralised bottleneck like this in
  18.331  	place is not often a good idea, and transaction visibility has
  18.332  	nothing to do with the problem.  As the size of a
  18.333  	project&emdash;and the time it takes to build and
  18.334 @@ -332,7 +332,7 @@
  18.335  	involved.
  18.336        </para>
  18.337  
  18.338 -      <para>An approach that scales better is to get people to build
  18.339 +      <para id="x_211">An approach that scales better is to get people to build
  18.340  	and test before they push, then run automated builds and tests
  18.341  	centrally <emphasis>after</emphasis> a push, to be sure all is
  18.342  	well.  The advantage of this approach is that it does not
  18.343 @@ -342,21 +342,21 @@
  18.344  
  18.345      </sect2>
  18.346    </sect1>
  18.347 -  <sect1 id="sec.hook.simple">
  18.348 +  <sect1 id="sec:hook:simple">
  18.349      <title>A short tutorial on using hooks</title>
  18.350  
  18.351 -    <para>It is easy to write a Mercurial hook.  Let's start with a
  18.352 +    <para id="x_212">It is easy to write a Mercurial hook.  Let's start with a
  18.353        hook that runs when you finish a <command role="hg-cmd">hg
  18.354  	commit</command>, and simply prints the hash of the changeset
  18.355        you just created.  The hook is called <literal
  18.356  	role="hook">commit</literal>.
  18.357      </para>
  18.358  
  18.359 -    <para>All hooks follow the pattern in this example.</para>
  18.360 +    <para id="x_213">All hooks follow the pattern in this example.</para>
  18.361  
  18.362  &interaction.hook.simple.init;
  18.363  
  18.364 -    <para>You add an entry to the <literal
  18.365 +    <para id="x_214">You add an entry to the <literal
  18.366  	role="rc-hooks">hooks</literal> section of your <filename
  18.367  	role="special">~/.hgrc</filename>.  On the left is the name of
  18.368        the event to trigger on; on the right is the action to take.  As
  18.369 @@ -368,12 +368,12 @@
  18.370      <sect2>
  18.371        <title>Performing multiple actions per event</title>
  18.372  
  18.373 -      <para>Quite often, you will want to define more than one hook
  18.374 +      <para id="x_215">Quite often, you will want to define more than one hook
  18.375  	for a particular kind of event, as shown below.</para>
  18.376  
  18.377  &interaction.hook.simple.ext;
  18.378  
  18.379 -      <para>Mercurial lets you do this by adding an
  18.380 +      <para id="x_216">Mercurial lets you do this by adding an
  18.381  	<emphasis>extension</emphasis> to the end of a hook's name.
  18.382  	You extend a hook's name by giving the name of the hook,
  18.383  	followed by a full stop (the
  18.384 @@ -384,7 +384,7 @@
  18.385  	<literal>commit</literal> event occurs.
  18.386        </para>
  18.387  
  18.388 -      <para>To give a well-defined order of execution when there are
  18.389 +      <para id="x_217">To give a well-defined order of execution when there are
  18.390  	multiple hooks defined for an event, Mercurial sorts hooks by
  18.391  	extension, and executes the hook commands in this sorted
  18.392  	order.  In the above example, it will execute
  18.393 @@ -393,33 +393,33 @@
  18.394  	before both.
  18.395        </para>
  18.396  
  18.397 -      <para>It is a good idea to use a somewhat descriptive extension
  18.398 -	when you define a new hook.  This will help you to remember
  18.399 -	what the hook was for.  If the hook fails, you'll get an error
  18.400 -	message that contains the hook name and extension, so using a
  18.401 -	descriptive extension could give you an immediate hint as to
  18.402 -	why the hook failed (see section <xref
  18.403 -	  linkend="sec.hook.perm"/> for an example).
  18.404 -      </para>
  18.405 -
  18.406 -    </sect2>
  18.407 -    <sect2 id="sec.hook.perm">
  18.408 +      <para id="x_218">It is a good idea to use a somewhat descriptive
  18.409 +	extension when you define a new hook.  This will help you to
  18.410 +	remember what the hook was for.  If the hook fails, you'll get
  18.411 +	an error message that contains the hook name and extension, so
  18.412 +	using a descriptive extension could give you an immediate hint
  18.413 +	as to why the hook failed (see <xref
  18.414 +	  linkend="sec:hook:perm"/> for an example).
  18.415 +      </para>
  18.416 +
  18.417 +    </sect2>
  18.418 +    <sect2 id="sec:hook:perm">
  18.419        <title>Controlling whether an activity can proceed</title>
  18.420  
  18.421 -      <para>In our earlier examples, we used the <literal
  18.422 +      <para id="x_219">In our earlier examples, we used the <literal
  18.423  	  role="hook">commit</literal> hook, which is run after a
  18.424  	commit has completed.  This is one of several Mercurial hooks
  18.425  	that run after an activity finishes.  Such hooks have no way
  18.426  	of influencing the activity itself.
  18.427        </para>
  18.428  
  18.429 -      <para>Mercurial defines a number of events that occur before an
  18.430 +      <para id="x_21a">Mercurial defines a number of events that occur before an
  18.431  	activity starts; or after it starts, but before it finishes.
  18.432  	Hooks that trigger on these events have the added ability to
  18.433  	choose whether the activity can continue, or will abort.
  18.434        </para>
  18.435  
  18.436 -      <para>The <literal role="hook">pretxncommit</literal> hook runs
  18.437 +      <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs
  18.438  	after a commit has all but completed.  In other words, the
  18.439  	metadata representing the changeset has been written out to
  18.440  	disk, but the transaction has not yet been allowed to
  18.441 @@ -428,7 +428,7 @@
  18.442  	complete, or must be rolled back.
  18.443        </para>
  18.444  
  18.445 -      <para>If the <literal role="hook">pretxncommit</literal> hook
  18.446 +      <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook
  18.447  	exits with a status code of zero, the transaction is allowed
  18.448  	to complete; the commit finishes; and the <literal
  18.449  	  role="hook">commit</literal> hook is run.  If the <literal
  18.450 @@ -440,7 +440,7 @@
  18.451  
  18.452  &interaction.hook.simple.pretxncommit;
  18.453  
  18.454 -      <para>The hook in the example above checks that a commit comment
  18.455 +      <para id="x_21d">The hook in the example above checks that a commit comment
  18.456  	contains a bug ID.  If it does, the commit can complete.  If
  18.457  	not, the commit is rolled back.
  18.458        </para>
  18.459 @@ -450,7 +450,7 @@
  18.460    <sect1>
  18.461      <title>Writing your own hooks</title>
  18.462  
  18.463 -    <para>When you are writing a hook, you might find it useful to run
  18.464 +    <para id="x_21e">When you are writing a hook, you might find it useful to run
  18.465        Mercurial either with the <option
  18.466  	role="hg-opt-global">-v</option> option, or the <envar
  18.467  	role="rc-item-ui">verbose</envar> config item set to
  18.468 @@ -458,22 +458,22 @@
  18.469        message before it calls each hook.
  18.470      </para>
  18.471  
  18.472 -    <sect2 id="sec.hook.lang">
  18.473 +    <sect2 id="sec:hook:lang">
  18.474        <title>Choosing how your hook should run</title>
  18.475  
  18.476 -      <para>You can write a hook either as a normal
  18.477 +      <para id="x_21f">You can write a hook either as a normal
  18.478  	program&emdash;typically a shell script&emdash;or as a Python
  18.479  	function that is executed within the Mercurial process.
  18.480        </para>
  18.481  
  18.482 -      <para>Writing a hook as an external program has the advantage
  18.483 +      <para id="x_220">Writing a hook as an external program has the advantage
  18.484  	that it requires no knowledge of Mercurial's internals.  You
  18.485  	can call normal Mercurial commands to get any added
  18.486  	information you need.  The trade-off is that external hooks
  18.487  	are slower than in-process hooks.
  18.488        </para>
  18.489  
  18.490 -      <para>An in-process Python hook has complete access to the
  18.491 +      <para id="x_221">An in-process Python hook has complete access to the
  18.492  	Mercurial API, and does not <quote>shell out</quote> to
  18.493  	another process, so it is inherently faster than an external
  18.494  	hook.  It is also easier to obtain much of the information
  18.495 @@ -481,7 +481,7 @@
  18.496  	running Mercurial commands.
  18.497        </para>
  18.498  
  18.499 -      <para>If you are comfortable with Python, or require high
  18.500 +      <para id="x_222">If you are comfortable with Python, or require high
  18.501  	performance, writing your hooks in Python may be a good
  18.502  	choice.  However, when you have a straightforward hook to
  18.503  	write and you don't need to care about performance (probably
  18.504 @@ -489,16 +489,16 @@
  18.505        </para>
  18.506  
  18.507      </sect2>
  18.508 -    <sect2 id="sec.hook.param">
  18.509 +    <sect2 id="sec:hook:param">
  18.510        <title>Hook parameters</title>
  18.511  
  18.512 -      <para>Mercurial calls each hook with a set of well-defined
  18.513 +      <para id="x_223">Mercurial calls each hook with a set of well-defined
  18.514  	parameters.  In Python, a parameter is passed as a keyword
  18.515  	argument to your hook function.  For an external program, a
  18.516  	parameter is passed as an environment variable.
  18.517        </para>
  18.518  
  18.519 -      <para>Whether your hook is written in Python or as a shell
  18.520 +      <para id="x_224">Whether your hook is written in Python or as a shell
  18.521  	script, the hook-specific parameter names and values will be
  18.522  	the same.  A boolean parameter will be represented as a
  18.523  	boolean value in Python, but as the number 1 (for
  18.524 @@ -514,7 +514,7 @@
  18.525      <sect2>
  18.526        <title>Hook return values and activity control</title>
  18.527  
  18.528 -      <para>A hook that executes successfully must exit with a status
  18.529 +      <para id="x_225">A hook that executes successfully must exit with a status
  18.530  	of zero if external, or return boolean <quote>false</quote> if
  18.531  	in-process.  Failure is indicated with a non-zero exit status
  18.532  	from an external hook, or an in-process hook returning boolean
  18.533 @@ -522,7 +522,7 @@
  18.534  	exception, the hook is considered to have failed.
  18.535        </para>
  18.536  
  18.537 -      <para>For a hook that controls whether an activity can proceed,
  18.538 +      <para id="x_226">For a hook that controls whether an activity can proceed,
  18.539  	zero/false means <quote>allow</quote>, while
  18.540  	non-zero/true/exception means <quote>deny</quote>.
  18.541        </para>
  18.542 @@ -531,23 +531,23 @@
  18.543      <sect2>
  18.544        <title>Writing an external hook</title>
  18.545  
  18.546 -      <para>When you define an external hook in your <filename
  18.547 +      <para id="x_227">When you define an external hook in your <filename
  18.548  	  role="special">~/.hgrc</filename> and the hook is run, its
  18.549  	value is passed to your shell, which interprets it.  This
  18.550  	means that you can use normal shell constructs in the body of
  18.551  	the hook.
  18.552        </para>
  18.553  
  18.554 -      <para>An executable hook is always run with its current
  18.555 +      <para id="x_228">An executable hook is always run with its current
  18.556  	directory set to a repository's root directory.
  18.557        </para>
  18.558  
  18.559 -      <para>Each hook parameter is passed in as an environment
  18.560 +      <para id="x_229">Each hook parameter is passed in as an environment
  18.561  	variable; the name is upper-cased, and prefixed with the
  18.562  	string <quote><literal>HG_</literal></quote>.
  18.563        </para>
  18.564  
  18.565 -      <para>With the exception of hook parameters, Mercurial does not
  18.566 +      <para id="x_22a">With the exception of hook parameters, Mercurial does not
  18.567  	set or modify any environment variables when running a hook.
  18.568  	This is useful to remember if you are writing a site-wide hook
  18.569  	that may be run by a number of different users with differing
  18.570 @@ -560,7 +560,7 @@
  18.571      <sect2>
  18.572        <title>Telling Mercurial to use an in-process hook</title>
  18.573  
  18.574 -      <para>The <filename role="special">~/.hgrc</filename> syntax
  18.575 +      <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax
  18.576  	for defining an in-process hook is slightly different than for
  18.577  	an executable hook.  The value of the hook must start with the
  18.578  	text <quote><literal>python:</literal></quote>, and continue
  18.579 @@ -568,19 +568,19 @@
  18.580  	the hook's value.
  18.581        </para>
  18.582  
  18.583 -      <para>The module in which a hook lives is automatically imported
  18.584 +      <para id="x_22c">The module in which a hook lives is automatically imported
  18.585  	when a hook is run.  So long as you have the module name and
  18.586  	<envar>PYTHONPATH</envar> right, it should <quote>just
  18.587  	  work</quote>.
  18.588        </para>
  18.589  
  18.590 -      <para>The following <filename role="special">~/.hgrc</filename>
  18.591 +      <para id="x_22d">The following <filename role="special">~/.hgrc</filename>
  18.592  	example snippet illustrates the syntax and meaning of the
  18.593  	notions we just described.
  18.594        </para>
  18.595        <programlisting>[hooks]
  18.596  commit.example = python:mymodule.submodule.myhook</programlisting>
  18.597 -      <para>When Mercurial runs the <literal>commit.example</literal>
  18.598 +      <para id="x_22e">When Mercurial runs the <literal>commit.example</literal>
  18.599  	hook, it imports <literal>mymodule.submodule</literal>, looks
  18.600  	for the callable object named <literal>myhook</literal>, and
  18.601  	calls it.
  18.602 @@ -590,12 +590,12 @@
  18.603      <sect2>
  18.604        <title>Writing an in-process hook</title>
  18.605  
  18.606 -      <para>The simplest in-process hook does nothing, but illustrates
  18.607 +      <para id="x_22f">The simplest in-process hook does nothing, but illustrates
  18.608  	the basic shape of the hook API:
  18.609        </para>
  18.610        <programlisting>def myhook(ui, repo, **kwargs):
  18.611      pass</programlisting>
  18.612 -      <para>The first argument to a Python hook is always a <literal
  18.613 +      <para id="x_230">The first argument to a Python hook is always a <literal
  18.614  	  role="py-mod-mercurial.ui">ui</literal> object.  The second
  18.615  	is a repository object; at the moment, it is always an
  18.616  	instance of <literal
  18.617 @@ -615,7 +615,7 @@
  18.618      <sect2>
  18.619        <title>Writing meaningful commit messages</title>
  18.620  
  18.621 -      <para>It's hard to imagine a useful commit message being very
  18.622 +      <para id="x_231">It's hard to imagine a useful commit message being very
  18.623  	short. The simple <literal role="hook">pretxncommit</literal>
  18.624  	hook of the example below will prevent you from committing a
  18.625  	changeset with a message that is less than ten bytes long.
  18.626 @@ -627,7 +627,7 @@
  18.627      <sect2>
  18.628        <title>Checking for trailing whitespace</title>
  18.629  
  18.630 -      <para>An interesting use of a commit-related hook is to help you
  18.631 +      <para id="x_232">An interesting use of a commit-related hook is to help you
  18.632  	to write cleaner code.  A simple example of <quote>cleaner
  18.633  	  code</quote> is the dictum that a change should not add any
  18.634  	new lines of text that contain <quote>trailing
  18.635 @@ -638,7 +638,7 @@
  18.636  	prefer to get rid of it.
  18.637        </para>
  18.638  
  18.639 -      <para>You can use either the <literal
  18.640 +      <para id="x_233">You can use either the <literal
  18.641  	  role="hook">precommit</literal> or <literal
  18.642  	  role="hook">pretxncommit</literal> hook to tell whether you
  18.643  	have a trailing whitespace problem.  If you use the <literal
  18.644 @@ -654,7 +654,7 @@
  18.645  	seem right.
  18.646        </para>
  18.647  
  18.648 -      <para>Should you choose the <literal
  18.649 +      <para id="x_234">Should you choose the <literal
  18.650  	  role="hook">pretxncommit</literal> hook, the check won't
  18.651  	occur until just before the transaction for the commit
  18.652  	completes.  This will allow you to check for problems only the
  18.653 @@ -667,7 +667,7 @@
  18.654  
  18.655  &interaction.hook.ws.simple;
  18.656  
  18.657 -      <para>In this example, we introduce a simple <literal
  18.658 +      <para id="x_235">In this example, we introduce a simple <literal
  18.659  	  role="hook">pretxncommit</literal> hook that checks for
  18.660  	trailing whitespace.  This hook is short, but not very
  18.661  	helpful.  It exits with an error status if a change adds a
  18.662 @@ -678,7 +678,7 @@
  18.663  	trailing whitespace cause problems.
  18.664        </para>
  18.665  
  18.666 -      <para>The above version is much more complex, but also more
  18.667 +      <para id="x_236">The above version is much more complex, but also more
  18.668  	useful.  It parses a unified diff to see if any lines add
  18.669  	trailing whitespace, and prints the name of the file and the
  18.670  	line number of each such occurrence.  Even better, if the
  18.671 @@ -692,7 +692,7 @@
  18.672  
  18.673  &interaction.hook.ws.better;
  18.674  
  18.675 -      <para>As a final aside, note in the example above the use of
  18.676 +      <para id="x_237">As a final aside, note in the example above the use of
  18.677  	<command>perl</command>'s in-place editing feature to get rid
  18.678  	of trailing whitespace from a file.  This is concise and
  18.679  	useful enough that I will reproduce it here.
  18.680 @@ -704,7 +704,7 @@
  18.681    <sect1>
  18.682      <title>Bundled hooks</title>
  18.683  
  18.684 -    <para>Mercurial ships with several bundled hooks.  You can find
  18.685 +    <para id="x_238">Mercurial ships with several bundled hooks.  You can find
  18.686        them in the <filename class="directory">hgext</filename>
  18.687        directory of a Mercurial source tree.  If you are using a
  18.688        Mercurial binary package, the hooks will be located in the
  18.689 @@ -716,7 +716,7 @@
  18.690        <title><literal role="hg-ext">acl</literal>&emdash;access
  18.691  	control for parts of a repository</title>
  18.692  
  18.693 -      <para>The <literal role="hg-ext">acl</literal> extension lets
  18.694 +      <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets
  18.695  	you control which remote users are allowed to push changesets
  18.696  	to a networked server.  You can protect any portion of a
  18.697  	repository (including the entire repo), so that a specific
  18.698 @@ -724,7 +724,7 @@
  18.699  	portion.
  18.700        </para>
  18.701  
  18.702 -      <para>This extension implements access control based on the
  18.703 +      <para id="x_23a">This extension implements access control based on the
  18.704  	identity of the user performing a push,
  18.705  	<emphasis>not</emphasis> on who committed the changesets
  18.706  	they're pushing.  It makes sense to use this hook only if you
  18.707 @@ -737,7 +737,7 @@
  18.708  	<title>Configuring the <literal role="hook">acl</literal>
  18.709  	  hook</title>
  18.710  
  18.711 -	<para>In order to manage incoming changesets, the <literal
  18.712 +	<para id="x_23b">In order to manage incoming changesets, the <literal
  18.713  	    role="hg-ext">acl</literal> hook must be used as a
  18.714  	  <literal role="hook">pretxnchangegroup</literal> hook.  This
  18.715  	  lets it see which files are modified by each incoming
  18.716 @@ -747,18 +747,18 @@
  18.717  	<programlisting>[hooks]
  18.718  pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
  18.719  
  18.720 -	<para>The <literal role="hg-ext">acl</literal> extension is
  18.721 +	<para id="x_23c">The <literal role="hg-ext">acl</literal> extension is
  18.722  	  configured using three sections.
  18.723  	</para>
  18.724  
  18.725 -	<para>The <literal role="rc-acl">acl</literal> section has
  18.726 +	<para id="x_23d">The <literal role="rc-acl">acl</literal> section has
  18.727  	  only one entry, <envar role="rc-item-acl">sources</envar>,
  18.728  	  which lists the sources of incoming changesets that the hook
  18.729  	  should pay attention to.  You don't normally need to
  18.730  	  configure this section.
  18.731  	</para>
  18.732  	<itemizedlist>
  18.733 -	  <listitem><para><envar role="rc-item-acl">serve</envar>:
  18.734 +	  <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>:
  18.735  	      Control incoming changesets that are arriving from a
  18.736  	      remote repository over http or ssh.  This is the default
  18.737  	      value of <envar role="rc-item-acl">sources</envar>, and
  18.738 @@ -766,23 +766,23 @@
  18.739  	      configuration item.
  18.740  	    </para>
  18.741  	  </listitem>
  18.742 -	  <listitem><para><envar role="rc-item-acl">pull</envar>:
  18.743 +	  <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>:
  18.744  	      Control incoming changesets that are arriving via a pull
  18.745  	      from a local repository.
  18.746  	    </para>
  18.747  	  </listitem>
  18.748 -	  <listitem><para><envar role="rc-item-acl">push</envar>:
  18.749 +	  <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>:
  18.750  	      Control incoming changesets that are arriving via a push
  18.751  	      from a local repository.
  18.752  	    </para>
  18.753  	  </listitem>
  18.754 -	  <listitem><para><envar role="rc-item-acl">bundle</envar>:
  18.755 +	  <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>:
  18.756  	      Control incoming changesets that are arriving from
  18.757  	      another repository via a bundle.
  18.758  	    </para>
  18.759  	  </listitem></itemizedlist>
  18.760  
  18.761 -	<para>The <literal role="rc-acl.allow">acl.allow</literal>
  18.762 +	<para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal>
  18.763  	  section controls the users that are allowed to add
  18.764  	  changesets to the repository.  If this section is not
  18.765  	  present, all users that are not explicitly denied are
  18.766 @@ -791,13 +791,13 @@
  18.767  	  that all users are denied).
  18.768  	</para>
  18.769  
  18.770 -	<para>The <literal role="rc-acl.deny">acl.deny</literal>
  18.771 +	<para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal>
  18.772  	  section determines which users are denied from adding
  18.773  	  changesets to the repository.  If this section is not
  18.774  	  present or is empty, no users are denied.
  18.775  	</para>
  18.776  
  18.777 -	<para>The syntaxes for the <literal
  18.778 +	<para id="x_244">The syntaxes for the <literal
  18.779  	    role="rc-acl.allow">acl.allow</literal> and <literal
  18.780  	    role="rc-acl.deny">acl.deny</literal> sections are
  18.781  	  identical.  On the left of each entry is a glob pattern that
  18.782 @@ -805,7 +805,7 @@
  18.783  	  repository; on the right, a user name.
  18.784  	</para>
  18.785  
  18.786 -	<para>In the following example, the user
  18.787 +	<para id="x_245">In the following example, the user
  18.788  	  <literal>docwriter</literal> can only push changes to the
  18.789  	  <filename class="directory">docs</filename> subtree of the
  18.790  	  repository, while <literal>intern</literal> can push changes
  18.791 @@ -821,7 +821,7 @@
  18.792        <sect3>
  18.793  	<title>Testing and troubleshooting</title>
  18.794  
  18.795 -	<para>If you want to test the <literal
  18.796 +	<para id="x_246">If you want to test the <literal
  18.797  	    role="hg-ext">acl</literal> hook, run it with Mercurial's
  18.798  	  debugging output enabled.  Since you'll probably be running
  18.799  	  it on a server where it's not convenient (or sometimes
  18.800 @@ -832,7 +832,7 @@
  18.801  	</para>
  18.802  	<programlisting>[ui]
  18.803  debug = true</programlisting>
  18.804 -	<para>With this enabled, the <literal
  18.805 +	<para id="x_247">With this enabled, the <literal
  18.806  	    role="hg-ext">acl</literal> hook will print enough
  18.807  	  information to let you figure out why it is allowing or
  18.808  	  forbidding pushes from specific users.
  18.809 @@ -845,14 +845,14 @@
  18.810  	  role="hg-ext">bugzilla</literal>&emdash;integration with
  18.811  	Bugzilla</title>
  18.812  
  18.813 -      <para>The <literal role="hg-ext">bugzilla</literal> extension
  18.814 +      <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension
  18.815  	adds a comment to a Bugzilla bug whenever it finds a reference
  18.816  	to that bug ID in a commit comment.  You can install this hook
  18.817  	on a shared server, so that any time a remote user pushes
  18.818  	changes to this server, the hook gets run.
  18.819        </para>
  18.820  
  18.821 -      <para>It adds a comment to the bug that looks like this (you can
  18.822 +      <para id="x_249">It adds a comment to the bug that looks like this (you can
  18.823  	configure the contents of the comment&emdash;see below):
  18.824        </para>
  18.825        <programlisting>Changeset aad8b264143a, made by Joe User
  18.826 @@ -861,19 +861,19 @@
  18.827  	http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
  18.828  	Changeset description: Fix bug 10483 by guarding against some
  18.829  	NULL pointers</programlisting>
  18.830 -      <para>The value of this hook is that it automates the process of
  18.831 +      <para id="x_24a">The value of this hook is that it automates the process of
  18.832  	updating a bug any time a changeset refers to it.  If you
  18.833  	configure the hook properly, it makes it easy for people to
  18.834  	browse straight from a Bugzilla bug to a changeset that refers
  18.835  	to that bug.
  18.836        </para>
  18.837  
  18.838 -      <para>You can use the code in this hook as a starting point for
  18.839 +      <para id="x_24b">You can use the code in this hook as a starting point for
  18.840  	some more exotic Bugzilla integration recipes.  Here are a few
  18.841  	possibilities:
  18.842        </para>
  18.843        <itemizedlist>
  18.844 -	<listitem><para>Require that every changeset pushed to the
  18.845 +	<listitem><para id="x_24c">Require that every changeset pushed to the
  18.846  	    server have a valid bug ID in its commit comment.  In this
  18.847  	    case, you'd want to configure the hook as a <literal
  18.848  	      role="hook">pretxncommit</literal> hook.  This would
  18.849 @@ -881,7 +881,7 @@
  18.850  	    IDs.
  18.851  	  </para>
  18.852  	</listitem>
  18.853 -	<listitem><para>Allow incoming changesets to automatically
  18.854 +	<listitem><para id="x_24d">Allow incoming changesets to automatically
  18.855  	    modify the <emphasis>state</emphasis> of a bug, as well as
  18.856  	    simply adding a comment.  For example, the hook could
  18.857  	    recognise the string <quote>fixed bug 31337</quote> as
  18.858 @@ -890,11 +890,11 @@
  18.859  	  </para>
  18.860  	</listitem></itemizedlist>
  18.861  
  18.862 -      <sect3 id="sec.hook.bugzilla.config">
  18.863 +      <sect3 id="sec:hook:bugzilla:config">
  18.864  	<title>Configuring the <literal role="hook">bugzilla</literal>
  18.865  	  hook</title>
  18.866  
  18.867 -	<para>You should configure this hook in your server's
  18.868 +	<para id="x_24e">You should configure this hook in your server's
  18.869  	  <filename role="special">~/.hgrc</filename> as an <literal
  18.870  	    role="hook">incoming</literal> hook, for example as
  18.871  	  follows:
  18.872 @@ -902,25 +902,25 @@
  18.873  	<programlisting>[hooks]
  18.874  incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
  18.875  
  18.876 -	<para>Because of the specialised nature of this hook, and
  18.877 +	<para id="x_24f">Because of the specialised nature of this hook, and
  18.878  	  because Bugzilla was not written with this kind of
  18.879  	  integration in mind, configuring this hook is a somewhat
  18.880  	  involved process.
  18.881  	</para>
  18.882  
  18.883 -	<para>Before you begin, you must install the MySQL bindings
  18.884 +	<para id="x_250">Before you begin, you must install the MySQL bindings
  18.885  	  for Python on the host(s) where you'll be running the hook.
  18.886  	  If this is not available as a binary package for your
  18.887  	  system, you can download it from
  18.888  	  <citation>web:mysql-python</citation>.
  18.889  	</para>
  18.890  
  18.891 -	<para>Configuration information for this hook lives in the
  18.892 +	<para id="x_251">Configuration information for this hook lives in the
  18.893  	  <literal role="rc-bugzilla">bugzilla</literal> section of
  18.894  	  your <filename role="special">~/.hgrc</filename>.
  18.895  	</para>
  18.896  	<itemizedlist>
  18.897 -	  <listitem><para><envar
  18.898 +	  <listitem><para id="x_252"><envar
  18.899  		role="rc-item-bugzilla">version</envar>: The version
  18.900  	      of Bugzilla installed on the server.  The database
  18.901  	      schema that Bugzilla uses changes occasionally, so this
  18.902 @@ -929,14 +929,14 @@
  18.903  	      <literal>2.16</literal>.
  18.904  	    </para>
  18.905  	  </listitem>
  18.906 -	  <listitem><para><envar role="rc-item-bugzilla">host</envar>:
  18.907 +	  <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>:
  18.908  	      The hostname of the MySQL server that stores your
  18.909  	      Bugzilla data.  The database must be configured to allow
  18.910  	      connections from whatever host you are running the
  18.911  	      <literal role="hook">bugzilla</literal> hook on.
  18.912  	    </para>
  18.913  	  </listitem>
  18.914 -	  <listitem><para><envar role="rc-item-bugzilla">user</envar>:
  18.915 +	  <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>:
  18.916  	      The username with which to connect to the MySQL server.
  18.917  	      The database must be configured to allow this user to
  18.918  	      connect from whatever host you are running the <literal
  18.919 @@ -947,7 +947,7 @@
  18.920  	      MySQL database.
  18.921  	    </para>
  18.922  	  </listitem>
  18.923 -	  <listitem><para><envar
  18.924 +	  <listitem><para id="x_255"><envar
  18.925  		role="rc-item-bugzilla">password</envar>: The MySQL
  18.926  	      password for the user you configured above.  This is
  18.927  	      stored as plain text, so you should make sure that
  18.928 @@ -956,14 +956,14 @@
  18.929  	      store this information.
  18.930  	    </para>
  18.931  	  </listitem>
  18.932 -	  <listitem><para><envar role="rc-item-bugzilla">db</envar>:
  18.933 +	  <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>:
  18.934  	      The name of the Bugzilla database on the MySQL server.
  18.935  	      The default value of this item is
  18.936  	      <literal>bugs</literal>, which is the standard name of
  18.937  	      the MySQL database where Bugzilla stores its data.
  18.938  	    </para>
  18.939  	  </listitem>
  18.940 -	  <listitem><para><envar
  18.941 +	  <listitem><para id="x_257"><envar
  18.942  		role="rc-item-bugzilla">notify</envar>: If you want
  18.943  	      Bugzilla to send out a notification email to subscribers
  18.944  	      after this hook has added a comment to a bug, you will
  18.945 @@ -976,7 +976,7 @@
  18.946  	    <programlisting>cd /var/www/html/bugzilla &amp;&amp;
  18.947  	      ./processmail %s nobody@nowhere.com</programlisting>
  18.948  	  </listitem>
  18.949 -	  <listitem><para>  The Bugzilla
  18.950 +	  <listitem><para id="x_258">  The Bugzilla
  18.951  	      <literal>processmail</literal> program expects to be
  18.952  	      given a bug ID (the hook replaces
  18.953  	      <quote><literal>%s</literal></quote> with the bug ID)
  18.954 @@ -993,7 +993,7 @@
  18.955        <sect3>
  18.956  	<title>Mapping committer names to Bugzilla user names</title>
  18.957  
  18.958 -	<para>By default, the <literal
  18.959 +	<para id="x_259">By default, the <literal
  18.960  	    role="hg-ext">bugzilla</literal> hook tries to use the
  18.961  	  email address of a changeset's committer as the Bugzilla
  18.962  	  user name with which to update a bug.  If this does not suit
  18.963 @@ -1002,14 +1002,14 @@
  18.964  	    role="rc-usermap">usermap</literal> section.
  18.965  	</para>
  18.966  
  18.967 -	<para>Each item in the <literal
  18.968 +	<para id="x_25a">Each item in the <literal
  18.969  	    role="rc-usermap">usermap</literal> section contains an
  18.970  	  email address on the left, and a Bugzilla user name on the
  18.971  	  right.
  18.972  	</para>
  18.973  	<programlisting>[usermap]
  18.974  jane.user@example.com = jane</programlisting>
  18.975 -	<para>You can either keep the <literal
  18.976 +	<para id="x_25b">You can either keep the <literal
  18.977  	    role="rc-usermap">usermap</literal> data in a normal
  18.978  	  <filename role="special">~/.hgrc</filename>, or tell the
  18.979  	  <literal role="hg-ext">bugzilla</literal> hook to read the
  18.980 @@ -1025,7 +1025,7 @@
  18.981  	<programlisting># regular hgrc file refers to external usermap file
  18.982  [bugzilla]
  18.983  usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
  18.984 -	<para>While the <filename>usermap</filename> file that it
  18.985 +	<para id="x_25c">While the <filename>usermap</filename> file that it
  18.986  	  refers to might look like this:
  18.987  	</para>
  18.988  	<programlisting># bugzilla-usermap.conf - inside a hg repository
  18.989 @@ -1035,14 +1035,14 @@
  18.990        <sect3>
  18.991  	<title>Configuring the text that gets added to a bug</title>
  18.992  
  18.993 -	<para>You can configure the text that this hook adds as a
  18.994 +	<para id="x_25d">You can configure the text that this hook adds as a
  18.995  	  comment; you specify it in the form of a Mercurial template.
  18.996  	  Several <filename role="special">~/.hgrc</filename> entries
  18.997  	  (still in the <literal role="rc-bugzilla">bugzilla</literal>
  18.998  	  section) control this behaviour.
  18.999  	</para>
 18.1000  	<itemizedlist>
 18.1001 -	  <listitem><para><literal>strip</literal>: The number of
 18.1002 +	  <listitem><para id="x_25e"><literal>strip</literal>: The number of
 18.1003  	      leading path elements to strip from a repository's path
 18.1004  	      name to construct a partial path for a URL. For example,
 18.1005  	      if the repositories on your server live under <filename
 18.1006 @@ -1056,7 +1056,7 @@
 18.1007  	      expanding a template, as <literal>webroot</literal>.
 18.1008  	    </para>
 18.1009  	  </listitem>
 18.1010 -	  <listitem><para><literal>template</literal>: The text of the
 18.1011 +	  <listitem><para id="x_25f"><literal>template</literal>: The text of the
 18.1012  	      template to use.  In addition to the usual
 18.1013  	      changeset-related variables, this template can use
 18.1014  	      <literal>hgweb</literal> (the value of the
 18.1015 @@ -1066,7 +1066,7 @@
 18.1016  	    </para>
 18.1017  	  </listitem></itemizedlist>
 18.1018  
 18.1019 -	<para>In addition, you can add a <envar
 18.1020 +	<para id="x_260">In addition, you can add a <envar
 18.1021  	    role="rc-item-web">baseurl</envar> item to the <literal
 18.1022  	    role="rc-web">web</literal> section of your <filename
 18.1023  	    role="special">~/.hgrc</filename>.  The <literal
 18.1024 @@ -1078,24 +1078,24 @@
 18.1025  	<programlisting>[web]
 18.1026  baseurl = http://hg.domain.com/</programlisting>
 18.1027  
 18.1028 -	<para>Here is an example set of <literal
 18.1029 +	<para id="x_261">Here is an example set of <literal
 18.1030  	    role="hg-ext">bugzilla</literal> hook config information.
 18.1031  	</para>
 18.1032  
 18.1033 -	<programlisting>&ch10-bugzilla-config.lst;</programlisting>
 18.1034 +	&ch10-bugzilla-config.lst;
 18.1035  
 18.1036        </sect3>
 18.1037        <sect3>
 18.1038  	<title>Testing and troubleshooting</title>
 18.1039  
 18.1040 -	<para>The most common problems with configuring the <literal
 18.1041 +	<para id="x_262">The most common problems with configuring the <literal
 18.1042  	    role="hg-ext">bugzilla</literal> hook relate to running
 18.1043  	  Bugzilla's <filename>processmail</filename> script and
 18.1044  	  mapping committer names to user names.
 18.1045  	</para>
 18.1046  
 18.1047 -	<para>Recall from section <xref
 18.1048 -	    linkend="sec.hook.bugzilla.config"/> above that the user
 18.1049 +	<para id="x_263">Recall from <xref
 18.1050 +	    linkend="sec:hook:bugzilla:config"/> above that the user
 18.1051  	  that runs the Mercurial process on the server is also the
 18.1052  	  one that will run the <filename>processmail</filename>
 18.1053  	  script.  The <filename>processmail</filename> script
 18.1054 @@ -1105,19 +1105,19 @@
 18.1055  	  under.
 18.1056  	</para>
 18.1057  
 18.1058 -	<para>You can cause <filename>processmail</filename> to be run
 18.1059 +	<para id="x_264">You can cause <filename>processmail</filename> to be run
 18.1060  	  with the suitable user's identity using the
 18.1061  	  <command>sudo</command> command.  Here is an example entry
 18.1062  	  for a <filename>sudoers</filename> file.
 18.1063  	</para>
 18.1064  	<programlisting>hg_user = (httpd_user)
 18.1065  NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
 18.1066 -	<para>This allows the <literal>hg_user</literal> user to run a
 18.1067 +	<para id="x_265">This allows the <literal>hg_user</literal> user to run a
 18.1068  	  <filename>processmail-wrapper</filename> program under the
 18.1069  	  identity of <literal>httpd_user</literal>.
 18.1070  	</para>
 18.1071  
 18.1072 -	<para>This indirection through a wrapper script is necessary,
 18.1073 +	<para id="x_266">This indirection through a wrapper script is necessary,
 18.1074  	  because <filename>processmail</filename> expects to be run
 18.1075  	  with its current directory set to wherever you installed
 18.1076  	  Bugzilla; you can't specify that kind of constraint in a
 18.1077 @@ -1126,18 +1126,18 @@
 18.1078  	</para>
 18.1079  	<programlisting>#!/bin/sh
 18.1080  cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com</programlisting>
 18.1081 -	<para>It doesn't seem to matter what email address you pass to
 18.1082 +	<para id="x_267">It doesn't seem to matter what email address you pass to
 18.1083  	  <filename>processmail</filename>.
 18.1084  	</para>
 18.1085  
 18.1086 -	<para>If your <literal role="rc-usermap">usermap</literal> is
 18.1087 +	<para id="x_268">If your <literal role="rc-usermap">usermap</literal> is
 18.1088  	  not set up correctly, users will see an error message from
 18.1089  	  the <literal role="hg-ext">bugzilla</literal> hook when they
 18.1090  	  push changes to the server.  The error message will look
 18.1091  	  like this:
 18.1092  	</para>
 18.1093  	<programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting>
 18.1094 -	<para>What this means is that the committer's address,
 18.1095 +	<para id="x_269">What this means is that the committer's address,
 18.1096  	  <literal>john.q.public@example.com</literal>, is not a valid
 18.1097  	  Bugzilla user name, nor does it have an entry in your
 18.1098  	  <literal role="rc-usermap">usermap</literal> that maps it to
 18.1099 @@ -1150,7 +1150,7 @@
 18.1100        <title><literal role="hg-ext">notify</literal>&emdash;send email
 18.1101  	notifications</title>
 18.1102  
 18.1103 -      <para>Although Mercurial's built-in web server provides RSS
 18.1104 +      <para id="x_26a">Although Mercurial's built-in web server provides RSS
 18.1105  	feeds of changes in every repository, many people prefer to
 18.1106  	receive change notifications via email.  The <literal
 18.1107  	  role="hg-ext">notify</literal> hook lets you send out
 18.1108 @@ -1158,13 +1158,13 @@
 18.1109  	arrive that those subscribers are interested in.
 18.1110        </para>
 18.1111  
 18.1112 -      <para>As with the <literal role="hg-ext">bugzilla</literal>
 18.1113 +      <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal>
 18.1114  	hook, the <literal role="hg-ext">notify</literal> hook is
 18.1115  	template-driven, so you can customise the contents of the
 18.1116  	notification messages that it sends.
 18.1117        </para>
 18.1118  
 18.1119 -      <para>By default, the <literal role="hg-ext">notify</literal>
 18.1120 +      <para id="x_26c">By default, the <literal role="hg-ext">notify</literal>
 18.1121  	hook includes a diff of every changeset that it sends out; you
 18.1122  	can limit the size of the diff, or turn this feature off
 18.1123  	entirely.  It is useful for letting subscribers review changes
 18.1124 @@ -1175,7 +1175,7 @@
 18.1125  	<title>Configuring the <literal role="hg-ext">notify</literal>
 18.1126  	  hook</title>
 18.1127  
 18.1128 -	<para>You can set up the <literal
 18.1129 +	<para id="x_26d">You can set up the <literal
 18.1130  	    role="hg-ext">notify</literal> hook to send one email
 18.1131  	  message per incoming changeset, or one per incoming group of
 18.1132  	  changesets (all those that arrived in a single pull or
 18.1133 @@ -1187,12 +1187,12 @@
 18.1134  # send one email per change
 18.1135  incoming.notify = python:hgext.notify.hook</programlisting>
 18.1136  
 18.1137 -	<para>Configuration information for this hook lives in the
 18.1138 +	<para id="x_26e">Configuration information for this hook lives in the
 18.1139  	  <literal role="rc-notify">notify</literal> section of a
 18.1140  	  <filename role="special">~/.hgrc</filename> file.
 18.1141  	</para>
 18.1142  	<itemizedlist>
 18.1143 -	  <listitem><para><envar role="rc-item-notify">test</envar>:
 18.1144 +	  <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>:
 18.1145  	      By default, this hook does not send out email at all;
 18.1146  	      instead, it prints the message that it
 18.1147  	      <emphasis>would</emphasis> send.  Set this item to
 18.1148 @@ -1204,7 +1204,7 @@
 18.1149  	      notifications while you debug your configuration.
 18.1150  	    </para>
 18.1151  	  </listitem>
 18.1152 -	  <listitem><para><envar role="rc-item-notify">config</envar>:
 18.1153 +	  <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>:
 18.1154  	      The path to a configuration file that contains
 18.1155  	      subscription information.  This is kept separate from
 18.1156  	      the main <filename role="special">~/.hgrc</filename> so
 18.1157 @@ -1213,7 +1213,7 @@
 18.1158  	      subscriptions, and push the changes back to your server.
 18.1159  	    </para>
 18.1160  	  </listitem>
 18.1161 -	  <listitem><para><envar role="rc-item-notify">strip</envar>:
 18.1162 +	  <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>:
 18.1163  	      The number of leading path separator characters to strip
 18.1164  	      from a repository's path, when deciding whether a
 18.1165  	      repository has subscribers.  For example, if the
 18.1166 @@ -1230,13 +1230,13 @@
 18.1167  	      match subscribers against that.
 18.1168  	    </para>
 18.1169  	  </listitem>
 18.1170 -	  <listitem><para><envar
 18.1171 +	  <listitem><para id="x_272"><envar
 18.1172  		role="rc-item-notify">template</envar>: The template
 18.1173  	      text to use when sending messages.  This specifies both
 18.1174  	      the contents of the message header and its body.
 18.1175  	    </para>
 18.1176  	  </listitem>
 18.1177 -	  <listitem><para><envar
 18.1178 +	  <listitem><para id="x_273"><envar
 18.1179  		role="rc-item-notify">maxdiff</envar>: The maximum
 18.1180  	      number of lines of diff data to append to the end of a
 18.1181  	      message.  If a diff is longer than this, it is
 18.1182 @@ -1245,41 +1245,40 @@
 18.1183  	      emails.
 18.1184  	    </para>
 18.1185  	  </listitem>
 18.1186 -	  <listitem><para><envar
 18.1187 +	  <listitem><para id="x_274"><envar
 18.1188  		role="rc-item-notify">sources</envar>: A list of
 18.1189  	      sources of changesets to consider.  This lets you limit
 18.1190  	      <literal role="hg-ext">notify</literal> to only sending
 18.1191  	      out email about changes that remote users pushed into
 18.1192 -	      this repository via a server, for example.  See section
 18.1193 -	      <xref
 18.1194 -		linkend="sec.hook.sources"/> for the sources you can
 18.1195 -	      specify here.
 18.1196 +	      this repository via a server, for example.  See 
 18.1197 +	      <xref linkend="sec:hook:sources"/> for the sources you
 18.1198 +	      can specify here.
 18.1199  	    </para>
 18.1200  	  </listitem></itemizedlist>
 18.1201  
 18.1202 -	<para>If you set the <envar role="rc-item-web">baseurl</envar>
 18.1203 +	<para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar>
 18.1204  	  item in the <literal role="rc-web">web</literal> section,
 18.1205  	  you can use it in a template; it will be available as
 18.1206  	  <literal>webroot</literal>.
 18.1207  	</para>
 18.1208  
 18.1209 -	<para>Here is an example set of <literal
 18.1210 +	<para id="x_276">Here is an example set of <literal
 18.1211  	    role="hg-ext">notify</literal> configuration information.
 18.1212  	</para>
 18.1213  
 18.1214 -	<programlisting>&ch10-notify-config.lst;</programlisting>
 18.1215 -
 18.1216 -	<para>This will produce a message that looks like the
 18.1217 +	&ch10-notify-config.lst;
 18.1218 +
 18.1219 +	<para id="x_277">This will produce a message that looks like the
 18.1220  	  following:
 18.1221  	</para>
 18.1222  
 18.1223 -	<programlisting>&ch10-notify-config-mail.lst;</programlisting>
 18.1224 +	&ch10-notify-config-mail.lst;
 18.1225  
 18.1226        </sect3>
 18.1227        <sect3>
 18.1228  	<title>Testing and troubleshooting</title>
 18.1229  
 18.1230 -	<para>Do not forget that by default, the <literal
 18.1231 +	<para id="x_278">Do not forget that by default, the <literal
 18.1232  		role="hg-ext">notify</literal> extension <emphasis>will not
 18.1233  	  send any mail</emphasis> until you explicitly configure it to do so,
 18.1234  	  by setting <envar role="rc-item-notify">test</envar> to
 18.1235 @@ -1290,17 +1289,17 @@
 18.1236        </sect3>
 18.1237      </sect2>
 18.1238    </sect1>
 18.1239 -  <sect1 id="sec.hook.ref">
 18.1240 +  <sect1 id="sec:hook:ref">
 18.1241      <title>Information for writers of hooks</title>
 18.1242  
 18.1243      <sect2>
 18.1244        <title>In-process hook execution</title>
 18.1245  
 18.1246 -      <para>An in-process hook is called with arguments of the
 18.1247 +      <para id="x_279">An in-process hook is called with arguments of the
 18.1248  	following form:
 18.1249        </para>
 18.1250        <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting>
 18.1251 -      <para>The <literal>ui</literal> parameter is a <literal
 18.1252 +      <para id="x_27a">The <literal>ui</literal> parameter is a <literal
 18.1253  	  role="py-mod-mercurial.ui">ui</literal> object. The
 18.1254  	<literal>repo</literal> parameter is a <literal
 18.1255  	  role="py-mod-mercurial.localrepo">localrepository</literal>
 18.1256 @@ -1309,38 +1308,38 @@
 18.1257  	being invoked, with the following common features:
 18.1258        </para>
 18.1259        <itemizedlist>
 18.1260 -	<listitem><para>If a parameter is named
 18.1261 +	<listitem><para id="x_27b">If a parameter is named
 18.1262  	    <literal>node</literal> or <literal>parentN</literal>, it
 18.1263  	    will contain a hexadecimal changeset ID. The empty string
 18.1264  	    is used to represent <quote>null changeset ID</quote>
 18.1265  	    instead of a string of zeroes.
 18.1266  	  </para>
 18.1267  	</listitem>
 18.1268 -	<listitem><para>If a parameter is named
 18.1269 +	<listitem><para id="x_27c">If a parameter is named
 18.1270  	    <literal>url</literal>, it will contain the URL of a
 18.1271  	    remote repository, if that can be determined.
 18.1272  	  </para>
 18.1273  	</listitem>
 18.1274 -	<listitem><para>Boolean-valued parameters are represented as
 18.1275 +	<listitem><para id="x_27d">Boolean-valued parameters are represented as
 18.1276  	    Python <literal>bool</literal> objects.
 18.1277  	  </para>
 18.1278  	</listitem></itemizedlist>
 18.1279  
 18.1280 -      <para>An in-process hook is called without a change to the
 18.1281 +      <para id="x_27e">An in-process hook is called without a change to the
 18.1282  	process's working directory (unlike external hooks, which are
 18.1283  	run in the root of the repository).  It must not change the
 18.1284  	process's working directory, or it will cause any calls it
 18.1285  	makes into the Mercurial API to fail.
 18.1286        </para>
 18.1287  
 18.1288 -      <para>If a hook returns a boolean <quote>false</quote> value, it
 18.1289 +      <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it
 18.1290  	is considered to have succeeded.  If it returns a boolean
 18.1291  	<quote>true</quote> value or raises an exception, it is
 18.1292  	considered to have failed.  A useful way to think of the
 18.1293  	calling convention is <quote>tell me if you fail</quote>.
 18.1294        </para>
 18.1295  
 18.1296 -      <para>Note that changeset IDs are passed into Python hooks as
 18.1297 +      <para id="x_280">Note that changeset IDs are passed into Python hooks as
 18.1298  	hexadecimal strings, not the binary hashes that Mercurial's
 18.1299  	APIs normally use.  To convert a hash from hex to binary, use
 18.1300  	the <literal>bin</literal> function.
 18.1301 @@ -1350,7 +1349,7 @@
 18.1302      <sect2>
 18.1303        <title>External hook execution</title>
 18.1304  
 18.1305 -      <para>An external hook is passed to the shell of the user
 18.1306 +      <para id="x_281">An external hook is passed to the shell of the user
 18.1307  	running Mercurial. Features of that shell, such as variable
 18.1308  	substitution and command redirection, are available.  The hook
 18.1309  	is run in the root directory of the repository (unlike
 18.1310 @@ -1358,7 +1357,7 @@
 18.1311  	Mercurial was run in).
 18.1312        </para>
 18.1313  
 18.1314 -      <para>Hook parameters are passed to the hook as environment
 18.1315 +      <para id="x_282">Hook parameters are passed to the hook as environment
 18.1316  	variables.  Each environment variable's name is converted in
 18.1317  	upper case and prefixed with the string
 18.1318  	<quote><literal>HG_</literal></quote>.  For example, if the
 18.1319 @@ -1367,7 +1366,7 @@
 18.1320  	parameter will be <quote><literal>HG_NODE</literal></quote>.
 18.1321        </para>
 18.1322  
 18.1323 -      <para>A boolean parameter is represented as the string
 18.1324 +      <para id="x_283">A boolean parameter is represented as the string
 18.1325  	<quote><literal>1</literal></quote> for <quote>true</quote>,
 18.1326  	<quote><literal>0</literal></quote> for <quote>false</quote>.
 18.1327  	If an environment variable is named <envar>HG_NODE</envar>,
 18.1328 @@ -1379,7 +1378,7 @@
 18.1329  	URL of a remote repository, if that can be determined.
 18.1330        </para>
 18.1331  
 18.1332 -      <para>If a hook exits with a status of zero, it is considered to
 18.1333 +      <para id="x_284">If a hook exits with a status of zero, it is considered to
 18.1334  	have succeeded.  If it exits with a non-zero status, it is
 18.1335  	considered to have failed.
 18.1336        </para>
 18.1337 @@ -1388,7 +1387,7 @@
 18.1338      <sect2>
 18.1339        <title>Finding out where changesets come from</title>
 18.1340  
 18.1341 -      <para>A hook that involves the transfer of changesets between a
 18.1342 +      <para id="x_285">A hook that involves the transfer of changesets between a
 18.1343  	local repository and another may be able to find out
 18.1344  	information about the <quote>far side</quote>.  Mercurial
 18.1345  	knows <emphasis>how</emphasis> changes are being transferred,
 18.1346 @@ -1396,10 +1395,10 @@
 18.1347  	transferred to or from.
 18.1348        </para>
 18.1349  
 18.1350 -      <sect3 id="sec.hook.sources">
 18.1351 +      <sect3 id="sec:hook:sources">
 18.1352  	<title>Sources of changesets</title>
 18.1353  
 18.1354 -	<para>Mercurial will tell a hook what means are, or were, used
 18.1355 +	<para id="x_286">Mercurial will tell a hook what means are, or were, used
 18.1356  	  to transfer changesets between repositories.  This is
 18.1357  	  provided by Mercurial in a Python parameter named
 18.1358  	  <literal>source</literal>, or an environment variable named
 18.1359 @@ -1407,32 +1406,32 @@
 18.1360  	</para>
 18.1361  
 18.1362  	<itemizedlist>
 18.1363 -	  <listitem><para><literal>serve</literal>: Changesets are
 18.1364 +	  <listitem><para id="x_287"><literal>serve</literal>: Changesets are
 18.1365  	      transferred to or from a remote repository over http or
 18.1366  	      ssh.
 18.1367  	    </para>
 18.1368  	  </listitem>
 18.1369 -	  <listitem><para><literal>pull</literal>: Changesets are
 18.1370 +	  <listitem><para id="x_288"><literal>pull</literal>: Changesets are
 18.1371  	      being transferred via a pull from one repository into
 18.1372  	      another.
 18.1373  	    </para>
 18.1374  	  </listitem>
 18.1375 -	  <listitem><para><literal>push</literal>: Changesets are
 18.1376 +	  <listitem><para id="x_289"><literal>push</literal>: Changesets are
 18.1377  	      being transferred via a push from one repository into
 18.1378  	      another.
 18.1379  	    </para>
 18.1380  	  </listitem>
 18.1381 -	  <listitem><para><literal>bundle</literal>: Changesets are
 18.1382 +	  <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are
 18.1383  	      being transferred to or from a bundle.
 18.1384  	    </para>
 18.1385  	  </listitem></itemizedlist>
 18.1386  
 18.1387        </sect3>
 18.1388 -      <sect3 id="sec.hook.url">
 18.1389 +      <sect3 id="sec:hook:url">
 18.1390  	<title>Where changes are going&emdash;remote repository
 18.1391  	  URLs</title>
 18.1392  
 18.1393 -	<para>When possible, Mercurial will tell a hook the location
 18.1394 +	<para id="x_28b">When possible, Mercurial will tell a hook the location
 18.1395  	  of the <quote>far side</quote> of an activity that transfers
 18.1396  	  changeset data between repositories.  This is provided by
 18.1397  	  Mercurial in a Python parameter named
 18.1398 @@ -1440,26 +1439,26 @@
 18.1399  	  <envar>HG_URL</envar>.
 18.1400  	</para>
 18.1401  
 18.1402 -	<para>This information is not always known.  If a hook is
 18.1403 +	<para id="x_28c">This information is not always known.  If a hook is
 18.1404  	  invoked in a repository that is being served via http or
 18.1405  	  ssh, Mercurial cannot tell where the remote repository is,
 18.1406  	  but it may know where the client is connecting from.  In
 18.1407  	  such cases, the URL will take one of the following forms:
 18.1408  	</para>
 18.1409  	<itemizedlist>
 18.1410 -	  <listitem><para><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 
 18.1411 +	  <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 
 18.1412  	      ssh client, at the IP address
 18.1413  	      <literal>1.2.3.4</literal>.
 18.1414  	    </para>
 18.1415  	  </listitem>
 18.1416 -	  <listitem><para><literal>remote:http:1.2.3.4</literal>&emdash;remote 
 18.1417 +	  <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote 
 18.1418  	      http client, at the IP address
 18.1419  	      <literal>1.2.3.4</literal>.  If the client is using SSL,
 18.1420  	      this will be of the form
 18.1421  	      <literal>remote:https:1.2.3.4</literal>.
 18.1422  	    </para>
 18.1423  	  </listitem>
 18.1424 -	  <listitem><para>Empty&emdash;no information could be
 18.1425 +	  <listitem><para id="x_28f">Empty&emdash;no information could be
 18.1426  	      discovered about the remote client.
 18.1427  	    </para>
 18.1428  	  </listitem></itemizedlist>
 18.1429 @@ -1470,11 +1469,11 @@
 18.1430    <sect1>
 18.1431      <title>Hook reference</title>
 18.1432  
 18.1433 -    <sect2 id="sec.hook.changegroup">
 18.1434 +    <sect2 id="sec:hook:changegroup">
 18.1435        <title><literal role="hook">changegroup</literal>&emdash;after
 18.1436  	remote changesets added</title>
 18.1437  
 18.1438 -      <para>This hook is run after a group of pre-existing changesets
 18.1439 +      <para id="x_290">This hook is run after a group of pre-existing changesets
 18.1440  	has been added to the repository, for example via a <command
 18.1441  	  role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg
 18.1442  	  unbundle</command>.  This hook is run once per operation
 18.1443 @@ -1484,16 +1483,16 @@
 18.1444  	arrive in a group.
 18.1445        </para>
 18.1446  
 18.1447 -      <para>Some possible uses for this hook include kicking off an
 18.1448 +      <para id="x_291">Some possible uses for this hook include kicking off an
 18.1449  	automated build or test of the added changesets, updating a
 18.1450  	bug database, or notifying subscribers that a repository
 18.1451  	contains new changes.
 18.1452        </para>
 18.1453  
 18.1454 -      <para>Parameters to this hook:
 18.1455 +      <para id="x_292">Parameters to this hook:
 18.1456        </para>
 18.1457        <itemizedlist>
 18.1458 -	<listitem><para><literal>node</literal>: A changeset ID.  The
 18.1459 +	<listitem><para id="x_293"><literal>node</literal>: A changeset ID.  The
 18.1460  	    changeset ID of the first changeset in the group that was
 18.1461  	    added.  All changesets between this and
 18.1462  	    <literal role="tag">tip</literal>, inclusive, were added by a single
 18.1463 @@ -1502,130 +1501,131 @@
 18.1464  	      role="hg-cmd">hg unbundle</command>.
 18.1465  	  </para>
 18.1466  	</listitem>
 18.1467 -	<listitem><para><literal>source</literal>: A string.  The
 18.1468 -	    source of these changes.  See section <xref
 18.1469 -	      linkend="sec.hook.sources"/> for details.
 18.1470 -	  </para>
 18.1471 -	</listitem>
 18.1472 -	<listitem><para><literal>url</literal>: A URL.  The location
 18.1473 -	    of the remote repository, if known.  See section <xref
 18.1474 -	      linkend="sec.hook.url"/> for more
 18.1475 -	    information.
 18.1476 +	<listitem><para id="x_294"><literal>source</literal>: A
 18.1477 +	    string.  The source of these changes.  See <xref
 18.1478 +	      linkend="sec:hook:sources"/> for details.
 18.1479 +	  </para>
 18.1480 +	</listitem>
 18.1481 +	<listitem><para id="x_295"><literal>url</literal>: A URL.  The
 18.1482 +	    location of the remote repository, if known.  See <xref
 18.1483 +	      linkend="sec:hook:url"/> for more information.
 18.1484  	  </para>
 18.1485  	</listitem></itemizedlist>
 18.1486  
 18.1487 -      <para>See also: <literal role="hook">incoming</literal> (section
 18.1488 -	<xref linkend="sec.hook.incoming"/>), <literal
 18.1489 -	  role="hook">prechangegroup</literal> (section <xref
 18.1490 -	  linkend="sec.hook.prechangegroup"/>), <literal
 18.1491 -	  role="hook">pretxnchangegroup</literal> (section <xref
 18.1492 -	  linkend="sec.hook.pretxnchangegroup"/>)
 18.1493 -      </para>
 18.1494 -
 18.1495 -    </sect2>
 18.1496 -    <sect2 id="sec.hook.commit">
 18.1497 +      <para id="x_296">See also: <literal
 18.1498 +	  role="hook">incoming</literal> (<xref
 18.1499 +	  linkend="sec:hook:incoming"/>), <literal
 18.1500 +	  role="hook">prechangegroup</literal> (<xref
 18.1501 +	  linkend="sec:hook:prechangegroup"/>), <literal
 18.1502 +	  role="hook">pretxnchangegroup</literal> (<xref
 18.1503 +	  linkend="sec:hook:pretxnchangegroup"/>)
 18.1504 +      </para>
 18.1505 +
 18.1506 +    </sect2>
 18.1507 +    <sect2 id="sec:hook:commit">
 18.1508        <title><literal role="hook">commit</literal>&emdash;after a new
 18.1509  	changeset is created</title>
 18.1510  
 18.1511 -      <para>This hook is run after a new changeset has been created.
 18.1512 -      </para>
 18.1513 -
 18.1514 -      <para>Parameters to this hook:
 18.1515 +      <para id="x_297">This hook is run after a new changeset has been created.
 18.1516 +      </para>
 18.1517 +
 18.1518 +      <para id="x_298">Parameters to this hook:
 18.1519        </para>
 18.1520        <itemizedlist>
 18.1521 -	<listitem><para><literal>node</literal>: A changeset ID.  The
 18.1522 +	<listitem><para id="x_299"><literal>node</literal>: A changeset ID.  The
 18.1523  	    changeset ID of the newly committed changeset.
 18.1524  	  </para>
 18.1525  	</listitem>
 18.1526 -	<listitem><para><literal>parent1</literal>: A changeset ID.
 18.1527 +	<listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID.
 18.1528  	    The changeset ID of the first parent of the newly
 18.1529  	    committed changeset.
 18.1530  	  </para>
 18.1531  	</listitem>
 18.1532 -	<listitem><para><literal>parent2</literal>: A changeset ID.
 18.1533 +	<listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID.
 18.1534  	    The changeset ID of the second parent of the newly
 18.1535  	    committed changeset.
 18.1536  	  </para>
 18.1537  	</listitem></itemizedlist>
 18.1538  
 18.1539 -      <para>See also: <literal role="hook">precommit</literal>
 18.1540 -	(section <xref linkend="sec.hook.precommit"/>), <literal
 18.1541 -	  role="hook">pretxncommit</literal> (section <xref
 18.1542 -	  linkend="sec.hook.pretxncommit"/>)
 18.1543 -      </para>
 18.1544 -
 18.1545 -    </sect2>
 18.1546 -    <sect2 id="sec.hook.incoming">
 18.1547 +      <para id="x_29c">See also: <literal
 18.1548 +	  role="hook">precommit</literal> (<xref
 18.1549 +	  linkend="sec:hook:precommit"/>), <literal
 18.1550 +	  role="hook">pretxncommit</literal> (<xref
 18.1551 +	  linkend="sec:hook:pretxncommit"/>)
 18.1552 +      </para>
 18.1553 +
 18.1554 +    </sect2>
 18.1555 +    <sect2 id="sec:hook:incoming">
 18.1556        <title><literal role="hook">incoming</literal>&emdash;after one
 18.1557  	remote changeset is added</title>
 18.1558  
 18.1559 -      <para>This hook is run after a pre-existing changeset has been
 18.1560 +      <para id="x_29d">This hook is run after a pre-existing changeset has been
 18.1561  	added to the repository, for example via a <command
 18.1562  	  role="hg-cmd">hg push</command>.  If a group of changesets
 18.1563  	was added in a single operation, this hook is called once for
 18.1564  	each added changeset.
 18.1565        </para>
 18.1566  
 18.1567 -      <para>You can use this hook for the same purposes as the
 18.1568 -	<literal role="hook">changegroup</literal> hook (section <xref
 18.1569 -	  linkend="sec.hook.changegroup"/>); it's simply
 18.1570 -	more convenient sometimes to run a hook once per group of
 18.1571 +      <para id="x_29e">You can use this hook for the same purposes as
 18.1572 +	the <literal role="hook">changegroup</literal> hook (<xref
 18.1573 +	  linkend="sec:hook:changegroup"/>); it's simply more
 18.1574 +	convenient sometimes to run a hook once per group of
 18.1575  	changesets, while other times it's handier once per changeset.
 18.1576        </para>
 18.1577  
 18.1578 -      <para>Parameters to this hook:
 18.1579 +      <para id="x_29f">Parameters to this hook:
 18.1580        </para>
 18.1581        <itemizedlist>
 18.1582 -	<listitem><para><literal>node</literal>: A changeset ID.  The
 18.1583 +	<listitem><para id="x_2a0"><literal>node</literal>: A changeset ID.  The
 18.1584  	    ID of the newly added changeset.
 18.1585  	  </para>
 18.1586  	</listitem>
 18.1587 -	<listitem><para><literal>source</literal>: A string.  The
 18.1588 -	    source of these changes.  See section <xref
 18.1589 -	      linkend="sec.hook.sources"/> for details.
 18.1590 -	  </para>
 18.1591 -	</listitem>
 18.1592 -	<listitem><para><literal>url</literal>: A URL.  The location
 18.1593 -	    of the remote repository, if known.  See section <xref
 18.1594 -	      linkend="sec.hook.url"/> for more
 18.1595 -	    information.
 18.1596 +	<listitem><para id="x_2a1"><literal>source</literal>: A
 18.1597 +	    string.  The source of these changes.  See <xref
 18.1598 +	      linkend="sec:hook:sources"/> for details.
 18.1599 +	  </para>
 18.1600 +	</listitem>
 18.1601 +	<listitem><para id="x_2a2"><literal>url</literal>: A URL.  The
 18.1602 +	    location of the remote repository, if known.  See <xref
 18.1603 +	      linkend="sec:hook:url"/> for more information.
 18.1604  	  </para>
 18.1605  	</listitem></itemizedlist>
 18.1606  
 18.1607 -      <para>See also: <literal role="hook">changegroup</literal>
 18.1608 -	(section <xref linkend="sec.hook.changegroup"/>) <literal
 18.1609 -	  role="hook">prechangegroup</literal> (section <xref
 18.1610 -	  linkend="sec.hook.prechangegroup"/>), <literal
 18.1611 -	  role="hook">pretxnchangegroup</literal> (section <xref
 18.1612 -	  linkend="sec.hook.pretxnchangegroup"/>)
 18.1613 -      </para>
 18.1614 -
 18.1615 -    </sect2>
 18.1616 -    <sect2 id="sec.hook.outgoing">
 18.1617 +      <para id="x_2a3">See also: <literal
 18.1618 +	  role="hook">changegroup</literal> (<xref
 18.1619 +	  linkend="sec:hook:changegroup"/>) <literal
 18.1620 +	  role="hook">prechangegroup</literal> (<xref
 18.1621 +	  linkend="sec:hook:prechangegroup"/>), <literal
 18.1622 +	  role="hook">pretxnchangegroup</literal> (<xref
 18.1623 +	  linkend="sec:hook:pretxnchangegroup"/>)
 18.1624 +      </para>
 18.1625 +
 18.1626 +    </sect2>
 18.1627 +    <sect2 id="sec:hook:outgoing">
 18.1628        <title><literal role="hook">outgoing</literal>&emdash;after
 18.1629  	changesets are propagated</title>
 18.1630  
 18.1631 -      <para>This hook is run after a group of changesets has been
 18.1632 +      <para id="x_2a4">This hook is run after a group of changesets has been
 18.1633  	propagated out of this repository, for example by a <command
 18.1634  	  role="hg-cmd">hg push</command> or <command role="hg-cmd">hg
 18.1635  	  bundle</command> command.
 18.1636        </para>
 18.1637  
 18.1638 -      <para>One possible use for this hook is to notify administrators
 18.1639 +      <para id="x_2a5">One possible use for this hook is to notify administrators
 18.1640  	that changes have been pulled.
 18.1641        </para>
 18.1642  
 18.1643 -      <para>Parameters to this hook:
 18.1644 +      <para id="x_2a6">Parameters to this hook:
 18.1645        </para>
 18.1646        <itemizedlist>
 18.1647 -	<listitem><para><literal>node</literal>: A changeset ID.  The
 18.1648 +	<listitem><para id="x_2a7"><literal>node</literal>: A changeset ID.  The
 18.1649  	    changeset ID of the first changeset of the group that was
 18.1650  	    sent.
 18.1651  	  </para>
 18.1652  	</listitem>
 18.1653 -	<listitem><para><literal>source</literal>: A string.  The
 18.1654 -	    source of the of the operation (see section <xref
 18.1655 -	      linkend="sec.hook.sources"/>).  If a remote
 18.1656 +	<listitem><para id="x_2a8"><literal>source</literal>: A string.  The
 18.1657 +	    source of the of the operation (see <xref
 18.1658 +	      linkend="sec:hook:sources"/>).  If a remote
 18.1659  	    client pulled changes from this repository,
 18.1660  	    <literal>source</literal> will be
 18.1661  	    <literal>serve</literal>.  If the client that obtained
 18.1662 @@ -1636,187 +1636,187 @@
 18.1663  	    client performed.
 18.1664  	  </para>
 18.1665  	</listitem>
 18.1666 -	<listitem><para><literal>url</literal>: A URL.  The location
 18.1667 -	    of the remote repository, if known.  See section <xref
 18.1668 -	      linkend="sec.hook.url"/> for more
 18.1669 -	    information.
 18.1670 +	<listitem><para id="x_2a9"><literal>url</literal>: A URL.  The
 18.1671 +	    location of the remote repository, if known.  See <xref
 18.1672 +	      linkend="sec:hook:url"/> for more information.
 18.1673  	  </para>
 18.1674  	</listitem></itemizedlist>
 18.1675  
 18.1676 -      <para>See also: <literal role="hook">preoutgoing</literal>
 18.1677 -	(section <xref linkend="sec.hook.preoutgoing"/>)
 18.1678 -      </para>
 18.1679 -
 18.1680 -    </sect2>
 18.1681 -    <sect2 id="sec.hook.prechangegroup">
 18.1682 +      <para id="x_2aa">See also: <literal
 18.1683 +	  role="hook">preoutgoing</literal> (<xref
 18.1684 +	  linkend="sec:hook:preoutgoing"/>)
 18.1685 +      </para>
 18.1686 +
 18.1687 +    </sect2>
 18.1688 +    <sect2 id="sec:hook:prechangegroup">
 18.1689        <title><literal
 18.1690  	  role="hook">prechangegroup</literal>&emdash;before starting
 18.1691  	to add remote changesets</title>
 18.1692  
 18.1693 -      <para>This controlling hook is run before Mercurial begins to
 18.1694 +      <para id="x_2ab">This controlling hook is run before Mercurial begins to
 18.1695  	add a group of changesets from another repository.
 18.1696        </para>
 18.1697  
 18.1698 -      <para>This hook does not have any information about the
 18.1699 +      <para id="x_2ac">This hook does not have any information about the
 18.1700  	changesets to be added, because it is run before transmission
 18.1701  	of those changesets is allowed to begin.  If this hook fails,
 18.1702  	the changesets will not be transmitted.
 18.1703        </para>
 18.1704  
 18.1705 -      <para>One use for this hook is to prevent external changes from
 18.1706 +      <para id="x_2ad">One use for this hook is to prevent external changes from
 18.1707  	being added to a repository.  For example, you could use this
 18.1708  	to <quote>freeze</quote> a server-hosted branch temporarily or
 18.1709  	permanently so that users cannot push to it, while still
 18.1710  	allowing a local administrator to modify the repository.
 18.1711        </para>
 18.1712  
 18.1713 -      <para>Parameters to this hook:
 18.1714 +      <para id="x_2ae">Parameters to this hook:
 18.1715        </para>
 18.1716        <itemizedlist>
 18.1717 -	<listitem><para><literal>source</literal>: A string.  The
 18.1718 -	    source of these changes.  See section <xref
 18.1719 -	      linkend="sec.hook.sources"/> for details.
 18.1720 -	  </para>
 18.1721 -	</listitem>
 18.1722 -	<listitem><para><literal>url</literal>: A URL.  The location
 18.1723 -	    of the remote repository, if known.  See section <xref
 18.1724 -	      linkend="sec.hook.url"/> for more
 18.1725 -	    information.
 18.1726 +	<listitem><para id="x_2af"><literal>source</literal>: A string.  The
 18.1727 +	    source of these changes.  See <xref
 18.1728 +	      linkend="sec:hook:sources"/> for details.
 18.1729 +	  </para>
 18.1730 +	</listitem>
 18.1731 +	<listitem><para id="x_2b0"><literal>url</literal>: A URL.  The
 18.1732 +	    location of the remote repository, if known.  See <xref
 18.1733 +	      linkend="sec:hook:url"/> for more information.
 18.1734  	  </para>
 18.1735  	</listitem></itemizedlist>
 18.1736  
 18.1737 -      <para>See also: <literal role="hook">changegroup</literal>
 18.1738 -	(section <xref linkend="sec.hook.changegroup"/>), <literal
 18.1739 -	  role="hook">incoming</literal> (section <xref
 18.1740 -	  linkend="sec.hook.incoming"/>), , <literal
 18.1741 -	  role="hook">pretxnchangegroup</literal> (section <xref
 18.1742 -	  linkend="sec.hook.pretxnchangegroup"/>)
 18.1743 -      </para>
 18.1744 -
 18.1745 -    </sect2>
 18.1746 -    <sect2 id="sec.hook.precommit">
 18.1747 +      <para id="x_2b1">See also: <literal
 18.1748 +	  role="hook">changegroup</literal> (<xref
 18.1749 +	  linkend="sec:hook:changegroup"/>), <literal
 18.1750 +	  role="hook">incoming</literal> (<xref
 18.1751 +	  linkend="sec:hook:incoming"/>), <literal
 18.1752 +	  role="hook">pretxnchangegroup</literal> (<xref
 18.1753 +	  linkend="sec:hook:pretxnchangegroup"/>)
 18.1754 +      </para>
 18.1755 +
 18.1756 +    </sect2>
 18.1757 +    <sect2 id="sec:hook:precommit">
 18.1758        <title><literal role="hook">precommit</literal>&emdash;before
 18.1759  	starting to commit a changeset</title>
 18.1760  
 18.1761 -      <para>This hook is run before Mercurial begins to commit a new
 18.1762 +      <para id="x_2b2">This hook is run before Mercurial begins to commit a new
 18.1763  	changeset. It is run before Mercurial has any of the metadata
 18.1764  	for the commit, such as the files to be committed, the commit
 18.1765  	message, or the commit date.
 18.1766        </para>
 18.1767  
 18.1768 -      <para>One use for this hook is to disable the ability to commit
 18.1769 +      <para id="x_2b3">One use for this hook is to disable the ability to commit
 18.1770  	new changesets, while still allowing incoming changesets.
 18.1771  	Another is to run a build or test, and only allow the commit
 18.1772  	to begin if the build or test succeeds.
 18.1773        </para>
 18.1774  
 18.1775 -      <para>Parameters to this hook:
 18.1776 +      <para id="x_2b4">Parameters to this hook:
 18.1777        </para>
 18.1778        <itemizedlist>
 18.1779 -	<listitem><para><literal>parent1</literal>: A changeset ID.
 18.1780 +	<listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID.
 18.1781  	    The changeset ID of the first parent of the working
 18.1782  	    directory.
 18.1783  	  </para>
 18.1784  	</listitem>
 18.1785 -	<listitem><para><literal>parent2</literal>: A changeset ID.
 18.1786 +	<listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID.
 18.1787  	    The changeset ID of the second parent of the working
 18.1788  	    directory.
 18.1789  	  </para>
 18.1790  	</listitem></itemizedlist>
 18.1791 -      <para>If the commit proceeds, the parents of the working
 18.1792 +      <para id="x_2b7">If the commit proceeds, the parents of the working
 18.1793  	directory will become the parents of the new changeset.
 18.1794        </para>
 18.1795  
 18.1796 -      <para>See also: <literal role="hook">commit</literal> (section
 18.1797 -	<xref linkend="sec.hook.commit"/>), <literal
 18.1798 -	  role="hook">pretxncommit</literal> (section <xref
 18.1799 -	  linkend="sec.hook.pretxncommit"/>)
 18.1800 -      </para>
 18.1801 -
 18.1802 -    </sect2>
 18.1803 -    <sect2 id="sec.hook.preoutgoing">
 18.1804 +      <para id="x_2b8">See also: <literal role="hook">commit</literal>
 18.1805 +	(<xref linkend="sec:hook:commit"/>), <literal
 18.1806 +	  role="hook">pretxncommit</literal> (<xref
 18.1807 +	  linkend="sec:hook:pretxncommit"/>)
 18.1808 +      </para>
 18.1809 +
 18.1810 +    </sect2>
 18.1811 +    <sect2 id="sec:hook:preoutgoing">
 18.1812        <title><literal role="hook">preoutgoing</literal>&emdash;before
 18.1813  	starting to propagate changesets</title>
 18.1814  
 18.1815 -      <para>This hook is invoked before Mercurial knows the identities
 18.1816 +      <para id="x_2b9">This hook is invoked before Mercurial knows the identities
 18.1817  	of the changesets to be transmitted.
 18.1818        </para>
 18.1819  
 18.1820 -      <para>One use for this hook is to prevent changes from being
 18.1821 +      <para id="x_2ba">One use for this hook is to prevent changes from being
 18.1822  	transmitted to another repository.
 18.1823        </para>
 18.1824  
 18.1825 -      <para>Parameters to this hook:
 18.1826 +      <para id="x_2bb">Parameters to this hook:
 18.1827        </para>
 18.1828        <itemizedlist>
 18.1829 -	<listitem><para><literal>source</literal>: A string.  The
 18.1830 -	    source of the operation that is attempting to obtain
 18.1831 -	    changes from this repository (see section <xref
 18.1832 -	      linkend="sec.hook.sources"/>).  See the documentation
 18.1833 +	<listitem><para id="x_2bc"><literal>source</literal>: A
 18.1834 +	    string.  The source of the operation that is attempting to
 18.1835 +	    obtain changes from this repository (see <xref
 18.1836 +	      linkend="sec:hook:sources"/>).  See the documentation
 18.1837  	    for the <literal>source</literal> parameter to the
 18.1838 -	    <literal role="hook">outgoing</literal> hook, in section
 18.1839 -	    <xref linkend="sec.hook.outgoing"/>, for possible values
 18.1840 -	    of
 18.1841 -	    this parameter.
 18.1842 -	  </para>
 18.1843 -	</listitem>
 18.1844 -	<listitem><para><literal>url</literal>: A URL.  The location
 18.1845 -	    of the remote repository, if known.  See section <xref
 18.1846 -	      linkend="sec.hook.url"/> for more
 18.1847 -	    information.
 18.1848 +	    <literal role="hook">outgoing</literal> hook, in
 18.1849 +	    <xref linkend="sec:hook:outgoing"/>, for possible values
 18.1850 +	    of this parameter.
 18.1851 +	  </para>
 18.1852 +	</listitem>
 18.1853 +	<listitem><para id="x_2bd"><literal>url</literal>: A URL.  The
 18.1854 +	    location of the remote repository, if known.  See <xref
 18.1855 +	      linkend="sec:hook:url"/> for more information.
 18.1856  	  </para>
 18.1857  	</listitem></itemizedlist>
 18.1858  
 18.1859 -      <para>See also: <literal role="hook">outgoing</literal> (section
 18.1860 -	<xref linkend="sec.hook.outgoing"/>)
 18.1861 -      </para>
 18.1862 -
 18.1863 -    </sect2>
 18.1864 -    <sect2 id="sec.hook.pretag">
 18.1865 +      <para id="x_2be">See also: <literal
 18.1866 +	  role="hook">outgoing</literal> (<xref
 18.1867 +	  linkend="sec:hook:outgoing"/>)
 18.1868 +      </para>
 18.1869 +
 18.1870 +    </sect2>
 18.1871 +    <sect2 id="sec:hook:pretag">
 18.1872        <title><literal role="hook">pretag</literal>&emdash;before
 18.1873  	tagging a changeset</title>
 18.1874  
 18.1875 -      <para>This controlling hook is run before a tag is created.  If
 18.1876 +      <para id="x_2bf">This controlling hook is run before a tag is created.  If
 18.1877  	the hook succeeds, creation of the tag proceeds.  If the hook
 18.1878  	fails, the tag is not created.
 18.1879        </para>
 18.1880  
 18.1881 -      <para>Parameters to this hook:
 18.1882 +      <para id="x_2c0">Parameters to this hook:
 18.1883        </para>
 18.1884        <itemizedlist>
 18.1885 -	<listitem><para><literal>local</literal>: A boolean.  Whether
 18.1886 +	<listitem><para id="x_2c1"><literal>local</literal>: A boolean.  Whether
 18.1887  	    the tag is local to this repository instance (i.e. stored
 18.1888  	    in <filename role="special">.hg/localtags</filename>) or
 18.1889  	    managed by Mercurial (stored in <filename
 18.1890  	      role="special">.hgtags</filename>).
 18.1891  	  </para>
 18.1892  	</listitem>
 18.1893 -	<listitem><para><literal>node</literal>: A changeset ID.  The
 18.1894 +	<listitem><para id="x_2c2"><literal>node</literal>: A changeset ID.  The
 18.1895  	    ID of the changeset to be tagged.
 18.1896  	  </para>
 18.1897  	</listitem>
 18.1898 -	<listitem><para><literal>tag</literal>: A string.  The name of
 18.1899 +	<listitem><para id="x_2c3"><literal>tag</literal>: A string.  The name of
 18.1900  	    the tag to be created.
 18.1901  	  </para>
 18.1902  	</listitem></itemizedlist>
 18.1903  
 18.1904 -      <para>If the tag to be created is revision-controlled, the
 18.1905 -	<literal role="hook">precommit</literal> and <literal
 18.1906 -	  role="hook">pretxncommit</literal> hooks (sections <xref
 18.1907 -	  linkend="sec.hook.commit"/> and <xref
 18.1908 -	  linkend="sec.hook.pretxncommit"/>) will also be run.
 18.1909 -      </para>
 18.1910 -
 18.1911 -      <para>See also: <literal role="hook">tag</literal> (section
 18.1912 -	<xref linkend="sec.hook.tag"/>)
 18.1913 -      </para>
 18.1914 -    </sect2>
 18.1915 -    <sect2 id="sec.hook.pretxnchangegroup">
 18.1916 +      <para id="x_2c4">If the tag to be created is
 18.1917 +	revision-controlled, the <literal
 18.1918 +	  role="hook">precommit</literal> and <literal
 18.1919 +	  role="hook">pretxncommit</literal> hooks (<xref
 18.1920 +	  linkend="sec:hook:commit"/> and <xref
 18.1921 +	  linkend="sec:hook:pretxncommit"/>) will also be run.
 18.1922 +      </para>
 18.1923 +
 18.1924 +      <para id="x_2c5">See also: <literal role="hook">tag</literal>
 18.1925 +	(<xref linkend="sec:hook:tag"/>)
 18.1926 +      </para>
 18.1927 +    </sect2>
 18.1928 +    <sect2 id="sec:hook:pretxnchangegroup">
 18.1929        <title><literal
 18.1930  	  role="hook">pretxnchangegroup</literal>&emdash;before
 18.1931  	completing addition of remote changesets</title>
 18.1932  
 18.1933 -      <para>This controlling hook is run before a
 18.1934 +      <para id="x_2c6">This controlling hook is run before a
 18.1935  	transaction&emdash;that manages the addition of a group of new
 18.1936  	changesets from outside the repository&emdash;completes.  If
 18.1937  	the hook succeeds, the transaction completes, and all of the
 18.1938 @@ -1825,28 +1825,28 @@
 18.1939  	the changesets is erased.
 18.1940        </para>
 18.1941  
 18.1942 -      <para>This hook can access the metadata associated with the
 18.1943 +      <para id="x_2c7">This hook can access the metadata associated with the
 18.1944  	almost-added changesets, but it should not do anything
 18.1945  	permanent with this data. It must also not modify the working
 18.1946  	directory.
 18.1947        </para>
 18.1948  
 18.1949 -      <para>While this hook is running, if other Mercurial processes
 18.1950 +      <para id="x_2c8">While this hook is running, if other Mercurial processes
 18.1951  	access this repository, they will be able to see the
 18.1952  	almost-added changesets as if they are permanent.  This may
 18.1953  	lead to race conditions if you do not take steps to avoid
 18.1954  	them.
 18.1955        </para>
 18.1956  
 18.1957 -      <para>This hook can be used to automatically vet a group of
 18.1958 +      <para id="x_2c9">This hook can be used to automatically vet a group of
 18.1959  	changesets.  If the hook fails, all of the changesets are
 18.1960  	<quote>rejected</quote> when the transaction rolls back.
 18.1961        </para>
 18.1962  
 18.1963 -      <para>Parameters to this hook:
 18.1964 +      <para id="x_2ca">Parameters to this hook:
 18.1965        </para>
 18.1966        <itemizedlist>
 18.1967 -	<listitem><para><literal>node</literal>: A changeset ID.  The
 18.1968 +	<listitem><para id="x_2cb"><literal>node</literal>: A changeset ID.  The
 18.1969  	    changeset ID of the first changeset in the group that was
 18.1970  	    added.  All changesets between this and
 18.1971  	    <literal role="tag">tip</literal>,
 18.1972 @@ -1856,32 +1856,32 @@
 18.1973  	      role="hg-cmd">hg unbundle</command>.
 18.1974  	  </para>
 18.1975  	</listitem>
 18.1976 -	<listitem><para><literal>source</literal>: A string.  The
 18.1977 -	    source of these changes.  See section <xref
 18.1978 -	      linkend="sec.hook.sources"/> for details.
 18.1979 -	  </para>
 18.1980 -	</listitem>
 18.1981 -	<listitem><para><literal>url</literal>: A URL.  The location
 18.1982 -	    of the remote repository, if known.  See section <xref
 18.1983 -	      linkend="sec.hook.url"/> for more
 18.1984 -	    information.
 18.1985 +	<listitem><para id="x_2cc"><literal>source</literal>: A
 18.1986 +	    string.  The source of these changes.  See <xref
 18.1987 +	      linkend="sec:hook:sources"/> for details.
 18.1988 +	  </para>
 18.1989 +	</listitem>
 18.1990 +	<listitem><para id="x_2cd"><literal>url</literal>: A URL.  The
 18.1991 +	    location of the remote repository, if known.  See <xref
 18.1992 +	      linkend="sec:hook:url"/> for more information.
 18.1993  	  </para>
 18.1994  	</listitem></itemizedlist>
 18.1995  
 18.1996 -      <para>See also: <literal role="hook">changegroup</literal>
 18.1997 -	(section <xref linkend="sec.hook.changegroup"/>), <literal
 18.1998 -	  role="hook">incoming</literal> (section <xref
 18.1999 -	  linkend="sec.hook.incoming"/>), <literal
 18.2000 -	  role="hook">prechangegroup</literal> (section <xref
 18.2001 -	  linkend="sec.hook.prechangegroup"/>)
 18.2002 -      </para>
 18.2003 -
 18.2004 -    </sect2>
 18.2005 -    <sect2 id="sec.hook.pretxncommit">
 18.2006 +      <para id="x_2ce">See also: <literal
 18.2007 +	  role="hook">changegroup</literal> (<xref
 18.2008 +	  linkend="sec:hook:changegroup"/>), <literal
 18.2009 +	  role="hook">incoming</literal> (<xref
 18.2010 +	  linkend="sec:hook:incoming"/>), <literal
 18.2011 +	  role="hook">prechangegroup</literal> (<xref
 18.2012 +	  linkend="sec:hook:prechangegroup"/>)
 18.2013 +      </para>
 18.2014 +
 18.2015 +    </sect2>
 18.2016 +    <sect2 id="sec:hook:pretxncommit">
 18.2017        <title><literal role="hook">pretxncommit</literal>&emdash;before
 18.2018  	completing commit of new changeset</title>
 18.2019  
 18.2020 -      <para>This controlling hook is run before a
 18.2021 +      <para id="x_2cf">This controlling hook is run before a
 18.2022  	transaction&emdash;that manages a new commit&emdash;completes.
 18.2023  	If the hook succeeds, the transaction completes and the
 18.2024  	changeset becomes permanent within this repository.  If the
 18.2025 @@ -1889,84 +1889,85 @@
 18.2026  	data is erased.
 18.2027        </para>
 18.2028  
 18.2029 -      <para>This hook can access the metadata associated with the
 18.2030 +      <para id="x_2d0">This hook can access the metadata associated with the
 18.2031  	almost-new changeset, but it should not do anything permanent
 18.2032  	with this data.  It must also not modify the working
 18.2033  	directory.
 18.2034        </para>
 18.2035  
 18.2036 -      <para>While this hook is running, if other Mercurial processes
 18.2037 +      <para id="x_2d1">While this hook is running, if other Mercurial processes
 18.2038  	access this repository, they will be able to see the
 18.2039  	almost-new changeset as if it is permanent.  This may lead to
 18.2040  	race conditions if you do not take steps to avoid them.
 18.2041        </para>
 18.2042  
 18.2043 -      <para>Parameters to this hook:
 18.2044 +      <para id="x_2d2">Parameters to this hook:
 18.2045        </para>
 18.2046        <itemizedlist>
 18.2047 -	<listitem><para><literal>node</literal>: A changeset ID.  The
 18.2048 +	<listitem><para id="x_2d3"><literal>node</literal>: A changeset ID.  The
 18.2049  	    changeset ID of the newly committed changeset.
 18.2050  	  </para>
 18.2051  	</listitem>
 18.2052 -	<listitem><para><literal>parent1</literal>: A changeset ID.
 18.2053 +	<listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID.
 18.2054  	    The changeset ID of the first parent of the newly
 18.2055  	    committed changeset.
 18.2056  	  </para>
 18.2057  	</listitem>
 18.2058 -	<listitem><para><literal>parent2</literal>: A changeset ID.
 18.2059 +	<listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID.
 18.2060  	    The changeset ID of the second parent of the newly
 18.2061  	    committed changeset.
 18.2062  	  </para>
 18.2063  	</listitem></itemizedlist>
 18.2064  
 18.2065 -      <para>See also: <literal role="hook">precommit</literal>
 18.2066 -	(section <xref linkend="sec.hook.precommit"/>)
 18.2067 -      </para>
 18.2068 -
 18.2069 -    </sect2>
 18.2070 -    <sect2 id="sec.hook.preupdate">
 18.2071 +      <para id="x_2d6">See also: <literal
 18.2072 +	  role="hook">precommit</literal> (<xref
 18.2073 +	  linkend="sec:hook:precommit"/>)
 18.2074 +      </para>
 18.2075 +
 18.2076 +    </sect2>
 18.2077 +    <sect2 id="sec:hook:preupdate">
 18.2078        <title><literal role="hook">preupdate</literal>&emdash;before
 18.2079  	updating or merging working directory</title>
 18.2080  
 18.2081 -      <para>This controlling hook is run before an update or merge of
 18.2082 -	the working directory begins.  It is run only if Mercurial's
 18.2083 -	normal pre-update checks determine that the update or merge
 18.2084 -	can proceed.  If the hook succeeds, the update or merge may
 18.2085 -	proceed; if it fails, the update or merge does not start.
 18.2086 -      </para>
 18.2087 -
 18.2088 -      <para>Parameters to this hook:
 18.2089 +      <para id="x_2d7">This controlling hook is run before an update
 18.2090 +	or merge of the working directory begins.  It is run only if
 18.2091 +	Mercurial's normal pre-update checks determine that the update
 18.2092 +	or merge can proceed.  If the hook succeeds, the update or
 18.2093 +	merge may proceed; if it fails, the update or merge does not
 18.2094 +	start.
 18.2095 +      </para>
 18.2096 +
 18.2097 +      <para id="x_2d8">Parameters to this hook:
 18.2098        </para>
 18.2099        <itemizedlist>
 18.2100 -	<listitem><para><literal>parent1</literal>: A changeset ID.
 18.2101 -	    The ID of the parent that the working directory is to be
 18.2102 -	    updated to.  If the working directory is being merged, it
 18.2103 -	    will not change this parent.
 18.2104 -	  </para>
 18.2105 -	</listitem>
 18.2106 -	<listitem><para><literal>parent2</literal>: A changeset ID.
 18.2107 -	    Only set if the working directory is being merged.  The ID
 18.2108 -	    of the revision that the working directory is being merged
 18.2109 -	    with.
 18.2110 +	<listitem><para id="x_2d9"><literal>parent1</literal>: A
 18.2111 +	    changeset ID. The ID of the parent that the working
 18.2112 +	    directory is to be updated to.  If the working directory
 18.2113 +	    is being merged, it will not change this parent.
 18.2114 +	  </para>
 18.2115 +	</listitem>
 18.2116 +	<listitem><para id="x_2da"><literal>parent2</literal>: A
 18.2117 +	    changeset ID. Only set if the working directory is being
 18.2118 +	    merged.  The ID of the revision that the working directory
 18.2119 +	    is being merged with.
 18.2120  	  </para>
 18.2121  	</listitem></itemizedlist>
 18.2122  
 18.2123 -      <para>See also: <literal role="hook">update</literal> (section
 18.2124 -	<xref linkend="sec.hook.update"/>)
 18.2125 -      </para>
 18.2126 -
 18.2127 -    </sect2>
 18.2128 -    <sect2 id="sec.hook.tag">
 18.2129 +      <para id="x_2db">See also: <literal role="hook">update</literal>
 18.2130 +	(<xref linkend="sec:hook:update"/>)</para>
 18.2131 +
 18.2132 +    </sect2>
 18.2133 +    <sect2 id="sec:hook:tag">
 18.2134        <title><literal role="hook">tag</literal>&emdash;after tagging a
 18.2135  	changeset</title>
 18.2136  
 18.2137 -      <para>This hook is run after a tag has been created.
 18.2138 -      </para>
 18.2139 -
 18.2140 -      <para>Parameters to this hook:
 18.2141 +      <para id="x_2dc">This hook is run after a tag has been created.
 18.2142 +      </para>
 18.2143 +
 18.2144 +      <para id="x_2dd">Parameters to this hook:
 18.2145        </para>
 18.2146        <itemizedlist>
 18.2147 -	<listitem><para><literal>local</literal>: A boolean.  Whether
 18.2148 +	<listitem><para id="x_2de"><literal>local</literal>: A boolean.  Whether
 18.2149  	    the new tag is local to this repository instance (i.e.
 18.2150  	    stored in <filename
 18.2151  	      role="special">.hg/localtags</filename>) or managed by
 18.2152 @@ -1974,30 +1975,30 @@
 18.2153  	      role="special">.hgtags</filename>).
 18.2154  	  </para>
 18.2155  	</listitem>
 18.2156 -	<listitem><para><literal>node</literal>: A changeset ID.  The
 18.2157 +	<listitem><para id="x_2df"><literal>node</literal>: A changeset ID.  The
 18.2158  	    ID of the changeset that was tagged.
 18.2159  	  </para>
 18.2160  	</listitem>
 18.2161 -	<listitem><para><literal>tag</literal>: A string.  The name of
 18.2162 +	<listitem><para id="x_2e0"><literal>tag</literal>: A string.  The name of
 18.2163  	    the tag that was created.
 18.2164  	  </para>
 18.2165  	</listitem></itemizedlist>
 18.2166  
 18.2167 -      <para>If the created tag is revision-controlled, the <literal
 18.2168 +      <para id="x_2e1">If the created tag is revision-controlled, the <literal
 18.2169  	  role="hook">commit</literal> hook (section <xref
 18.2170 -	  linkend="sec.hook.commit"/>) is run before this hook.
 18.2171 -      </para>
 18.2172 -
 18.2173 -      <para>See also: <literal role="hook">pretag</literal> (section
 18.2174 -	<xref linkend="sec.hook.pretag"/>)
 18.2175 -      </para>
 18.2176 -
 18.2177 -    </sect2>
 18.2178 -    <sect2 id="sec.hook.update">
 18.2179 +	  linkend="sec:hook:commit"/>) is run before this hook.
 18.2180 +      </para>
 18.2181 +
 18.2182 +      <para id="x_2e2">See also: <literal role="hook">pretag</literal>
 18.2183 +	(<xref linkend="sec:hook:pretag"/>)
 18.2184 +      </para>
 18.2185 +
 18.2186 +    </sect2>
 18.2187 +    <sect2 id="sec:hook:update">
 18.2188        <title><literal role="hook">update</literal>&emdash;after
 18.2189  	updating or merging working directory</title>
 18.2190  
 18.2191 -      <para>This hook is run after an update or merge of the working
 18.2192 +      <para id="x_2e3">This hook is run after an update or merge of the working
 18.2193  	directory completes.  Since a merge can fail (if the external
 18.2194  	<command>hgmerge</command> command fails to resolve conflicts
 18.2195  	in a file), this hook communicates whether the update or merge
 18.2196 @@ -2005,25 +2006,25 @@
 18.2197        </para>
 18.2198  
 18.2199        <itemizedlist>
 18.2200 -	<listitem><para><literal>error</literal>: A boolean.
 18.2201 +	<listitem><para id="x_2e4"><literal>error</literal>: A boolean.
 18.2202  	    Indicates whether the update or merge completed
 18.2203  	    successfully.
 18.2204  	  </para>
 18.2205  	</listitem>
 18.2206 -	<listitem><para><literal>parent1</literal>: A changeset ID.
 18.2207 +	<listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID.
 18.2208  	    The ID of the parent that the working directory was
 18.2209  	    updated to.  If the working directory was merged, it will
 18.2210  	    not have changed this parent.
 18.2211  	  </para>
 18.2212  	</listitem>
 18.2213 -	<listitem><para><literal>parent2</literal>: A changeset ID.
 18.2214 +	<listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID.
 18.2215  	    Only set if the working directory was merged.  The ID of
 18.2216  	    the revision that the working directory was merged with.
 18.2217  	  </para>
 18.2218  	</listitem></itemizedlist>
 18.2219  
 18.2220 -      <para>See also: <literal role="hook">preupdate</literal>
 18.2221 -	(section <xref linkend="sec.hook.preupdate"/>)
 18.2222 +      <para id="x_2e7">See also: <literal role="hook">preupdate</literal>
 18.2223 +	(<xref linkend="sec:hook:preupdate"/>)
 18.2224        </para>
 18.2225  
 18.2226      </sect2>