1.1 --- a/en/ch09-hook.xml	Thu Mar 19 20:54:12 2009 -0700
     1.2 +++ b/en/ch09-hook.xml	Thu Mar 19 21:18:52 2009 -0700
     1.3 @@ -4,12 +4,12 @@
     1.4    <?dbhtml filename="handling-repository-events-with-hooks.html"?>
     1.5    <title>Handling repository events with hooks</title>
     1.6  
     1.7 -  <para>Mercurial offers a powerful mechanism to let you perform
     1.8 +  <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform
     1.9      automated actions in response to events that occur in a
    1.10      repository.  In some cases, you can even control Mercurial's
    1.11      response to those events.</para>
    1.12  
    1.13 -  <para>The name Mercurial uses for one of these actions is a
    1.14 +  <para id="x_1e7">The name Mercurial uses for one of these actions is a
    1.15      <emphasis>hook</emphasis>. Hooks are called
    1.16      <quote>triggers</quote> in some revision control systems, but the
    1.17      two names refer to the same idea.</para>
    1.18 @@ -17,49 +17,49 @@
    1.19    <sect1>
    1.20      <title>An overview of hooks in Mercurial</title>
    1.21  
    1.22 -    <para>Here is a brief list of the hooks that Mercurial supports.
    1.23 +    <para id="x_1e8">Here is a brief list of the hooks that Mercurial supports.
    1.24        We will revisit each of these hooks in more detail later, in
    1.25        section <xref linkend="sec:hook:ref"/>.</para>
    1.26  
    1.27      <itemizedlist>
    1.28 -      <listitem><para><literal role="hook">changegroup</literal>: This
    1.29 +      <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This
    1.30  	  is run after a group of changesets has been brought into the
    1.31  	  repository from elsewhere.</para>
    1.32        </listitem>
    1.33 -      <listitem><para><literal role="hook">commit</literal>: This is
    1.34 +      <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is
    1.35  	  run after a new changeset has been created in the local
    1.36  	  repository.</para>
    1.37        </listitem>
    1.38 -      <listitem><para><literal role="hook">incoming</literal>: This is
    1.39 +      <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is
    1.40  	  run once for each new changeset that is brought into the
    1.41  	  repository from elsewhere.  Notice the difference from
    1.42  	  <literal role="hook">changegroup</literal>, which is run
    1.43  	  once per <emphasis>group</emphasis> of changesets brought
    1.44  	  in.</para>
    1.45        </listitem>
    1.46 -      <listitem><para><literal role="hook">outgoing</literal>: This is
    1.47 +      <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is
    1.48  	  run after a group of changesets has been transmitted from
    1.49  	  this repository.</para>
    1.50        </listitem>
    1.51 -      <listitem><para><literal role="hook">prechangegroup</literal>:
    1.52 +      <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>:
    1.53  	  This is run before starting to bring a group of changesets
    1.54  	  into the repository.
    1.55  	</para>
    1.56        </listitem>
    1.57 -      <listitem><para><literal role="hook">precommit</literal>:
    1.58 +      <listitem><para id="x_1ee"><literal role="hook">precommit</literal>:
    1.59  	  Controlling. This is run before starting a commit.
    1.60  	</para>
    1.61        </listitem>
    1.62 -      <listitem><para><literal role="hook">preoutgoing</literal>:
    1.63 +      <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>:
    1.64  	  Controlling. This is run before starting to transmit a group
    1.65  	  of changesets from this repository.
    1.66  	</para>
    1.67        </listitem>
    1.68 -      <listitem><para><literal role="hook">pretag</literal>:
    1.69 +      <listitem><para id="x_1f0"><literal role="hook">pretag</literal>:
    1.70  	  Controlling. This is run before creating a tag.
    1.71  	</para>
    1.72        </listitem>
    1.73 -      <listitem><para><literal
    1.74 +      <listitem><para id="x_1f1"><literal
    1.75  	    role="hook">pretxnchangegroup</literal>: Controlling. This
    1.76  	  is run after a group of changesets has been brought into the
    1.77  	  local repository from another, but before the transaction
    1.78 @@ -67,27 +67,27 @@
    1.79  	  repository.
    1.80  	</para>
    1.81        </listitem>
    1.82 -      <listitem><para><literal role="hook">pretxncommit</literal>:
    1.83 +      <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>:
    1.84  	  Controlling. This is run after a new changeset has been
    1.85  	  created in the local repository, but before the transaction
    1.86  	  completes that will make it permanent.
    1.87  	</para>
    1.88        </listitem>
    1.89 -      <listitem><para><literal role="hook">preupdate</literal>:
    1.90 +      <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>:
    1.91  	  Controlling. This is run before starting an update or merge
    1.92  	  of the working directory.
    1.93  	</para>
    1.94        </listitem>
    1.95 -      <listitem><para><literal role="hook">tag</literal>: This is run
    1.96 +      <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run
    1.97  	  after a tag is created.
    1.98  	</para>
    1.99        </listitem>
   1.100 -      <listitem><para><literal role="hook">update</literal>: This is
   1.101 +      <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is
   1.102  	  run after an update or merge of the working directory has
   1.103  	  finished.
   1.104  	</para>
   1.105        </listitem></itemizedlist>
   1.106 -    <para>Each of the hooks whose description begins with the word
   1.107 +    <para id="x_1f6">Each of the hooks whose description begins with the word
   1.108        <quote>Controlling</quote> has the ability to determine whether
   1.109        an activity can proceed.  If the hook succeeds, the activity may
   1.110        proceed; if it fails, the activity is either not permitted or
   1.111 @@ -101,7 +101,7 @@
   1.112      <sect2>
   1.113        <title>Hooks are run with your privileges</title>
   1.114  
   1.115 -      <para>When you run a Mercurial command in a repository, and the
   1.116 +      <para id="x_1f7">When you run a Mercurial command in a repository, and the
   1.117  	command causes a hook to run, that hook runs on
   1.118  	<emphasis>your</emphasis> system, under
   1.119  	<emphasis>your</emphasis> user account, with
   1.120 @@ -112,14 +112,14 @@
   1.121  	it does.
   1.122        </para>
   1.123  
   1.124 -      <para>In some cases, you may be exposed to hooks that you did
   1.125 +      <para id="x_1f8">In some cases, you may be exposed to hooks that you did
   1.126  	not install yourself.  If you work with Mercurial on an
   1.127  	unfamiliar system, Mercurial will run hooks defined in that
   1.128  	system's global <filename role="special">~/.hgrc</filename>
   1.129  	file.
   1.130        </para>
   1.131  
   1.132 -      <para>If you are working with a repository owned by another
   1.133 +      <para id="x_1f9">If you are working with a repository owned by another
   1.134  	user, Mercurial can run hooks defined in that user's
   1.135  	repository, but it will still run them as <quote>you</quote>.
   1.136  	For example, if you <command role="hg-cmd">hg pull</command>
   1.137 @@ -131,7 +131,7 @@
   1.138        </para>
   1.139  
   1.140        <note>
   1.141 -	<para>  This only applies if you are pulling from a repository
   1.142 +	<para id="x_1fa">  This only applies if you are pulling from a repository
   1.143  	  on a local or network filesystem.  If you're pulling over
   1.144  	  http or ssh, any <literal role="hook">outgoing</literal>
   1.145  	  hook will run under whatever account is executing the server
   1.146 @@ -139,7 +139,7 @@
   1.147  	</para>
   1.148        </note>
   1.149  
   1.150 -      <para>XXX To see what hooks are defined in a repository, use the
   1.151 +      <para id="x_1fb">XXX To see what hooks are defined in a repository, use the
   1.152  	<command role="hg-cmd">hg config hooks</command> command.  If
   1.153  	you are working in one repository, but talking to another that
   1.154  	you do not own (e.g. using <command role="hg-cmd">hg
   1.155 @@ -152,27 +152,27 @@
   1.156      <sect2>
   1.157        <title>Hooks do not propagate</title>
   1.158  
   1.159 -      <para>In Mercurial, hooks are not revision controlled, and do
   1.160 +      <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do
   1.161  	not propagate when you clone, or pull from, a repository.  The
   1.162  	reason for this is simple: a hook is a completely arbitrary
   1.163  	piece of executable code.  It runs under your user identity,
   1.164  	with your privilege level, on your machine.
   1.165        </para>
   1.166  
   1.167 -      <para>It would be extremely reckless for any distributed
   1.168 +      <para id="x_1fd">It would be extremely reckless for any distributed
   1.169  	revision control system to implement revision-controlled
   1.170  	hooks, as this would offer an easily exploitable way to
   1.171  	subvert the accounts of users of the revision control system.
   1.172        </para>
   1.173  
   1.174 -      <para>Since Mercurial does not propagate hooks, if you are
   1.175 +      <para id="x_1fe">Since Mercurial does not propagate hooks, if you are
   1.176  	collaborating with other people on a common project, you
   1.177  	should not assume that they are using the same Mercurial hooks
   1.178  	as you are, or that theirs are correctly configured.  You
   1.179  	should document the hooks you expect people to use.
   1.180        </para>
   1.181  
   1.182 -      <para>In a corporate intranet, this is somewhat easier to
   1.183 +      <para id="x_1ff">In a corporate intranet, this is somewhat easier to
   1.184  	control, as you can for example provide a
   1.185  	<quote>standard</quote> installation of Mercurial on an NFS
   1.186  	filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will
   1.187 @@ -183,12 +183,12 @@
   1.188      <sect2>
   1.189        <title>Hooks can be overridden</title>
   1.190  
   1.191 -      <para>Mercurial allows you to override a hook definition by
   1.192 +      <para id="x_200">Mercurial allows you to override a hook definition by
   1.193  	redefining the hook.  You can disable it by setting its value
   1.194  	to the empty string, or change its behaviour as you wish.
   1.195        </para>
   1.196  
   1.197 -      <para>If you deploy a system- or site-wide <filename
   1.198 +      <para id="x_201">If you deploy a system- or site-wide <filename
   1.199  	  role="special">~/.hgrc</filename> file that defines some
   1.200  	hooks, you should thus understand that your users can disable
   1.201  	or override those hooks.
   1.202 @@ -198,7 +198,7 @@
   1.203      <sect2>
   1.204        <title>Ensuring that critical hooks are run</title>
   1.205  
   1.206 -      <para>Sometimes you may want to enforce a policy that you do not
   1.207 +      <para id="x_202">Sometimes you may want to enforce a policy that you do not
   1.208  	want others to be able to work around.  For example, you may
   1.209  	have a requirement that every changeset must pass a rigorous
   1.210  	set of tests.  Defining this requirement via a hook in a
   1.211 @@ -207,13 +207,13 @@
   1.212  	can subvert it at will by overriding the hook.
   1.213        </para>
   1.214  
   1.215 -      <para>Instead, you can set up your policies for use of Mercurial
   1.216 +      <para id="x_203">Instead, you can set up your policies for use of Mercurial
   1.217  	so that people are expected to propagate changes through a
   1.218  	well-known <quote>canonical</quote> server that you have
   1.219  	locked down and configured appropriately.
   1.220        </para>
   1.221  
   1.222 -      <para>One way to do this is via a combination of social
   1.223 +      <para id="x_204">One way to do this is via a combination of social
   1.224  	engineering and technology.  Set up a restricted-access
   1.225  	account; users can push changes over the network to
   1.226  	repositories managed by this account, but they cannot log into
   1.227 @@ -222,7 +222,7 @@
   1.228  	they want.
   1.229        </para>
   1.230  
   1.231 -      <para>When someone pushes a changeset to the server that
   1.232 +      <para id="x_205">When someone pushes a changeset to the server that
   1.233  	everyone pulls from, the server will test the changeset before
   1.234  	it accepts it as permanent, and reject it if it fails to pass
   1.235  	the test suite.  If people only pull changes from this
   1.236 @@ -236,19 +236,19 @@
   1.237      <title>Care with <literal>pretxn</literal> hooks in a
   1.238        shared-access repository</title>
   1.239  
   1.240 -    <para>If you want to use hooks to do some automated work in a
   1.241 +    <para id="x_206">If you want to use hooks to do some automated work in a
   1.242        repository that a number of people have shared access to, you
   1.243        need to be careful in how you do this.
   1.244      </para>
   1.245  
   1.246 -    <para>Mercurial only locks a repository when it is writing to the
   1.247 +    <para id="x_207">Mercurial only locks a repository when it is writing to the
   1.248        repository, and only the parts of Mercurial that write to the
   1.249        repository pay attention to locks.  Write locks are necessary to
   1.250        prevent multiple simultaneous writers from scribbling on each
   1.251        other's work, corrupting the repository.
   1.252      </para>
   1.253  
   1.254 -    <para>Because Mercurial is careful with the order in which it
   1.255 +    <para id="x_208">Because Mercurial is careful with the order in which it
   1.256        reads and writes data, it does not need to acquire a lock when
   1.257        it wants to read data from the repository.  The parts of
   1.258        Mercurial that read from the repository never pay attention to
   1.259 @@ -256,14 +256,14 @@
   1.260        performance and concurrency.
   1.261      </para>
   1.262  
   1.263 -    <para>With great performance comes a trade-off, though, one which
   1.264 +    <para id="x_209">With great performance comes a trade-off, though, one which
   1.265        has the potential to cause you trouble unless you're aware of
   1.266        it.  To describe this requires a little detail about how
   1.267        Mercurial adds changesets to a repository and reads those
   1.268        changes.
   1.269      </para>
   1.270  
   1.271 -    <para>When Mercurial <emphasis>writes</emphasis> metadata, it
   1.272 +    <para id="x_20a">When Mercurial <emphasis>writes</emphasis> metadata, it
   1.273        writes it straight into the destination file.  It writes file
   1.274        data first, then manifest data (which contains pointers to the
   1.275        new file data), then changelog data (which contains pointers to
   1.276 @@ -274,13 +274,13 @@
   1.277        before the transaction began.
   1.278      </para>
   1.279  
   1.280 -    <para>When Mercurial <emphasis>reads</emphasis> metadata, it reads
   1.281 +    <para id="x_20b">When Mercurial <emphasis>reads</emphasis> metadata, it reads
   1.282        the changelog first, then everything else.  Since a reader will
   1.283        only access parts of the manifest or file metadata that it can
   1.284        see in the changelog, it can never see partially written data.
   1.285      </para>
   1.286  
   1.287 -    <para>Some controlling hooks (<literal
   1.288 +    <para id="x_20c">Some controlling hooks (<literal
   1.289  	role="hook">pretxncommit</literal> and <literal
   1.290  	role="hook">pretxnchangegroup</literal>) run when a
   1.291        transaction is almost complete. All of the metadata has been
   1.292 @@ -288,7 +288,7 @@
   1.293        cause the newly-written data to disappear.
   1.294      </para>
   1.295  
   1.296 -    <para>If one of these hooks runs for long, it opens a window of
   1.297 +    <para id="x_20d">If one of these hooks runs for long, it opens a window of
   1.298        time during which a reader can see the metadata for changesets
   1.299        that are not yet permanent, and should not be thought of as
   1.300        <quote>really there</quote>.  The longer the hook runs, the
   1.301 @@ -298,7 +298,7 @@
   1.302      <sect2>
   1.303        <title>The problem illustrated</title>
   1.304  
   1.305 -      <para>In principle, a good use for the <literal
   1.306 +      <para id="x_20e">In principle, a good use for the <literal
   1.307  	  role="hook">pretxnchangegroup</literal> hook would be to
   1.308  	automatically build and test incoming changes before they are
   1.309  	accepted into a central repository.  This could let you
   1.310 @@ -309,7 +309,7 @@
   1.311  	potentially breaking their build.
   1.312        </para>
   1.313  
   1.314 -      <para>The safest technological answer to this challenge is to
   1.315 +      <para id="x_20f">The safest technological answer to this challenge is to
   1.316  	set up such a <quote>gatekeeper</quote> repository as
   1.317  	<emphasis>unidirectional</emphasis>.  Let it take changes
   1.318  	pushed in from the outside, but do not allow anyone to pull
   1.319 @@ -321,7 +321,7 @@
   1.320  	<emphasis>can</emphasis> pull from.
   1.321        </para>
   1.322  
   1.323 -      <para>In practice, putting a centralised bottleneck like this in
   1.324 +      <para id="x_210">In practice, putting a centralised bottleneck like this in
   1.325  	place is not often a good idea, and transaction visibility has
   1.326  	nothing to do with the problem.  As the size of a
   1.327  	project&emdash;and the time it takes to build and
   1.328 @@ -332,7 +332,7 @@
   1.329  	involved.
   1.330        </para>
   1.331  
   1.332 -      <para>An approach that scales better is to get people to build
   1.333 +      <para id="x_211">An approach that scales better is to get people to build
   1.334  	and test before they push, then run automated builds and tests
   1.335  	centrally <emphasis>after</emphasis> a push, to be sure all is
   1.336  	well.  The advantage of this approach is that it does not
   1.337 @@ -345,18 +345,18 @@
   1.338    <sect1 id="sec:hook:simple">
   1.339      <title>A short tutorial on using hooks</title>
   1.340  
   1.341 -    <para>It is easy to write a Mercurial hook.  Let's start with a
   1.342 +    <para id="x_212">It is easy to write a Mercurial hook.  Let's start with a
   1.343        hook that runs when you finish a <command role="hg-cmd">hg
   1.344  	commit</command>, and simply prints the hash of the changeset
   1.345        you just created.  The hook is called <literal
   1.346  	role="hook">commit</literal>.
   1.347      </para>
   1.348  
   1.349 -    <para>All hooks follow the pattern in this example.</para>
   1.350 +    <para id="x_213">All hooks follow the pattern in this example.</para>
   1.351  
   1.352  &interaction.hook.simple.init;
   1.353  
   1.354 -    <para>You add an entry to the <literal
   1.355 +    <para id="x_214">You add an entry to the <literal
   1.356  	role="rc-hooks">hooks</literal> section of your <filename
   1.357  	role="special">~/.hgrc</filename>.  On the left is the name of
   1.358        the event to trigger on; on the right is the action to take.  As
   1.359 @@ -368,12 +368,12 @@
   1.360      <sect2>
   1.361        <title>Performing multiple actions per event</title>
   1.362  
   1.363 -      <para>Quite often, you will want to define more than one hook
   1.364 +      <para id="x_215">Quite often, you will want to define more than one hook
   1.365  	for a particular kind of event, as shown below.</para>
   1.366  
   1.367  &interaction.hook.simple.ext;
   1.368  
   1.369 -      <para>Mercurial lets you do this by adding an
   1.370 +      <para id="x_216">Mercurial lets you do this by adding an
   1.371  	<emphasis>extension</emphasis> to the end of a hook's name.
   1.372  	You extend a hook's name by giving the name of the hook,
   1.373  	followed by a full stop (the
   1.374 @@ -384,7 +384,7 @@
   1.375  	<literal>commit</literal> event occurs.
   1.376        </para>
   1.377  
   1.378 -      <para>To give a well-defined order of execution when there are
   1.379 +      <para id="x_217">To give a well-defined order of execution when there are
   1.380  	multiple hooks defined for an event, Mercurial sorts hooks by
   1.381  	extension, and executes the hook commands in this sorted
   1.382  	order.  In the above example, it will execute
   1.383 @@ -393,7 +393,7 @@
   1.384  	before both.
   1.385        </para>
   1.386  
   1.387 -      <para>It is a good idea to use a somewhat descriptive extension
   1.388 +      <para id="x_218">It is a good idea to use a somewhat descriptive extension
   1.389  	when you define a new hook.  This will help you to remember
   1.390  	what the hook was for.  If the hook fails, you'll get an error
   1.391  	message that contains the hook name and extension, so using a
   1.392 @@ -406,20 +406,20 @@
   1.393      <sect2 id="sec:hook:perm">
   1.394        <title>Controlling whether an activity can proceed</title>
   1.395  
   1.396 -      <para>In our earlier examples, we used the <literal
   1.397 +      <para id="x_219">In our earlier examples, we used the <literal
   1.398  	  role="hook">commit</literal> hook, which is run after a
   1.399  	commit has completed.  This is one of several Mercurial hooks
   1.400  	that run after an activity finishes.  Such hooks have no way
   1.401  	of influencing the activity itself.
   1.402        </para>
   1.403  
   1.404 -      <para>Mercurial defines a number of events that occur before an
   1.405 +      <para id="x_21a">Mercurial defines a number of events that occur before an
   1.406  	activity starts; or after it starts, but before it finishes.
   1.407  	Hooks that trigger on these events have the added ability to
   1.408  	choose whether the activity can continue, or will abort.
   1.409        </para>
   1.410  
   1.411 -      <para>The <literal role="hook">pretxncommit</literal> hook runs
   1.412 +      <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs
   1.413  	after a commit has all but completed.  In other words, the
   1.414  	metadata representing the changeset has been written out to
   1.415  	disk, but the transaction has not yet been allowed to
   1.416 @@ -428,7 +428,7 @@
   1.417  	complete, or must be rolled back.
   1.418        </para>
   1.419  
   1.420 -      <para>If the <literal role="hook">pretxncommit</literal> hook
   1.421 +      <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook
   1.422  	exits with a status code of zero, the transaction is allowed
   1.423  	to complete; the commit finishes; and the <literal
   1.424  	  role="hook">commit</literal> hook is run.  If the <literal
   1.425 @@ -440,7 +440,7 @@
   1.426  
   1.427  &interaction.hook.simple.pretxncommit;
   1.428  
   1.429 -      <para>The hook in the example above checks that a commit comment
   1.430 +      <para id="x_21d">The hook in the example above checks that a commit comment
   1.431  	contains a bug ID.  If it does, the commit can complete.  If
   1.432  	not, the commit is rolled back.
   1.433        </para>
   1.434 @@ -450,7 +450,7 @@
   1.435    <sect1>
   1.436      <title>Writing your own hooks</title>
   1.437  
   1.438 -    <para>When you are writing a hook, you might find it useful to run
   1.439 +    <para id="x_21e">When you are writing a hook, you might find it useful to run
   1.440        Mercurial either with the <option
   1.441  	role="hg-opt-global">-v</option> option, or the <envar
   1.442  	role="rc-item-ui">verbose</envar> config item set to
   1.443 @@ -461,19 +461,19 @@
   1.444      <sect2 id="sec:hook:lang">
   1.445        <title>Choosing how your hook should run</title>
   1.446  
   1.447 -      <para>You can write a hook either as a normal
   1.448 +      <para id="x_21f">You can write a hook either as a normal
   1.449  	program&emdash;typically a shell script&emdash;or as a Python
   1.450  	function that is executed within the Mercurial process.
   1.451        </para>
   1.452  
   1.453 -      <para>Writing a hook as an external program has the advantage
   1.454 +      <para id="x_220">Writing a hook as an external program has the advantage
   1.455  	that it requires no knowledge of Mercurial's internals.  You
   1.456  	can call normal Mercurial commands to get any added
   1.457  	information you need.  The trade-off is that external hooks
   1.458  	are slower than in-process hooks.
   1.459        </para>
   1.460  
   1.461 -      <para>An in-process Python hook has complete access to the
   1.462 +      <para id="x_221">An in-process Python hook has complete access to the
   1.463  	Mercurial API, and does not <quote>shell out</quote> to
   1.464  	another process, so it is inherently faster than an external
   1.465  	hook.  It is also easier to obtain much of the information
   1.466 @@ -481,7 +481,7 @@
   1.467  	running Mercurial commands.
   1.468        </para>
   1.469  
   1.470 -      <para>If you are comfortable with Python, or require high
   1.471 +      <para id="x_222">If you are comfortable with Python, or require high
   1.472  	performance, writing your hooks in Python may be a good
   1.473  	choice.  However, when you have a straightforward hook to
   1.474  	write and you don't need to care about performance (probably
   1.475 @@ -492,13 +492,13 @@
   1.476      <sect2 id="sec:hook:param">
   1.477        <title>Hook parameters</title>
   1.478  
   1.479 -      <para>Mercurial calls each hook with a set of well-defined
   1.480 +      <para id="x_223">Mercurial calls each hook with a set of well-defined
   1.481  	parameters.  In Python, a parameter is passed as a keyword
   1.482  	argument to your hook function.  For an external program, a
   1.483  	parameter is passed as an environment variable.
   1.484        </para>
   1.485  
   1.486 -      <para>Whether your hook is written in Python or as a shell
   1.487 +      <para id="x_224">Whether your hook is written in Python or as a shell
   1.488  	script, the hook-specific parameter names and values will be
   1.489  	the same.  A boolean parameter will be represented as a
   1.490  	boolean value in Python, but as the number 1 (for
   1.491 @@ -514,7 +514,7 @@
   1.492      <sect2>
   1.493        <title>Hook return values and activity control</title>
   1.494  
   1.495 -      <para>A hook that executes successfully must exit with a status
   1.496 +      <para id="x_225">A hook that executes successfully must exit with a status
   1.497  	of zero if external, or return boolean <quote>false</quote> if
   1.498  	in-process.  Failure is indicated with a non-zero exit status
   1.499  	from an external hook, or an in-process hook returning boolean
   1.500 @@ -522,7 +522,7 @@
   1.501  	exception, the hook is considered to have failed.
   1.502        </para>
   1.503  
   1.504 -      <para>For a hook that controls whether an activity can proceed,
   1.505 +      <para id="x_226">For a hook that controls whether an activity can proceed,
   1.506  	zero/false means <quote>allow</quote>, while
   1.507  	non-zero/true/exception means <quote>deny</quote>.
   1.508        </para>
   1.509 @@ -531,23 +531,23 @@
   1.510      <sect2>
   1.511        <title>Writing an external hook</title>
   1.512  
   1.513 -      <para>When you define an external hook in your <filename
   1.514 +      <para id="x_227">When you define an external hook in your <filename
   1.515  	  role="special">~/.hgrc</filename> and the hook is run, its
   1.516  	value is passed to your shell, which interprets it.  This
   1.517  	means that you can use normal shell constructs in the body of
   1.518  	the hook.
   1.519        </para>
   1.520  
   1.521 -      <para>An executable hook is always run with its current
   1.522 +      <para id="x_228">An executable hook is always run with its current
   1.523  	directory set to a repository's root directory.
   1.524        </para>
   1.525  
   1.526 -      <para>Each hook parameter is passed in as an environment
   1.527 +      <para id="x_229">Each hook parameter is passed in as an environment
   1.528  	variable; the name is upper-cased, and prefixed with the
   1.529  	string <quote><literal>HG_</literal></quote>.
   1.530        </para>
   1.531  
   1.532 -      <para>With the exception of hook parameters, Mercurial does not
   1.533 +      <para id="x_22a">With the exception of hook parameters, Mercurial does not
   1.534  	set or modify any environment variables when running a hook.
   1.535  	This is useful to remember if you are writing a site-wide hook
   1.536  	that may be run by a number of different users with differing
   1.537 @@ -560,7 +560,7 @@
   1.538      <sect2>
   1.539        <title>Telling Mercurial to use an in-process hook</title>
   1.540  
   1.541 -      <para>The <filename role="special">~/.hgrc</filename> syntax
   1.542 +      <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax
   1.543  	for defining an in-process hook is slightly different than for
   1.544  	an executable hook.  The value of the hook must start with the
   1.545  	text <quote><literal>python:</literal></quote>, and continue
   1.546 @@ -568,19 +568,19 @@
   1.547  	the hook's value.
   1.548        </para>
   1.549  
   1.550 -      <para>The module in which a hook lives is automatically imported
   1.551 +      <para id="x_22c">The module in which a hook lives is automatically imported
   1.552  	when a hook is run.  So long as you have the module name and
   1.553  	<envar>PYTHONPATH</envar> right, it should <quote>just
   1.554  	  work</quote>.
   1.555        </para>
   1.556  
   1.557 -      <para>The following <filename role="special">~/.hgrc</filename>
   1.558 +      <para id="x_22d">The following <filename role="special">~/.hgrc</filename>
   1.559  	example snippet illustrates the syntax and meaning of the
   1.560  	notions we just described.
   1.561        </para>
   1.562        <programlisting>[hooks]
   1.563  commit.example = python:mymodule.submodule.myhook</programlisting>
   1.564 -      <para>When Mercurial runs the <literal>commit.example</literal>
   1.565 +      <para id="x_22e">When Mercurial runs the <literal>commit.example</literal>
   1.566  	hook, it imports <literal>mymodule.submodule</literal>, looks
   1.567  	for the callable object named <literal>myhook</literal>, and
   1.568  	calls it.
   1.569 @@ -590,12 +590,12 @@
   1.570      <sect2>
   1.571        <title>Writing an in-process hook</title>
   1.572  
   1.573 -      <para>The simplest in-process hook does nothing, but illustrates
   1.574 +      <para id="x_22f">The simplest in-process hook does nothing, but illustrates
   1.575  	the basic shape of the hook API:
   1.576        </para>
   1.577        <programlisting>def myhook(ui, repo, **kwargs):
   1.578      pass</programlisting>
   1.579 -      <para>The first argument to a Python hook is always a <literal
   1.580 +      <para id="x_230">The first argument to a Python hook is always a <literal
   1.581  	  role="py-mod-mercurial.ui">ui</literal> object.  The second
   1.582  	is a repository object; at the moment, it is always an
   1.583  	instance of <literal
   1.584 @@ -615,7 +615,7 @@
   1.585      <sect2>
   1.586        <title>Writing meaningful commit messages</title>
   1.587  
   1.588 -      <para>It's hard to imagine a useful commit message being very
   1.589 +      <para id="x_231">It's hard to imagine a useful commit message being very
   1.590  	short. The simple <literal role="hook">pretxncommit</literal>
   1.591  	hook of the example below will prevent you from committing a
   1.592  	changeset with a message that is less than ten bytes long.
   1.593 @@ -627,7 +627,7 @@
   1.594      <sect2>
   1.595        <title>Checking for trailing whitespace</title>
   1.596  
   1.597 -      <para>An interesting use of a commit-related hook is to help you
   1.598 +      <para id="x_232">An interesting use of a commit-related hook is to help you
   1.599  	to write cleaner code.  A simple example of <quote>cleaner
   1.600  	  code</quote> is the dictum that a change should not add any
   1.601  	new lines of text that contain <quote>trailing
   1.602 @@ -638,7 +638,7 @@
   1.603  	prefer to get rid of it.
   1.604        </para>
   1.605  
   1.606 -      <para>You can use either the <literal
   1.607 +      <para id="x_233">You can use either the <literal
   1.608  	  role="hook">precommit</literal> or <literal
   1.609  	  role="hook">pretxncommit</literal> hook to tell whether you
   1.610  	have a trailing whitespace problem.  If you use the <literal
   1.611 @@ -654,7 +654,7 @@
   1.612  	seem right.
   1.613        </para>
   1.614  
   1.615 -      <para>Should you choose the <literal
   1.616 +      <para id="x_234">Should you choose the <literal
   1.617  	  role="hook">pretxncommit</literal> hook, the check won't
   1.618  	occur until just before the transaction for the commit
   1.619  	completes.  This will allow you to check for problems only the
   1.620 @@ -667,7 +667,7 @@
   1.621  
   1.622  &interaction.hook.ws.simple;
   1.623  
   1.624 -      <para>In this example, we introduce a simple <literal
   1.625 +      <para id="x_235">In this example, we introduce a simple <literal
   1.626  	  role="hook">pretxncommit</literal> hook that checks for
   1.627  	trailing whitespace.  This hook is short, but not very
   1.628  	helpful.  It exits with an error status if a change adds a
   1.629 @@ -678,7 +678,7 @@
   1.630  	trailing whitespace cause problems.
   1.631        </para>
   1.632  
   1.633 -      <para>The above version is much more complex, but also more
   1.634 +      <para id="x_236">The above version is much more complex, but also more
   1.635  	useful.  It parses a unified diff to see if any lines add
   1.636  	trailing whitespace, and prints the name of the file and the
   1.637  	line number of each such occurrence.  Even better, if the
   1.638 @@ -692,7 +692,7 @@
   1.639  
   1.640  &interaction.hook.ws.better;
   1.641  
   1.642 -      <para>As a final aside, note in the example above the use of
   1.643 +      <para id="x_237">As a final aside, note in the example above the use of
   1.644  	<command>perl</command>'s in-place editing feature to get rid
   1.645  	of trailing whitespace from a file.  This is concise and
   1.646  	useful enough that I will reproduce it here.
   1.647 @@ -704,7 +704,7 @@
   1.648    <sect1>
   1.649      <title>Bundled hooks</title>
   1.650  
   1.651 -    <para>Mercurial ships with several bundled hooks.  You can find
   1.652 +    <para id="x_238">Mercurial ships with several bundled hooks.  You can find
   1.653        them in the <filename class="directory">hgext</filename>
   1.654        directory of a Mercurial source tree.  If you are using a
   1.655        Mercurial binary package, the hooks will be located in the
   1.656 @@ -716,7 +716,7 @@
   1.657        <title><literal role="hg-ext">acl</literal>&emdash;access
   1.658  	control for parts of a repository</title>
   1.659  
   1.660 -      <para>The <literal role="hg-ext">acl</literal> extension lets
   1.661 +      <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets
   1.662  	you control which remote users are allowed to push changesets
   1.663  	to a networked server.  You can protect any portion of a
   1.664  	repository (including the entire repo), so that a specific
   1.665 @@ -724,7 +724,7 @@
   1.666  	portion.
   1.667        </para>
   1.668  
   1.669 -      <para>This extension implements access control based on the
   1.670 +      <para id="x_23a">This extension implements access control based on the
   1.671  	identity of the user performing a push,
   1.672  	<emphasis>not</emphasis> on who committed the changesets
   1.673  	they're pushing.  It makes sense to use this hook only if you
   1.674 @@ -737,7 +737,7 @@
   1.675  	<title>Configuring the <literal role="hook">acl</literal>
   1.676  	  hook</title>
   1.677  
   1.678 -	<para>In order to manage incoming changesets, the <literal
   1.679 +	<para id="x_23b">In order to manage incoming changesets, the <literal
   1.680  	    role="hg-ext">acl</literal> hook must be used as a
   1.681  	  <literal role="hook">pretxnchangegroup</literal> hook.  This
   1.682  	  lets it see which files are modified by each incoming
   1.683 @@ -747,18 +747,18 @@
   1.684  	<programlisting>[hooks]
   1.685  pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
   1.686  
   1.687 -	<para>The <literal role="hg-ext">acl</literal> extension is
   1.688 +	<para id="x_23c">The <literal role="hg-ext">acl</literal> extension is
   1.689  	  configured using three sections.
   1.690  	</para>
   1.691  
   1.692 -	<para>The <literal role="rc-acl">acl</literal> section has
   1.693 +	<para id="x_23d">The <literal role="rc-acl">acl</literal> section has
   1.694  	  only one entry, <envar role="rc-item-acl">sources</envar>,
   1.695  	  which lists the sources of incoming changesets that the hook
   1.696  	  should pay attention to.  You don't normally need to
   1.697  	  configure this section.
   1.698  	</para>
   1.699  	<itemizedlist>
   1.700 -	  <listitem><para><envar role="rc-item-acl">serve</envar>:
   1.701 +	  <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>:
   1.702  	      Control incoming changesets that are arriving from a
   1.703  	      remote repository over http or ssh.  This is the default
   1.704  	      value of <envar role="rc-item-acl">sources</envar>, and
   1.705 @@ -766,23 +766,23 @@
   1.706  	      configuration item.
   1.707  	    </para>
   1.708  	  </listitem>
   1.709 -	  <listitem><para><envar role="rc-item-acl">pull</envar>:
   1.710 +	  <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>:
   1.711  	      Control incoming changesets that are arriving via a pull
   1.712  	      from a local repository.
   1.713  	    </para>
   1.714  	  </listitem>
   1.715 -	  <listitem><para><envar role="rc-item-acl">push</envar>:
   1.716 +	  <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>:
   1.717  	      Control incoming changesets that are arriving via a push
   1.718  	      from a local repository.
   1.719  	    </para>
   1.720  	  </listitem>
   1.721 -	  <listitem><para><envar role="rc-item-acl">bundle</envar>:
   1.722 +	  <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>:
   1.723  	      Control incoming changesets that are arriving from
   1.724  	      another repository via a bundle.
   1.725  	    </para>
   1.726  	  </listitem></itemizedlist>
   1.727  
   1.728 -	<para>The <literal role="rc-acl.allow">acl.allow</literal>
   1.729 +	<para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal>
   1.730  	  section controls the users that are allowed to add
   1.731  	  changesets to the repository.  If this section is not
   1.732  	  present, all users that are not explicitly denied are
   1.733 @@ -791,13 +791,13 @@
   1.734  	  that all users are denied).
   1.735  	</para>
   1.736  
   1.737 -	<para>The <literal role="rc-acl.deny">acl.deny</literal>
   1.738 +	<para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal>
   1.739  	  section determines which users are denied from adding
   1.740  	  changesets to the repository.  If this section is not
   1.741  	  present or is empty, no users are denied.
   1.742  	</para>
   1.743  
   1.744 -	<para>The syntaxes for the <literal
   1.745 +	<para id="x_244">The syntaxes for the <literal
   1.746  	    role="rc-acl.allow">acl.allow</literal> and <literal
   1.747  	    role="rc-acl.deny">acl.deny</literal> sections are
   1.748  	  identical.  On the left of each entry is a glob pattern that
   1.749 @@ -805,7 +805,7 @@
   1.750  	  repository; on the right, a user name.
   1.751  	</para>
   1.752  
   1.753 -	<para>In the following example, the user
   1.754 +	<para id="x_245">In the following example, the user
   1.755  	  <literal>docwriter</literal> can only push changes to the
   1.756  	  <filename class="directory">docs</filename> subtree of the
   1.757  	  repository, while <literal>intern</literal> can push changes
   1.758 @@ -821,7 +821,7 @@
   1.759        <sect3>
   1.760  	<title>Testing and troubleshooting</title>
   1.761  
   1.762 -	<para>If you want to test the <literal
   1.763 +	<para id="x_246">If you want to test the <literal
   1.764  	    role="hg-ext">acl</literal> hook, run it with Mercurial's
   1.765  	  debugging output enabled.  Since you'll probably be running
   1.766  	  it on a server where it's not convenient (or sometimes
   1.767 @@ -832,7 +832,7 @@
   1.768  	</para>
   1.769  	<programlisting>[ui]
   1.770  debug = true</programlisting>
   1.771 -	<para>With this enabled, the <literal
   1.772 +	<para id="x_247">With this enabled, the <literal
   1.773  	    role="hg-ext">acl</literal> hook will print enough
   1.774  	  information to let you figure out why it is allowing or
   1.775  	  forbidding pushes from specific users.
   1.776 @@ -845,14 +845,14 @@
   1.777  	  role="hg-ext">bugzilla</literal>&emdash;integration with
   1.778  	Bugzilla</title>
   1.779  
   1.780 -      <para>The <literal role="hg-ext">bugzilla</literal> extension
   1.781 +      <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension
   1.782  	adds a comment to a Bugzilla bug whenever it finds a reference
   1.783  	to that bug ID in a commit comment.  You can install this hook
   1.784  	on a shared server, so that any time a remote user pushes
   1.785  	changes to this server, the hook gets run.
   1.786        </para>
   1.787  
   1.788 -      <para>It adds a comment to the bug that looks like this (you can
   1.789 +      <para id="x_249">It adds a comment to the bug that looks like this (you can
   1.790  	configure the contents of the comment&emdash;see below):
   1.791        </para>
   1.792        <programlisting>Changeset aad8b264143a, made by Joe User
   1.793 @@ -861,19 +861,19 @@
   1.794  	http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
   1.795  	Changeset description: Fix bug 10483 by guarding against some
   1.796  	NULL pointers</programlisting>
   1.797 -      <para>The value of this hook is that it automates the process of
   1.798 +      <para id="x_24a">The value of this hook is that it automates the process of
   1.799  	updating a bug any time a changeset refers to it.  If you
   1.800  	configure the hook properly, it makes it easy for people to
   1.801  	browse straight from a Bugzilla bug to a changeset that refers
   1.802  	to that bug.
   1.803        </para>
   1.804  
   1.805 -      <para>You can use the code in this hook as a starting point for
   1.806 +      <para id="x_24b">You can use the code in this hook as a starting point for
   1.807  	some more exotic Bugzilla integration recipes.  Here are a few
   1.808  	possibilities:
   1.809        </para>
   1.810        <itemizedlist>
   1.811 -	<listitem><para>Require that every changeset pushed to the
   1.812 +	<listitem><para id="x_24c">Require that every changeset pushed to the
   1.813  	    server have a valid bug ID in its commit comment.  In this
   1.814  	    case, you'd want to configure the hook as a <literal
   1.815  	      role="hook">pretxncommit</literal> hook.  This would
   1.816 @@ -881,7 +881,7 @@
   1.817  	    IDs.
   1.818  	  </para>
   1.819  	</listitem>
   1.820 -	<listitem><para>Allow incoming changesets to automatically
   1.821 +	<listitem><para id="x_24d">Allow incoming changesets to automatically
   1.822  	    modify the <emphasis>state</emphasis> of a bug, as well as
   1.823  	    simply adding a comment.  For example, the hook could
   1.824  	    recognise the string <quote>fixed bug 31337</quote> as
   1.825 @@ -894,7 +894,7 @@
   1.826  	<title>Configuring the <literal role="hook">bugzilla</literal>
   1.827  	  hook</title>
   1.828  
   1.829 -	<para>You should configure this hook in your server's
   1.830 +	<para id="x_24e">You should configure this hook in your server's
   1.831  	  <filename role="special">~/.hgrc</filename> as an <literal
   1.832  	    role="hook">incoming</literal> hook, for example as
   1.833  	  follows:
   1.834 @@ -902,25 +902,25 @@
   1.835  	<programlisting>[hooks]
   1.836  incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
   1.837  
   1.838 -	<para>Because of the specialised nature of this hook, and
   1.839 +	<para id="x_24f">Because of the specialised nature of this hook, and
   1.840  	  because Bugzilla was not written with this kind of
   1.841  	  integration in mind, configuring this hook is a somewhat
   1.842  	  involved process.
   1.843  	</para>
   1.844  
   1.845 -	<para>Before you begin, you must install the MySQL bindings
   1.846 +	<para id="x_250">Before you begin, you must install the MySQL bindings
   1.847  	  for Python on the host(s) where you'll be running the hook.
   1.848  	  If this is not available as a binary package for your
   1.849  	  system, you can download it from
   1.850  	  <citation>web:mysql-python</citation>.
   1.851  	</para>
   1.852  
   1.853 -	<para>Configuration information for this hook lives in the
   1.854 +	<para id="x_251">Configuration information for this hook lives in the
   1.855  	  <literal role="rc-bugzilla">bugzilla</literal> section of
   1.856  	  your <filename role="special">~/.hgrc</filename>.
   1.857  	</para>
   1.858  	<itemizedlist>
   1.859 -	  <listitem><para><envar
   1.860 +	  <listitem><para id="x_252"><envar
   1.861  		role="rc-item-bugzilla">version</envar>: The version
   1.862  	      of Bugzilla installed on the server.  The database
   1.863  	      schema that Bugzilla uses changes occasionally, so this
   1.864 @@ -929,14 +929,14 @@
   1.865  	      <literal>2.16</literal>.
   1.866  	    </para>
   1.867  	  </listitem>
   1.868 -	  <listitem><para><envar role="rc-item-bugzilla">host</envar>:
   1.869 +	  <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>:
   1.870  	      The hostname of the MySQL server that stores your
   1.871  	      Bugzilla data.  The database must be configured to allow
   1.872  	      connections from whatever host you are running the
   1.873  	      <literal role="hook">bugzilla</literal> hook on.
   1.874  	    </para>
   1.875  	  </listitem>
   1.876 -	  <listitem><para><envar role="rc-item-bugzilla">user</envar>:
   1.877 +	  <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>:
   1.878  	      The username with which to connect to the MySQL server.
   1.879  	      The database must be configured to allow this user to
   1.880  	      connect from whatever host you are running the <literal
   1.881 @@ -947,7 +947,7 @@
   1.882  	      MySQL database.
   1.883  	    </para>
   1.884  	  </listitem>
   1.885 -	  <listitem><para><envar
   1.886 +	  <listitem><para id="x_255"><envar
   1.887  		role="rc-item-bugzilla">password</envar>: The MySQL
   1.888  	      password for the user you configured above.  This is
   1.889  	      stored as plain text, so you should make sure that
   1.890 @@ -956,14 +956,14 @@
   1.891  	      store this information.
   1.892  	    </para>
   1.893  	  </listitem>
   1.894 -	  <listitem><para><envar role="rc-item-bugzilla">db</envar>:
   1.895 +	  <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>:
   1.896  	      The name of the Bugzilla database on the MySQL server.
   1.897  	      The default value of this item is
   1.898  	      <literal>bugs</literal>, which is the standard name of
   1.899  	      the MySQL database where Bugzilla stores its data.
   1.900  	    </para>
   1.901  	  </listitem>
   1.902 -	  <listitem><para><envar
   1.903 +	  <listitem><para id="x_257"><envar
   1.904  		role="rc-item-bugzilla">notify</envar>: If you want
   1.905  	      Bugzilla to send out a notification email to subscribers
   1.906  	      after this hook has added a comment to a bug, you will
   1.907 @@ -976,7 +976,7 @@
   1.908  	    <programlisting>cd /var/www/html/bugzilla &amp;&amp;
   1.909  	      ./processmail %s nobody@nowhere.com</programlisting>
   1.910  	  </listitem>
   1.911 -	  <listitem><para>  The Bugzilla
   1.912 +	  <listitem><para id="x_258">  The Bugzilla
   1.913  	      <literal>processmail</literal> program expects to be
   1.914  	      given a bug ID (the hook replaces
   1.915  	      <quote><literal>%s</literal></quote> with the bug ID)
   1.916 @@ -993,7 +993,7 @@
   1.917        <sect3>
   1.918  	<title>Mapping committer names to Bugzilla user names</title>
   1.919  
   1.920 -	<para>By default, the <literal
   1.921 +	<para id="x_259">By default, the <literal
   1.922  	    role="hg-ext">bugzilla</literal> hook tries to use the
   1.923  	  email address of a changeset's committer as the Bugzilla
   1.924  	  user name with which to update a bug.  If this does not suit
   1.925 @@ -1002,14 +1002,14 @@
   1.926  	    role="rc-usermap">usermap</literal> section.
   1.927  	</para>
   1.928  
   1.929 -	<para>Each item in the <literal
   1.930 +	<para id="x_25a">Each item in the <literal
   1.931  	    role="rc-usermap">usermap</literal> section contains an
   1.932  	  email address on the left, and a Bugzilla user name on the
   1.933  	  right.
   1.934  	</para>
   1.935  	<programlisting>[usermap]
   1.936  jane.user@example.com = jane</programlisting>
   1.937 -	<para>You can either keep the <literal
   1.938 +	<para id="x_25b">You can either keep the <literal
   1.939  	    role="rc-usermap">usermap</literal> data in a normal
   1.940  	  <filename role="special">~/.hgrc</filename>, or tell the
   1.941  	  <literal role="hg-ext">bugzilla</literal> hook to read the
   1.942 @@ -1025,7 +1025,7 @@
   1.943  	<programlisting># regular hgrc file refers to external usermap file
   1.944  [bugzilla]
   1.945  usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
   1.946 -	<para>While the <filename>usermap</filename> file that it
   1.947 +	<para id="x_25c">While the <filename>usermap</filename> file that it
   1.948  	  refers to might look like this:
   1.949  	</para>
   1.950  	<programlisting># bugzilla-usermap.conf - inside a hg repository
   1.951 @@ -1035,14 +1035,14 @@
   1.952        <sect3>
   1.953  	<title>Configuring the text that gets added to a bug</title>
   1.954  
   1.955 -	<para>You can configure the text that this hook adds as a
   1.956 +	<para id="x_25d">You can configure the text that this hook adds as a
   1.957  	  comment; you specify it in the form of a Mercurial template.
   1.958  	  Several <filename role="special">~/.hgrc</filename> entries
   1.959  	  (still in the <literal role="rc-bugzilla">bugzilla</literal>
   1.960  	  section) control this behaviour.
   1.961  	</para>
   1.962  	<itemizedlist>
   1.963 -	  <listitem><para><literal>strip</literal>: The number of
   1.964 +	  <listitem><para id="x_25e"><literal>strip</literal>: The number of
   1.965  	      leading path elements to strip from a repository's path
   1.966  	      name to construct a partial path for a URL. For example,
   1.967  	      if the repositories on your server live under <filename
   1.968 @@ -1056,7 +1056,7 @@
   1.969  	      expanding a template, as <literal>webroot</literal>.
   1.970  	    </para>
   1.971  	  </listitem>
   1.972 -	  <listitem><para><literal>template</literal>: The text of the
   1.973 +	  <listitem><para id="x_25f"><literal>template</literal>: The text of the
   1.974  	      template to use.  In addition to the usual
   1.975  	      changeset-related variables, this template can use
   1.976  	      <literal>hgweb</literal> (the value of the
   1.977 @@ -1066,7 +1066,7 @@
   1.978  	    </para>
   1.979  	  </listitem></itemizedlist>
   1.980  
   1.981 -	<para>In addition, you can add a <envar
   1.982 +	<para id="x_260">In addition, you can add a <envar
   1.983  	    role="rc-item-web">baseurl</envar> item to the <literal
   1.984  	    role="rc-web">web</literal> section of your <filename
   1.985  	    role="special">~/.hgrc</filename>.  The <literal
   1.986 @@ -1078,7 +1078,7 @@
   1.987  	<programlisting>[web]
   1.988  baseurl = http://hg.domain.com/</programlisting>
   1.989  
   1.990 -	<para>Here is an example set of <literal
   1.991 +	<para id="x_261">Here is an example set of <literal
   1.992  	    role="hg-ext">bugzilla</literal> hook config information.
   1.993  	</para>
   1.994  
   1.995 @@ -1088,13 +1088,13 @@
   1.996        <sect3>
   1.997  	<title>Testing and troubleshooting</title>
   1.998  
   1.999 -	<para>The most common problems with configuring the <literal
  1.1000 +	<para id="x_262">The most common problems with configuring the <literal
  1.1001  	    role="hg-ext">bugzilla</literal> hook relate to running
  1.1002  	  Bugzilla's <filename>processmail</filename> script and
  1.1003  	  mapping committer names to user names.
  1.1004  	</para>
  1.1005  
  1.1006 -	<para>Recall from section <xref
  1.1007 +	<para id="x_263">Recall from section <xref
  1.1008  	    linkend="sec:hook:bugzilla:config"/> above that the user
  1.1009  	  that runs the Mercurial process on the server is also the
  1.1010  	  one that will run the <filename>processmail</filename>
  1.1011 @@ -1105,19 +1105,19 @@
  1.1012  	  under.
  1.1013  	</para>
  1.1014  
  1.1015 -	<para>You can cause <filename>processmail</filename> to be run
  1.1016 +	<para id="x_264">You can cause <filename>processmail</filename> to be run
  1.1017  	  with the suitable user's identity using the
  1.1018  	  <command>sudo</command> command.  Here is an example entry
  1.1019  	  for a <filename>sudoers</filename> file.
  1.1020  	</para>
  1.1021  	<programlisting>hg_user = (httpd_user)
  1.1022  NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
  1.1023 -	<para>This allows the <literal>hg_user</literal> user to run a
  1.1024 +	<para id="x_265">This allows the <literal>hg_user</literal> user to run a
  1.1025  	  <filename>processmail-wrapper</filename> program under the
  1.1026  	  identity of <literal>httpd_user</literal>.
  1.1027  	</para>
  1.1028  
  1.1029 -	<para>This indirection through a wrapper script is necessary,
  1.1030 +	<para id="x_266">This indirection through a wrapper script is necessary,
  1.1031  	  because <filename>processmail</filename> expects to be run
  1.1032  	  with its current directory set to wherever you installed
  1.1033  	  Bugzilla; you can't specify that kind of constraint in a
  1.1034 @@ -1126,18 +1126,18 @@
  1.1035  	</para>
  1.1036  	<programlisting>#!/bin/sh
  1.1037  cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com</programlisting>
  1.1038 -	<para>It doesn't seem to matter what email address you pass to
  1.1039 +	<para id="x_267">It doesn't seem to matter what email address you pass to
  1.1040  	  <filename>processmail</filename>.
  1.1041  	</para>
  1.1042  
  1.1043 -	<para>If your <literal role="rc-usermap">usermap</literal> is
  1.1044 +	<para id="x_268">If your <literal role="rc-usermap">usermap</literal> is
  1.1045  	  not set up correctly, users will see an error message from
  1.1046  	  the <literal role="hg-ext">bugzilla</literal> hook when they
  1.1047  	  push changes to the server.  The error message will look
  1.1048  	  like this:
  1.1049  	</para>
  1.1050  	<programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting>
  1.1051 -	<para>What this means is that the committer's address,
  1.1052 +	<para id="x_269">What this means is that the committer's address,
  1.1053  	  <literal>john.q.public@example.com</literal>, is not a valid
  1.1054  	  Bugzilla user name, nor does it have an entry in your
  1.1055  	  <literal role="rc-usermap">usermap</literal> that maps it to
  1.1056 @@ -1150,7 +1150,7 @@
  1.1057        <title><literal role="hg-ext">notify</literal>&emdash;send email
  1.1058  	notifications</title>
  1.1059  
  1.1060 -      <para>Although Mercurial's built-in web server provides RSS
  1.1061 +      <para id="x_26a">Although Mercurial's built-in web server provides RSS
  1.1062  	feeds of changes in every repository, many people prefer to
  1.1063  	receive change notifications via email.  The <literal
  1.1064  	  role="hg-ext">notify</literal> hook lets you send out
  1.1065 @@ -1158,13 +1158,13 @@
  1.1066  	arrive that those subscribers are interested in.
  1.1067        </para>
  1.1068  
  1.1069 -      <para>As with the <literal role="hg-ext">bugzilla</literal>
  1.1070 +      <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal>
  1.1071  	hook, the <literal role="hg-ext">notify</literal> hook is
  1.1072  	template-driven, so you can customise the contents of the
  1.1073  	notification messages that it sends.
  1.1074        </para>
  1.1075  
  1.1076 -      <para>By default, the <literal role="hg-ext">notify</literal>
  1.1077 +      <para id="x_26c">By default, the <literal role="hg-ext">notify</literal>
  1.1078  	hook includes a diff of every changeset that it sends out; you
  1.1079  	can limit the size of the diff, or turn this feature off
  1.1080  	entirely.  It is useful for letting subscribers review changes
  1.1081 @@ -1175,7 +1175,7 @@
  1.1082  	<title>Configuring the <literal role="hg-ext">notify</literal>
  1.1083  	  hook</title>
  1.1084  
  1.1085 -	<para>You can set up the <literal
  1.1086 +	<para id="x_26d">You can set up the <literal
  1.1087  	    role="hg-ext">notify</literal> hook to send one email
  1.1088  	  message per incoming changeset, or one per incoming group of
  1.1089  	  changesets (all those that arrived in a single pull or
  1.1090 @@ -1187,12 +1187,12 @@
  1.1091  # send one email per change
  1.1092  incoming.notify = python:hgext.notify.hook</programlisting>
  1.1093  
  1.1094 -	<para>Configuration information for this hook lives in the
  1.1095 +	<para id="x_26e">Configuration information for this hook lives in the
  1.1096  	  <literal role="rc-notify">notify</literal> section of a
  1.1097  	  <filename role="special">~/.hgrc</filename> file.
  1.1098  	</para>
  1.1099  	<itemizedlist>
  1.1100 -	  <listitem><para><envar role="rc-item-notify">test</envar>:
  1.1101 +	  <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>:
  1.1102  	      By default, this hook does not send out email at all;
  1.1103  	      instead, it prints the message that it
  1.1104  	      <emphasis>would</emphasis> send.  Set this item to
  1.1105 @@ -1204,7 +1204,7 @@
  1.1106  	      notifications while you debug your configuration.
  1.1107  	    </para>
  1.1108  	  </listitem>
  1.1109 -	  <listitem><para><envar role="rc-item-notify">config</envar>:
  1.1110 +	  <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>:
  1.1111  	      The path to a configuration file that contains
  1.1112  	      subscription information.  This is kept separate from
  1.1113  	      the main <filename role="special">~/.hgrc</filename> so
  1.1114 @@ -1213,7 +1213,7 @@
  1.1115  	      subscriptions, and push the changes back to your server.
  1.1116  	    </para>
  1.1117  	  </listitem>
  1.1118 -	  <listitem><para><envar role="rc-item-notify">strip</envar>:
  1.1119 +	  <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>:
  1.1120  	      The number of leading path separator characters to strip
  1.1121  	      from a repository's path, when deciding whether a
  1.1122  	      repository has subscribers.  For example, if the
  1.1123 @@ -1230,13 +1230,13 @@
  1.1124  	      match subscribers against that.
  1.1125  	    </para>
  1.1126  	  </listitem>
  1.1127 -	  <listitem><para><envar
  1.1128 +	  <listitem><para id="x_272"><envar
  1.1129  		role="rc-item-notify">template</envar>: The template
  1.1130  	      text to use when sending messages.  This specifies both
  1.1131  	      the contents of the message header and its body.
  1.1132  	    </para>
  1.1133  	  </listitem>
  1.1134 -	  <listitem><para><envar
  1.1135 +	  <listitem><para id="x_273"><envar
  1.1136  		role="rc-item-notify">maxdiff</envar>: The maximum
  1.1137  	      number of lines of diff data to append to the end of a
  1.1138  	      message.  If a diff is longer than this, it is
  1.1139 @@ -1245,7 +1245,7 @@
  1.1140  	      emails.
  1.1141  	    </para>
  1.1142  	  </listitem>
  1.1143 -	  <listitem><para><envar
  1.1144 +	  <listitem><para id="x_274"><envar
  1.1145  		role="rc-item-notify">sources</envar>: A list of
  1.1146  	      sources of changesets to consider.  This lets you limit
  1.1147  	      <literal role="hg-ext">notify</literal> to only sending
  1.1148 @@ -1257,19 +1257,19 @@
  1.1149  	    </para>
  1.1150  	  </listitem></itemizedlist>
  1.1151  
  1.1152 -	<para>If you set the <envar role="rc-item-web">baseurl</envar>
  1.1153 +	<para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar>
  1.1154  	  item in the <literal role="rc-web">web</literal> section,
  1.1155  	  you can use it in a template; it will be available as
  1.1156  	  <literal>webroot</literal>.
  1.1157  	</para>
  1.1158  
  1.1159 -	<para>Here is an example set of <literal
  1.1160 +	<para id="x_276">Here is an example set of <literal
  1.1161  	    role="hg-ext">notify</literal> configuration information.
  1.1162  	</para>
  1.1163  
  1.1164  	&ch10-notify-config.lst;
  1.1165  
  1.1166 -	<para>This will produce a message that looks like the
  1.1167 +	<para id="x_277">This will produce a message that looks like the
  1.1168  	  following:
  1.1169  	</para>
  1.1170  
  1.1171 @@ -1279,7 +1279,7 @@
  1.1172        <sect3>
  1.1173  	<title>Testing and troubleshooting</title>
  1.1174  
  1.1175 -	<para>Do not forget that by default, the <literal
  1.1176 +	<para id="x_278">Do not forget that by default, the <literal
  1.1177  		role="hg-ext">notify</literal> extension <emphasis>will not
  1.1178  	  send any mail</emphasis> until you explicitly configure it to do so,
  1.1179  	  by setting <envar role="rc-item-notify">test</envar> to
  1.1180 @@ -1296,11 +1296,11 @@
  1.1181      <sect2>
  1.1182        <title>In-process hook execution</title>
  1.1183  
  1.1184 -      <para>An in-process hook is called with arguments of the
  1.1185 +      <para id="x_279">An in-process hook is called with arguments of the
  1.1186  	following form:
  1.1187        </para>
  1.1188        <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting>
  1.1189 -      <para>The <literal>ui</literal> parameter is a <literal
  1.1190 +      <para id="x_27a">The <literal>ui</literal> parameter is a <literal
  1.1191  	  role="py-mod-mercurial.ui">ui</literal> object. The
  1.1192  	<literal>repo</literal> parameter is a <literal
  1.1193  	  role="py-mod-mercurial.localrepo">localrepository</literal>
  1.1194 @@ -1309,38 +1309,38 @@
  1.1195  	being invoked, with the following common features:
  1.1196        </para>
  1.1197        <itemizedlist>
  1.1198 -	<listitem><para>If a parameter is named
  1.1199 +	<listitem><para id="x_27b">If a parameter is named
  1.1200  	    <literal>node</literal> or <literal>parentN</literal>, it
  1.1201  	    will contain a hexadecimal changeset ID. The empty string
  1.1202  	    is used to represent <quote>null changeset ID</quote>
  1.1203  	    instead of a string of zeroes.
  1.1204  	  </para>
  1.1205  	</listitem>
  1.1206 -	<listitem><para>If a parameter is named
  1.1207 +	<listitem><para id="x_27c">If a parameter is named
  1.1208  	    <literal>url</literal>, it will contain the URL of a
  1.1209  	    remote repository, if that can be determined.
  1.1210  	  </para>
  1.1211  	</listitem>
  1.1212 -	<listitem><para>Boolean-valued parameters are represented as
  1.1213 +	<listitem><para id="x_27d">Boolean-valued parameters are represented as
  1.1214  	    Python <literal>bool</literal> objects.
  1.1215  	  </para>
  1.1216  	</listitem></itemizedlist>
  1.1217  
  1.1218 -      <para>An in-process hook is called without a change to the
  1.1219 +      <para id="x_27e">An in-process hook is called without a change to the
  1.1220  	process's working directory (unlike external hooks, which are
  1.1221  	run in the root of the repository).  It must not change the
  1.1222  	process's working directory, or it will cause any calls it
  1.1223  	makes into the Mercurial API to fail.
  1.1224        </para>
  1.1225  
  1.1226 -      <para>If a hook returns a boolean <quote>false</quote> value, it
  1.1227 +      <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it
  1.1228  	is considered to have succeeded.  If it returns a boolean
  1.1229  	<quote>true</quote> value or raises an exception, it is
  1.1230  	considered to have failed.  A useful way to think of the
  1.1231  	calling convention is <quote>tell me if you fail</quote>.
  1.1232        </para>
  1.1233  
  1.1234 -      <para>Note that changeset IDs are passed into Python hooks as
  1.1235 +      <para id="x_280">Note that changeset IDs are passed into Python hooks as
  1.1236  	hexadecimal strings, not the binary hashes that Mercurial's
  1.1237  	APIs normally use.  To convert a hash from hex to binary, use
  1.1238  	the <literal>bin</literal> function.
  1.1239 @@ -1350,7 +1350,7 @@
  1.1240      <sect2>
  1.1241        <title>External hook execution</title>
  1.1242  
  1.1243 -      <para>An external hook is passed to the shell of the user
  1.1244 +      <para id="x_281">An external hook is passed to the shell of the user
  1.1245  	running Mercurial. Features of that shell, such as variable
  1.1246  	substitution and command redirection, are available.  The hook
  1.1247  	is run in the root directory of the repository (unlike
  1.1248 @@ -1358,7 +1358,7 @@
  1.1249  	Mercurial was run in).
  1.1250        </para>
  1.1251  
  1.1252 -      <para>Hook parameters are passed to the hook as environment
  1.1253 +      <para id="x_282">Hook parameters are passed to the hook as environment
  1.1254  	variables.  Each environment variable's name is converted in
  1.1255  	upper case and prefixed with the string
  1.1256  	<quote><literal>HG_</literal></quote>.  For example, if the
  1.1257 @@ -1367,7 +1367,7 @@
  1.1258  	parameter will be <quote><literal>HG_NODE</literal></quote>.
  1.1259        </para>
  1.1260  
  1.1261 -      <para>A boolean parameter is represented as the string
  1.1262 +      <para id="x_283">A boolean parameter is represented as the string
  1.1263  	<quote><literal>1</literal></quote> for <quote>true</quote>,
  1.1264  	<quote><literal>0</literal></quote> for <quote>false</quote>.
  1.1265  	If an environment variable is named <envar>HG_NODE</envar>,
  1.1266 @@ -1379,7 +1379,7 @@
  1.1267  	URL of a remote repository, if that can be determined.
  1.1268        </para>
  1.1269  
  1.1270 -      <para>If a hook exits with a status of zero, it is considered to
  1.1271 +      <para id="x_284">If a hook exits with a status of zero, it is considered to
  1.1272  	have succeeded.  If it exits with a non-zero status, it is
  1.1273  	considered to have failed.
  1.1274        </para>
  1.1275 @@ -1388,7 +1388,7 @@
  1.1276      <sect2>
  1.1277        <title>Finding out where changesets come from</title>
  1.1278  
  1.1279 -      <para>A hook that involves the transfer of changesets between a
  1.1280 +      <para id="x_285">A hook that involves the transfer of changesets between a
  1.1281  	local repository and another may be able to find out
  1.1282  	information about the <quote>far side</quote>.  Mercurial
  1.1283  	knows <emphasis>how</emphasis> changes are being transferred,
  1.1284 @@ -1399,7 +1399,7 @@
  1.1285        <sect3 id="sec:hook:sources">
  1.1286  	<title>Sources of changesets</title>
  1.1287  
  1.1288 -	<para>Mercurial will tell a hook what means are, or were, used
  1.1289 +	<para id="x_286">Mercurial will tell a hook what means are, or were, used
  1.1290  	  to transfer changesets between repositories.  This is
  1.1291  	  provided by Mercurial in a Python parameter named
  1.1292  	  <literal>source</literal>, or an environment variable named
  1.1293 @@ -1407,22 +1407,22 @@
  1.1294  	</para>
  1.1295  
  1.1296  	<itemizedlist>
  1.1297 -	  <listitem><para><literal>serve</literal>: Changesets are
  1.1298 +	  <listitem><para id="x_287"><literal>serve</literal>: Changesets are
  1.1299  	      transferred to or from a remote repository over http or
  1.1300  	      ssh.
  1.1301  	    </para>
  1.1302  	  </listitem>
  1.1303 -	  <listitem><para><literal>pull</literal>: Changesets are
  1.1304 +	  <listitem><para id="x_288"><literal>pull</literal>: Changesets are
  1.1305  	      being transferred via a pull from one repository into
  1.1306  	      another.
  1.1307  	    </para>
  1.1308  	  </listitem>
  1.1309 -	  <listitem><para><literal>push</literal>: Changesets are
  1.1310 +	  <listitem><para id="x_289"><literal>push</literal>: Changesets are
  1.1311  	      being transferred via a push from one repository into
  1.1312  	      another.
  1.1313  	    </para>
  1.1314  	  </listitem>
  1.1315 -	  <listitem><para><literal>bundle</literal>: Changesets are
  1.1316 +	  <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are
  1.1317  	      being transferred to or from a bundle.
  1.1318  	    </para>
  1.1319  	  </listitem></itemizedlist>
  1.1320 @@ -1432,7 +1432,7 @@
  1.1321  	<title>Where changes are going&emdash;remote repository
  1.1322  	  URLs</title>
  1.1323  
  1.1324 -	<para>When possible, Mercurial will tell a hook the location
  1.1325 +	<para id="x_28b">When possible, Mercurial will tell a hook the location
  1.1326  	  of the <quote>far side</quote> of an activity that transfers
  1.1327  	  changeset data between repositories.  This is provided by
  1.1328  	  Mercurial in a Python parameter named
  1.1329 @@ -1440,26 +1440,26 @@
  1.1330  	  <envar>HG_URL</envar>.
  1.1331  	</para>
  1.1332  
  1.1333 -	<para>This information is not always known.  If a hook is
  1.1334 +	<para id="x_28c">This information is not always known.  If a hook is
  1.1335  	  invoked in a repository that is being served via http or
  1.1336  	  ssh, Mercurial cannot tell where the remote repository is,
  1.1337  	  but it may know where the client is connecting from.  In
  1.1338  	  such cases, the URL will take one of the following forms:
  1.1339  	</para>
  1.1340  	<itemizedlist>
  1.1341 -	  <listitem><para><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 
  1.1342 +	  <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 
  1.1343  	      ssh client, at the IP address
  1.1344  	      <literal>1.2.3.4</literal>.
  1.1345  	    </para>
  1.1346  	  </listitem>
  1.1347 -	  <listitem><para><literal>remote:http:1.2.3.4</literal>&emdash;remote 
  1.1348 +	  <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote 
  1.1349  	      http client, at the IP address
  1.1350  	      <literal>1.2.3.4</literal>.  If the client is using SSL,
  1.1351  	      this will be of the form
  1.1352  	      <literal>remote:https:1.2.3.4</literal>.
  1.1353  	    </para>
  1.1354  	  </listitem>
  1.1355 -	  <listitem><para>Empty&emdash;no information could be
  1.1356 +	  <listitem><para id="x_28f">Empty&emdash;no information could be
  1.1357  	      discovered about the remote client.
  1.1358  	    </para>
  1.1359  	  </listitem></itemizedlist>
  1.1360 @@ -1474,7 +1474,7 @@
  1.1361        <title><literal role="hook">changegroup</literal>&emdash;after
  1.1362  	remote changesets added</title>
  1.1363  
  1.1364 -      <para>This hook is run after a group of pre-existing changesets
  1.1365 +      <para id="x_290">This hook is run after a group of pre-existing changesets
  1.1366  	has been added to the repository, for example via a <command
  1.1367  	  role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg
  1.1368  	  unbundle</command>.  This hook is run once per operation
  1.1369 @@ -1484,16 +1484,16 @@
  1.1370  	arrive in a group.
  1.1371        </para>
  1.1372  
  1.1373 -      <para>Some possible uses for this hook include kicking off an
  1.1374 +      <para id="x_291">Some possible uses for this hook include kicking off an
  1.1375  	automated build or test of the added changesets, updating a
  1.1376  	bug database, or notifying subscribers that a repository
  1.1377  	contains new changes.
  1.1378        </para>
  1.1379  
  1.1380 -      <para>Parameters to this hook:
  1.1381 +      <para id="x_292">Parameters to this hook:
  1.1382        </para>
  1.1383        <itemizedlist>
  1.1384 -	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1385 +	<listitem><para id="x_293"><literal>node</literal>: A changeset ID.  The
  1.1386  	    changeset ID of the first changeset in the group that was
  1.1387  	    added.  All changesets between this and
  1.1388  	    <literal role="tag">tip</literal>, inclusive, were added by a single
  1.1389 @@ -1502,19 +1502,19 @@
  1.1390  	      role="hg-cmd">hg unbundle</command>.
  1.1391  	  </para>
  1.1392  	</listitem>
  1.1393 -	<listitem><para><literal>source</literal>: A string.  The
  1.1394 +	<listitem><para id="x_294"><literal>source</literal>: A string.  The
  1.1395  	    source of these changes.  See section <xref
  1.1396  	      linkend="sec:hook:sources"/> for details.
  1.1397  	  </para>
  1.1398  	</listitem>
  1.1399 -	<listitem><para><literal>url</literal>: A URL.  The location
  1.1400 +	<listitem><para id="x_295"><literal>url</literal>: A URL.  The location
  1.1401  	    of the remote repository, if known.  See section <xref
  1.1402  	      linkend="sec:hook:url"/> for more
  1.1403  	    information.
  1.1404  	  </para>
  1.1405  	</listitem></itemizedlist>
  1.1406  
  1.1407 -      <para>See also: <literal role="hook">incoming</literal> (section
  1.1408 +      <para id="x_296">See also: <literal role="hook">incoming</literal> (section
  1.1409  	<xref linkend="sec:hook:incoming"/>), <literal
  1.1410  	  role="hook">prechangegroup</literal> (section <xref
  1.1411  	  linkend="sec:hook:prechangegroup"/>), <literal
  1.1412 @@ -1527,28 +1527,28 @@
  1.1413        <title><literal role="hook">commit</literal>&emdash;after a new
  1.1414  	changeset is created</title>
  1.1415  
  1.1416 -      <para>This hook is run after a new changeset has been created.
  1.1417 -      </para>
  1.1418 -
  1.1419 -      <para>Parameters to this hook:
  1.1420 +      <para id="x_297">This hook is run after a new changeset has been created.
  1.1421 +      </para>
  1.1422 +
  1.1423 +      <para id="x_298">Parameters to this hook:
  1.1424        </para>
  1.1425        <itemizedlist>
  1.1426 -	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1427 +	<listitem><para id="x_299"><literal>node</literal>: A changeset ID.  The
  1.1428  	    changeset ID of the newly committed changeset.
  1.1429  	  </para>
  1.1430  	</listitem>
  1.1431 -	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1432 +	<listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID.
  1.1433  	    The changeset ID of the first parent of the newly
  1.1434  	    committed changeset.
  1.1435  	  </para>
  1.1436  	</listitem>
  1.1437 -	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1438 +	<listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID.
  1.1439  	    The changeset ID of the second parent of the newly
  1.1440  	    committed changeset.
  1.1441  	  </para>
  1.1442  	</listitem></itemizedlist>
  1.1443  
  1.1444 -      <para>See also: <literal role="hook">precommit</literal>
  1.1445 +      <para id="x_29c">See also: <literal role="hook">precommit</literal>
  1.1446  	(section <xref linkend="sec:hook:precommit"/>), <literal
  1.1447  	  role="hook">pretxncommit</literal> (section <xref
  1.1448  	  linkend="sec:hook:pretxncommit"/>)
  1.1449 @@ -1559,40 +1559,40 @@
  1.1450        <title><literal role="hook">incoming</literal>&emdash;after one
  1.1451  	remote changeset is added</title>
  1.1452  
  1.1453 -      <para>This hook is run after a pre-existing changeset has been
  1.1454 +      <para id="x_29d">This hook is run after a pre-existing changeset has been
  1.1455  	added to the repository, for example via a <command
  1.1456  	  role="hg-cmd">hg push</command>.  If a group of changesets
  1.1457  	was added in a single operation, this hook is called once for
  1.1458  	each added changeset.
  1.1459        </para>
  1.1460  
  1.1461 -      <para>You can use this hook for the same purposes as the
  1.1462 +      <para id="x_29e">You can use this hook for the same purposes as the
  1.1463  	<literal role="hook">changegroup</literal> hook (section <xref
  1.1464  	  linkend="sec:hook:changegroup"/>); it's simply
  1.1465  	more convenient sometimes to run a hook once per group of
  1.1466  	changesets, while other times it's handier once per changeset.
  1.1467        </para>
  1.1468  
  1.1469 -      <para>Parameters to this hook:
  1.1470 +      <para id="x_29f">Parameters to this hook:
  1.1471        </para>
  1.1472        <itemizedlist>
  1.1473 -	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1474 +	<listitem><para id="x_2a0"><literal>node</literal>: A changeset ID.  The
  1.1475  	    ID of the newly added changeset.
  1.1476  	  </para>
  1.1477  	</listitem>
  1.1478 -	<listitem><para><literal>source</literal>: A string.  The
  1.1479 +	<listitem><para id="x_2a1"><literal>source</literal>: A string.  The
  1.1480  	    source of these changes.  See section <xref
  1.1481  	      linkend="sec:hook:sources"/> for details.
  1.1482  	  </para>
  1.1483  	</listitem>
  1.1484 -	<listitem><para><literal>url</literal>: A URL.  The location
  1.1485 +	<listitem><para id="x_2a2"><literal>url</literal>: A URL.  The location
  1.1486  	    of the remote repository, if known.  See section <xref
  1.1487  	      linkend="sec:hook:url"/> for more
  1.1488  	    information.
  1.1489  	  </para>
  1.1490  	</listitem></itemizedlist>
  1.1491  
  1.1492 -      <para>See also: <literal role="hook">changegroup</literal>
  1.1493 +      <para id="x_2a3">See also: <literal role="hook">changegroup</literal>
  1.1494  	(section <xref linkend="sec:hook:changegroup"/>) <literal
  1.1495  	  role="hook">prechangegroup</literal> (section <xref
  1.1496  	  linkend="sec:hook:prechangegroup"/>), <literal
  1.1497 @@ -1605,25 +1605,25 @@
  1.1498        <title><literal role="hook">outgoing</literal>&emdash;after
  1.1499  	changesets are propagated</title>
  1.1500  
  1.1501 -      <para>This hook is run after a group of changesets has been
  1.1502 +      <para id="x_2a4">This hook is run after a group of changesets has been
  1.1503  	propagated out of this repository, for example by a <command
  1.1504  	  role="hg-cmd">hg push</command> or <command role="hg-cmd">hg
  1.1505  	  bundle</command> command.
  1.1506        </para>
  1.1507  
  1.1508 -      <para>One possible use for this hook is to notify administrators
  1.1509 +      <para id="x_2a5">One possible use for this hook is to notify administrators
  1.1510  	that changes have been pulled.
  1.1511        </para>
  1.1512  
  1.1513 -      <para>Parameters to this hook:
  1.1514 +      <para id="x_2a6">Parameters to this hook:
  1.1515        </para>
  1.1516        <itemizedlist>
  1.1517 -	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1518 +	<listitem><para id="x_2a7"><literal>node</literal>: A changeset ID.  The
  1.1519  	    changeset ID of the first changeset of the group that was
  1.1520  	    sent.
  1.1521  	  </para>
  1.1522  	</listitem>
  1.1523 -	<listitem><para><literal>source</literal>: A string.  The
  1.1524 +	<listitem><para id="x_2a8"><literal>source</literal>: A string.  The
  1.1525  	    source of the of the operation (see section <xref
  1.1526  	      linkend="sec:hook:sources"/>).  If a remote
  1.1527  	    client pulled changes from this repository,
  1.1528 @@ -1636,14 +1636,14 @@
  1.1529  	    client performed.
  1.1530  	  </para>
  1.1531  	</listitem>
  1.1532 -	<listitem><para><literal>url</literal>: A URL.  The location
  1.1533 +	<listitem><para id="x_2a9"><literal>url</literal>: A URL.  The location
  1.1534  	    of the remote repository, if known.  See section <xref
  1.1535  	      linkend="sec:hook:url"/> for more
  1.1536  	    information.
  1.1537  	  </para>
  1.1538  	</listitem></itemizedlist>
  1.1539  
  1.1540 -      <para>See also: <literal role="hook">preoutgoing</literal>
  1.1541 +      <para id="x_2aa">See also: <literal role="hook">preoutgoing</literal>
  1.1542  	(section <xref linkend="sec:hook:preoutgoing"/>)
  1.1543        </para>
  1.1544  
  1.1545 @@ -1653,39 +1653,39 @@
  1.1546  	  role="hook">prechangegroup</literal>&emdash;before starting
  1.1547  	to add remote changesets</title>
  1.1548  
  1.1549 -      <para>This controlling hook is run before Mercurial begins to
  1.1550 +      <para id="x_2ab">This controlling hook is run before Mercurial begins to
  1.1551  	add a group of changesets from another repository.
  1.1552        </para>
  1.1553  
  1.1554 -      <para>This hook does not have any information about the
  1.1555 +      <para id="x_2ac">This hook does not have any information about the
  1.1556  	changesets to be added, because it is run before transmission
  1.1557  	of those changesets is allowed to begin.  If this hook fails,
  1.1558  	the changesets will not be transmitted.
  1.1559        </para>
  1.1560  
  1.1561 -      <para>One use for this hook is to prevent external changes from
  1.1562 +      <para id="x_2ad">One use for this hook is to prevent external changes from
  1.1563  	being added to a repository.  For example, you could use this
  1.1564  	to <quote>freeze</quote> a server-hosted branch temporarily or
  1.1565  	permanently so that users cannot push to it, while still
  1.1566  	allowing a local administrator to modify the repository.
  1.1567        </para>
  1.1568  
  1.1569 -      <para>Parameters to this hook:
  1.1570 +      <para id="x_2ae">Parameters to this hook:
  1.1571        </para>
  1.1572        <itemizedlist>
  1.1573 -	<listitem><para><literal>source</literal>: A string.  The
  1.1574 +	<listitem><para id="x_2af"><literal>source</literal>: A string.  The
  1.1575  	    source of these changes.  See section <xref
  1.1576  	      linkend="sec:hook:sources"/> for details.
  1.1577  	  </para>
  1.1578  	</listitem>
  1.1579 -	<listitem><para><literal>url</literal>: A URL.  The location
  1.1580 +	<listitem><para id="x_2b0"><literal>url</literal>: A URL.  The location
  1.1581  	    of the remote repository, if known.  See section <xref
  1.1582  	      linkend="sec:hook:url"/> for more
  1.1583  	    information.
  1.1584  	  </para>
  1.1585  	</listitem></itemizedlist>
  1.1586  
  1.1587 -      <para>See also: <literal role="hook">changegroup</literal>
  1.1588 +      <para id="x_2b1">See also: <literal role="hook">changegroup</literal>
  1.1589  	(section <xref linkend="sec:hook:changegroup"/>), <literal
  1.1590  	  role="hook">incoming</literal> (section <xref
  1.1591  	  linkend="sec:hook:incoming"/>), , <literal
  1.1592 @@ -1698,36 +1698,36 @@
  1.1593        <title><literal role="hook">precommit</literal>&emdash;before
  1.1594  	starting to commit a changeset</title>
  1.1595  
  1.1596 -      <para>This hook is run before Mercurial begins to commit a new
  1.1597 +      <para id="x_2b2">This hook is run before Mercurial begins to commit a new
  1.1598  	changeset. It is run before Mercurial has any of the metadata
  1.1599  	for the commit, such as the files to be committed, the commit
  1.1600  	message, or the commit date.
  1.1601        </para>
  1.1602  
  1.1603 -      <para>One use for this hook is to disable the ability to commit
  1.1604 +      <para id="x_2b3">One use for this hook is to disable the ability to commit
  1.1605  	new changesets, while still allowing incoming changesets.
  1.1606  	Another is to run a build or test, and only allow the commit
  1.1607  	to begin if the build or test succeeds.
  1.1608        </para>
  1.1609  
  1.1610 -      <para>Parameters to this hook:
  1.1611 +      <para id="x_2b4">Parameters to this hook:
  1.1612        </para>
  1.1613        <itemizedlist>
  1.1614 -	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1615 +	<listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID.
  1.1616  	    The changeset ID of the first parent of the working
  1.1617  	    directory.
  1.1618  	  </para>
  1.1619  	</listitem>
  1.1620 -	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1621 +	<listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID.
  1.1622  	    The changeset ID of the second parent of the working
  1.1623  	    directory.
  1.1624  	  </para>
  1.1625  	</listitem></itemizedlist>
  1.1626 -      <para>If the commit proceeds, the parents of the working
  1.1627 +      <para id="x_2b7">If the commit proceeds, the parents of the working
  1.1628  	directory will become the parents of the new changeset.
  1.1629        </para>
  1.1630  
  1.1631 -      <para>See also: <literal role="hook">commit</literal> (section
  1.1632 +      <para id="x_2b8">See also: <literal role="hook">commit</literal> (section
  1.1633  	<xref linkend="sec:hook:commit"/>), <literal
  1.1634  	  role="hook">pretxncommit</literal> (section <xref
  1.1635  	  linkend="sec:hook:pretxncommit"/>)
  1.1636 @@ -1738,18 +1738,18 @@
  1.1637        <title><literal role="hook">preoutgoing</literal>&emdash;before
  1.1638  	starting to propagate changesets</title>
  1.1639  
  1.1640 -      <para>This hook is invoked before Mercurial knows the identities
  1.1641 +      <para id="x_2b9">This hook is invoked before Mercurial knows the identities
  1.1642  	of the changesets to be transmitted.
  1.1643        </para>
  1.1644  
  1.1645 -      <para>One use for this hook is to prevent changes from being
  1.1646 +      <para id="x_2ba">One use for this hook is to prevent changes from being
  1.1647  	transmitted to another repository.
  1.1648        </para>
  1.1649  
  1.1650 -      <para>Parameters to this hook:
  1.1651 +      <para id="x_2bb">Parameters to this hook:
  1.1652        </para>
  1.1653        <itemizedlist>
  1.1654 -	<listitem><para><literal>source</literal>: A string.  The
  1.1655 +	<listitem><para id="x_2bc"><literal>source</literal>: A string.  The
  1.1656  	    source of the operation that is attempting to obtain
  1.1657  	    changes from this repository (see section <xref
  1.1658  	      linkend="sec:hook:sources"/>).  See the documentation
  1.1659 @@ -1760,14 +1760,14 @@
  1.1660  	    this parameter.
  1.1661  	  </para>
  1.1662  	</listitem>
  1.1663 -	<listitem><para><literal>url</literal>: A URL.  The location
  1.1664 +	<listitem><para id="x_2bd"><literal>url</literal>: A URL.  The location
  1.1665  	    of the remote repository, if known.  See section <xref
  1.1666  	      linkend="sec:hook:url"/> for more
  1.1667  	    information.
  1.1668  	  </para>
  1.1669  	</listitem></itemizedlist>
  1.1670  
  1.1671 -      <para>See also: <literal role="hook">outgoing</literal> (section
  1.1672 +      <para id="x_2be">See also: <literal role="hook">outgoing</literal> (section
  1.1673  	<xref linkend="sec:hook:outgoing"/>)
  1.1674        </para>
  1.1675  
  1.1676 @@ -1776,38 +1776,38 @@
  1.1677        <title><literal role="hook">pretag</literal>&emdash;before
  1.1678  	tagging a changeset</title>
  1.1679  
  1.1680 -      <para>This controlling hook is run before a tag is created.  If
  1.1681 +      <para id="x_2bf">This controlling hook is run before a tag is created.  If
  1.1682  	the hook succeeds, creation of the tag proceeds.  If the hook
  1.1683  	fails, the tag is not created.
  1.1684        </para>
  1.1685  
  1.1686 -      <para>Parameters to this hook:
  1.1687 +      <para id="x_2c0">Parameters to this hook:
  1.1688        </para>
  1.1689        <itemizedlist>
  1.1690 -	<listitem><para><literal>local</literal>: A boolean.  Whether
  1.1691 +	<listitem><para id="x_2c1"><literal>local</literal>: A boolean.  Whether
  1.1692  	    the tag is local to this repository instance (i.e. stored
  1.1693  	    in <filename role="special">.hg/localtags</filename>) or
  1.1694  	    managed by Mercurial (stored in <filename
  1.1695  	      role="special">.hgtags</filename>).
  1.1696  	  </para>
  1.1697  	</listitem>
  1.1698 -	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1699 +	<listitem><para id="x_2c2"><literal>node</literal>: A changeset ID.  The
  1.1700  	    ID of the changeset to be tagged.
  1.1701  	  </para>
  1.1702  	</listitem>
  1.1703 -	<listitem><para><literal>tag</literal>: A string.  The name of
  1.1704 +	<listitem><para id="x_2c3"><literal>tag</literal>: A string.  The name of
  1.1705  	    the tag to be created.
  1.1706  	  </para>
  1.1707  	</listitem></itemizedlist>
  1.1708  
  1.1709 -      <para>If the tag to be created is revision-controlled, the
  1.1710 +      <para id="x_2c4">If the tag to be created is revision-controlled, the
  1.1711  	<literal role="hook">precommit</literal> and <literal
  1.1712  	  role="hook">pretxncommit</literal> hooks (sections <xref
  1.1713  	  linkend="sec:hook:commit"/> and <xref
  1.1714  	  linkend="sec:hook:pretxncommit"/>) will also be run.
  1.1715        </para>
  1.1716  
  1.1717 -      <para>See also: <literal role="hook">tag</literal> (section
  1.1718 +      <para id="x_2c5">See also: <literal role="hook">tag</literal> (section
  1.1719  	<xref linkend="sec:hook:tag"/>)
  1.1720        </para>
  1.1721      </sect2>
  1.1722 @@ -1816,7 +1816,7 @@
  1.1723  	  role="hook">pretxnchangegroup</literal>&emdash;before
  1.1724  	completing addition of remote changesets</title>
  1.1725  
  1.1726 -      <para>This controlling hook is run before a
  1.1727 +      <para id="x_2c6">This controlling hook is run before a
  1.1728  	transaction&emdash;that manages the addition of a group of new
  1.1729  	changesets from outside the repository&emdash;completes.  If
  1.1730  	the hook succeeds, the transaction completes, and all of the
  1.1731 @@ -1825,28 +1825,28 @@
  1.1732  	the changesets is erased.
  1.1733        </para>
  1.1734  
  1.1735 -      <para>This hook can access the metadata associated with the
  1.1736 +      <para id="x_2c7">This hook can access the metadata associated with the
  1.1737  	almost-added changesets, but it should not do anything
  1.1738  	permanent with this data. It must also not modify the working
  1.1739  	directory.
  1.1740        </para>
  1.1741  
  1.1742 -      <para>While this hook is running, if other Mercurial processes
  1.1743 +      <para id="x_2c8">While this hook is running, if other Mercurial processes
  1.1744  	access this repository, they will be able to see the
  1.1745  	almost-added changesets as if they are permanent.  This may
  1.1746  	lead to race conditions if you do not take steps to avoid
  1.1747  	them.
  1.1748        </para>
  1.1749  
  1.1750 -      <para>This hook can be used to automatically vet a group of
  1.1751 +      <para id="x_2c9">This hook can be used to automatically vet a group of
  1.1752  	changesets.  If the hook fails, all of the changesets are
  1.1753  	<quote>rejected</quote> when the transaction rolls back.
  1.1754        </para>
  1.1755  
  1.1756 -      <para>Parameters to this hook:
  1.1757 +      <para id="x_2ca">Parameters to this hook:
  1.1758        </para>
  1.1759        <itemizedlist>
  1.1760 -	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1761 +	<listitem><para id="x_2cb"><literal>node</literal>: A changeset ID.  The
  1.1762  	    changeset ID of the first changeset in the group that was
  1.1763  	    added.  All changesets between this and
  1.1764  	    <literal role="tag">tip</literal>,
  1.1765 @@ -1856,19 +1856,19 @@
  1.1766  	      role="hg-cmd">hg unbundle</command>.
  1.1767  	  </para>
  1.1768  	</listitem>
  1.1769 -	<listitem><para><literal>source</literal>: A string.  The
  1.1770 +	<listitem><para id="x_2cc"><literal>source</literal>: A string.  The
  1.1771  	    source of these changes.  See section <xref
  1.1772  	      linkend="sec:hook:sources"/> for details.
  1.1773  	  </para>
  1.1774  	</listitem>
  1.1775 -	<listitem><para><literal>url</literal>: A URL.  The location
  1.1776 +	<listitem><para id="x_2cd"><literal>url</literal>: A URL.  The location
  1.1777  	    of the remote repository, if known.  See section <xref
  1.1778  	      linkend="sec:hook:url"/> for more
  1.1779  	    information.
  1.1780  	  </para>
  1.1781  	</listitem></itemizedlist>
  1.1782  
  1.1783 -      <para>See also: <literal role="hook">changegroup</literal>
  1.1784 +      <para id="x_2ce">See also: <literal role="hook">changegroup</literal>
  1.1785  	(section <xref linkend="sec:hook:changegroup"/>), <literal
  1.1786  	  role="hook">incoming</literal> (section <xref
  1.1787  	  linkend="sec:hook:incoming"/>), <literal
  1.1788 @@ -1881,7 +1881,7 @@
  1.1789        <title><literal role="hook">pretxncommit</literal>&emdash;before
  1.1790  	completing commit of new changeset</title>
  1.1791  
  1.1792 -      <para>This controlling hook is run before a
  1.1793 +      <para id="x_2cf">This controlling hook is run before a
  1.1794  	transaction&emdash;that manages a new commit&emdash;completes.
  1.1795  	If the hook succeeds, the transaction completes and the
  1.1796  	changeset becomes permanent within this repository.  If the
  1.1797 @@ -1889,37 +1889,37 @@
  1.1798  	data is erased.
  1.1799        </para>
  1.1800  
  1.1801 -      <para>This hook can access the metadata associated with the
  1.1802 +      <para id="x_2d0">This hook can access the metadata associated with the
  1.1803  	almost-new changeset, but it should not do anything permanent
  1.1804  	with this data.  It must also not modify the working
  1.1805  	directory.
  1.1806        </para>
  1.1807  
  1.1808 -      <para>While this hook is running, if other Mercurial processes
  1.1809 +      <para id="x_2d1">While this hook is running, if other Mercurial processes
  1.1810  	access this repository, they will be able to see the
  1.1811  	almost-new changeset as if it is permanent.  This may lead to
  1.1812  	race conditions if you do not take steps to avoid them.
  1.1813        </para>
  1.1814  
  1.1815 -      <para>Parameters to this hook:
  1.1816 +      <para id="x_2d2">Parameters to this hook:
  1.1817        </para>
  1.1818        <itemizedlist>
  1.1819 -	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1820 +	<listitem><para id="x_2d3"><literal>node</literal>: A changeset ID.  The
  1.1821  	    changeset ID of the newly committed changeset.
  1.1822  	  </para>
  1.1823  	</listitem>
  1.1824 -	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1825 +	<listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID.
  1.1826  	    The changeset ID of the first parent of the newly
  1.1827  	    committed changeset.
  1.1828  	  </para>
  1.1829  	</listitem>
  1.1830 -	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1831 +	<listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID.
  1.1832  	    The changeset ID of the second parent of the newly
  1.1833  	    committed changeset.
  1.1834  	  </para>
  1.1835  	</listitem></itemizedlist>
  1.1836  
  1.1837 -      <para>See also: <literal role="hook">precommit</literal>
  1.1838 +      <para id="x_2d6">See also: <literal role="hook">precommit</literal>
  1.1839  	(section <xref linkend="sec:hook:precommit"/>)
  1.1840        </para>
  1.1841  
  1.1842 @@ -1928,30 +1928,30 @@
  1.1843        <title><literal role="hook">preupdate</literal>&emdash;before
  1.1844  	updating or merging working directory</title>
  1.1845  
  1.1846 -      <para>This controlling hook is run before an update or merge of
  1.1847 +      <para id="x_2d7">This controlling hook is run before an update or merge of
  1.1848  	the working directory begins.  It is run only if Mercurial's
  1.1849  	normal pre-update checks determine that the update or merge
  1.1850  	can proceed.  If the hook succeeds, the update or merge may
  1.1851  	proceed; if it fails, the update or merge does not start.
  1.1852        </para>
  1.1853  
  1.1854 -      <para>Parameters to this hook:
  1.1855 +      <para id="x_2d8">Parameters to this hook:
  1.1856        </para>
  1.1857        <itemizedlist>
  1.1858 -	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1859 +	<listitem><para id="x_2d9"><literal>parent1</literal>: A changeset ID.
  1.1860  	    The ID of the parent that the working directory is to be
  1.1861  	    updated to.  If the working directory is being merged, it
  1.1862  	    will not change this parent.
  1.1863  	  </para>
  1.1864  	</listitem>
  1.1865 -	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1866 +	<listitem><para id="x_2da"><literal>parent2</literal>: A changeset ID.
  1.1867  	    Only set if the working directory is being merged.  The ID
  1.1868  	    of the revision that the working directory is being merged
  1.1869  	    with.
  1.1870  	  </para>
  1.1871  	</listitem></itemizedlist>
  1.1872  
  1.1873 -      <para>See also: <literal role="hook">update</literal> (section
  1.1874 +      <para id="x_2db">See also: <literal role="hook">update</literal> (section
  1.1875  	<xref linkend="sec:hook:update"/>)
  1.1876        </para>
  1.1877  
  1.1878 @@ -1960,13 +1960,13 @@
  1.1879        <title><literal role="hook">tag</literal>&emdash;after tagging a
  1.1880  	changeset</title>
  1.1881  
  1.1882 -      <para>This hook is run after a tag has been created.
  1.1883 -      </para>
  1.1884 -
  1.1885 -      <para>Parameters to this hook:
  1.1886 +      <para id="x_2dc">This hook is run after a tag has been created.
  1.1887 +      </para>
  1.1888 +
  1.1889 +      <para id="x_2dd">Parameters to this hook:
  1.1890        </para>
  1.1891        <itemizedlist>
  1.1892 -	<listitem><para><literal>local</literal>: A boolean.  Whether
  1.1893 +	<listitem><para id="x_2de"><literal>local</literal>: A boolean.  Whether
  1.1894  	    the new tag is local to this repository instance (i.e.
  1.1895  	    stored in <filename
  1.1896  	      role="special">.hg/localtags</filename>) or managed by
  1.1897 @@ -1974,21 +1974,21 @@
  1.1898  	      role="special">.hgtags</filename>).
  1.1899  	  </para>
  1.1900  	</listitem>
  1.1901 -	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1902 +	<listitem><para id="x_2df"><literal>node</literal>: A changeset ID.  The
  1.1903  	    ID of the changeset that was tagged.
  1.1904  	  </para>
  1.1905  	</listitem>
  1.1906 -	<listitem><para><literal>tag</literal>: A string.  The name of
  1.1907 +	<listitem><para id="x_2e0"><literal>tag</literal>: A string.  The name of
  1.1908  	    the tag that was created.
  1.1909  	  </para>
  1.1910  	</listitem></itemizedlist>
  1.1911  
  1.1912 -      <para>If the created tag is revision-controlled, the <literal
  1.1913 +      <para id="x_2e1">If the created tag is revision-controlled, the <literal
  1.1914  	  role="hook">commit</literal> hook (section <xref
  1.1915  	  linkend="sec:hook:commit"/>) is run before this hook.
  1.1916        </para>
  1.1917  
  1.1918 -      <para>See also: <literal role="hook">pretag</literal> (section
  1.1919 +      <para id="x_2e2">See also: <literal role="hook">pretag</literal> (section
  1.1920  	<xref linkend="sec:hook:pretag"/>)
  1.1921        </para>
  1.1922  
  1.1923 @@ -1997,7 +1997,7 @@
  1.1924        <title><literal role="hook">update</literal>&emdash;after
  1.1925  	updating or merging working directory</title>
  1.1926  
  1.1927 -      <para>This hook is run after an update or merge of the working
  1.1928 +      <para id="x_2e3">This hook is run after an update or merge of the working
  1.1929  	directory completes.  Since a merge can fail (if the external
  1.1930  	<command>hgmerge</command> command fails to resolve conflicts
  1.1931  	in a file), this hook communicates whether the update or merge
  1.1932 @@ -2005,24 +2005,24 @@
  1.1933        </para>
  1.1934  
  1.1935        <itemizedlist>
  1.1936 -	<listitem><para><literal>error</literal>: A boolean.
  1.1937 +	<listitem><para id="x_2e4"><literal>error</literal>: A boolean.
  1.1938  	    Indicates whether the update or merge completed
  1.1939  	    successfully.
  1.1940  	  </para>
  1.1941  	</listitem>
  1.1942 -	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1943 +	<listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID.
  1.1944  	    The ID of the parent that the working directory was
  1.1945  	    updated to.  If the working directory was merged, it will
  1.1946  	    not have changed this parent.
  1.1947  	  </para>
  1.1948  	</listitem>
  1.1949 -	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1950 +	<listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID.
  1.1951  	    Only set if the working directory was merged.  The ID of
  1.1952  	    the revision that the working directory was merged with.
  1.1953  	  </para>
  1.1954  	</listitem></itemizedlist>
  1.1955  
  1.1956 -      <para>See also: <literal role="hook">preupdate</literal>
  1.1957 +      <para id="x_2e7">See also: <literal role="hook">preupdate</literal>
  1.1958  	(section <xref linkend="sec:hook:preupdate"/>)
  1.1959        </para>
  1.1960