changeset 828:477d6a3e5023

Many final changes.
author Bryan O'Sullivan <bos@serpentine.com>
date Mon, 04 May 2009 23:52:38 -0700
parents d2aacc06e562
children 18131160f7ee
files en/appB-mq-ref.xml en/ch02-tour-merge.xml en/ch03-concepts.xml en/ch04-daily.xml en/ch05-collab.xml en/ch06-filenames.xml en/ch07-branch.xml en/ch09-hook.xml en/examples/auto-snippets.xml en/examples/daily.copy en/examples/tour
diffstat 11 files changed, 231 insertions(+), 170 deletions(-) [+]
line wrap: on
line diff
--- a/en/appB-mq-ref.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/appB-mq-ref.xml	Mon May 04 23:52:38 2009 -0700
@@ -72,6 +72,16 @@
 
     </sect2>
     <sect2>
+      <title><command role="hg-ext-mq">qfold</command>&emdash;move
+	applied patches into repository history</title>
+
+      <para>The <command>hg qfinish</command> command converts the
+	specified applied patches into permanent changes by moving
+	them out of MQ's control so that they will be treated as
+	normal repository history.</para>
+    </sect2>
+
+    <sect2>
       <title><command role="hg-ext-mq">qfold</command>&emdash;merge
 	(<quote>fold</quote>) several patches into one</title>
 
@@ -328,8 +338,8 @@
 	    no such text, a default commit message is used that
 	    identifies the name of the patch.</para>
 	</listitem></itemizedlist>
-      <para id="x_615">If a patch contains a Mercurial patch header (XXX add
-	link), the information in the patch header overrides these
+      <para id="x_615">If a patch contains a Mercurial patch header,
+	the information in the patch header overrides these
 	defaults.</para>
 
       <para id="x_616">Options:</para>
@@ -435,21 +445,6 @@
 
     </sect2>
     <sect2>
-      <title><command
-	  role="hg-ext-mq">qrestore</command>&emdash;restore saved
-	queue state</title>
-
-      <para id="x_628">XXX No idea what this does.</para>
-
-    </sect2>
-    <sect2>
-      <title><command role="hg-ext-mq">qsave</command>&emdash;save
-	current queue state</title>
-
-      <para id="x_629">XXX Likewise.</para>
-
-    </sect2>
-    <sect2>
       <title><command role="hg-ext-mq">qseries</command>&emdash;print
 	the entire patch series</title>
 
@@ -501,9 +496,7 @@
 	    changesets in the backup bundle.</para>
 	</listitem>
 	<listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
-	    branch has multiple heads, remove all heads. XXX This
-	    should be renamed, and use <literal>-f</literal> to strip
-	    revs when there are pending changes.</para>
+	    branch has multiple heads, remove all heads.</para>
 	</listitem>
 	<listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
 	    not save a backup bundle.</para>
--- a/en/ch02-tour-merge.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/ch02-tour-merge.xml	Mon May 04 23:52:38 2009 -0700
@@ -146,6 +146,7 @@
 
       &interaction.tour.merge.parents;
     </sect2>
+
     <sect2>
       <title>Committing the results of the merge</title>
 
@@ -292,8 +293,8 @@
 	strengths and weaknesses.  Most are tuned for merging files
 	containing plain text, while a few are aimed at specialised
 	file formats (generally XML).</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>A worked example</title>
 
@@ -365,6 +366,7 @@
       </note>
     </sect2>
   </sect1>
+
   <sect1 id="sec:tour-merge:fetch">
     <title>Simplifying the pull-merge-commit sequence</title>
 
@@ -421,7 +423,27 @@
       the extension, but since the <literal
 	role="hg-ext">fetch</literal> extension is in the standard
       distribution, Mercurial knows where to search for it.)</para>
+  </sect1>
 
