diff en/ch13-hgext.xml @ 683:c838b3975bc6

Add IDs to paragraphs.

--- a/en/ch13-hgext.xml	Thu Mar 19 20:54:12 2009 -0700
+++ b/en/ch13-hgext.xml	Thu Mar 19 21:18:52 2009 -0700
@@ -4,24 +4,24 @@
   <?dbhtml filename="adding-functionality-with-extensions.html"?>
   <title>Adding functionality with extensions</title>
 
-  <para>While the core of Mercurial is quite complete from a
+  <para id="x_4fe">While the core of Mercurial is quite complete from a
     functionality standpoint, it's deliberately shorn of fancy
     features.  This approach of preserving simplicity keeps the
     software easy to deal with for both maintainers and users.</para>
 
-  <para>However, Mercurial doesn't box you in with an inflexible
+  <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible
     command set: you can add features to it as
     <emphasis>extensions</emphasis> (sometimes known as
     <emphasis>plugins</emphasis>).  We've already discussed a few of
     these extensions in earlier chapters.</para>
   <itemizedlist>
-    <listitem><para>Section <xref linkend="sec:tour-merge:fetch"/>
+    <listitem><para id="x_500">Section <xref linkend="sec:tour-merge:fetch"/>
 	covers the <literal role="hg-ext">fetch</literal> extension;
 	this combines pulling new changes and merging them with local
 	changes into a single command, <command
 	  role="hg-ext-fetch">fetch</command>.</para>
     </listitem>
-    <listitem><para>In chapter <xref linkend="chap:hook"/>, we covered
+    <listitem><para id="x_501">In chapter <xref linkend="chap:hook"/>, we covered
 	several extensions that are useful for hook-related
 	functionality: <literal role="hg-ext">acl</literal> adds
 	access control lists; <literal
@@ -30,7 +30,7 @@
 	  role="hg-ext">notify</literal> sends notification emails on
 	new changes.</para>
     </listitem>
-    <listitem><para>The Mercurial Queues patch management extension is
+    <listitem><para id="x_502">The Mercurial Queues patch management extension is
 	so invaluable that it merits two chapters and an appendix all
 	to itself. Chapter <xref linkend="chap:mq"/> covers the
 	basics; chapter <xref
@@ -40,12 +40,12 @@
 	command.</para>
     </listitem></itemizedlist>
 
-  <para>In this chapter, we'll cover some of the other extensions that
+  <para id="x_503">In this chapter, we'll cover some of the other extensions that
     are available for Mercurial, and briefly touch on some of the
     machinery you'll need to know about if you want to write an
     extension of your own.</para>
   <itemizedlist>
-    <listitem><para>In section <xref linkend="sec:hgext:inotify"/>,
+    <listitem><para id="x_504">In section <xref linkend="sec:hgext:inotify"/>,
 	we'll discuss the possibility of <emphasis>huge</emphasis>
 	performance improvements using the <literal
 	  role="hg-ext">inotify</literal> extension.</para>
@@ -55,11 +55,11 @@
     <title>Improve performance with the <literal
 	role="hg-ext">inotify</literal> extension</title>
 
-    <para>Are you interested in having some of the most common
+    <para id="x_505">Are you interested in having some of the most common
       Mercurial operations run as much as a hundred times faster?
       Read on!</para>
 
-    <para>Mercurial has great performance under normal circumstances.
+    <para id="x_506">Mercurial has great performance under normal circumstances.
       For example, when you run the <command role="hg-cmd">hg
 	status</command> command, Mercurial has to scan almost every
       directory and file in your repository so that it can display
@@ -69,7 +69,7 @@
       machinery to avoid doing an expensive comparison operation on
       files that obviously haven't changed.</para>
 
-    <para>Because obtaining file status is crucial to good
+    <para id="x_507">Because obtaining file status is crucial to good
       performance, the authors of Mercurial have optimised this code
       to within an inch of its life.  However, there's no avoiding the
       fact that when you run <command role="hg-cmd">hg
@@ -79,20 +79,20 @@
       checked.  For a sufficiently large repository, this can take a
       long time.</para>
 
