1.1 --- a/en/ch13-hgext.xml	Fri Mar 20 16:43:35 2009 +0800
     1.2 +++ b/en/ch13-hgext.xml	Mon Mar 30 16:23:33 2009 +0800
     1.3 @@ -1,27 +1,27 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter id="chap.hgext">
     1.7 +<chapter id="chap:hgext">
     1.8    <?dbhtml filename="adding-functionality-with-extensions.html"?>
     1.9    <title>Adding functionality with extensions</title>
    1.10  
    1.11 -  <para>While the core of Mercurial is quite complete from a
    1.12 +  <para id="x_4fe">While the core of Mercurial is quite complete from a
    1.13      functionality standpoint, it's deliberately shorn of fancy
    1.14      features.  This approach of preserving simplicity keeps the
    1.15      software easy to deal with for both maintainers and users.</para>
    1.16  
    1.17 -  <para>However, Mercurial doesn't box you in with an inflexible
    1.18 +  <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible
    1.19      command set: you can add features to it as
    1.20      <emphasis>extensions</emphasis> (sometimes known as
    1.21      <emphasis>plugins</emphasis>).  We've already discussed a few of
    1.22      these extensions in earlier chapters.</para>
    1.23    <itemizedlist>
    1.24 -    <listitem><para>Section <xref linkend="sec.tour-merge.fetch"/>
    1.25 +    <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/>
    1.26  	covers the <literal role="hg-ext">fetch</literal> extension;
    1.27  	this combines pulling new changes and merging them with local
    1.28  	changes into a single command, <command
    1.29  	  role="hg-ext-fetch">fetch</command>.</para>
    1.30      </listitem>
    1.31 -    <listitem><para>In chapter <xref linkend="chap.hook"/>, we covered
    1.32 +    <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered
    1.33  	several extensions that are useful for hook-related
    1.34  	functionality: <literal role="hg-ext">acl</literal> adds
    1.35  	access control lists; <literal
    1.36 @@ -30,36 +30,36 @@
    1.37  	  role="hg-ext">notify</literal> sends notification emails on
    1.38  	new changes.</para>
    1.39      </listitem>
    1.40 -    <listitem><para>The Mercurial Queues patch management extension is
    1.41 +    <listitem><para id="x_502">The Mercurial Queues patch management extension is
    1.42  	so invaluable that it merits two chapters and an appendix all
    1.43 -	to itself. Chapter <xref linkend="chap.mq"/> covers the
    1.44 -	basics; chapter <xref
    1.45 -	  linkend="chap.mq-collab"/> discusses advanced topics;
    1.46 -	and appendix <xref linkend="chap.mqref"/> goes into detail on
    1.47 +	to itself. <xref linkend="chap:mq"/> covers the
    1.48 +	basics; <xref
    1.49 +	  linkend="chap:mq-collab"/> discusses advanced topics;
    1.50 +	and <xref linkend="chap:mqref"/> goes into detail on
    1.51  	each
    1.52  	command.</para>
    1.53      </listitem></itemizedlist>
    1.54  
    1.55 -  <para>In this chapter, we'll cover some of the other extensions that
    1.56 +  <para id="x_503">In this chapter, we'll cover some of the other extensions that
    1.57      are available for Mercurial, and briefly touch on some of the
    1.58      machinery you'll need to know about if you want to write an
    1.59      extension of your own.</para>
    1.60    <itemizedlist>
    1.61 -    <listitem><para>In section <xref linkend="sec.hgext.inotify"/>,
    1.62 +    <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>,
    1.63  	we'll discuss the possibility of <emphasis>huge</emphasis>
    1.64  	performance improvements using the <literal
    1.65  	  role="hg-ext">inotify</literal> extension.</para>
    1.66      </listitem></itemizedlist>
    1.67  
    1.68 -  <sect1 id="sec.hgext.inotify">
    1.69 +  <sect1 id="sec:hgext:inotify">
    1.70      <title>Improve performance with the <literal
    1.71  	role="hg-ext">inotify</literal> extension</title>
    1.72  
    1.73 -    <para>Are you interested in having some of the most common
    1.74 +    <para id="x_505">Are you interested in having some of the most common
    1.75        Mercurial operations run as much as a hundred times faster?
    1.76        Read on!</para>
    1.77  
    1.78 -    <para>Mercurial has great performance under normal circumstances.
    1.79 +    <para id="x_506">Mercurial has great performance under normal circumstances.
    1.80        For example, when you run the <command role="hg-cmd">hg
    1.81  	status</command> command, Mercurial has to scan almost every
    1.82        directory and file in your repository so that it can display
    1.83 @@ -69,7 +69,7 @@
    1.84        machinery to avoid doing an expensive comparison operation on
    1.85        files that obviously haven't changed.</para>
    1.86  
    1.87 -    <para>Because obtaining file status is crucial to good
    1.88 +    <para id="x_507">Because obtaining file status is crucial to good
    1.89        performance, the authors of Mercurial have optimised this code
    1.90        to within an inch of its life.  However, there's no avoiding the
    1.91        fact that when you run <command role="hg-cmd">hg
    1.92 @@ -79,20 +79,20 @@
    1.93        checked.  For a sufficiently large repository, this can take a
    1.94        long time.</para>
    1.95  
    1.96 -    <para>To put a number on the magnitude of this effect, I created a
    1.97 +    <para id="x_508">To put a number on the magnitude of this effect, I created a
    1.98        repository containing 150,000 managed files.  I timed <command
    1.99  	role="hg-cmd">hg status</command> as taking ten seconds to
   1.100        run, even when <emphasis>none</emphasis> of those files had been
   1.101        modified.</para>
   1.102  
   1.103 -    <para>Many modern operating systems contain a file notification
   1.104 +    <para id="x_509">Many modern operating systems contain a file notification
   1.105        facility. If a program signs up to an appropriate service, the
   1.106        operating system will notify it every time a file of interest is
   1.107        created, modified, or deleted.  On Linux systems, the kernel
   1.108        component that does this is called
   1.109        <literal>inotify</literal>.</para>
   1.110  
   1.111 -    <para>Mercurial's <literal role="hg-ext">inotify</literal>
   1.112 +    <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal>
   1.113        extension talks to the kernel's <literal>inotify</literal>
   1.114        component to optimise <command role="hg-cmd">hg status</command>
   1.115        commands.  The extension has two components.  A daemon sits in
   1.116 @@ -105,29 +105,29 @@
   1.117        with a result instantaneously, avoiding the need to scan every
   1.118        directory and file in the repository.</para>
   1.119  
   1.120 -    <para>Recall the ten seconds that I measured plain Mercurial as
   1.121 +    <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as
   1.122        taking to run <command role="hg-cmd">hg status</command> on a
   1.123        150,000 file repository.  With the <literal
   1.124  	role="hg-ext">inotify</literal> extension enabled, the time
   1.125        dropped to 0.1 seconds, a factor of <emphasis>one
   1.126  	hundred</emphasis> faster.</para>
   1.127  
   1.128 -    <para>Before we continue, please pay attention to some
   1.129 +    <para id="x_50c">Before we continue, please pay attention to some
   1.130        caveats.</para>
   1.131      <itemizedlist>
   1.132 -      <listitem><para>The <literal role="hg-ext">inotify</literal>
   1.133 +      <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal>
   1.134  	  extension is Linux-specific.  Because it interfaces directly
   1.135  	  to the Linux kernel's <literal>inotify</literal> subsystem,
   1.136  	  it does not work on other operating systems.</para>
   1.137        </listitem>
   1.138 -      <listitem><para>It should work on any Linux distribution that
   1.139 +      <listitem><para id="x_50e">It should work on any Linux distribution that
   1.140  	  was released after early 2005.  Older distributions are
   1.141  	  likely to have a kernel that lacks
   1.142  	  <literal>inotify</literal>, or a version of
   1.143  	  <literal>glibc</literal> that does not have the necessary
   1.144  	  interfacing support.</para>
   1.145        </listitem>
   1.146 -      <listitem><para>Not all filesystems are suitable for use with
   1.147 +      <listitem><para id="x_50f">Not all filesystems are suitable for use with
   1.148  	  the <literal role="hg-ext">inotify</literal> extension.
   1.149  	  Network filesystems such as NFS are a non-starter, for
   1.150  	  example, particularly if you're running Mercurial on several
   1.151 @@ -138,40 +138,40 @@
   1.152  	  fine.</para>
   1.153        </listitem></itemizedlist>
   1.154  
   1.155 -    <para>The <literal role="hg-ext">inotify</literal> extension is
   1.156 +    <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is
   1.157        not yet shipped with Mercurial as of May 2007, so it's a little
   1.158        more involved to set up than other extensions.  But the
   1.159        performance improvement is worth it!</para>
   1.160  
   1.161 -    <para>The extension currently comes in two parts: a set of patches
   1.162 +    <para id="x_511">The extension currently comes in two parts: a set of patches
   1.163        to the Mercurial source code, and a library of Python bindings
   1.164        to the <literal>inotify</literal> subsystem.</para>
   1.165      <note>
   1.166 -      <para>  There are <emphasis>two</emphasis> Python
   1.167 +      <para id="x_512">  There are <emphasis>two</emphasis> Python
   1.168  	<literal>inotify</literal> binding libraries.  One of them is
   1.169  	called <literal>pyinotify</literal>, and is packaged by some
   1.170  	Linux distributions as <literal>python-inotify</literal>.
   1.171  	This is <emphasis>not</emphasis> the one you'll need, as it is
   1.172  	too buggy and inefficient to be practical.</para>
   1.173      </note>
   1.174 -    <para>To get going, it's best to already have a functioning copy
   1.175 +    <para id="x_513">To get going, it's best to already have a functioning copy
   1.176        of Mercurial installed.</para>
   1.177      <note>
   1.178 -      <para>  If you follow the instructions below, you'll be
   1.179 +      <para id="x_514">  If you follow the instructions below, you'll be
   1.180  	<emphasis>replacing</emphasis> and overwriting any existing
   1.181  	installation of Mercurial that you might already have, using
   1.182  	the latest <quote>bleeding edge</quote> Mercurial code. Don't
   1.183  	say you weren't warned!</para>
   1.184      </note>
   1.185      <orderedlist>
   1.186 -      <listitem><para>Clone the Python <literal>inotify</literal>
   1.187 +      <listitem><para id="x_515">Clone the Python <literal>inotify</literal>
   1.188  	  binding repository.  Build and install it.</para>
   1.189  	<programlisting>hg clone http://hg.kublai.com/python/inotify
   1.190  cd inotify
   1.191  python setup.py build --force
   1.192  sudo python setup.py install --skip-build</programlisting>
   1.193        </listitem>
   1.194 -      <listitem><para>Clone the <filename
   1.195 +      <listitem><para id="x_516">Clone the <filename
   1.196  	    class="directory">crew</filename> Mercurial repository.
   1.197  	  Clone the <literal role="hg-ext">inotify</literal> patch
   1.198  	  repository so that Mercurial Queues will be able to apply
   1.199 @@ -181,13 +181,13 @@
   1.200  hg clone crew inotify
   1.201  hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting>
   1.202        </listitem>
   1.203 -      <listitem><para>Make sure that you have the Mercurial Queues
   1.204 +      <listitem><para id="x_517">Make sure that you have the Mercurial Queues
   1.205  	  extension, <literal role="hg-ext">mq</literal>, enabled.  If
   1.206 -	  you've never used MQ, read section <xref
   1.207 -	    linkend="sec.mq.start"/> to get started
   1.208 +	  you've never used MQ, read <xref
   1.209 +	    linkend="sec:mq:start"/> to get started
   1.210  	  quickly.</para>
   1.211        </listitem>
   1.212 -      <listitem><para>Go into the <filename
   1.213 +      <listitem><para id="x_518">Go into the <filename
   1.214  	    class="directory">inotify</filename> repo, and apply all
   1.215  	  of the <literal role="hg-ext">inotify</literal> patches
   1.216  	  using the <option role="hg-ext-mq-cmd-qpush-opt">hg
   1.217 @@ -196,28 +196,28 @@
   1.218  	<programlisting>cd inotify
   1.219  hg qpush -a</programlisting>
   1.220        </listitem>
   1.221 -      <listitem><para>  If you get an error message from <command
   1.222 +      <listitem><para id="x_519">  If you get an error message from <command
   1.223  	    role="hg-ext-mq">qpush</command>, you should not continue.
   1.224  	  Instead, ask for help.</para>
   1.225        </listitem>
   1.226 -      <listitem><para>Build and install the patched version of
   1.227 +      <listitem><para id="x_51a">Build and install the patched version of
   1.228  	  Mercurial.</para>
   1.229  	<programlisting>python setup.py build --force
   1.230  sudo python setup.py install --skip-build</programlisting>
   1.231        </listitem>
   1.232      </orderedlist>
   1.233 -    <para>Once you've build a suitably patched version of Mercurial,
   1.234 +    <para id="x_51b">Once you've build a suitably patched version of Mercurial,
   1.235        all you need to do to enable the <literal
   1.236  	role="hg-ext">inotify</literal> extension is add an entry to
   1.237        your <filename role="special">~/.hgrc</filename>.</para>
   1.238      <programlisting>[extensions] inotify =</programlisting>
   1.239 -    <para>When the <literal role="hg-ext">inotify</literal> extension
   1.240 +    <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension
   1.241        is enabled, Mercurial will automatically and transparently start
   1.242        the status daemon the first time you run a command that needs
   1.243        status in a repository.  It runs one status daemon per
   1.244        repository.</para>
   1.245  
   1.246 -    <para>The status daemon is started silently, and runs in the
   1.247 +    <para id="x_51d">The status daemon is started silently, and runs in the
   1.248        background.  If you look at a list of running processes after
   1.249        you've enabled the <literal role="hg-ext">inotify</literal>
   1.250        extension and run a few commands in different repositories,
   1.251 @@ -225,7 +225,7 @@
   1.252        around, waiting for updates from the kernel and queries from
   1.253        Mercurial.</para>
   1.254  
   1.255 -    <para>The first time you run a Mercurial command in a repository
   1.256 +    <para id="x_51e">The first time you run a Mercurial command in a repository
   1.257        when you have the <literal role="hg-ext">inotify</literal>
   1.258        extension enabled, it will run with about the same performance
   1.259        as a normal Mercurial command.  This is because the status
   1.260 @@ -239,14 +239,14 @@
   1.261        status operations almost instantaneous on repositories of all
   1.262        sizes!</para>
   1.263  
   1.264 -    <para>If you like, you can manually start a status daemon using
   1.265 +    <para id="x_51f">If you like, you can manually start a status daemon using
   1.266        the <command role="hg-ext-inotify">inserve</command> command.
   1.267        This gives you slightly finer control over how the daemon ought
   1.268        to run.  This command will of course only be available when the
   1.269        <literal role="hg-ext">inotify</literal> extension is
   1.270        enabled.</para>
   1.271  
   1.272 -    <para>When you're using the <literal
   1.273 +    <para id="x_520">When you're using the <literal
   1.274  	role="hg-ext">inotify</literal> extension, you should notice
   1.275        <emphasis>no difference at all</emphasis> in Mercurial's
   1.276        behaviour, with the sole exception of status-related commands
   1.277 @@ -256,28 +256,28 @@
   1.278        these situations occurs, please report a bug.</para>
   1.279  
   1.280    </sect1>
   1.281 -  <sect1 id="sec.hgext.extdiff">
   1.282 +  <sect1 id="sec:hgext:extdiff">
   1.283      <title>Flexible diff support with the <literal
   1.284  	role="hg-ext">extdiff</literal> extension</title>
   1.285  
   1.286 -    <para>Mercurial's built-in <command role="hg-cmd">hg
   1.287 +    <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg
   1.288  	diff</command> command outputs plaintext unified diffs.</para>
   1.289  
   1.290      &interaction.extdiff.diff;
   1.291  
   1.292 -    <para>If you would like to use an external tool to display
   1.293 +    <para id="x_522">If you would like to use an external tool to display
   1.294        modifications, you'll want to use the <literal
   1.295  	role="hg-ext">extdiff</literal> extension.  This will let you
   1.296        use, for example, a graphical diff tool.</para>
   1.297  
   1.298 -    <para>The <literal role="hg-ext">extdiff</literal> extension is
   1.299 +    <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is
   1.300        bundled with Mercurial, so it's easy to set up.  In the <literal
   1.301  	role="rc-extensions">extensions</literal> section of your
   1.302        <filename role="special">~/.hgrc</filename>, simply add a
   1.303        one-line entry to enable the extension.</para>
   1.304      <programlisting>[extensions]
   1.305  extdiff =</programlisting>
   1.306 -    <para>This introduces a command named <command
   1.307 +    <para id="x_524">This introduces a command named <command
   1.308  	role="hg-ext-extdiff">extdiff</command>, which by default uses
   1.309        your system's <command>diff</command> command to generate a
   1.310        unified diff in the same form as the built-in <command
   1.311 @@ -285,12 +285,12 @@
   1.312      
   1.313      &interaction.extdiff.extdiff;
   1.314  
   1.315 -    <para>The result won't be exactly the same as with the built-in
   1.316 +    <para id="x_525">The result won't be exactly the same as with the built-in
   1.317        <command role="hg-cmd">hg diff</command> variations, because the
   1.318        output of <command>diff</command> varies from one system to
   1.319        another, even when passed the same options.</para>
   1.320  
   1.321 -    <para>As the <quote><literal>making snapshot</literal></quote>
   1.322 +    <para id="x_526">As the <quote><literal>making snapshot</literal></quote>
   1.323        lines of output above imply, the <command
   1.324  	role="hg-ext-extdiff">extdiff</command> command works by
   1.325        creating two snapshots of your source tree.  The first snapshot
   1.326 @@ -303,7 +303,7 @@
   1.327        directories and files that have changed between the two
   1.328        revisions.</para>
   1.329  
   1.330 -    <para>Snapshot directory names have the same base name as your
   1.331 +    <para id="x_527">Snapshot directory names have the same base name as your
   1.332        repository. If your repository path is <filename
   1.333  	class="directory">/quux/bar/foo</filename>, then <filename
   1.334  	class="directory">foo</filename> will be the name of each
   1.335 @@ -319,7 +319,7 @@
   1.336        that the diff has the snapshot directory names embedded in its
   1.337        header.</para>
   1.338  
   1.339 -    <para>The <command role="hg-ext-extdiff">extdiff</command> command
   1.340 +    <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command
   1.341        accepts two important options. The <option
   1.342  	role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option
   1.343        lets you choose a program to view differences with, instead of
   1.344 @@ -336,7 +336,7 @@
   1.345        and arguments to specify the revisions you want, the files you
   1.346        want, and so on.</para>
   1.347  
   1.348 -    <para>As an example, here's how to run the normal system
   1.349 +    <para id="x_529">As an example, here's how to run the normal system
   1.350        <command>diff</command> command, getting it to generate context
   1.351        diffs (using the <option role="cmd-opt-diff">-c</option> option)
   1.352        instead of unified diffs, and five lines of context instead of
   1.353 @@ -345,28 +345,28 @@
   1.354  
   1.355        &interaction.extdiff.extdiff-ctx;
   1.356  
   1.357 -    <para>Launching a visual diff tool is just as easy.  Here's how to
   1.358 +    <para id="x_52a">Launching a visual diff tool is just as easy.  Here's how to
   1.359        launch the <command>kdiff3</command> viewer.</para>
   1.360      <programlisting>hg extdiff -p kdiff3 -o</programlisting>
   1.361  
   1.362 -    <para>If your diff viewing command can't deal with directories,
   1.363 +    <para id="x_52b">If your diff viewing command can't deal with directories,
   1.364        you can easily work around this with a little scripting.  For an
   1.365        example of such scripting in action with the <literal
   1.366  	role="hg-ext">mq</literal> extension and the
   1.367 -      <command>interdiff</command> command, see section <xref
   1.368 -	linkend="mq-collab.tips.interdiff"/>.</para>
   1.369 +      <command>interdiff</command> command, see <xref
   1.370 +	linkend="mq-collab:tips:interdiff"/>.</para>
   1.371  
   1.372      <sect2>
   1.373        <title>Defining command aliases</title>
   1.374  
   1.375 -      <para>It can be cumbersome to remember the options to both the
   1.376 +      <para id="x_52c">It can be cumbersome to remember the options to both the
   1.377  	<command role="hg-ext-extdiff">extdiff</command> command and
   1.378  	the diff viewer you want to use, so the <literal
   1.379  	  role="hg-ext">extdiff</literal> extension lets you define
   1.380  	<emphasis>new</emphasis> commands that will invoke your diff
   1.381  	viewer with exactly the right options.</para>
   1.382  
   1.383 -      <para>All you need to do is edit your <filename
   1.384 +      <para id="x_52d">All you need to do is edit your <filename
   1.385  	  role="special">~/.hgrc</filename>, and add a section named
   1.386  	<literal role="rc-extdiff">extdiff</literal>.  Inside this
   1.387  	section, you can define multiple commands.  Here's how to add
   1.388 @@ -376,7 +376,7 @@
   1.389  	will run <command>kdiff3</command> for you.</para>
   1.390        <programlisting>[extdiff]
   1.391  cmd.kdiff3 =</programlisting>
   1.392 -      <para>If you leave the right hand side of the definition empty,
   1.393 +      <para id="x_52e">If you leave the right hand side of the definition empty,
   1.394  	as above, the <literal role="hg-ext">extdiff</literal>
   1.395  	extension uses the name of the command you defined as the name
   1.396  	of the external program to run.  But these names don't have to
   1.397 @@ -386,7 +386,7 @@
   1.398        <programlisting>[extdiff]
   1.399   cmd.wibble = kdiff3</programlisting>
   1.400  
   1.401 -      <para>You can also specify the default options that you want to
   1.402 +      <para id="x_52f">You can also specify the default options that you want to
   1.403  	invoke your diff viewing program with.  The prefix to use is
   1.404  	<quote><literal>opts.</literal></quote>, followed by the name
   1.405  	of the command to which the options apply.  This example
   1.406 @@ -399,18 +399,18 @@
   1.407  
   1.408      </sect2>
   1.409    </sect1>
   1.410 -  <sect1 id="sec.hgext.transplant">
   1.411 +  <sect1 id="sec:hgext:transplant">
   1.412      <title>Cherrypicking changes with the <literal
   1.413  	role="hg-ext">transplant</literal> extension</title>
   1.414  
   1.415 -    <para>Need to have a long chat with Brendan about this.</para>
   1.416 +    <para id="x_530">Need to have a long chat with Brendan about this.</para>
   1.417  
   1.418    </sect1>
   1.419 -  <sect1 id="sec.hgext.patchbomb">
   1.420 +  <sect1 id="sec:hgext:patchbomb">
   1.421      <title>Send changes via email with the <literal
   1.422  	role="hg-ext">patchbomb</literal> extension</title>
   1.423  
   1.424 -    <para>Many projects have a culture of <quote>change
   1.425 +    <para id="x_531">Many projects have a culture of <quote>change
   1.426  	review</quote>, in which people send their modifications to a
   1.427        mailing list for others to read and comment on before they
   1.428        commit the final version to a shared repository.  Some projects
   1.429 @@ -418,7 +418,7 @@
   1.430        other people to a repository to which those others don't have
   1.431        access.</para>
   1.432  
   1.433 -    <para>Mercurial makes it easy to send changes over email for
   1.434 +    <para id="x_532">Mercurial makes it easy to send changes over email for
   1.435        review or application, via its <literal
   1.436  	role="hg-ext">patchbomb</literal> extension.  The extension is
   1.437        so named because changes are formatted as patches, and it's usual
   1.438 @@ -426,17 +426,17 @@
   1.439        of changes by email is thus much like <quote>bombing</quote> the
   1.440        recipient's inbox, hence <quote>patchbomb</quote>.</para>
   1.441  
   1.442 -    <para>As usual, the basic configuration of the <literal
   1.443 +    <para id="x_533">As usual, the basic configuration of the <literal
   1.444  	role="hg-ext">patchbomb</literal> extension takes just one or
   1.445        two lines in your <filename role="special">
   1.446  	/.hgrc</filename>.</para>
   1.447      <programlisting>[extensions]
   1.448  patchbomb =</programlisting>
   1.449 -    <para>Once you've enabled the extension, you will have a new
   1.450 +    <para id="x_534">Once you've enabled the extension, you will have a new
   1.451        command available, named <command
   1.452  	role="hg-ext-patchbomb">email</command>.</para>
   1.453  
   1.454 -    <para>The safest and best way to invoke the <command
   1.455 +    <para id="x_535">The safest and best way to invoke the <command
   1.456  	role="hg-ext-patchbomb">email</command> command is to
   1.457        <emphasis>always</emphasis> run it first with the <option
   1.458  	role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option.
   1.459 @@ -447,12 +447,12 @@
   1.460  	role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option
   1.461        removed.</para>
   1.462  
   1.463 -    <para>The <command role="hg-ext-patchbomb">email</command> command
   1.464 +    <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command
   1.465        accepts the same kind of revision syntax as every other
   1.466        Mercurial command.  For example, this command will send every
   1.467        revision between 7 and <literal>tip</literal>, inclusive.</para>
   1.468      <programlisting>hg email -n 7:tip</programlisting>
   1.469 -    <para>You can also specify a <emphasis>repository</emphasis> to
   1.470 +    <para id="x_537">You can also specify a <emphasis>repository</emphasis> to
   1.471        compare with.  If you provide a repository but no revisions, the
   1.472        <command role="hg-ext-patchbomb">email</command> command will
   1.473        send all revisions in the local repository that are not present
   1.474 @@ -461,7 +461,7 @@
   1.475  	role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option),
   1.476        this will constrain the revisions sent.</para>
   1.477  
   1.478 -    <para>It's perfectly safe to run the <command
   1.479 +    <para id="x_538">It's perfectly safe to run the <command
   1.480  	role="hg-ext-patchbomb">email</command> command without the
   1.481        names of the people you want to send to: if you do this, it will
   1.482        just prompt you for those values interactively.  (If you're
   1.483 @@ -469,12 +469,12 @@
   1.484        <literal>readline</literal>-style editing capabilities when
   1.485        entering those headers, too, which is useful.)</para>
   1.486  
   1.487 -    <para>When you are sending just one revision, the <command
   1.488 +    <para id="x_539">When you are sending just one revision, the <command
   1.489  	role="hg-ext-patchbomb">email</command> command will by
   1.490        default use the first line of the changeset description as the
   1.491        subject of the single email message it sends.</para>
   1.492  
   1.493 -    <para>If you send multiple revisions, the <command
   1.494 +    <para id="x_53a">If you send multiple revisions, the <command
   1.495  	role="hg-ext-patchbomb">email</command> command will usually
   1.496        send one message per changeset.  It will preface the series with
   1.497        an introductory message, in which you should describe the
   1.498 @@ -483,39 +483,39 @@
   1.499      <sect2>
   1.500        <title>Changing the behaviour of patchbombs</title>
   1.501  
   1.502 -      <para>Not every project has exactly the same conventions for
   1.503 +      <para id="x_53b">Not every project has exactly the same conventions for
   1.504  	sending changes in email; the <literal
   1.505  	  role="hg-ext">patchbomb</literal> extension tries to
   1.506  	accommodate a number of variations through command line
   1.507  	options.</para>
   1.508        <itemizedlist>
   1.509 -	<listitem><para>You can write a subject for the introductory
   1.510 +	<listitem><para id="x_53c">You can write a subject for the introductory
   1.511  	    message on the command line using the <option
   1.512  	      role="hg-ext-patchbomb-cmd-email-opt">hg -s</option>
   1.513  	    option.  This takes one argument, the text of the subject
   1.514  	    to use.</para>
   1.515  	</listitem>
   1.516 -	<listitem><para>To change the email address from which the
   1.517 +	<listitem><para id="x_53d">To change the email address from which the
   1.518  	    messages originate, use the <option
   1.519  	      role="hg-ext-patchbomb-cmd-email-opt">hg -f</option>
   1.520  	    option.  This takes one argument, the email address to
   1.521  	    use.</para>
   1.522  	</listitem>
   1.523 -	<listitem><para>The default behaviour is to send unified diffs
   1.524 -	    (see section <xref linkend="sec.mq.patch"/> for a
   1.525 +	<listitem><para id="x_53e">The default behaviour is to send unified diffs
   1.526 +	    (see <xref linkend="sec:mq:patch"/> for a
   1.527  	    description of the
   1.528  	    format), one per message.  You can send a binary bundle
   1.529  	    instead with the <option
   1.530  	      role="hg-ext-patchbomb-cmd-email-opt">hg -b</option>
   1.531  	    option.</para>
   1.532  	</listitem>
   1.533 -	<listitem><para>Unified diffs are normally prefaced with a
   1.534 +	<listitem><para id="x_53f">Unified diffs are normally prefaced with a
   1.535  	    metadata header.  You can omit this, and send unadorned
   1.536  	    diffs, with the <option
   1.537  	      role="hg-ext-patchbomb-cmd-email-opt">hg
   1.538  	      --plain</option> option.</para>
   1.539  	</listitem>
   1.540 -	<listitem><para>Diffs are normally sent <quote>inline</quote>,
   1.541 +	<listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>,
   1.542  	    in the same body part as the description of a patch.  This
   1.543  	    makes it easiest for the largest number of readers to
   1.544  	    quote and respond to parts of a diff, as some mail clients
   1.545 @@ -525,14 +525,14 @@
   1.546  	      role="hg-ext-patchbomb-cmd-email-opt">hg -a</option>
   1.547  	    option.</para>
   1.548  	</listitem>
   1.549 -	<listitem><para>Instead of sending mail messages, you can
   1.550 +	<listitem><para id="x_541">Instead of sending mail messages, you can
   1.551  	    write them to an <literal>mbox</literal>-format mail
   1.552  	    folder using the <option
   1.553  	      role="hg-ext-patchbomb-cmd-email-opt">hg -m</option>
   1.554  	    option.  That option takes one argument, the name of the
   1.555  	    file to write to.</para>
   1.556  	</listitem>
   1.557 -	<listitem><para>If you would like to add a
   1.558 +	<listitem><para id="x_542">If you would like to add a
   1.559  	    <command>diffstat</command>-format summary to each patch,
   1.560  	    and one to the introductory message, use the <option
   1.561  	      role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>