+  <sect1>
+    <title>Renaming, copying, and merging</title>
+
+    <para>During the life of a project, we will often want to change
+      the layout of its files and directories. This can be as simple
+      as renaming a single file, or as complex as restructuring the
+      entire hierarchy of files within the project.</para>
+
+    <para>Mercurial supports these kinds of complex changes fluently,
+      provided we tell it what we're doing.  If we want to rename a
+      file, we should use the <command>hg rename</command><footnote>
+	<para>If you're a Unix user, you'll be glad to know that the
+	  <command>hg rename</command> command can be abbreviated as
+	  <command>hg mv</command>.</para>
+      </footnote> command to rename it, so that Mercurial can do the
+      right thing later when we merge.</para>
+
+    <para>We will cover the use of these commands in more detail in
+      <xref linkend="chap:daily.copy"/>.</para>
   </sect1>
 </chapter>
 
--- a/en/ch03-concepts.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/ch03-concepts.xml	Mon May 04 23:52:38 2009 -0700
@@ -112,12 +112,15 @@
       <para id="x_2f3">As the illustration shows, there is
 	<emphasis>not</emphasis> a <quote>one to one</quote>
 	relationship between revisions in the changelog, manifest, or
-	filelog. If the manifest hasn't changed between two
-	changesets, the changelog entries for those changesets will
-	point to the same revision of the manifest.  If a file that
+	filelog. If a file that
 	Mercurial tracks hasn't changed between two changesets, the
 	entry for that file in the two revisions of the manifest will
-	point to the same revision of its filelog.</para>
+	point to the same revision of its filelog<footnote>
+	  <para>It is possible (though unusual) for the manifest to
+	    remain the same between two changesets, in which case the
+	    changelog entries for those changesets will point to the
+	    same revision of the manifest.</para>
+	</footnote>.</para>
 
     </sect2>
   </sect1>
@@ -175,16 +178,18 @@
     <sect2>
       <title>Fast retrieval</title>
 
-      <para id="x_2fa">Mercurial cleverly avoids a pitfall common to all earlier
-	revision control systems: the problem of <emphasis>inefficient
-	  retrieval</emphasis>. Most revision control systems store
-	the contents of a revision as an incremental series of
-	modifications against a <quote>snapshot</quote>.  To
-	reconstruct a specific revision, you must first read the
-	snapshot, and then every one of the revisions between the
-	snapshot and your target revision.  The more history that a
-	file accumulates, the more revisions you must read, hence the
-	longer it takes to reconstruct a particular revision.</para>
+      <para id="x_2fa">Mercurial cleverly avoids a pitfall common to
+	all earlier revision control systems: the problem of
+	<emphasis>inefficient retrieval</emphasis>. Most revision
+	control systems store the contents of a revision as an
+	incremental series of modifications against a
+	<quote>snapshot</quote>.  (Some base the snapshot on the
+	oldest revision, others on the newest.)  To reconstruct a
+	specific revision, you must first read the snapshot, and then
+	every one of the revisions between the snapshot and your
+	target revision.  The more history that a file accumulates,
+	the more revisions you must read, hence the longer it takes to
+	reconstruct a particular revision.</para>
 
       <figure id="fig:concepts:snapshot">
 	<title>Snapshot of a revlog, with incremental deltas</title>
@@ -211,25 +216,15 @@
       <sect3>
 	<title>Aside: the influence of video compression</title>
 
-	<para id="x_2fe">If you're familiar with video compression or have ever
-	  watched a TV feed through a digital cable or satellite
-	  service, you may know that most video compression schemes
-	  store each frame of video as a delta against its predecessor
-	  frame.  In addition, these schemes use <quote>lossy</quote>
-	  compression techniques to increase the compression ratio, so
-	  visual errors accumulate over the course of a number of
-	  inter-frame deltas.</para>
+	<para id="x_2fe">If you're familiar with video compression or
+	  have ever watched a TV feed through a digital cable or
+	  satellite service, you may know that most video compression
+	  schemes store each frame of video as a delta against its
+	  predecessor frame.</para>
 
-	<para id="x_2ff">Because it's possible for a video stream to <quote>drop
-	    out</quote> occasionally due to signal glitches, and to
-	  limit the accumulation of artefacts introduced by the lossy
-	  compression process, video encoders periodically insert a
-	  complete frame (called a <quote>key frame</quote>) into the
-	  video stream; the next delta is generated against that
-	  frame.  This means that if the video signal gets
-	  interrupted, it will resume once the next key frame is
-	  received.  Also, the accumulation of encoding errors
-	  restarts anew with each key frame.</para>
+	<para id="x_2ff">Mercurial borrows this idea to make it
+	  possible to reconstruct a revision from a snapshot and a
+	  small number of deltas.</para>
 
       </sect3>
     </sect2>