-    <para>To put a number on the magnitude of this effect, I created a
+    <para id="x_508">To put a number on the magnitude of this effect, I created a
       repository containing 150,000 managed files.  I timed <command
 	role="hg-cmd">hg status</command> as taking ten seconds to
       run, even when <emphasis>none</emphasis> of those files had been
       modified.</para>
 
-    <para>Many modern operating systems contain a file notification
+    <para id="x_509">Many modern operating systems contain a file notification
       facility. If a program signs up to an appropriate service, the
       operating system will notify it every time a file of interest is
       created, modified, or deleted.  On Linux systems, the kernel
       component that does this is called
       <literal>inotify</literal>.</para>
 
-    <para>Mercurial's <literal role="hg-ext">inotify</literal>
+    <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal>
       extension talks to the kernel's <literal>inotify</literal>
       component to optimise <command role="hg-cmd">hg status</command>
       commands.  The extension has two components.  A daemon sits in
@@ -105,29 +105,29 @@
       with a result instantaneously, avoiding the need to scan every
       directory and file in the repository.</para>
 
-    <para>Recall the ten seconds that I measured plain Mercurial as
+    <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as
       taking to run <command role="hg-cmd">hg status</command> on a
       150,000 file repository.  With the <literal
 	role="hg-ext">inotify</literal> extension enabled, the time
       dropped to 0.1 seconds, a factor of <emphasis>one
 	hundred</emphasis> faster.</para>
 
-    <para>Before we continue, please pay attention to some
+    <para id="x_50c">Before we continue, please pay attention to some
       caveats.</para>
     <itemizedlist>
-      <listitem><para>The <literal role="hg-ext">inotify</literal>
+      <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal>
 	  extension is Linux-specific.  Because it interfaces directly
 	  to the Linux kernel's <literal>inotify</literal> subsystem,
 	  it does not work on other operating systems.</para>
       </listitem>
-      <listitem><para>It should work on any Linux distribution that
+      <listitem><para id="x_50e">It should work on any Linux distribution that
 	  was released after early 2005.  Older distributions are
 	  likely to have a kernel that lacks
 	  <literal>inotify</literal>, or a version of
 	  <literal>glibc</literal> that does not have the necessary
 	  interfacing support.</para>
       </listitem>
-      <listitem><para>Not all filesystems are suitable for use with
+      <listitem><para id="x_50f">Not all filesystems are suitable for use with
 	  the <literal role="hg-ext">inotify</literal> extension.
 	  Network filesystems such as NFS are a non-starter, for
 	  example, particularly if you're running Mercurial on several
@@ -138,40 +138,40 @@
 	  fine.</para>
       </listitem></itemizedlist>
 
-    <para>The <literal role="hg-ext">inotify</literal> extension is
+    <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is
       not yet shipped with Mercurial as of May 2007, so it's a little
       more involved to set up than other extensions.  But the
       performance improvement is worth it!</para>
 
-    <para>The extension currently comes in two parts: a set of patches
+    <para id="x_511">The extension currently comes in two parts: a set of patches
       to the Mercurial source code, and a library of Python bindings
       to the <literal>inotify</literal> subsystem.</para>
     <note>
-      <para>  There are <emphasis>two</emphasis> Python
+      <para id="x_512">  There are <emphasis>two</emphasis> Python
 	<literal>inotify</literal> binding libraries.  One of them is
 	called <literal>pyinotify</literal>, and is packaged by some
 	Linux distributions as <literal>python-inotify</literal>.
 	This is <emphasis>not</emphasis> the one you'll need, as it is
 	too buggy and inefficient to be practical.</para>
     </note>
-    <para>To get going, it's best to already have a functioning copy
+    <para id="x_513">To get going, it's best to already have a functioning copy
       of Mercurial installed.</para>
     <note>
-      <para>  If you follow the instructions below, you'll be
+      <para id="x_514">  If you follow the instructions below, you'll be
 	<emphasis>replacing</emphasis> and overwriting any existing
 	installation of Mercurial that you might already have, using
 	the latest <quote>bleeding edge</quote> Mercurial code. Don't
 	say you weren't warned!</para>
     </note>
     <orderedlist>
