1.1 --- a/en/ch09-hook.xml	Tue Apr 21 23:51:47 2009 -0700
     1.2 +++ b/en/ch09-hook.xml	Thu Apr 23 22:24:02 2009 -0700
     1.3 @@ -147,8 +147,8 @@
     1.4  	  incoming</command>), remember that it is the other
     1.5  	repository's hooks you should be checking, not your own.
     1.6        </para>
     1.7 -
     1.8 -    </sect2>
     1.9 +    </sect2>
    1.10 +
    1.11      <sect2>
    1.12        <title>Hooks do not propagate</title>
    1.13  
    1.14 @@ -178,8 +178,8 @@
    1.15  	filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will
    1.16  	see.  However, this too has its limits; see below.
    1.17        </para>
    1.18 -
    1.19 -    </sect2>
    1.20 +    </sect2>
    1.21 +
    1.22      <sect2>
    1.23        <title>Hooks can be overridden</title>
    1.24  
    1.25 @@ -193,8 +193,8 @@
    1.26  	hooks, you should thus understand that your users can disable
    1.27  	or override those hooks.
    1.28        </para>
    1.29 -
    1.30 -    </sect2>
    1.31 +    </sect2>
    1.32 +
    1.33      <sect2>
    1.34        <title>Ensuring that critical hooks are run</title>
    1.35  
    1.36 @@ -232,116 +232,7 @@
    1.37  
    1.38      </sect2>
    1.39    </sect1>
    1.40 -  <sect1>
    1.41 -    <title>Care with <literal>pretxn</literal> hooks in a
    1.42 -      shared-access repository</title>
    1.43 -
    1.44 -    <para id="x_206">If you want to use hooks to do some automated work in a
    1.45 -      repository that a number of people have shared access to, you
    1.46 -      need to be careful in how you do this.
    1.47 -    </para>
    1.48 -
    1.49 -    <para id="x_207">Mercurial only locks a repository when it is writing to the
    1.50 -      repository, and only the parts of Mercurial that write to the
    1.51 -      repository pay attention to locks.  Write locks are necessary to
    1.52 -      prevent multiple simultaneous writers from scribbling on each
    1.53 -      other's work, corrupting the repository.
    1.54 -    </para>
    1.55 -
    1.56 -    <para id="x_208">Because Mercurial is careful with the order in which it
    1.57 -      reads and writes data, it does not need to acquire a lock when
    1.58 -      it wants to read data from the repository.  The parts of
    1.59 -      Mercurial that read from the repository never pay attention to
    1.60 -      locks.  This lockless reading scheme greatly increases
    1.61 -      performance and concurrency.
    1.62 -    </para>
    1.63 -
    1.64 -    <para id="x_209">With great performance comes a trade-off, though, one which
    1.65 -      has the potential to cause you trouble unless you're aware of
    1.66 -      it.  To describe this requires a little detail about how
    1.67 -      Mercurial adds changesets to a repository and reads those
    1.68 -      changes.
    1.69 -    </para>
    1.70 -
    1.71 -    <para id="x_20a">When Mercurial <emphasis>writes</emphasis> metadata, it
    1.72 -      writes it straight into the destination file.  It writes file
    1.73 -      data first, then manifest data (which contains pointers to the
    1.74 -      new file data), then changelog data (which contains pointers to
    1.75 -      the new manifest data).  Before the first write to each file, it
    1.76 -      stores a record of where the end of the file was in its
    1.77 -      transaction log.  If the transaction must be rolled back,
    1.78 -      Mercurial simply truncates each file back to the size it was
    1.79 -      before the transaction began.
    1.80 -    </para>
    1.81 -
    1.82 -    <para id="x_20b">When Mercurial <emphasis>reads</emphasis> metadata, it reads
    1.83 -      the changelog first, then everything else.  Since a reader will
    1.84 -      only access parts of the manifest or file metadata that it can
    1.85 -      see in the changelog, it can never see partially written data.
    1.86 -    </para>
    1.87 -
    1.88 -    <para id="x_20c">Some controlling hooks (<literal
    1.89 -	role="hook">pretxncommit</literal> and <literal
    1.90 -	role="hook">pretxnchangegroup</literal>) run when a
    1.91 -      transaction is almost complete. All of the metadata has been
    1.92 -      written, but Mercurial can still roll the transaction back and
    1.93 -      cause the newly-written data to disappear.
    1.94 -    </para>
    1.95 -
    1.96 -    <para id="x_20d">If one of these hooks runs for long, it opens a window of
    1.97 -      time during which a reader can see the metadata for changesets
    1.98 -      that are not yet permanent, and should not be thought of as
    1.99 -      <quote>really there</quote>.  The longer the hook runs, the
   1.100 -      longer that window is open.
   1.101 -    </para>
   1.102 -
   1.103 -    <sect2>
   1.104 -      <title>The problem illustrated</title>
   1.105 -
   1.106 -      <para id="x_20e">In principle, a good use for the <literal
   1.107 -	  role="hook">pretxnchangegroup</literal> hook would be to
   1.108 -	automatically build and test incoming changes before they are
   1.109 -	accepted into a central repository.  This could let you
   1.110 -	guarantee that nobody can push changes to this repository that
   1.111 -	<quote>break the build</quote>. But if a client can pull
   1.112 -	changes while they're being tested, the usefulness of the test
   1.113 -	is zero; an unsuspecting someone can pull untested changes,
   1.114 -	potentially breaking their build.
   1.115 -      </para>
   1.116 -
   1.117 -      <para id="x_20f">The safest technological answer to this challenge is to
   1.118 -	set up such a <quote>gatekeeper</quote> repository as
   1.119 -	<emphasis>unidirectional</emphasis>.  Let it take changes
   1.120 -	pushed in from the outside, but do not allow anyone to pull
   1.121 -	changes from it (use the <literal
   1.122 -	  role="hook">preoutgoing</literal> hook to lock it down).
   1.123 -	Configure a <literal role="hook">changegroup</literal> hook so
   1.124 -	that if a build or test succeeds, the hook will push the new
   1.125 -	changes out to another repository that people
   1.126 -	<emphasis>can</emphasis> pull from.
   1.127 -      </para>
   1.128 -
   1.129 -      <para id="x_210">In practice, putting a centralised bottleneck like this in
   1.130 -	place is not often a good idea, and transaction visibility has
   1.131 -	nothing to do with the problem.  As the size of a
   1.132 -	project&emdash;and the time it takes to build and
   1.133 -	test&emdash;grows, you rapidly run into a wall with this
   1.134 -	<quote>try before you buy</quote> approach, where you have
   1.135 -	more changesets to test than time in which to deal with them.
   1.136 -	The inevitable result is frustration on the part of all
   1.137 -	involved.
   1.138 -      </para>
   1.139 -
   1.140 -      <para id="x_211">An approach that scales better is to get people to build
   1.141 -	and test before they push, then run automated builds and tests
   1.142 -	centrally <emphasis>after</emphasis> a push, to be sure all is
   1.143 -	well.  The advantage of this approach is that it does not
   1.144 -	impose a limit on the rate at which the repository can accept
   1.145 -	changes.
   1.146 -      </para>
   1.147 -
   1.148 -    </sect2>
   1.149 -  </sect1>
   1.150 +
   1.151    <sect1 id="sec:hook:simple">
   1.152      <title>A short tutorial on using hooks</title>
   1.153  
   1.154 @@ -509,8 +400,8 @@
   1.155  	<literal>foo</literal>, while the environment variable for an
   1.156  	external hook will be named <literal>HG_FOO</literal>.
   1.157        </para>
   1.158 -
   1.159 -    </sect2>
   1.160 +    </sect2>
   1.161 +
   1.162      <sect2>
   1.163        <title>Hook return values and activity control</title>
   1.164  
   1.165 @@ -526,8 +417,8 @@
   1.166  	zero/false means <quote>allow</quote>, while
   1.167  	non-zero/true/exception means <quote>deny</quote>.
   1.168        </para>
   1.169 -
   1.170 -    </sect2>
   1.171 +    </sect2>
   1.172 +
   1.173      <sect2>
   1.174        <title>Writing an external hook</title>
   1.175  
   1.176 @@ -555,8 +446,8 @@
   1.177  	should not rely on environment variables being set to the
   1.178  	values you have in your environment when testing the hook.
   1.179        </para>
   1.180 -
   1.181 -    </sect2>
   1.182 +    </sect2>
   1.183 +
   1.184      <sect2>
   1.185        <title>Telling Mercurial to use an in-process hook</title>
   1.186  
   1.187 @@ -585,8 +476,8 @@
   1.188  	for the callable object named <literal>myhook</literal>, and
   1.189  	calls it.
   1.190        </para>
   1.191 -
   1.192 -    </sect2>
   1.193 +    </sect2>
   1.194 +
   1.195      <sect2>
   1.196        <title>Writing an in-process hook</title>
   1.197  
   1.198 @@ -622,8 +513,8 @@
   1.199        </para>
   1.200  
   1.201  &interaction.hook.msglen.go;
   1.202 -
   1.203 -    </sect2>
   1.204 +    </sect2>
   1.205 +
   1.206      <sect2>
   1.207        <title>Checking for trailing whitespace</title>
   1.208  
   1.209 @@ -838,8 +729,8 @@
   1.210  	  forbidding pushes from specific users.
   1.211  	</para>
   1.212  
   1.213 -      </sect3>
   1.214 -    </sect2>
   1.215 +      </sect3>    </sect2>
   1.216 +
   1.217      <sect2>
   1.218        <title><literal
   1.219  	  role="hg-ext">bugzilla</literal>&emdash;integration with
   1.220 @@ -1144,8 +1035,8 @@
   1.221  	  a valid Bugzilla user name.
   1.222  	</para>
   1.223  
   1.224 -      </sect3>
   1.225 -    </sect2>
   1.226 +      </sect3>    </sect2>
   1.227 +
   1.228      <sect2>
   1.229        <title><literal role="hg-ext">notify</literal>&emdash;send email
   1.230  	notifications</title>
   1.231 @@ -1344,8 +1235,8 @@
   1.232  	APIs normally use.  To convert a hash from hex to binary, use
   1.233  	the <literal>bin</literal> function.
   1.234        </para>
   1.235 -
   1.236 -    </sect2>
   1.237 +    </sect2>
   1.238 +
   1.239      <sect2>
   1.240        <title>External hook execution</title>
   1.241  
   1.242 @@ -1382,8 +1273,8 @@
   1.243  	have succeeded.  If it exits with a non-zero status, it is
   1.244  	considered to have failed.
   1.245        </para>
   1.246 -
   1.247 -    </sect2>
   1.248 +    </sect2>
   1.249 +
   1.250      <sect2>
   1.251        <title>Finding out where changesets come from</title>
   1.252  
   1.253 @@ -1425,8 +1316,8 @@
   1.254  	      being transferred to or from a bundle.
   1.255  	    </para>
   1.256  	  </listitem></itemizedlist>
   1.257 -
   1.258        </sect3>
   1.259 +
   1.260        <sect3 id="sec:hook:url">
   1.261  	<title>Where changes are going&emdash;remote repository
   1.262  	  URLs</title>
   1.263 @@ -1462,7 +1353,6 @@
   1.264  	      discovered about the remote client.
   1.265  	    </para>
   1.266  	  </listitem></itemizedlist>
   1.267 -
   1.268        </sect3>
   1.269      </sect2>
   1.270    </sect1>
   1.271 @@ -1520,8 +1410,8 @@
   1.272  	  role="hook">pretxnchangegroup</literal> (<xref
   1.273  	  linkend="sec:hook:pretxnchangegroup"/>)
   1.274        </para>
   1.275 -
   1.276 -    </sect2>
   1.277 +    </sect2>
   1.278 +
   1.279      <sect2 id="sec:hook:commit">
   1.280        <title><literal role="hook">commit</literal>&emdash;after a new
   1.281  	changeset is created</title>
   1.282 @@ -1553,8 +1443,8 @@
   1.283  	  role="hook">pretxncommit</literal> (<xref
   1.284  	  linkend="sec:hook:pretxncommit"/>)
   1.285        </para>
   1.286 -
   1.287 -    </sect2>
   1.288 +    </sect2>
   1.289 +
   1.290      <sect2 id="sec:hook:incoming">
   1.291        <title><literal role="hook">incoming</literal>&emdash;after one
   1.292  	remote changeset is added</title>
   1.293 @@ -1599,8 +1489,8 @@
   1.294  	  role="hook">pretxnchangegroup</literal> (<xref
   1.295  	  linkend="sec:hook:pretxnchangegroup"/>)
   1.296        </para>
   1.297 -
   1.298 -    </sect2>
   1.299 +    </sect2>
   1.300 +
   1.301      <sect2 id="sec:hook:outgoing">
   1.302        <title><literal role="hook">outgoing</literal>&emdash;after
   1.303  	changesets are propagated</title>
   1.304 @@ -1646,8 +1536,8 @@
   1.305  	  role="hook">preoutgoing</literal> (<xref
   1.306  	  linkend="sec:hook:preoutgoing"/>)
   1.307        </para>
   1.308 -
   1.309 -    </sect2>
   1.310 +    </sect2>
   1.311 +
   1.312      <sect2 id="sec:hook:prechangegroup">
   1.313        <title><literal
   1.314  	  role="hook">prechangegroup</literal>&emdash;before starting
   1.315 @@ -1692,8 +1582,8 @@
   1.316  	  role="hook">pretxnchangegroup</literal> (<xref
   1.317  	  linkend="sec:hook:pretxnchangegroup"/>)
   1.318        </para>
   1.319 -
   1.320 -    </sect2>
   1.321 +    </sect2>
   1.322 +
   1.323      <sect2 id="sec:hook:precommit">
   1.324        <title><literal role="hook">precommit</literal>&emdash;before
   1.325  	starting to commit a changeset</title>
   1.326 @@ -1732,8 +1622,8 @@
   1.327  	  role="hook">pretxncommit</literal> (<xref
   1.328  	  linkend="sec:hook:pretxncommit"/>)
   1.329        </para>
   1.330 -
   1.331 -    </sect2>
   1.332 +    </sect2>
   1.333 +
   1.334      <sect2 id="sec:hook:preoutgoing">
   1.335        <title><literal role="hook">preoutgoing</literal>&emdash;before
   1.336  	starting to propagate changesets</title>
   1.337 @@ -1769,8 +1659,8 @@
   1.338  	  role="hook">outgoing</literal> (<xref
   1.339  	  linkend="sec:hook:outgoing"/>)
   1.340        </para>
   1.341 -
   1.342 -    </sect2>
   1.343 +    </sect2>
   1.344 +
   1.345      <sect2 id="sec:hook:pretag">
   1.346        <title><literal role="hook">pretag</literal>&emdash;before
   1.347  	tagging a changeset</title>
   1.348 @@ -1811,6 +1701,7 @@
   1.349  	(<xref linkend="sec:hook:tag"/>)
   1.350        </para>
   1.351      </sect2>
   1.352 +
   1.353      <sect2 id="sec:hook:pretxnchangegroup">
   1.354        <title><literal
   1.355  	  role="hook">pretxnchangegroup</literal>&emdash;before
   1.356 @@ -1875,8 +1766,8 @@
   1.357  	  role="hook">prechangegroup</literal> (<xref
   1.358  	  linkend="sec:hook:prechangegroup"/>)
   1.359        </para>
   1.360 -
   1.361 -    </sect2>
   1.362 +    </sect2>
   1.363 +
   1.364      <sect2 id="sec:hook:pretxncommit">
   1.365        <title><literal role="hook">pretxncommit</literal>&emdash;before
   1.366  	completing commit of new changeset</title>
   1.367 @@ -1901,8 +1792,8 @@
   1.368  	race conditions if you do not take steps to avoid them.
   1.369        </para>
   1.370  
   1.371 -      <para id="x_2d2">Parameters to this hook:
   1.372 -      </para>
   1.373 +      <para id="x_2d2">Parameters to this hook:</para>
   1.374 +
   1.375        <itemizedlist>
   1.376  	<listitem><para id="x_2d3"><literal>node</literal>: A changeset ID.  The
   1.377  	    changeset ID of the newly committed changeset.
   1.378 @@ -1923,8 +1814,8 @@
   1.379  	  role="hook">precommit</literal> (<xref
   1.380  	  linkend="sec:hook:precommit"/>)
   1.381        </para>
   1.382 -
   1.383 -    </sect2>
   1.384 +    </sect2>
   1.385 +
   1.386      <sect2 id="sec:hook:preupdate">
   1.387        <title><literal role="hook">preupdate</literal>&emdash;before
   1.388  	updating or merging working directory</title>
   1.389 @@ -1955,8 +1846,8 @@
   1.390  
   1.391        <para id="x_2db">See also: <literal role="hook">update</literal>
   1.392  	(<xref linkend="sec:hook:update"/>)</para>
   1.393 -
   1.394 -    </sect2>
   1.395 +    </sect2>
   1.396 +
   1.397      <sect2 id="sec:hook:tag">
   1.398        <title><literal role="hook">tag</literal>&emdash;after tagging a
   1.399  	changeset</title>
   1.400 @@ -1992,8 +1883,8 @@
   1.401        <para id="x_2e2">See also: <literal role="hook">pretag</literal>
   1.402  	(<xref linkend="sec:hook:pretag"/>)
   1.403        </para>
   1.404 -
   1.405 -    </sect2>
   1.406 +    </sect2>
   1.407 +
   1.408      <sect2 id="sec:hook:update">
   1.409        <title><literal role="hook">update</literal>&emdash;after
   1.410  	updating or merging working directory</title>

     2.1 --- a/en/ch10-template.xml	Tue Apr 21 23:51:47 2009 -0700
     2.2 +++ b/en/ch10-template.xml	Thu Apr 23 22:24:02 2009 -0700
     2.3 @@ -56,9 +56,9 @@
     2.4  	file into a location where Mercurial can find it (typically
     2.5  	the <literal>templates</literal> subdirectory of your
     2.6  	Mercurial install directory).</para>
     2.7 -
     2.8      </sect2>
     2.9    </sect1>
    2.10 +
    2.11    <sect1>
    2.12      <title>Commands that support styles and templates</title>
    2.13  
    2.14 @@ -125,8 +125,8 @@
    2.15        braces and text with the expansion of whatever is inside.  To
    2.16        print a literal curly brace, you must escape it, as described in
    2.17        <xref linkend="sec:template:escape"/>.</para>
    2.18 -
    2.19 -  </sect1>
    2.20 +  </sect1>
    2.21 +
    2.22    <sect1 id="sec:template:keyword">
    2.23      <title>Common template keywords</title>
    2.24  
    2.25 @@ -199,8 +199,8 @@
    2.26        in <xref linkend="sec:template:filter"/>.</para>
    2.27  
    2.28      &interaction.template.simple.datekeyword;
    2.29 -
    2.30 -  </sect1>
    2.31 +  </sect1>
    2.32 +
    2.33    <sect1 id="sec:template:escape">
    2.34      <title>Escape sequences</title>
    2.35  
    2.36 @@ -241,8 +241,8 @@
    2.37        <quote><literal>{</literal></quote>, or
    2.38        <quote><literal>{</literal></quote> character, you must escape
    2.39        it.</para>
    2.40 -
    2.41 -  </sect1>
    2.42 +  </sect1>
    2.43 +
    2.44    <sect1 id="sec:template:filter">
    2.45      <title>Filtering keywords to change their results</title>
    2.46  
    2.47 @@ -410,7 +410,7 @@
    2.48  	  <quote><literal>bos</literal></quote>.</para>
    2.49        </listitem></itemizedlist>
    2.50  
    2.51 -&interaction.template.simple.manyfilters;
    2.52 +    &interaction.template.simple.manyfilters;
    2.53  
    2.54      <note>
    2.55        <para id="x_5b7">  If you try to apply a filter to a piece of data that it
    2.56 @@ -445,10 +445,9 @@
    2.57  	on.  For example, using <literal>fill68|tabindent</literal>
    2.58  	gives very different results from
    2.59  	<literal>tabindent|fill68</literal>.</para>
    2.60 -
    2.61 -
    2.62      </sect2>
    2.63    </sect1>
    2.64 +
    2.65    <sect1>
    2.66      <title>From templates to styles</title>
    2.67  
    2.68 @@ -513,9 +512,9 @@
    2.69  	    treated as the name of a file; the contents of this file
    2.70  	    will be read and used as a template body.</para>
    2.71  	</listitem></itemizedlist>
    2.72 -
    2.73      </sect2>
    2.74    </sect1>
    2.75 +
    2.76    <sect1>
    2.77      <title>Style files by example</title>
    2.78  
    2.79 @@ -566,8 +565,8 @@
    2.80  	    is almost always trivial to visually inspect the offending
    2.81  	    line in the style file and see what is wrong.</para>
    2.82  	</listitem></itemizedlist>
    2.83 -
    2.84      </sect2>
    2.85 +
    2.86      <sect2>
    2.87        <title>Uniquely identifying a repository</title>
    2.88  
    2.89 @@ -602,8 +601,8 @@
    2.90  	    or other activity, so that you can <quote>replay</quote>
    2.91  	    the build later if necessary.</para>
    2.92  	</listitem></itemizedlist>
    2.93 -
    2.94      </sect2>
    2.95 +
    2.96      <sect2>
    2.97        <title>Mimicking Subversion's output</title>
    2.98  
    2.99 @@ -661,7 +660,6 @@
   2.100  	file points to.  If the style file will look too big or
   2.101  	cluttered if you insert a literal piece of text, drop it into
   2.102  	a template instead.</para>
   2.103 -
   2.104      </sect2>
   2.105    </sect1>
   2.106  </chapter>

     3.1 --- a/en/ch11-mq.xml	Tue Apr 21 23:51:47 2009 -0700
     3.2 +++ b/en/ch11-mq.xml	Thu Apr 23 22:24:02 2009 -0700
     3.3 @@ -118,8 +118,8 @@
     3.4        <para id="x_3b9">Quilt knows nothing about revision control tools, so it
     3.5  	works equally well on top of an unpacked tarball or a
     3.6  	Subversion working copy.</para>
     3.7 -
     3.8 -    </sect2>
     3.9 +    </sect2>
    3.10 +
    3.11      <sect2 id="sec:mq:quilt-mq">
    3.12        <title>From patchwork quilt to Mercurial Queues</title>
    3.13  
    3.14 @@ -181,8 +181,8 @@
    3.15  	role="hg-cmd">hg annotate</command> command to see which
    3.16        changeset or patch modified a particular line of a source file.
    3.17        And so on.</para>
    3.18 -
    3.19 -  </sect1>
    3.20 +  </sect1>
    3.21 +
    3.22    <sect1 id="sec:mq:patch">
    3.23      <title>Understanding patches</title>
    3.24  
    3.25 @@ -244,8 +244,8 @@
    3.26        later (in <xref linkend="sec:mq:adv-patch"/>), but you
    3.27        should have
    3.28        enough information now to use MQ.</para>
    3.29 -
    3.30 -  </sect1>
    3.31 +  </sect1>
    3.32 +
    3.33    <sect1 id="sec:mq:start">
    3.34      <title>Getting started with Mercurial Queues</title>
    3.35  
    3.36 @@ -265,14 +265,14 @@
    3.37        the <command role="hg-ext-mq">qinit</command> command is now
    3.38        available.</para>
    3.39  
    3.40 -&interaction.mq.qinit-help.help;
    3.41 +    &interaction.mq.qinit-help.help;
    3.42  
    3.43      <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial
    3.44        repository, and its commands only operate within that
    3.45        repository.  To get started, simply prepare the repository using
    3.46        the <command role="hg-ext-mq">qinit</command> command.</para>
    3.47  
    3.48 -&interaction.mq.tutorial.qinit;
    3.49 +    &interaction.mq.tutorial.qinit;
    3.50  
    3.51      <para id="x_3cd">This command creates an empty directory called <filename
    3.52  	role="special" class="directory">.hg/patches</filename>, where
    3.53 @@ -292,7 +292,7 @@
    3.54  	  class="directory">.hg/patches</filename> directory, as you
    3.55  	can see below.</para>
    3.56  
    3.57 -&interaction.mq.tutorial.qnew;
    3.58 +      &interaction.mq.tutorial.qnew;
    3.59  
    3.60        <para id="x_3d0">Also newly present in the <filename role="special"
    3.61  	  class="directory">.hg/patches</filename> directory are two
    3.62 @@ -320,8 +320,8 @@
    3.63  	normal Mercurial commands, such as <command role="hg-cmd">hg
    3.64  	  diff</command> and <command role="hg-cmd">hg
    3.65  	  annotate</command>, work exactly as they did before.</para>
    3.66 -
    3.67 -    </sect2>
    3.68 +    </sect2>
    3.69 +
    3.70      <sect2>
    3.71        <title>Refreshing a patch</title>
    3.72  
    3.73 @@ -329,7 +329,7 @@
    3.74  	use the <command role="hg-ext-mq">qrefresh</command> command
    3.75  	to update the patch you are working on.</para>
    3.76  
    3.77 -&interaction.mq.tutorial.qrefresh;
    3.78 +      &interaction.mq.tutorial.qrefresh;
    3.79  
    3.80        <para id="x_3d4">This command folds the changes you have made in the
    3.81  	working directory into your patch, and updates its
    3.82 @@ -342,9 +342,9 @@
    3.83  	doesn't work out, <command role="hg-cmd">hg revert</command>
    3.84  	your modifications back to the last time you refreshed.</para>
    3.85  
    3.86 -&interaction.mq.tutorial.qrefresh2;
    3.87 -
    3.88 -    </sect2>
    3.89 +      &interaction.mq.tutorial.qrefresh2;
    3.90 +    </sect2>
    3.91 +
    3.92      <sect2>
    3.93        <title>Stacking and tracking patches</title>
    3.94  
    3.95 @@ -354,7 +354,8 @@
    3.96  	new patch. Mercurial will apply this patch on top of your
    3.97  	existing patch.</para>
    3.98  
    3.99 -&interaction.mq.tutorial.qnew2;
   3.100 +      &interaction.mq.tutorial.qnew2;
   3.101 +
   3.102        <para id="x_3d7">Notice that the patch contains the changes in our prior
   3.103  	patch as part of its context (you can see this more clearly in
   3.104  	the output of <command role="hg-cmd">hg
   3.105 @@ -367,7 +368,7 @@
   3.106  	many commands that are easier to use when you are thinking
   3.107  	about patches, as illustrated below.</para>
   3.108  
   3.109 -&interaction.mq.tutorial.qseries;
   3.110 +      &interaction.mq.tutorial.qseries;
   3.111  
   3.112        <itemizedlist>
   3.113  	<listitem><para id="x_3d9">The <command
   3.114 @@ -382,8 +383,8 @@
   3.115  	    repository, again from oldest to newest (most recently
   3.116  	    applied).</para>
   3.117  	</listitem></itemizedlist>
   3.118 -
   3.119 -    </sect2>
   3.120 +    </sect2>
   3.121 +
   3.122      <sect2>
   3.123        <title>Manipulating the patch stack</title>
   3.124  
   3.125 @@ -420,15 +421,16 @@
   3.126  	directory.  See below for examples of <command
   3.127  	  role="hg-ext-mq">qpop</command> and <command
   3.128  	  role="hg-ext-mq">qpush</command> in action.</para>
   3.129 -&interaction.mq.tutorial.qpop;
   3.130 +
   3.131 +      &interaction.mq.tutorial.qpop;
   3.132  
   3.133        <para id="x_3df">Notice that once we have popped a patch or two patches,
   3.134  	the output of <command role="hg-ext-mq">qseries</command>
   3.135  	remains the same, while that of <command
   3.136  	  role="hg-ext-mq">qapplied</command> has changed.</para>
   3.137  
   3.138 -
   3.139 -    </sect2>
   3.140 +    </sect2>
   3.141 +
   3.142      <sect2>
   3.143        <title>Pushing and popping many patches</title>
   3.144  
   3.145 @@ -444,9 +446,9 @@
   3.146  	patches.  (For some more ways to push and pop many patches,
   3.147  	see <xref linkend="sec:mq:perf"/> below.)</para>
   3.148  
   3.149 -&interaction.mq.tutorial.qpush-a;
   3.150 -
   3.151 -    </sect2>
   3.152 +      &interaction.mq.tutorial.qpush-a;
   3.153 +    </sect2>
   3.154 +
   3.155      <sect2>
   3.156        <title>Safety checks, and overriding them</title>
   3.157  
   3.158 @@ -460,7 +462,7 @@
   3.159  	case by the <command role="hg-cmd">hg add</command> of
   3.160  	<filename>file3</filename>.</para>
   3.161  
   3.162 -&interaction.mq.tutorial.add;
   3.163 +      &interaction.mq.tutorial.add;
   3.164  
   3.165        <para id="x_3e2">Commands that check the working directory all take an
   3.166  	<quote>I know what I'm doing</quote> option, which is always
   3.167 @@ -474,8 +476,8 @@
   3.168  	will revert modifications to any files affected by the patch
   3.169  	that it is popping.  Be sure to read the documentation for a
   3.170  	command's <option>-f</option> option before you use it!</para>
   3.171 -
   3.172 -    </sect2>
   3.173 +    </sect2>
   3.174 +
   3.175      <sect2>
   3.176        <title>Working on several patches at once</title>
   3.177  
   3.178 @@ -499,9 +501,9 @@
   3.179  	the core bug, <command role="hg-ext-mq">qrefresh</command> the
   3.180  	core patch, and <command role="hg-ext-mq">qpush</command> back
   3.181  	to the UI patch to continue where you left off.</para>
   3.182 -
   3.183 -    </sect2>
   3.184 -  </sect1>
   3.185 +    </sect2>
   3.186 +  </sect1>
   3.187 +
   3.188    <sect1 id="sec:mq:adv-patch">
   3.189      <title>More about patches</title>
   3.190  
   3.191 @@ -580,6 +582,7 @@
   3.192  	  311</ulink> for details.
   3.193        </para>
   3.194      </sect2>
   3.195 +
   3.196      <sect2>
   3.197        <title>Strategies for applying a patch</title>
   3.198  
   3.199 @@ -623,8 +626,8 @@
   3.200  	<filename>foo.orig</filename>, a <filename>foo.rej</filename>
   3.201  	containing one hunk, and <filename>foo</filename>, containing
   3.202  	the changes made by the five successful hunks.</para>
   3.203 -
   3.204 -    </sect2>
   3.205 +    </sect2>
   3.206 +
   3.207      <sect2>
   3.208        <title>Some quirks of patch representation</title>
   3.209  
   3.210 @@ -663,6 +666,7 @@
   3.211  	      tree</quote>.</para>
   3.212  	</listitem></itemizedlist>
   3.213      </sect2>
   3.214 +
   3.215      <sect2>
   3.216        <title>Beware the fuzz</title>
   3.217  
   3.218 @@ -686,8 +690,8 @@
   3.219  	on top of multiple versions of a source tree, it's acceptable
   3.220  	to have a patch apply with some fuzz, provided you've verified
   3.221  	the results of the patching process in such cases.</para>
   3.222 -
   3.223 -    </sect2>
   3.224 +    </sect2>
   3.225 +
   3.226      <sect2>
   3.227        <title>Handling rejection</title>
   3.228  
   3.229 @@ -707,15 +711,10 @@
   3.230  	the <filename role="special">.rej</filename> file and edit the
   3.231  	target file, applying the rejected hunks by hand.</para>
   3.232  
   3.233 -      <para id="x_3fc">If you're feeling adventurous, Neil Brown, a Linux kernel
   3.234 -	hacker, wrote a tool called <command>wiggle</command>
   3.235 -	<citation>web:wiggle</citation>, which is more vigorous than
   3.236 -	<command>patch</command> in its attempts to make a patch
   3.237 -	apply.</para>
   3.238 -
   3.239 -      <para id="x_3fd">Another Linux kernel hacker, Chris Mason (the author of
   3.240 -	Mercurial Queues), wrote a similar tool called
   3.241 -	<command>mpatch</command> <citation>web:mpatch</citation>,
   3.242 +      <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author
   3.243 +	of Mercurial Queues), wrote a tool called
   3.244 +	<command>mpatch</command> (<ulink
   3.245 +	  url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 
   3.246  	which takes a simple approach to automating the application of
   3.247  	hunks rejected by <command>patch</command>.  The
   3.248  	<command>mpatch</command> command can help with four common
   3.249 @@ -736,24 +735,67 @@
   3.250  	    content than those currently present in the file.</para>
   3.251  	</listitem></itemizedlist>
   3.252  
   3.253 -      <para id="x_402">If you use <command>wiggle</command> or
   3.254 -	<command>mpatch</command>, you should be doubly careful to
   3.255 -	check your results when you're done.  In fact,
   3.256 -	<command>mpatch</command> enforces this method of
   3.257 -	double-checking the tool's output, by automatically dropping
   3.258 -	you into a merge program when it has done its job, so that you
   3.259 -	can verify its work and finish off any remaining
   3.260 +      <para id="x_402">If you use <command>mpatch</command>, you
   3.261 +	should be doubly careful to check your results when you're
   3.262 +	done.  In fact, <command>mpatch</command> enforces this method
   3.263 +	of double-checking the tool's output, by automatically
   3.264 +	dropping you into a merge program when it has done its job, so
   3.265 +	that you can verify its work and finish off any remaining
   3.266  	merges.</para>
   3.267 -
   3.268 -    </sect2>
   3.269 -  </sect1>
   3.270 +    </sect2>
   3.271 +  </sect1>
   3.272 +
   3.273 +  <sect1>
   3.274 +    <title>More on patch management</title>
   3.275 +
   3.276 +    <para>As you grow familiar with MQ, you will find yourself wanting
   3.277 +      to perform other kinds of patch management operations.</para>
   3.278 +
   3.279 +    <sect2>
   3.280 +      <title>Deleting unwanted patches</title>
   3.281 +
   3.282 +      <para>If you want to get rid of a patch, use the <command
   3.283 +	  role="hg-ext-mq">hg qdelete</command> command to delete the
   3.284 +	patch file and remove its entry from the patch series.  If you
   3.285 +	try to delete a patch that is still applied, <command
   3.286 +	  role="hg-ext-mq">hg qdelete</command> will refuse.</para>
   3.287 +
   3.288 +      &interaction.ch11-qdelete.go;
   3.289 +    </sect2>
   3.290 +
   3.291 +    <sect2>
   3.292 +      <title>Converting to and from permanent revisions</title>
   3.293 +
   3.294 +      <para>Once you're done working on a patch and want to turn it
   3.295 +	into a permanent changeset, use the <command
   3.296 +	  role="hg-ext-mq">hg qdelete -r</command> command.  Pass a
   3.297 +	revision to the <option>-r</option> option to identify the
   3.298 +	patch that you want to turn into a regular changeset; this
   3.299 +	patch must already be applied.</para>
   3.300 +
   3.301 +      &interaction.ch11-qdelete.convert;
   3.302 +
   3.303 +      <para>It is also possible to turn an existing changeset into a
   3.304 +	patch, by passing the <option>-r</option> option to <command
   3.305 +	  role="hg-ext-mq">hg qimport</command>.</para>
   3.306 +
   3.307 +      &interaction.ch11-qdelete.import;
   3.308 +
   3.309 +      <para>Note that it only makes sense to convert a changeset into
   3.310 +	a patch if you have not propagated that changeset into any
   3.311 +	other repositories.  The imported changeset's ID will change
   3.312 +	every time you refresh the patch, which will make Mercurial
   3.313 +	treat it as unrelated to the original changeset if you have
   3.314 +	pushed it somewhere else.</para>
   3.315 +    </sect2>
   3.316 +  </sect1>
   3.317 +
   3.318    <sect1 id="sec:mq:perf">
   3.319      <title>Getting the best performance out of MQ</title>
   3.320  
   3.321      <para id="x_403">MQ is very efficient at handling a large number of patches.
   3.322        I ran some performance experiments in mid-2006 for a talk that I
   3.323 -      gave at the 2006 EuroPython conference
   3.324 -      <citation>web:europython</citation>.  I used as my data set the
   3.325 +      gave at the 2006 EuroPython conference.  I used as my data set the
   3.326        Linux 2.6.17-mm1 patch series, which consists of 1,738 patches.
   3.327        I applied these on top of a Linux kernel repository containing
   3.328        all 27,472 revisions between Linux 2.6.12-rc2 and Linux
   3.329 @@ -799,8 +841,8 @@
   3.330        of the patch, or by number.  If you use numeric addressing,
   3.331        patches are counted from zero; this means that the first patch
   3.332        is zero, the second is one, and so on.</para>
   3.333 -
   3.334 -  </sect1>
   3.335 +  </sect1>
   3.336 +
   3.337    <sect1 id="sec:mq:merge">
   3.338      <title>Updating your patches when the underlying code
   3.339        changes</title>
   3.340 @@ -899,8 +941,8 @@
   3.341  	strip</command>.  You can delete <filename role="special"
   3.342  	class="directory">.hg/patches.N</filename> once you are sure
   3.343        that you no longer need it as a backup.</para>
   3.344 -
   3.345 -  </sect1>
   3.346 +  </sect1>
   3.347 +
   3.348    <sect1>
   3.349      <title>Identifying patches</title>
   3.350  
   3.351 @@ -963,9 +1005,9 @@
   3.352        few normal Mercurial commands in use with applied
   3.353        patches.</para>
   3.354  
   3.355 -&interaction.mq.id.output;
   3.356 -
   3.357 -  </sect1>
   3.358 +    &interaction.mq.id.output;
   3.359 +  </sect1>
   3.360 +
   3.361    <sect1>
   3.362      <title>Useful things to know about</title>
   3.363  
   3.364 @@ -991,8 +1033,8 @@
   3.365  	  this, it will appear to succeed, but MQ will become
   3.366  	  confused.</para>
   3.367        </listitem></itemizedlist>
   3.368 -
   3.369 -  </sect1>
   3.370 +  </sect1>
   3.371 +
   3.372    <sect1 id="sec:mq:repo">
   3.373      <title>Managing patches in a repository</title>
   3.374  
   3.375 @@ -1077,8 +1119,8 @@
   3.376  
   3.377        <para id="x_42d">You can then issue commands of the form <command>mq
   3.378  	  pull</command> from the main repository.</para>
   3.379 -
   3.380 -    </sect2>
   3.381 +    </sect2>
   3.382 +
   3.383      <sect2>
   3.384        <title>A few things to watch out for</title>
   3.385  
   3.386 @@ -1216,8 +1258,8 @@
   3.387  	tree.</para>
   3.388  
   3.389        &interaction.mq.tarball.repush;
   3.390 -
   3.391 -    </sect2>
   3.392 +    </sect2>
   3.393 +
   3.394      <sect2 id="sec:mq:combine">
   3.395        <title>Combining entire patches</title>
   3.396  
   3.397 @@ -1237,8 +1279,8 @@
   3.398  	you applied first <literal>foo</literal>, then
   3.399  	<literal>bar</literal>, followed by
   3.400  	<literal>quux</literal>.</para>
   3.401 -
   3.402 -    </sect2>
   3.403 +    </sect2>
   3.404 +
   3.405      <sect2>
   3.406        <title>Merging part of one patch into another</title>
   3.407  

     4.1 --- a/en/examples/auto-snippets.xml	Tue Apr 21 23:51:47 2009 -0700
     4.2 +++ b/en/examples/auto-snippets.xml	Thu Apr 23 22:24:02 2009 -0700
     4.3 @@ -60,6 +60,9 @@
     4.4  <!ENTITY interaction.ch04-resolve.merge SYSTEM "results/ch04-resolve.merge.lxo">
     4.5  <!ENTITY interaction.ch04-resolve.pull SYSTEM "results/ch04-resolve.pull.lxo">
     4.6  <!ENTITY interaction.ch04-resolve.right SYSTEM "results/ch04-resolve.right.lxo">
     4.7 +<!ENTITY interaction.ch11-qdelete.convert SYSTEM "results/ch11-qdelete.convert.lxo">
     4.8 +<!ENTITY interaction.ch11-qdelete.go SYSTEM "results/ch11-qdelete.go.lxo">
     4.9 +<!ENTITY interaction.ch11-qdelete.import SYSTEM "results/ch11-qdelete.import.lxo">
    4.10  <!ENTITY interaction.cmdref.diff-p SYSTEM "results/cmdref.diff-p.lxo">
    4.11  <!ENTITY interaction.daily.copy.after SYSTEM "results/daily.copy.after.lxo">
    4.12  <!ENTITY interaction.daily.copy.cat SYSTEM "results/daily.copy.cat.lxo">

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/ch11/qdelete	Thu Apr 23 22:24:02 2009 -0700
     5.3 @@ -0,0 +1,32 @@
     5.4 +#!/bin/bash
     5.5 +
     5.6 +echo '[extensions]' >> $HGRC
     5.7 +echo 'hgext.mq =' >> $HGRC
     5.8 +
     5.9 +#$ name: go
    5.10 +
    5.11 +hg init myrepo
    5.12 +cd myrepo
    5.13 +hg qinit
    5.14 +hg qnew bad.patch
    5.15 +echo a > a
    5.16 +hg add a
    5.17 +hg qrefresh
    5.18 +hg qdelete bad.patch
    5.19 +hg qpop
    5.20 +hg qdelete bad.patch
    5.21 +
    5.22 +#$ name: convert
    5.23 +
    5.24 +hg qnew good.patch
    5.25 +echo a > a
    5.26 +hg add a
    5.27 +hg qrefresh -m 'Good change'
    5.28 +hg qdelete -r tip
    5.29 +hg qapplied
    5.30 +hg tip --style=compact
    5.31 +
    5.32 +#$ name: import
    5.33 +
    5.34 +hg qimport -r tip
    5.35 +hg qapplied