@@ -261,9 +256,9 @@
 	uncorrupted sections of the revlog, both before and after the
 	corrupted section.  This would not be possible with a
 	delta-only storage model.</para>
-
     </sect2>
   </sect1>
+
   <sect1>
     <title>Revision history, branching, and merging</title>
 
@@ -314,11 +309,15 @@
       those files, with the same contents it had when the changeset
       was committed.</para>
 
-    <para id="x_309">The <emphasis>dirstate</emphasis> contains Mercurial's
-      knowledge of the working directory.  This details which
-      changeset the working directory is updated to, and all of the
-      files that Mercurial is tracking in the working
-      directory.</para>
+    <para id="x_309">The <emphasis>dirstate</emphasis> is a special
+      structure that contains Mercurial's knowledge of the working
+      directory.  It is maintained as a file named
+      <filename>.hg/dirstate</filename> inside a repository.  The
+      dirstate details which changeset the working directory is
+      updated to, and all of the files that Mercurial is tracking in
+      the working directory. It also lets Mercurial quickly notice
+      changed files, by recording their checkout times and
+      sizes.</para>
 
     <para id="x_30a">Just as a revision of a revlog has room for two parents, so
       that it can represent either a normal revision (with one parent)
@@ -426,9 +425,9 @@
       </figure>
 
       <note>
-	<para id="x_315">  If you're new to Mercurial, you should keep in mind a
-	  common <quote>error</quote>, which is to use the <command
-	    role="hg-cmd">hg pull</command> command without any
+	<para id="x_315">If you're new to Mercurial, you should keep
+	  in mind a common <quote>error</quote>, which is to use the
+	  <command role="hg-cmd">hg pull</command> command without any
 	  options.  By default, the <command role="hg-cmd">hg
 	    pull</command> command <emphasis>does not</emphasis>
 	  update the working directory, so you'll bring new changesets
@@ -436,16 +435,19 @@
 	  synced at the same changeset as before the pull.  If you
 	  make some changes and commit afterwards, you'll thus create
 	  a new head, because your working directory isn't synced to
-	  whatever the current tip is.</para>
+	  whatever the current tip is.  To combine the operation of a
+	  pull, followed by an update, run <command>hg pull
+	    -u</command>.</para>
 
-	<para id="x_316">  I put the word <quote>error</quote> in
-	  quotes because all that you need to do to rectify this
-	  situation is <command role="hg-cmd">hg merge</command>, then
-	  <command role="hg-cmd">hg commit</command>.  In other words,
-	  this almost never has negative consequences; it's just
-	  something of a surprise for newcomers.  I'll discuss other
-	  ways to avoid this behavior, and why Mercurial behaves in
-	  this initially surprising way, later on.</para>
+	<para id="x_316">I put the word <quote>error</quote> in quotes
+	  because all that you need to do to rectify the situation
+	  where you created a new head by accident is
+	  <command role="hg-cmd">hg merge</command>, then <command
+	    role="hg-cmd">hg commit</command>.  In other words, this
+	  almost never has negative consequences; it's just something
+	  of a surprise for newcomers.  I'll discuss other ways to
+	  avoid this behavior, and why Mercurial behaves in this
+	  initially surprising way, later on.</para>
       </note>
 
     </sect2>
@@ -511,13 +513,15 @@
 	working directory has two parents; these will become the
 	parents of the new changeset.</para>
 