-      <listitem><para>Clone the Python <literal>inotify</literal>
+      <listitem><para id="x_515">Clone the Python <literal>inotify</literal>
 	  binding repository.  Build and install it.</para>
 	<programlisting>hg clone http://hg.kublai.com/python/inotify
 cd inotify
 python setup.py build --force
 sudo python setup.py install --skip-build</programlisting>
       </listitem>
-      <listitem><para>Clone the <filename
+      <listitem><para id="x_516">Clone the <filename
 	    class="directory">crew</filename> Mercurial repository.
 	  Clone the <literal role="hg-ext">inotify</literal> patch
 	  repository so that Mercurial Queues will be able to apply
@@ -181,13 +181,13 @@
 hg clone crew inotify
 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting>
       </listitem>
-      <listitem><para>Make sure that you have the Mercurial Queues
+      <listitem><para id="x_517">Make sure that you have the Mercurial Queues
 	  extension, <literal role="hg-ext">mq</literal>, enabled.  If
 	  you've never used MQ, read section <xref
 	    linkend="sec:mq:start"/> to get started
 	  quickly.</para>
       </listitem>
-      <listitem><para>Go into the <filename
+      <listitem><para id="x_518">Go into the <filename
 	    class="directory">inotify</filename> repo, and apply all
 	  of the <literal role="hg-ext">inotify</literal> patches
 	  using the <option role="hg-ext-mq-cmd-qpush-opt">hg
@@ -196,28 +196,28 @@
 	<programlisting>cd inotify
 hg qpush -a</programlisting>
       </listitem>
-      <listitem><para>  If you get an error message from <command
+      <listitem><para id="x_519">  If you get an error message from <command
 	    role="hg-ext-mq">qpush</command>, you should not continue.
 	  Instead, ask for help.</para>
       </listitem>
-      <listitem><para>Build and install the patched version of
+      <listitem><para id="x_51a">Build and install the patched version of
 	  Mercurial.</para>
 	<programlisting>python setup.py build --force
 sudo python setup.py install --skip-build</programlisting>
       </listitem>
     </orderedlist>
-    <para>Once you've build a suitably patched version of Mercurial,
+    <para id="x_51b">Once you've build a suitably patched version of Mercurial,
       all you need to do to enable the <literal
 	role="hg-ext">inotify</literal> extension is add an entry to
       your <filename role="special">~/.hgrc</filename>.</para>
     <programlisting>[extensions] inotify =</programlisting>
-    <para>When the <literal role="hg-ext">inotify</literal> extension
+    <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension
       is enabled, Mercurial will automatically and transparently start
       the status daemon the first time you run a command that needs
       status in a repository.  It runs one status daemon per
       repository.</para>
 
-    <para>The status daemon is started silently, and runs in the
+    <para id="x_51d">The status daemon is started silently, and runs in the
       background.  If you look at a list of running processes after
       you've enabled the <literal role="hg-ext">inotify</literal>
       extension and run a few commands in different repositories,
@@ -225,7 +225,7 @@
       around, waiting for updates from the kernel and queries from
       Mercurial.</para>
 
-    <para>The first time you run a Mercurial command in a repository
+    <para id="x_51e">The first time you run a Mercurial command in a repository
       when you have the <literal role="hg-ext">inotify</literal>
       extension enabled, it will run with about the same performance
       as a normal Mercurial command.  This is because the status
@@ -239,14 +239,14 @@
       status operations almost instantaneous on repositories of all
       sizes!</para>
 
-    <para>If you like, you can manually start a status daemon using
+    <para id="x_51f">If you like, you can manually start a status daemon using
       the <command role="hg-ext-inotify">inserve</command> command.
       This gives you slightly finer control over how the daemon ought
       to run.  This command will of course only be available when the
       <literal role="hg-ext">inotify</literal> extension is
       enabled.</para>
 
