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