-      <para id="x_322">Mercurial lets you perform multiple merges, but you must
-	commit the results of each individual merge as you go.  This
-	is necessary because Mercurial only tracks two parents for
-	both revisions and the working directory.  While it would be
-	technically possible to merge multiple changesets at once, the
-	prospect of user confusion and making a terrible mess of a
-	merge immediately becomes overwhelming.</para>
+      <para id="x_322">Mercurial lets you perform multiple merges, but
+	you must commit the results of each individual merge as you
+	go.  This is necessary because Mercurial only tracks two
+	parents for both revisions and the working directory.  While
+	it would be technically feasible to merge multiple changesets
+	at once, Mercurial avoids this for simplicity.  With multi-way
+	merges, the risks of user confusion, nasty conflict
+	resolution, and making a terrible mess of a merge would grow
+	intolerable.</para>
 
     </sect2>
 
@@ -598,10 +602,17 @@
 	  transferred, yielding better network performance over most
 	  kinds of network.</para>
 
-	<para id="x_329">(If the connection is over <command>ssh</command>,
-	  Mercurial <emphasis>doesn't</emphasis> recompress the
-	  stream, because <command>ssh</command> can already do this
-	  itself.)</para>
+	<para id="x_329">If the connection is over
+	  <command>ssh</command>, Mercurial
+	  <emphasis>doesn't</emphasis> recompress the stream, because
+	  <command>ssh</command> can already do this itself.  You can
+	  tell Mercurial to always use <command>ssh</command>'s
+	  compression feature by editing the
+	  <filename>.hgrc</filename> file in your home directory as
+	  follows.</para>
+
+	<programlisting>[ui]
+ssh = ssh -C</programlisting>
 
       </sect3>
     </sect2>
@@ -611,9 +622,8 @@
       <para id="x_32a">Appending to files isn't the whole story when
 	it comes to guaranteeing that a reader won't see a partial
 	write.  If you recall <xref linkend="fig:concepts:metadata"/>,
-	revisions in
-	the changelog point to revisions in the manifest, and
-	revisions in the manifest point to revisions in filelogs.
+	revisions in the changelog point to revisions in the manifest,
+	and revisions in the manifest point to revisions in filelogs.
 	This hierarchy is deliberate.</para>
 
       <para id="x_32b">A writer starts a transaction by writing filelog and
@@ -637,7 +647,7 @@
 	being written to while the read is occurring. This has a big
 	effect on scalability; you can have an arbitrary number of
 	Mercurial processes safely reading data from a repository
-	safely all at once, no matter whether it's being written to or
+	all at once, no matter whether it's being written to or
 	not.</para>
 
       <para id="x_32e">The lockless nature of reading means that if you're
@@ -709,8 +719,8 @@
 	storage is cheap, and this method gives the highest
 	performance while deferring most book-keeping to the operating
 	system.  An alternative scheme would most likely reduce
-	performance and increase the complexity of the software, each
-	of which is much more important to the <quote>feel</quote> of
+	performance and increase the complexity of the software, but
+	speed and simplicity are key to the <quote>feel</quote> of
 	day-to-day use.</para>
 
     </sect2>
@@ -731,18 +741,32 @@
 	dirstate so that it knows what to do with those files when you
 	commit.</para>
 
-      <para id="x_337">When Mercurial is checking the states of files in the
-	working directory, it first checks a file's modification time.
-	If that has not changed, the file must not have been modified.
-	If the file's size has changed, the file must have been
-	modified.  If the modification time has changed, but the size
-	has not, only then does Mercurial need to read the actual
-	contents of the file to see if they've changed. Storing these
-	few extra pieces of information dramatically reduces the
-	amount of data that Mercurial needs to read, which yields
-	large performance improvements compared to other revision
-	control systems.</para>
+      <para id="x_337">The dirstate helps Mercurial to efficiently
+	  check the status of files in a repository.</para>
 
+      <itemizedlist>
+	<listitem>
+	  <para>When Mercurial checks the state of a file in the
+	    working directory, it first checks a file's modification
+	    time against the time in the dirstate that records when
+	    Mercurial last wrote the file. If the last modified time
+	    is the same as the time when Mercurial wrote the file, the
+	    file must not have been modified, so Mercurial does not
+	    need to check any further.</para>
+	</listitem>
+	<listitem>
+	  <para>If the file's size has changed, the file must have
+	    been modified.  If the modification time has changed, but
+	    the size has not, only then does Mercurial need to
+	    actually read the contents of the file to see if it has
+	    changed.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Storing the modification time and size dramatically
+	reduces the number of read operations that Mercurial needs to
+	perform when we run commands like <command>hg status</command>.
+	This results in large performance improvements.</para>
     </sect2>
   </sect1>
 </chapter>