-    <para>When you're using the <literal
+    <para id="x_520">When you're using the <literal
 	role="hg-ext">inotify</literal> extension, you should notice
       <emphasis>no difference at all</emphasis> in Mercurial's
       behaviour, with the sole exception of status-related commands
@@ -260,24 +260,24 @@
     <title>Flexible diff support with the <literal
 	role="hg-ext">extdiff</literal> extension</title>
 
-    <para>Mercurial's built-in <command role="hg-cmd">hg
+    <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg
 	diff</command> command outputs plaintext unified diffs.</para>
 
     &interaction.extdiff.diff;
 
-    <para>If you would like to use an external tool to display
+    <para id="x_522">If you would like to use an external tool to display
       modifications, you'll want to use the <literal
 	role="hg-ext">extdiff</literal> extension.  This will let you
       use, for example, a graphical diff tool.</para>
 
-    <para>The <literal role="hg-ext">extdiff</literal> extension is
+    <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is
       bundled with Mercurial, so it's easy to set up.  In the <literal
 	role="rc-extensions">extensions</literal> section of your
       <filename role="special">~/.hgrc</filename>, simply add a
       one-line entry to enable the extension.</para>
     <programlisting>[extensions]
 extdiff =</programlisting>
-    <para>This introduces a command named <command
+    <para id="x_524">This introduces a command named <command
 	role="hg-ext-extdiff">extdiff</command>, which by default uses
       your system's <command>diff</command> command to generate a
       unified diff in the same form as the built-in <command
@@ -285,12 +285,12 @@
     
     &interaction.extdiff.extdiff;
 
-    <para>The result won't be exactly the same as with the built-in
+    <para id="x_525">The result won't be exactly the same as with the built-in
       <command role="hg-cmd">hg diff</command> variations, because the
       output of <command>diff</command> varies from one system to
       another, even when passed the same options.</para>
 
-    <para>As the <quote><literal>making snapshot</literal></quote>
+    <para id="x_526">As the <quote><literal>making snapshot</literal></quote>
       lines of output above imply, the <command
 	role="hg-ext-extdiff">extdiff</command> command works by
       creating two snapshots of your source tree.  The first snapshot
@@ -303,7 +303,7 @@
       directories and files that have changed between the two
       revisions.</para>
 
-    <para>Snapshot directory names have the same base name as your
+    <para id="x_527">Snapshot directory names have the same base name as your
       repository. If your repository path is <filename
 	class="directory">/quux/bar/foo</filename>, then <filename
 	class="directory">foo</filename> will be the name of each
@@ -319,7 +319,7 @@
       that the diff has the snapshot directory names embedded in its
       header.</para>
 
-    <para>The <command role="hg-ext-extdiff">extdiff</command> command
+    <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command
       accepts two important options. The <option
 	role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option
       lets you choose a program to view differences with, instead of
@@ -336,7 +336,7 @@
       and arguments to specify the revisions you want, the files you
       want, and so on.</para>
 
-    <para>As an example, here's how to run the normal system
+    <para id="x_529">As an example, here's how to run the normal system
       <command>diff</command> command, getting it to generate context
       diffs (using the <option role="cmd-opt-diff">-c</option> option)
       instead of unified diffs, and five lines of context instead of
@@ -345,11 +345,11 @@
 
       &interaction.extdiff.extdiff-ctx;
 
-    <para>Launching a visual diff tool is just as easy.  Here's how to
+    <para id="x_52a">Launching a visual diff tool is just as easy.  Here's how to
       launch the <command>kdiff3</command> viewer.</para>
     <programlisting>hg extdiff -p kdiff3 -o</programlisting>
 
-    <para>If your diff viewing command can't deal with directories,
+    <para id="x_52b">If your diff viewing command can't deal with directories,
       you can easily work around this with a little scripting.  For an
       example of such scripting in action with the <literal
 	role="hg-ext">mq</literal> extension and the
@@ -359,14 +359,14 @@
     <sect2>
       <title>Defining command aliases</title>
 
-      <para>It can be cumbersome to remember the options to both the
+      <para id="x_52c">It can be cumbersome to remember the options to both the
 	<command role="hg-ext-extdiff">extdiff</command> command and
 	the diff viewer you want to use, so the <literal
 	  role="hg-ext">extdiff</literal> extension lets you define
 	<emphasis>new</emphasis> commands that will invoke your diff
 	viewer with exactly the right options.</para>
 
-      <para>All you need to do is edit your <filename
+      <para id="x_52d">All you need to do is edit your <filename
 	  role="special">~/.hgrc</filename>, and add a section named
 	<literal role="rc-extdiff">extdiff</literal>.  Inside this
 	section, you can define multiple commands.  Here's how to add
@@ -376,7 +376,7 @@
 	will run <command>kdiff3</command> for you.</para>
       <programlisting>[extdiff]
 cmd.kdiff3 =</programlisting>
-      <para>If you leave the right hand side of the definition empty,
+      <para id="x_52e">If you leave the right hand side of the definition empty,
 	as above, the <literal role="hg-ext">extdiff</literal>
 	extension uses the name of the command you defined as the name
 	of the external program to run.  But these names don't have to
@@ -386,7 +386,7 @@
       <programlisting>[extdiff]
  cmd.wibble = kdiff3</programlisting>
 
-      <para>You can also specify the default options that you want to
+      <para id="x_52f">You can also specify the default options that you want to
 	invoke your diff viewing program with.  The prefix to use is
 	<quote><literal>opts.</literal></quote>, followed by the name
 	of the command to which the options apply.  This example
@@ -403,14 +403,14 @@
     <title>Cherrypicking changes with the <literal
 	role="hg-ext">transplant</literal> extension</title>
 
-    <para>Need to have a long chat with Brendan about this.</para>
+    <para id="x_530">Need to have a long chat with Brendan about this.</para>
 
   </sect1>
   <sect1 id="sec:hgext:patchbomb">
     <title>Send changes via email with the <literal
 	role="hg-ext">patchbomb</literal> extension</title>
 
-    <para>Many projects have a culture of <quote>change
+    <para id="x_531">Many projects have a culture of <quote>change
 	review</quote>, in which people send their modifications to a
       mailing list for others to read and comment on before they
       commit the final version to a shared repository.  Some projects
@@ -418,7 +418,7 @@
       other people to a repository to which those others don't have
       access.</para>
 
-    <para>Mercurial makes it easy to send changes over email for
+    <para id="x_532">Mercurial makes it easy to send changes over email for
       review or application, via its <literal
 	role="hg-ext">patchbomb</literal> extension.  The extension is
       so named because changes are formatted as patches, and it's usual
@@ -426,17 +426,17 @@
       of changes by email is thus much like <quote>bombing</quote> the
       recipient's inbox, hence <quote>patchbomb</quote>.</para>
 
-    <para>As usual, the basic configuration of the <literal
+    <para id="x_533">As usual, the basic configuration of the <literal
 	role="hg-ext">patchbomb</literal> extension takes just one or
       two lines in your <filename role="special">
 	/.hgrc</filename>.</para>
     <programlisting>[extensions]
 patchbomb =</programlisting>
-    <para>Once you've enabled the extension, you will have a new
+    <para id="x_534">Once you've enabled the extension, you will have a new
       command available, named <command
 	role="hg-ext-patchbomb">email</command>.</para>
 
-    <para>The safest and best way to invoke the <command
+    <para id="x_535">The safest and best way to invoke the <command
 	role="hg-ext-patchbomb">email</command> command is to
       <emphasis>always</emphasis> run it first with the <option
 	role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option.
@@ -447,12 +447,12 @@
 	role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option
       removed.</para>
 
-    <para>The <command role="hg-ext-patchbomb">email</command> command
+    <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command
       accepts the same kind of revision syntax as every other
       Mercurial command.  For example, this command will send every
       revision between 7 and <literal>tip</literal>, inclusive.</para>
     <programlisting>hg email -n 7:tip</programlisting>
-    <para>You can also specify a <emphasis>repository</emphasis> to
+    <para id="x_537">You can also specify a <emphasis>repository</emphasis> to
       compare with.  If you provide a repository but no revisions, the
       <command role="hg-ext-patchbomb">email</command> command will
       send all revisions in the local repository that are not present