--- a/en/ch04-daily.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/ch04-daily.xml	Mon May 04 23:52:38 2009 -0700
@@ -108,10 +108,11 @@
   <sect1>
     <title>How to stop tracking a file</title>
 
-    <para id="x_1af">Once you decide that a file no longer belongs in your
-      repository, use the <command role="hg-cmd">hg remove</command>
-      command. This deletes the file, and tells Mercurial to stop
-      tracking it.  A removed file is represented in the output of
+    <para id="x_1af">Once you decide that a file no longer belongs in
+      your repository, use the <command role="hg-cmd">hg
+	remove</command> command. This deletes the file, and tells
+      Mercurial to stop tracking it (which will occur at the next
+      commit).  A removed file is represented in the output of
       <command role="hg-cmd">hg status</command> with a
       <quote><literal>R</literal></quote>.</para>
 
@@ -214,7 +215,7 @@
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="chap:daily.copy">
     <title>Copying files</title>
 
     <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg
@@ -535,11 +536,12 @@
       <command role="hg-cmd">hg revert</command> to get rid of
       erroneous changes to a file.</para>
 
-    <para id="x_1e4">It's good to remember that the <command role="hg-cmd">hg
-	revert</command> command is useful for changes that you have
-      not yet committed.  Once you've committed a change, if you
-      decide it was a mistake, you can still do something about it,
-      though your options may be more limited.</para>
+    <para id="x_1e4">It is helpful to remember that the <command
+	role="hg-cmd">hg revert</command> command is useful for
+      changes that you have not yet committed.  Once you've committed
+      a change, if you decide it was a mistake, you can still do
+      something about it, though your options may be more
+      limited.</para>
 
     <para id="x_1e5">For more information about the <command
 	role="hg-cmd">hg revert</command> command, and details about
@@ -817,7 +819,7 @@
 
     <para id="x_6d9">If you perform traditional backups of your master
       repositories to tape or disk, and you want to back up a
-      repository named <filename>myrepo</filename>.  Use <command>hg
+      repository named <filename>myrepo</filename>, use <command>hg
 	clone -U myrepo myrepo.bak</command> to create a
       clone of <filename>myrepo</filename> before you start your
       backups.  The <option>-U</option> option doesn't check out a
--- a/en/ch05-collab.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/ch05-collab.xml	Mon May 04 23:52:38 2009 -0700
@@ -55,18 +55,12 @@
 	linkend="sec:collab:serve"/> below for details of how to use
       this command.</para>
 
-    <para id="x_69e">For longer-lived repositories that you'd like to have
-      permanently available, there are several public hosting services
-      available.</para>
-
-    <itemizedlist>
-      <listitem>
-	<para id="x_69f">Bitbucket, at <ulink
-	    url="http://bitbucket.org/">http://bitbucket.org/</ulink>,
-	  provides free hosting for open source projects, and paid
-	  hosting for commercial projects.</para>
-      </listitem>
-    </itemizedlist>
+    <para id="x_69e">For longer-lived repositories that you'd like to
+      have permanently available, there are several public hosting
+      services available.  Some are free to open source projects,
+      while others offer paid commercial hosting.  An up-to-date list
+      is available at <ulink
+	url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
 
     <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
       has built-in support for several popular hosting technologies,
@@ -827,7 +821,7 @@
 	so that they only print output if they're run interactively.
 	Otherwise these banners will at least clutter up Mercurial's
 	output.  Worse, they could potentially cause problems with