@@ -461,7 +461,7 @@
 	role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option),
       this will constrain the revisions sent.</para>
 
-    <para>It's perfectly safe to run the <command
+    <para id="x_538">It's perfectly safe to run the <command
 	role="hg-ext-patchbomb">email</command> command without the
       names of the people you want to send to: if you do this, it will
       just prompt you for those values interactively.  (If you're
@@ -469,12 +469,12 @@
       <literal>readline</literal>-style editing capabilities when
       entering those headers, too, which is useful.)</para>
 
-    <para>When you are sending just one revision, the <command
+    <para id="x_539">When you are sending just one revision, the <command
 	role="hg-ext-patchbomb">email</command> command will by
       default use the first line of the changeset description as the
       subject of the single email message it sends.</para>
 
-    <para>If you send multiple revisions, the <command
+    <para id="x_53a">If you send multiple revisions, the <command
 	role="hg-ext-patchbomb">email</command> command will usually
       send one message per changeset.  It will preface the series with
       an introductory message, in which you should describe the
@@ -483,25 +483,25 @@
     <sect2>
       <title>Changing the behaviour of patchbombs</title>
 
-      <para>Not every project has exactly the same conventions for
+      <para id="x_53b">Not every project has exactly the same conventions for
 	sending changes in email; the <literal
 	  role="hg-ext">patchbomb</literal> extension tries to
 	accommodate a number of variations through command line
 	options.</para>
       <itemizedlist>
-	<listitem><para>You can write a subject for the introductory
+	<listitem><para id="x_53c">You can write a subject for the introductory
 	    message on the command line using the <option
 	      role="hg-ext-patchbomb-cmd-email-opt">hg -s</option>
 	    option.  This takes one argument, the text of the subject
 	    to use.</para>
 	</listitem>
-	<listitem><para>To change the email address from which the
+	<listitem><para id="x_53d">To change the email address from which the
 	    messages originate, use the <option
 	      role="hg-ext-patchbomb-cmd-email-opt">hg -f</option>
 	    option.  This takes one argument, the email address to
 	    use.</para>
 	</listitem>
-	<listitem><para>The default behaviour is to send unified diffs
+	<listitem><para id="x_53e">The default behaviour is to send unified diffs
 	    (see section <xref linkend="sec:mq:patch"/> for a
 	    description of the
 	    format), one per message.  You can send a binary bundle
@@ -509,13 +509,13 @@
 	      role="hg-ext-patchbomb-cmd-email-opt">hg -b</option>
 	    option.</para>
 	</listitem>
-	<listitem><para>Unified diffs are normally prefaced with a
+	<listitem><para id="x_53f">Unified diffs are normally prefaced with a
 	    metadata header.  You can omit this, and send unadorned
 	    diffs, with the <option
 	      role="hg-ext-patchbomb-cmd-email-opt">hg
 	      --plain</option> option.</para>
 	</listitem>
-	<listitem><para>Diffs are normally sent <quote>inline</quote>,
+	<listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>,
 	    in the same body part as the description of a patch.  This
 	    makes it easiest for the largest number of readers to
 	    quote and respond to parts of a diff, as some mail clients
@@ -525,14 +525,14 @@
 	      role="hg-ext-patchbomb-cmd-email-opt">hg -a</option>
 	    option.</para>
 	</listitem>
-	<listitem><para>Instead of sending mail messages, you can
+	<listitem><para id="x_541">Instead of sending mail messages, you can
 	    write them to an <literal>mbox</literal>-format mail
 	    folder using the <option
 	      role="hg-ext-patchbomb-cmd-email-opt">hg -m</option>
 	    option.  That option takes one argument, the name of the
 	    file to write to.</para>
 	</listitem>
-	<listitem><para>If you would like to add a
+	<listitem><para id="x_542">If you would like to add a
 	    <command>diffstat</command>-format summary to each patch,
 	    and one to the introductory message, use the <option
 	      role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>