-	running Mercurial commands remotely.  Mercurial makes tries to
+	running Mercurial commands remotely.  Mercurial tries to
 	detect and ignore banners in non-interactive
 	<command>ssh</command> sessions, but it is not foolproof.  (If
 	you're editing your login scripts on your server, the usual
@@ -1107,7 +1101,7 @@
 	  directions inside it to correctly set your
 	  <envar>PYTHONPATH</envar> environment variable.</para>
 
-	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to by
+	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
 	  served with another colourful Python backtrace: this one
 	  will complain that it can't find <filename
 	    class="directory">/path/to/repository</filename>.  Edit
--- a/en/ch06-filenames.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/ch06-filenames.xml	Mon May 04 23:52:38 2009 -0700
@@ -358,10 +358,11 @@
 	  interchangeable is also referred to as <emphasis>case
 	    folding</emphasis>.</para>
       </listitem>
-      <listitem><para id="x_56e">Case sensitive.  The case of a name is
-	  significant at all times. The names <filename>foo</filename>
-	  and {FoO} identify different files.  This is the way Linux
-	  and Unix systems normally work.</para>
+      <listitem><para id="x_56e">Case sensitive.  The case of a name
+	  is significant at all times. The names
+	  <filename>foo</filename> and <filename>FoO</filename>
+	  identify different files.  This is the way Linux and Unix
+	  systems normally work.</para>
       </listitem></itemizedlist>
 
     <para id="x_56f">On Unix-like systems, it is possible to have any or all of
--- a/en/ch07-branch.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/ch07-branch.xml	Mon May 04 23:52:38 2009 -0700
@@ -183,15 +183,15 @@
 	after the revision you specified.  This has an interaction
 	with tags that can surprise the unwary.</para>
 
-      <para id="x_381">Recall that a tag is stored as a revision to the <filename
-	  role="special">.hgtags</filename> file, so that when you
-	create a tag, the changeset in which it's recorded necessarily
-	refers to an older changeset.  When you run <command
-	  role="hg-cmd">hg clone -r foo</command> to clone a
-	repository as of tag <literal>foo</literal>, the new clone
-	<emphasis>will not contain the history that created the
-	  tag</emphasis> that you used to clone the repository.  The
-	result is that you'll get exactly the right subset of the
+      <para id="x_381">Recall that a tag is stored as a revision to
+	the <filename role="special">.hgtags</filename> file. When you
+	create a tag, the changeset in which its recorded refers to an
+	older changeset.  When you run <command role="hg-cmd">hg clone
+	  -r foo</command> to clone a repository as of tag
+	<literal>foo</literal>, the new clone <emphasis>will not
+	  contain any revision newer than the one the tag refers to,
+	  including the revision where the tag was created</emphasis>.
+	The result is that you'll get exactly the right subset of the
 	project's history in the new repository, but
 	<emphasis>not</emphasis> the tag you might have
 	expected.</para>
@@ -227,9 +227,10 @@
   <sect1>
     <title>The flow of changes&emdash;big picture vs. little</title>
 
-    <para id="x_384">To return to the outline I sketched at the beginning of a
-      chapter, let's think about a project that has multiple
-      concurrent pieces of work under development at once.</para>
+    <para id="x_384">To return to the outline I sketched at the
+      beginning of the chapter, let's think about a project that has
+      multiple concurrent pieces of work under development at
+      once.</para>
 
     <para id="x_385">There might be a push for a new <quote>main</quote> release;
       a new minor bugfix release to the last main release; and an
@@ -416,7 +417,7 @@
 
     <para id="x_39e">If you have more than one named branch in a repository,
       Mercurial will remember the branch that your working directory
-      on when you start a command like <command role="hg-cmd">hg
+      is on when you start a command like <command role="hg-cmd">hg
 	update</command> or <command role="hg-cmd">hg pull
 	-u</command>.  It will update the working directory to the tip
       of this branch, no matter what the <quote>repo-wide</quote> tip
--- a/en/ch09-hook.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/ch09-hook.xml	Mon May 04 23:52:38 2009 -0700
@@ -21,6 +21,12 @@
       supports. We will revisit each of these hooks in more detail
       later, in <xref linkend="sec:hook:ref"/>.</para>
 
+    <para id="x_1f6">Each of the hooks whose description begins with the word
+      <quote>Controlling</quote> has the ability to determine whether
+      an activity can proceed.  If the hook succeeds, the activity may
+      proceed; if it fails, the activity is either not permitted or
+      undone, depending on the hook.</para>
+
     <itemizedlist>
       <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This
 	  is run after a group of changesets has been brought into the
@@ -87,12 +93,6 @@
 	  finished.
 	</para>
       </listitem></itemizedlist>
-    <para id="x_1f6">Each of the hooks whose description begins with the word
-      <quote>Controlling</quote> has the ability to determine whether
-      an activity can proceed.  If the hook succeeds, the activity may
-      proceed; if it fails, the activity is either not permitted or
-      undone, depending on the hook.
-    </para>
 
   </sect1>
   <sect1>
@@ -139,11 +139,11 @@
 	</para>
       </note>
 
-      <para id="x_1fb">XXX To see what hooks are defined in a repository, use the
-	<command role="hg-cmd">hg config hooks</command> command.  If
-	you are working in one repository, but talking to another that
-	you do not own (e.g. using <command role="hg-cmd">hg
-	  pull</command> or <command role="hg-cmd">hg
+      <para id="x_1fb">To see what hooks are defined in a repository,
+	use the <command role="hg-cmd">hg showconfig hooks</command>
+	command.  If you are working in one repository, but talking to
+	another that you do not own (e.g. using <command
+	  role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg
 	  incoming</command>), remember that it is the other
 	repository's hooks you should be checking, not your own.
       </para>
@@ -585,11 +585,11 @@
 
       &interaction.ch09-hook.ws.better;
 
-      <para id="x_237">As a final aside, note in the example above the use of
-	<command>perl</command>'s in-place editing feature to get rid
-	of trailing whitespace from a file.  This is concise and
-	useful enough that I will reproduce it here.
-      </para>
+      <para id="x_237">As a final aside, note in the example above the
+	use of <command>sed</command>'s in-place editing feature to
+	get rid of trailing whitespace from a file.  This is concise
+	and useful enough that I will reproduce it here (using
+	<command>perl</command> for good measure).</para>
       <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting>
 
     </sect2>
@@ -817,10 +817,7 @@
 		role="rc-item-bugzilla">version</envar>: The version
 	      of Bugzilla installed on the server.  The database
 	      schema that Bugzilla uses changes occasionally, so this
-	      hook has to know exactly which schema to use. At the
-	      moment, the only version supported is
-	      <literal>2.16</literal>.
-	    </para>
+	      hook has to know exactly which schema to use.</para>
 	  </listitem>
 	  <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>:
 	      The hostname of the MySQL server that stores your
--- a/en/examples/auto-snippets.xml	Sun May 03 20:27:28 2009 -0700
+++ b/en/examples/auto-snippets.xml	Mon May 04 23:52:38 2009 -0700
@@ -57,6 +57,15 @@
 <!ENTITY interaction.ch01-new.init SYSTEM "results/ch01-new.init.lxo">
 <!ENTITY interaction.ch01-new.ls SYSTEM "results/ch01-new.ls.lxo">
 <!ENTITY interaction.ch01-new.ls2 SYSTEM "results/ch01-new.ls2.lxo">
+<!ENTITY interaction.ch02-rename.alice SYSTEM "results/ch02-rename.alice.lxo">
+<!ENTITY interaction.ch02-rename.bob SYSTEM "results/ch02-rename.bob.lxo">
+<!ENTITY interaction.ch02-rename.clone SYSTEM "results/ch02-rename.clone.lxo">
+<!ENTITY interaction.ch02-rename.clone2 SYSTEM "results/ch02-rename.clone2.lxo">
+<!ENTITY interaction.ch02-rename.init SYSTEM "results/ch02-rename.init.lxo">
+<!ENTITY interaction.ch02-rename.merge SYSTEM "results/ch02-rename.merge.lxo">
+<!ENTITY interaction.ch02-rename.merge2 SYSTEM "results/ch02-rename.merge2.lxo">
+<!ENTITY interaction.ch02-rename.status SYSTEM "results/ch02-rename.status.lxo">
+<!ENTITY interaction.ch02-rename.status2 SYSTEM "results/ch02-rename.status2.lxo">
 <!ENTITY interaction.ch04-diff.chmod SYSTEM "results/ch04-diff.chmod.lxo">
 <!ENTITY interaction.ch04-diff.chmod.git SYSTEM "results/ch04-diff.chmod.git.lxo">
 <!ENTITY interaction.ch04-diff.rename.basic SYSTEM "results/ch04-diff.rename.basic.lxo">
@@ -88,6 +97,19 @@
 <!ENTITY interaction.daily.copy.dir-src-dest SYSTEM "results/daily.copy.dir-src-dest.lxo">
 <!ENTITY interaction.daily.copy.init SYSTEM "results/daily.copy.init.lxo">
 <!ENTITY interaction.daily.copy.merge SYSTEM "results/daily.copy.merge.lxo">
+<!ENTITY interaction.daily.copy.orig.after SYSTEM "results/daily.copy.orig.after.lxo">
+<!ENTITY interaction.daily.copy.orig.cat SYSTEM "results/daily.copy.orig.cat.lxo">
+<!ENTITY interaction.daily.copy.orig.clone SYSTEM "results/daily.copy.orig.clone.lxo">
+<!ENTITY interaction.daily.copy.orig.copy SYSTEM "results/daily.copy.orig.copy.lxo">
+<!ENTITY interaction.daily.copy.orig.dir-dest SYSTEM "results/daily.copy.orig.dir-dest.lxo">
+<!ENTITY interaction.daily.copy.orig.dir-src SYSTEM "results/daily.copy.orig.dir-src.lxo">
+<!ENTITY interaction.daily.copy.orig.dir-src-dest SYSTEM "results/daily.copy.orig.dir-src-dest.lxo">
+<!ENTITY interaction.daily.copy.orig.init SYSTEM "results/daily.copy.orig.init.lxo">
+<!ENTITY interaction.daily.copy.orig.merge SYSTEM "results/daily.copy.orig.merge.lxo">
+<!ENTITY interaction.daily.copy.orig.other SYSTEM "results/daily.copy.orig.other.lxo">
+<!ENTITY interaction.daily.copy.orig.simple SYSTEM "results/daily.copy.orig.simple.lxo">
+<!ENTITY interaction.daily.copy.orig.status SYSTEM "results/daily.copy.orig.status.lxo">
+<!ENTITY interaction.daily.copy.orig.status-copy SYSTEM "results/daily.copy.orig.status-copy.lxo">
 <!ENTITY interaction.daily.copy.other SYSTEM "results/daily.copy.other.lxo">
 <!ENTITY interaction.daily.copy.simple SYSTEM "results/daily.copy.simple.lxo">
 <!ENTITY interaction.daily.copy.status SYSTEM "results/daily.copy.status.lxo">
--- a/en/examples/daily.copy	Sun May 03 20:27:28 2009 -0700
+++ b/en/examples/daily.copy	Mon May 04 23:52:38 2009 -0700
@@ -51,9 +51,9 @@
 cd copy-example
 echo a > a
 echo b > b
-mkdir c
-mkdir c/a
-echo c > c/a/c
+mkdir z
+mkdir z/a
+echo c > z/a/c
 hg ci -Ama
 
 #$ name: simple
@@ -70,13 +70,13 @@
 
 #$ name: dir-src
 
-hg copy c e
+hg copy z e
 
 #$ name: dir-src-dest
 
-hg copy c d
+hg copy z d
 
 #$ name: after
 
-cp a z
-hg copy --after a z
+cp a n
+hg copy --after a n
--- a/en/examples/tour	Sun May 03 20:27:28 2009 -0700
+++ b/en/examples/tour	Mon May 04 23:52:38 2009 -0700
@@ -151,13 +151,18 @@
 cp hello.c ../new-hello.c
 sed -i '/printf("hello,/i\\tprintf("once more, hello.\\n");' ../new-hello.c
 
+my-text-editor()
+{
+cp ../new-hello.c hello.c
+}
+
 #$ name: merge.clone
 
 cd ..
 hg clone hello my-new-hello
 cd my-new-hello
-# The file new-hello.c is lightly edited.
-cp ../new-hello.c hello.c
+# Make some simple edits to hello.c.
+my-text-editor hello.c
 hg commit -m 'A new hello for a new day.'
 
 #$ name: merge.dummy2