Anonymous avatar Anonymous committed f011000

french translation : sync with original files (en/ch05 to en/ch14 and appD)

Comments (0)

Files changed (11)

fr/appD-license.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<chapter>
-<title>Open Publication License</title>
-<para>\label{cha:opl}</para>
+<appendix id="cha:opl">
+  <?dbhtml filename="open-publication-license.html"?>
+  <title>Open Publication License</title>
 
-<para>Version 1.0, 8 June 1999</para>
+  <para id="x_638">Version 1.0, 8 June 1999</para>
 
-<sect1>
-<title>Requirements on both unmodified and modified versions</title>
+  <sect1>
+    <title>Requirements on both unmodified and modified
+      versions</title>
 
-<para>The Open Publication works may be reproduced and distributed in whole
-or in part, in any medium physical or electronic, provided that the
-terms of this license are adhered to, and that this license or an
-incorporation of it by reference (with any options elected by the
-author(s) and/or publisher) is displayed in the reproduction.</para>
+    <para id="x_639">The Open Publication works may be reproduced and distributed
+      in whole or in part, in any medium physical or electronic,
+      provided that the terms of this license are adhered to, and that
+      this license or an incorporation of it by reference (with any
+      options elected by the author(s) and/or publisher) is displayed
+      in the reproduction.</para>
 
-<para>Proper form for an incorporation by reference is as follows:</para>
+    <para id="x_63a">Proper form for an incorporation by reference is as
+      follows:</para>
 
-<blockquote>
-<para>  Copyright (c) <emphasis>year</emphasis> by <emphasis>author's name or designee</emphasis>. This
-  material may be distributed only subject to the terms and conditions
-  set forth in the Open Publication License, v<emphasis>x.y</emphasis> or later (the
-  latest version is presently available at
-  <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
-</blockquote>
+    <blockquote>
+      <para id="x_63b">  Copyright (c) <emphasis>year</emphasis> by
+	<emphasis>author's name or designee</emphasis>. This material
+	may be distributed only subject to the terms and conditions
+	set forth in the Open Publication License,
+	v<emphasis>x.y</emphasis> or later (the latest version is
+	presently available at <ulink
+	  url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
+    </blockquote>
 
-<para>The reference must be immediately followed with any options elected by
-the author(s) and/or publisher of the document (see
-section <xref linkend="sec:opl:options"/>).</para>
+    <para id="x_63c">The reference must be immediately followed with any options
+      elected by the author(s) and/or publisher of the document (see
+      <xref linkend="sec:opl:options"/>).</para>
 
-<para>Commercial redistribution of Open Publication-licensed material is
-permitted.</para>
+    <para id="x_63d">Commercial redistribution of Open Publication-licensed
+      material is permitted.</para>
 
-<para>Any publication in standard (paper) book form shall require the
-citation of the original publisher and author. The publisher and
-author's names shall appear on all outer surfaces of the book. On all
-outer surfaces of the book the original publisher's name shall be as
-large as the title of the work and cited as possessive with respect to
-the title.</para>
+    <para id="x_63e">Any publication in standard (paper) book form shall require
+      the citation of the original publisher and author. The publisher
+      and author's names shall appear on all outer surfaces of the
+      book. On all outer surfaces of the book the original publisher's
+      name shall be as large as the title of the work and cited as
+      possessive with respect to the title.</para>
 
-</sect1>
-<sect1>
-<title>Copyright</title>
+  </sect1>
+  <sect1>
+    <title>Copyright</title>
 
-<para>The copyright to each Open Publication is owned by its author(s) or
-designee.
-</para>
+    <para id="x_63f">The copyright to each Open Publication is owned by its
+      author(s) or designee.</para>
 
-</sect1>
-<sect1>
-<title>Scope of license</title>
+  </sect1>
+  <sect1>
+    <title>Scope of license</title>
 
-<para>The following license terms apply to all Open Publication works,
-unless otherwise explicitly stated in the document.
-</para>
+    <para id="x_640">The following license terms apply to all Open Publication
+      works, unless otherwise explicitly stated in the
+      document.</para>
 
-<para>Mere aggregation of Open Publication works or a portion of an Open
-Publication work with other works or programs on the same media shall
-not cause this license to apply to those other works. The aggregate
-work shall contain a notice specifying the inclusion of the Open
-Publication material and appropriate copyright notice.
-</para>
+    <para id="x_641">Mere aggregation of Open Publication works or a portion of
+      an Open Publication work with other works or programs on the
+      same media shall not cause this license to apply to those other
+      works. The aggregate work shall contain a notice specifying the
+      inclusion of the Open Publication material and appropriate
+      copyright notice.</para>
 
-<para><emphasis role="bold">Severability</emphasis>. If any part of this license is found to be
-unenforceable in any jurisdiction, the remaining portions of the
-license remain in force.
-</para>
+    <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part
+      of this license is found to be unenforceable in any
+      jurisdiction, the remaining portions of the license remain in
+      force.</para>
 
-<para><emphasis role="bold">No warranty</emphasis>. Open Publication works are licensed and provided
-<quote>as is</quote> without warranty of any kind, express or implied, including,
-but not limited to, the implied warranties of merchantability and
-fitness for a particular purpose or a warranty of non-infringement.
-</para>
+    <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open
+      Publication works are licensed and provided <quote>as is</quote>
+      without warranty of any kind, express or implied, including, but
+      not limited to, the implied warranties of merchantability and
+      fitness for a particular purpose or a warranty of
+      non-infringement.</para>
 
-</sect1>
-<sect1>
-<title>Requirements on modified works</title>
+  </sect1>
+  <sect1>
+    <title>Requirements on modified works</title>
 
-<para>All modified versions of documents covered by this license, including
-translations, anthologies, compilations and partial documents, must
-meet the following requirements:
-</para>
+    <para id="x_644">All modified versions of documents covered by this license,
+      including translations, anthologies, compilations and partial
+      documents, must meet the following requirements:</para>
 
-<orderedlist>
-<listitem><para>The modified version must be labeled as such.
-</para>
-</listitem>
-<listitem><para>The person making the modifications must be identified and the
-  modifications dated.
-</para>
-</listitem>
-<listitem><para>Acknowledgement of the original author and publisher if
-  applicable must be retained according to normal academic citation
-  practices.
-</para>
-</listitem>
-<listitem><para>The location of the original unmodified document must be
-  identified.
-</para>
-</listitem>
-<listitem><para>The original author's (or authors') name(s) may not be used to
-  assert or imply endorsement of the resulting document without the
-  original author's (or authors') permission.
-</para>
-</listitem></orderedlist>
+    <orderedlist>
+      <listitem><para id="x_645">The modified version must be labeled as
+	  such.</para>
+      </listitem>
+      <listitem><para id="x_646">The person making the modifications must be
+	  identified and the modifications dated.</para>
+      </listitem>
+      <listitem><para id="x_647">Acknowledgement of the original author and
+	  publisher if applicable must be retained according to normal
+	  academic citation practices.</para>
+      </listitem>
+      <listitem><para id="x_648">The location of the original unmodified document
+	  must be identified.</para>
+      </listitem>
+      <listitem><para id="x_649">The original author's (or authors') name(s) may
+	  not be used to assert or imply endorsement of the resulting
+	  document without the original author's (or authors')
+	  permission.</para>
+      </listitem></orderedlist>
 
-</sect1>
-<sect1>
-<title>Good-practice recommendations</title>
+  </sect1>
+  <sect1>
+    <title>Good-practice recommendations</title>
 
-<para>In addition to the requirements of this license, it is requested from
-and strongly recommended of redistributors that:
-</para>
+    <para id="x_64a">In addition to the requirements of this license, it is
+      requested from and strongly recommended of redistributors
+      that:</para>
 
-<orderedlist>
-<listitem><para>If you are distributing Open Publication works on hardcopy or
-  CD-ROM, you provide email notification to the authors of your intent
-  to redistribute at least thirty days before your manuscript or media
-  freeze, to give the authors time to provide updated documents. This
-  notification should describe modifications, if any, made to the
-  document.
-</para>
-</listitem>
-<listitem><para>All substantive modifications (including deletions) be either
-  clearly marked up in the document or else described in an attachment
-  to the document.
-</para>
-</listitem>
-<listitem><para>Finally, while it is not mandatory under this license, it is
-  considered good form to offer a free copy of any hardcopy and CD-ROM
-  expression of an Open Publication-licensed work to its author(s).
-</para>
-</listitem></orderedlist>
+    <orderedlist>
+      <listitem><para id="x_64b">If you are distributing Open Publication works
+	  on hardcopy or CD-ROM, you provide email notification to the
+	  authors of your intent to redistribute at least thirty days
+	  before your manuscript or media freeze, to give the authors
+	  time to provide updated documents. This notification should
+	  describe modifications, if any, made to the document.</para>
+      </listitem>
+      <listitem><para id="x_64c">All substantive modifications (including
+	  deletions) be either clearly marked up in the document or
+	  else described in an attachment to the document.</para>
+      </listitem>
+      <listitem><para id="x_64d">Finally, while it is not mandatory under this
+	  license, it is considered good form to offer a free copy of
+	  any hardcopy and CD-ROM expression of an Open
+	  Publication-licensed work to its author(s).</para>
+      </listitem></orderedlist>
 
-</sect1>
-<sect1>
-<title>License options</title>
-<para>\label{sec:opl:options}
-</para>
+  </sect1>
+  <sect1 id="sec:opl:options">
+    <title>License options</title>
 
-<para>The author(s) and/or publisher of an Open Publication-licensed
-document may elect certain options by appending language to the
-reference to or copy of the license. These options are considered part
-of the license instance and must be included with the license (or its
-incorporation by reference) in derived works.
-</para>
+    <para id="x_64e">The author(s) and/or publisher of an Open
+      Publication-licensed document may elect certain options by
+      appending language to the reference to or copy of the license.
+      These options are considered part of the license instance and
+      must be included with the license (or its incorporation by
+      reference) in derived works.</para>
 
-<orderedlist>
-<listitem><para>To prohibit distribution of substantively modified versions
-  without the explicit permission of the author(s). <quote>Substantive
-  modification</quote> is defined as a change to the semantic content of the
-  document, and excludes mere changes in format or typographical
-  corrections.
-</para>
-</listitem>
-<listitem><para>  To accomplish this, add the phrase <quote>Distribution of substantively
-  modified versions of this document is prohibited without the
-  explicit permission of the copyright holder.</quote> to the license
-  reference or copy.
-</para>
-</listitem>
-</para>
-</listitem>
-<listitem><para>To prohibit any publication of this work or derivative works in
-  whole or in part in standard (paper) book form for commercial
-  purposes is prohibited unless prior permission is obtained from the
-  copyright holder.
-</para>
-</listitem>
-<listitem><para>  To accomplish this, add the phrase <quote>Distribution of the work or
-  derivative of the work in any standard (paper) book form is
-  prohibited unless prior permission is obtained from the copyright
-  holder.</quote> to the license reference or copy.
-</para>
-</listitem></orderedlist>
+    <orderedlist>
+      <listitem><para id="x_64f">To prohibit distribution of substantively
+	  modified versions without the explicit permission of the
+	  author(s). <quote>Substantive modification</quote> is
+	  defined as a change to the semantic content of the document,
+	  and excludes mere changes in format or typographical
+	  corrections.</para>
+      </listitem>
+      <listitem><para id="x_650">  To accomplish this, add the phrase
+	  <quote>Distribution of substantively modified versions of
+	    this document is prohibited without the explicit
+	    permission of the copyright holder.</quote> to the license
+	  reference or copy.</para>
+      </listitem>
+      <listitem><para id="x_651">To prohibit any publication of this work or
+	  derivative works in whole or in part in standard (paper)
+	  book form for commercial purposes is prohibited unless prior
+	  permission is obtained from the copyright holder.</para>
+      </listitem>
+      <listitem><para id="x_652">To accomplish this, add the phrase
+	  <quote>Distribution of the work or derivative of the work in
+	    any standard (paper) book form is prohibited unless prior
+	    permission is obtained from the copyright holder.</quote>
+	  to the license reference or copy.</para>
+      </listitem></orderedlist>
 
-</sect1>
-</chapter>
+  </sect1>
+</appendix>
 
 <!--
 local variables: 
-sgml-parent-document: ("00book.xml" "book" "chapter")
+sgml-parent-document: ("00book.xml" "book" "appendix")
 end:
--->
+-->

fr/ch05-daily.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<chapter>
-<title>Mercurial in daily use</title>
-<para>\label{chap:daily}</para>
+<chapter id="chap:daily">
+  <?dbhtml filename="mercurial-in-daily-use.html"?>
+  <title>Mercurial in daily use</title>
 
-<sect1>
-<title>Telling Mercurial which files to track</title>
+  <sect1>
+    <title>Telling Mercurial which files to track</title>
 
-<para>Mercurial does not work with files in your repository unless you tell
-it to manage them.  The <command role="hg-cmd">hg status</command> command will tell you which
-files Mercurial doesn't know about; it uses a <quote><literal>?</literal></quote> to
-display such files.</para>
+    <para id="x_1a3">Mercurial does not work with files in your repository unless
+      you tell it to manage them.  The <command role="hg-cmd">hg
+	status</command> command will tell you which files Mercurial
+      doesn't know about; it uses a
+      <quote><literal>?</literal></quote> to display such
+      files.</para>
 
-<para>To tell Mercurial to track a file, use the <command role="hg-cmd">hg add</command> command.  Once
-you have added a file, the entry in the output of <command role="hg-cmd">hg status</command> for
-that file changes from <quote><literal>?</literal></quote> to <quote><literal>A</literal></quote>.
-<!-- &interaction.daily.files.add; --></para>
+    <para id="x_1a4">To tell Mercurial to track a file, use the <command
+	role="hg-cmd">hg add</command> command.  Once you have added a
+      file, the entry in the output of <command role="hg-cmd">hg
+	status</command> for that file changes from
+      <quote><literal>?</literal></quote> to
+      <quote><literal>A</literal></quote>.</para>
 
-<para>After you run a <command role="hg-cmd">hg commit</command>, the files that you added before the
-commit will no longer be listed in the output of <command role="hg-cmd">hg status</command>.  The
-reason for this is that <command role="hg-cmd">hg status</command> only tells you about
-<quote>interesting</quote> files&emdash;those that you have modified or told Mercurial
-to do something with&emdash;by default.  If you have a repository that
-contains thousands of files, you will rarely want to know about files
-that Mercurial is tracking, but that have not changed.  (You can still
-get this information; we'll return to this later.)</para>
+      &interaction.daily.files.add;
 
-<para>Once you add a file, Mercurial doesn't do anything with it
-immediately.  Instead, it will take a snapshot of the file's state the
-next time you perform a commit.  It will then continue to track the
-changes you make to the file every time you commit, until you remove
-the file.</para>
+    <para id="x_1a5">After you run a <command role="hg-cmd">hg commit</command>,
+      the files that you added before the commit will no longer be
+      listed in the output of <command role="hg-cmd">hg
+	status</command>.  The reason for this is that by default, <command
+	role="hg-cmd">hg status</command> only tells you about
+      <quote>interesting</quote> files&emdash;those that you have (for
+      example) modified, removed, or renamed.  If you have a repository
+      that contains thousands of files, you will rarely want to know
+      about files that Mercurial is tracking, but that have not
+      changed.  (You can still get this information; we'll return to
+      this later.)</para>
 
-<sect2>
-<title>Explicit versus implicit file naming</title>
+    <para id="x_1a6">Once you add a file, Mercurial doesn't do anything with it
+      immediately.  Instead, it will take a snapshot of the file's
+      state the next time you perform a commit.  It will then continue
+      to track the changes you make to the file every time you commit,
+      until you remove the file.</para>
 
-<para>A useful behaviour that Mercurial has is that if you pass the name of
-a directory to a command, every Mercurial command will treat this as
-<quote>I want to operate on every file in this directory and its
-subdirectories</quote>.
-<!-- &interaction.daily.files.add-dir; -->
-Notice in this example that Mercurial printed the names of the files
-it added, whereas it didn't do so when we added the file named
-<filename>a</filename> in the earlier example.</para>
+    <sect2>
+      <title>Explicit versus implicit file naming</title>
 
-<para>What's going on is that in the former case, we explicitly named the
-file to add on the command line, so the assumption that Mercurial
-makes in such cases is that you know what you were doing, and it
-doesn't print any output.</para>
+      <para id="x_1a7">A useful behavior that Mercurial has is that if you pass
+	the name of a directory to a command, every Mercurial command
+	will treat this as <quote>I want to operate on every file in
+	  this directory and its subdirectories</quote>.</para>
 
-<para>However, when we <emphasis>imply</emphasis> the names of files by giving the name of
-a directory, Mercurial takes the extra step of printing the name of
-each file that it does something with.  This makes it more clear what
-is happening, and reduces the likelihood of a silent and nasty
-surprise.  This behaviour is common to most Mercurial commands.</para>
+      &interaction.daily.files.add-dir;
 
-</sect2>
-<sect2>
-<title>Aside: Mercurial tracks files, not directories</title>
+      <para id="x_1a8">Notice in this example that Mercurial printed
+	the names of the files it added, whereas it didn't do so when
+	we added the file named <filename>myfile.txt</filename> in the
+	earlier example.</para>
 
-<para>Mercurial does not track directory information.  Instead, it tracks
-the path to a file.  Before creating a file, it first creates any
-missing directory components of the path.  After it deletes a file, it
-then deletes any empty directories that were in the deleted file's
-path.  This sounds like a trivial distinction, but it has one minor
-practical consequence: it is not possible to represent a completely
-empty directory in Mercurial.
-</para>
+      <para id="x_1a9">What's going on is that in the former case, we explicitly
+	named the file to add on the command line.  The assumption
+	that Mercurial makes in such cases is that we know what we
+	are doing, and it doesn't print any output.</para>
 
-<para>Empty directories are rarely useful, and there are unintrusive
-workarounds that you can use to achieve an appropriate effect.  The
-developers of Mercurial thus felt that the complexity that would be
-required to manage empty directories was not worth the limited benefit
-this feature would bring.
-</para>
+      <para id="x_1aa">However, when we <emphasis>imply</emphasis> the names of
+	files by giving the name of a directory, Mercurial takes the
+	extra step of printing the name of each file that it does
+	something with.  This makes it more clear what is happening,
+	and reduces the likelihood of a silent and nasty surprise.
+	This behavior is common to most Mercurial commands.</para>
+    </sect2>
 
-<para>If you need an empty directory in your repository, there are a few
-ways to achieve this. One is to create a directory, then <command role="hg-cmd">hg add</command> a
-<quote>hidden</quote> file to that directory.  On Unix-like systems, any file
-name that begins with a period (<quote><literal>.</literal></quote>) is treated as hidden
-by most commands and GUI tools.  This approach is illustrated in
-figure <xref linkend="ex:daily:hidden"/>.
-</para>
+    <sect2>
+      <title>Mercurial tracks files, not directories</title>
 
-<informalfigure>
-<para>  <!-- &interaction.daily.files.hidden; -->
-  <caption><para>Simulating an empty directory using a hidden file</para></caption>
-  \label{ex:daily:hidden}
-</para>
-</informalfigure>
+      <para id="x_1ab">Mercurial does not track directory information.  Instead,
+	it tracks the path to a file.  Before creating a file, it
+	first creates any missing directory components of the path.
+	After it deletes a file, it then deletes any empty directories
+	that were in the deleted file's path.  This sounds like a
+	trivial distinction, but it has one minor practical
+	consequence: it is not possible to represent a completely
+	empty directory in Mercurial.</para>
 
-<para>Another way to tackle a need for an empty directory is to simply
-create one in your automated build scripts before they will need it.
-</para>
+      <para id="x_1ac">Empty directories are rarely useful, and there are
+	unintrusive workarounds that you can use to achieve an
+	appropriate effect.  The developers of Mercurial thus felt
+	that the complexity that would be required to manage empty
+	directories was not worth the limited benefit this feature
+	would bring.</para>
 
-</sect2>
-</sect1>
-<sect1>
-<title>How to stop tracking a file</title>
+      <para id="x_1ad">If you need an empty directory in your repository, there
+	are a few ways to achieve this. One is to create a directory,
+	then <command role="hg-cmd">hg add</command> a
+	<quote>hidden</quote> file to that directory.  On Unix-like
+	systems, any file name that begins with a period
+	(<quote><literal>.</literal></quote>) is treated as hidden by
+	most commands and GUI tools.  This approach is illustrated
+	below.</para>
 
-<para>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
-<command role="hg-cmd">hg status</command> with a <quote><literal>R</literal></quote>.
-<!-- &interaction.daily.files.remove; -->
-</para>
+&interaction.daily.files.hidden;
 
-<para>After you <command role="hg-cmd">hg remove</command> a file, Mercurial will no longer track
-changes to that file, even if you recreate a file with the same name
-in your working directory.  If you do recreate a file with the same
-name and want Mercurial to track the new file, simply <command role="hg-cmd">hg add</command> it.
-Mercurial will know that the newly added file is not related to the
-old file of the same name.
-</para>
+      <para id="x_1ae">Another way to tackle a need for an empty directory is to
+	simply create one in your automated build scripts before they
+	will need it.</para>
+    </sect2>
+  </sect1>
 
-<sect2>
-<title>Removing a file does not affect its history</title>
+  <sect1>
+    <title>How to stop tracking a file</title>
 
-<para>It is important to understand that removing a file has only two
-effects.
-</para>
-<itemizedlist>
-<listitem><para>It removes the current version of the file from the working
-  directory.
-</para>
-</listitem>
-<listitem><para>It stops Mercurial from tracking changes to the file, from the
-  time of the next commit.
-</para>
-</listitem></itemizedlist>
-<para>Removing a file <emphasis>does not</emphasis> in any way alter the <emphasis>history</emphasis> of
-the file.
-</para>
+    <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>
 
-<para>If you update the working directory to a changeset in which a file
-that you have removed was still tracked, it will reappear in the
-working directory, with the contents it had when you committed that
-changeset.  If you then update the working directory to a later
-changeset, in which the file had been removed, Mercurial will once
-again remove the file from the working directory.
-</para>
+    &interaction.daily.files.remove;
 
-</sect2>
-<sect2>
-<title>Missing files</title>
+    <para id="x_1b0">After you <command role="hg-cmd">hg remove</command> a file,
+      Mercurial will no longer track changes to that file, even if you
+      recreate a file with the same name in your working directory.
+      If you do recreate a file with the same name and want Mercurial
+      to track the new file, simply <command role="hg-cmd">hg
+	add</command> it. Mercurial will know that the newly added
+      file is not related to the old file of the same name.</para>
 
-<para>Mercurial considers a file that you have deleted, but not used
-<command role="hg-cmd">hg remove</command> to delete, to be <emphasis>missing</emphasis>.  A missing file is
-represented with <quote><literal>!</literal></quote> in the output of <command role="hg-cmd">hg status</command>.
-Mercurial commands will not generally do anything with missing files.
-<!-- &interaction.daily.files.missing; -->
-</para>
+    <sect2>
+      <title>Removing a file does not affect its history</title>
 
-<para>If your repository contains a file that <command role="hg-cmd">hg status</command> reports as
-missing, and you want the file to stay gone, you can run
-<command role="hg-cmd">hg remove <option role="hg-opt-remove">--after</option></command> at any time later on, to
-tell Mercurial that you really did mean to remove the file.
-<!-- &interaction.daily.files.remove-after; -->
-</para>
+      <para id="x_1b1">It is important to understand that removing a file has
+	only two effects.</para>
+      <itemizedlist>
+	<listitem><para id="x_1b2">It removes the current version of the file
+	    from the working directory.</para>
+	</listitem>
+	<listitem><para id="x_1b3">It stops Mercurial from tracking changes to
+	    the file, from the time of the next commit.</para>
+	</listitem></itemizedlist>
+      <para id="x_1b4">Removing a file <emphasis>does not</emphasis> in any way
+	alter the <emphasis>history</emphasis> of the file.</para>
 
-<para>On the other hand, if you deleted the missing file by accident, use
-<command role="hg-cmd">hg revert <emphasis>filename</emphasis></command> to recover the file.  It will
-reappear, in unmodified form.
-<!-- &interaction.daily.files.recover-missing; -->
-</para>
+      <para id="x_1b5">If you update the working directory to a
+	changeset that was committed when it was still tracking a file
+	that you later removed, the file will reappear in the working
+	directory, with the contents it had when you committed that
+	changeset.  If you then update the working directory to a
+	later changeset, in which the file had been removed, Mercurial
+	will once again remove the file from the working
+	directory.</para>
+    </sect2>
 
-<para>\subsection{Aside: why tell Mercurial explicitly to
-  remove a file?}
-</para>
+    <sect2>
+      <title>Missing files</title>
 
-<para>You might wonder why Mercurial requires you to explicitly tell it that
-you are deleting a file.  Early during the development of Mercurial,
-it let you delete a file however you pleased; Mercurial would notice
-the absence of the file automatically when you next ran a
-<command role="hg-cmd">hg commit</command>, and stop tracking the file.  In practice, this made it
-too easy to accidentally remove a file without noticing.
-</para>
+      <para id="x_1b6">Mercurial considers a file that you have deleted, but not
+	used <command role="hg-cmd">hg remove</command> to delete, to
+	be <emphasis>missing</emphasis>.  A missing file is
+	represented with <quote><literal>!</literal></quote> in the
+	output of <command role="hg-cmd">hg status</command>.
+	Mercurial commands will not generally do anything with missing
+	files.</para>
 
-<para>\subsection{Useful shorthand&emdash;adding and removing files
-  in one step}
-</para>
+      &interaction.daily.files.missing;
 
-<para>Mercurial offers a combination command, <command role="hg-cmd">hg addremove</command>, that adds
-untracked files and marks missing files as removed.
-<!-- &interaction.daily.files.addremove; -->
-The <command role="hg-cmd">hg commit</command> command also provides a <option role="hg-opt-commit">-A</option> option
-that performs this same add-and-remove, immediately followed by a
-commit.
-<!-- &interaction.daily.files.commit-addremove; -->
-</para>
+      <para id="x_1b7">If your repository contains a file that <command
+	  role="hg-cmd">hg status</command> reports as missing, and
+	you want the file to stay gone, you can run <command
+	  role="hg-cmd">hg remove <option
+	    role="hg-opt-remove">--after</option></command> at any
+	time later on, to tell Mercurial that you really did mean to
+	remove the file.</para>
 
-</sect2>
-</sect1>
-<sect1>
-<title>Copying files</title>
+      &interaction.daily.files.remove-after;
 
-<para>Mercurial provides a <command role="hg-cmd">hg copy</command> command that lets you make a new
-copy of a file.  When you copy a file using this command, Mercurial
-makes a record of the fact that the new file is a copy of the original
-file.  It treats these copied files specially when you merge your work
-with someone else's.
-</para>
+      <para id="x_1b8">On the other hand, if you deleted the missing file by
+	accident, give <command role="hg-cmd">hg revert</command> the
+	name of the file to recover.  It will reappear, in unmodified
+	form.</para>
 
-<sect2>
-<title>The results of copying during a merge</title>
+      &interaction.daily.files.recover-missing;
+    </sect2>
 
-<para>What happens during a merge is that changes <quote>follow</quote> a copy.  To
-best illustrate what this means, let's create an example.  We'll start
-with the usual tiny repository that contains a single file.
-<!-- &interaction.daily.copy.init; -->
-We need to do some work in parallel, so that we'll have something to
-merge.  So let's clone our repository.
-<!-- &interaction.daily.copy.clone; -->
-Back in our initial repository, let's use the <command role="hg-cmd">hg copy</command> command to
-make a copy of the first file we created.
-<!-- &interaction.daily.copy.copy; -->
-</para>
+    <sect2>
+      <title>Aside: why tell Mercurial explicitly to remove a
+	file?</title>
 
-<para>If we look at the output of the <command role="hg-cmd">hg status</command> command afterwards, the
-copied file looks just like a normal added file.
-<!-- &interaction.daily.copy.status; -->
-But if we pass the <option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command>, it
-prints another line of output: this is the file that our newly-added
-file was copied <emphasis>from</emphasis>.
-<!-- &interaction.daily.copy.status-copy; -->
-</para>
+      <para id="x_1b9">You might wonder why Mercurial requires you to explicitly
+	tell it that you are deleting a file.  Early during the
+	development of Mercurial, it let you delete a file however you
+	pleased; Mercurial would notice the absence of the file
+	automatically when you next ran a <command role="hg-cmd">hg
+	  commit</command>, and stop tracking the file.  In practice,
+	this made it too easy to accidentally remove a file without
+	noticing.</para>
+    </sect2>
 
-<para>Now, back in the repository we cloned, let's make a change in
-parallel.  We'll add a line of content to the original file that we
-created.
-<!-- &interaction.daily.copy.other; -->
-Now we have a modified <filename>file</filename> in this repository.  When we
-pull the changes from the first repository, and merge the two heads,
-Mercurial will propagate the changes that we made locally to
-<filename>file</filename> into its copy, <filename>new-file</filename>.
-<!-- &interaction.daily.copy.merge; -->
-</para>
+    <sect2>
+      <title>Useful shorthand&emdash;adding and removing files in one
+	step</title>
 
-</sect2>
-<sect2>
-<title>Why should changes follow copies?</title>
-<para>\label{sec:daily:why-copy}
-</para>
+      <para id="x_1ba">Mercurial offers a combination command, <command
+	  role="hg-cmd">hg addremove</command>, that adds untracked
+	files and marks missing files as removed.</para>
 
-<para>This behaviour, of changes to a file propagating out to copies of the
-file, might seem esoteric, but in most cases it's highly desirable.
-</para>
+      &interaction.daily.files.addremove;
 
-<para>First of all, remember that this propagation <emphasis>only</emphasis> happens when
-you merge.  So if you <command role="hg-cmd">hg copy</command> a file, and subsequently modify the
-original file during the normal course of your work, nothing will
-happen.
-</para>
+      <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command
+	also provides a <option role="hg-opt-commit">-A</option>
+	option that performs this same add-and-remove, immediately
+	followed by a commit.</para>
 
-<para>The second thing to know is that modifications will only propagate
-across a copy as long as the repository that you're pulling changes
-from <emphasis>doesn't know</emphasis> about the copy.
-</para>
+      &interaction.daily.files.commit-addremove;
+    </sect2>
+  </sect1>
 
-<para>The reason that Mercurial does this is as follows.  Let's say I make
-an important bug fix in a source file, and commit my changes.
-Meanwhile, you've decided to <command role="hg-cmd">hg copy</command> the file in your repository,
-without knowing about the bug or having seen the fix, and you have
-started hacking on your copy of the file.
-</para>
+  <sect1 id="chap:daily.copy">
+    <title>Copying files</title>
 
-<para>If you pulled and merged my changes, and Mercurial <emphasis>didn't</emphasis>
-propagate changes across copies, your source file would now contain
-the bug, and unless you remembered to propagate the bug fix by hand,
-the bug would <emphasis>remain</emphasis> in your copy of the file.
-</para>
+    <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg
+	copy</command> command that lets you make a new copy of a
+      file.  When you copy a file using this command, Mercurial makes
+      a record of the fact that the new file is a copy of the original
+      file.  It treats these copied files specially when you merge
+      your work with someone else's.</para>
 
-<para>By automatically propagating the change that fixed the bug from the
-original file to the copy, Mercurial prevents this class of problem.
-To my knowledge, Mercurial is the <emphasis>only</emphasis> revision control system
-that propagates changes across copies like this.
-</para>
+    <sect2>
+      <title>The results of copying during a merge</title>
 
-<para>Once your change history has a record that the copy and subsequent
-merge occurred, there's usually no further need to propagate changes
-from the original file to the copied file, and that's why Mercurial
-only propagates changes across copies until this point, and no
-further.
-</para>
+      <para id="x_1bd">What happens during a merge is that changes
+	<quote>follow</quote> a copy.  To best illustrate what this
+	means, let's create an example.  We'll start with the usual
+	tiny repository that contains a single file.</para>
 
-</sect2>
-<sect2>
-<title>How to make changes <emphasis>not</emphasis> follow a copy</title>
+      &interaction.daily.copy.init;
 
-<para>If, for some reason, you decide that this business of automatically
-propagating changes across copies is not for you, simply use your
-system's normal file copy command (on Unix-like systems, that's
-<command>cp</command>) to make a copy of a file, then <command role="hg-cmd">hg add</command> the new copy
-by hand.  Before you do so, though, please do reread
-section <xref linkend="sec:daily:why-copy"/>, and make an informed decision that
-this behaviour is not appropriate to your specific case.
-</para>
+      <para id="x_1be">We need to do some work in
+	parallel, so that we'll have something to merge.  So let's
+	clone our repository.</para>
 
-</sect2>
-<sect2>
-<title>Behaviour of the <command role="hg-cmd">hg copy</command> command</title>
+      &interaction.daily.copy.clone;
 
-<para>When you use the <command role="hg-cmd">hg copy</command> command, Mercurial makes a copy of each
-source file as it currently stands in the working directory.  This
-means that if you make some modifications to a file, then <command role="hg-cmd">hg copy</command>
-it without first having committed those changes, the new copy will
-also contain the modifications you have made up until that point.  (I
-find this behaviour a little counterintuitive, which is why I mention
-it here.)
-</para>
+      <para id="x_1bf">Back in our initial repository, let's use the <command
+	  role="hg-cmd">hg copy</command> command to make a copy of
+	the first file we created.</para>
 
-<para>The <command role="hg-cmd">hg copy</command> command acts similarly to the Unix <command>cp</command>
-command (you can use the <command role="hg-cmd">hg cp</command> alias if you prefer).  The last
-argument is the <emphasis>destination</emphasis>, and all prior arguments are
-<emphasis>sources</emphasis>.  If you pass it a single file as the source, and the
-destination does not exist, it creates a new file with that name.
-<!-- &interaction.daily.copy.simple; -->
-If the destination is a directory, Mercurial copies its sources into
-that directory.
-<!-- &interaction.daily.copy.dir-dest; -->
-Copying a directory is recursive, and preserves the directory
-structure of the source.
-<!-- &interaction.daily.copy.dir-src; -->
-If the source and destination are both directories, the source tree is
-recreated in the destination directory.
-<!-- &interaction.daily.copy.dir-src-dest; -->
-</para>
+      &interaction.daily.copy.copy;
 
-<para>As with the <command role="hg-cmd">hg rename</command> command, if you copy a file manually and
-then want Mercurial to know that you've copied the file, simply use
-the <option role="hg-opt-copy">--after</option> option to <command role="hg-cmd">hg copy</command>.
-<!-- &interaction.daily.copy.after; -->
-</para>
+      <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg
+	  status</command> command afterwards, the copied file looks
+	just like a normal added file.</para>
 
-</sect2>
-</sect1>
-<sect1>
-<title>Renaming files</title>
+      &interaction.daily.copy.status;
 
-<para>It's rather more common to need to rename a file than to make a copy
-of it.  The reason I discussed the <command role="hg-cmd">hg copy</command> command before talking
-about renaming files is that Mercurial treats a rename in essentially
-the same way as a copy.  Therefore, knowing what Mercurial does when
-you copy a file tells you what to expect when you rename a file.
-</para>
+      <para id="x_1c1">But if we pass the <option
+	  role="hg-opt-status">-C</option> option to <command
+	  role="hg-cmd">hg status</command>, it prints another line of
+	output: this is the file that our newly-added file was copied
+	<emphasis>from</emphasis>.</para>
 
-<para>When you use the <command role="hg-cmd">hg rename</command> command, Mercurial makes a copy of
-each source file, then deletes it and marks the file as removed.
-<!-- &interaction.daily.rename.rename; -->
-The <command role="hg-cmd">hg status</command> command shows the newly copied file as added, and
-the copied-from file as removed.
-<!-- &interaction.daily.rename.status; -->
-As with the results of a <command role="hg-cmd">hg copy</command>, we must use the
-<option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command> to see that the added file
-is really being tracked by Mercurial as a copy of the original, now
-removed, file.
-<!-- &interaction.daily.rename.status-copy; -->
-</para>
+      &interaction.daily.copy.status-copy;
 
-<para>As with <command role="hg-cmd">hg remove</command> and <command role="hg-cmd">hg copy</command>, you can tell Mercurial about
-a rename after the fact using the <option role="hg-opt-rename">--after</option> option.  In
-most other respects, the behaviour of the <command role="hg-cmd">hg rename</command> command, and
-the options it accepts, are similar to the <command role="hg-cmd">hg copy</command> command.
-</para>
+      <para id="x_1c2">Now, back in the repository we cloned, let's make a change
+	in parallel.  We'll add a line of content to the original file
+	that we created.</para>
 
-<sect2>
-<title>Renaming files and merging changes</title>
+      &interaction.daily.copy.other;
 
-<para>Since Mercurial's rename is implemented as copy-and-remove, the same
-propagation of changes happens when you merge after a rename as after
-a copy.
-</para>
+      <para id="x_1c3">Now we have a modified <filename>file</filename> in this
+	repository.  When we pull the changes from the first
+	repository, and merge the two heads, Mercurial will propagate
+	the changes that we made locally to <filename>file</filename>
+	into its copy, <filename>new-file</filename>.</para>
 
-<para>If I modify a file, and you rename it to a new name, and then we merge
-our respective changes, my modifications to the file under its
-original name will be propagated into the file under its new name.
-(This is something you might expect to <quote>simply work,</quote> but not all
-revision control systems actually do this.)
-</para>
+      &interaction.daily.copy.merge;
+    </sect2>
 
-<para>Whereas having changes follow a copy is a feature where you can
-perhaps nod and say <quote>yes, that might be useful,</quote> it should be clear
-that having them follow a rename is definitely important.  Without
-this facility, it would simply be too easy for changes to become
-orphaned when files are renamed.
-</para>
+    <sect2 id="sec:daily:why-copy">
+      <title>Why should changes follow copies?</title>
 
-</sect2>
-<sect2>
-<title>Divergent renames and merging</title>
+      <para id="x_1c4">This behavior&emdash;of changes to a file
+	propagating out to copies of the file&emdash;might seem
+	esoteric, but in most cases it's highly desirable.</para>
 
-<para>The case of diverging names occurs when two developers start with a
-file&emdash;let's call it <filename>foo</filename>&emdash;in their respective
-repositories.
-</para>
+      <para id="x_1c5">First of all, remember that this propagation
+	<emphasis>only</emphasis> happens when you merge.  So if you
+	<command role="hg-cmd">hg copy</command> a file, and
+	subsequently modify the original file during the normal course
+	of your work, nothing will happen.</para>
 
-<para><!-- &interaction.rename.divergent.clone; -->
-Anne renames the file to <filename>bar</filename>.
-<!-- &interaction.rename.divergent.rename.anne; -->
-Meanwhile, Bob renames it to <filename>quux</filename>.
-<!-- &interaction.rename.divergent.rename.bob; -->
-</para>
+      <para id="x_1c6">The second thing to know is that modifications will only
+	propagate across a copy as long as the changeset that you're
+	merging changes from <emphasis>hasn't yet seen</emphasis> 
+	the copy.</para>
 
-<para>I like to think of this as a conflict because each developer has
-expressed different intentions about what the file ought to be named.
-</para>
+      <para id="x_1c7">The reason that Mercurial does this is as follows.  Let's
+	say I make an important bug fix in a source file, and commit
+	my changes. Meanwhile, you've decided to <command
+	  role="hg-cmd">hg copy</command> the file in your repository,
+	without knowing about the bug or having seen the fix, and you
+	have started hacking on your copy of the file.</para>
 
-<para>What do you think should happen when they merge their work?
-Mercurial's actual behaviour is that it always preserves <emphasis>both</emphasis>
-names when it merges changesets that contain divergent renames.
-<!-- &interaction.rename.divergent.merge; -->
-</para>
+      <para id="x_1c8">If you pulled and merged my changes, and Mercurial
+	<emphasis>didn't</emphasis> propagate changes across copies,
+	your new source file would now contain the bug, and unless you
+	knew to propagate the bug fix by hand, the bug would
+	<emphasis>remain</emphasis> in your copy of the file.</para>
 
-<para>Notice that Mercurial does warn about the divergent renames, but it
-leaves it up to you to do something about the divergence after the merge.
-</para>
+      <para id="x_1c9">By automatically propagating the change that fixed the bug
+	from the original file to the copy, Mercurial prevents this
+	class of problem. To my knowledge, Mercurial is the
+	<emphasis>only</emphasis> revision control system that
+	propagates changes across copies like this.</para>
 
-</sect2>
-<sect2>
-<title>Convergent renames and merging</title>
+      <para id="x_1ca">Once your change history has a record that the copy and
+	subsequent merge occurred, there's usually no further need to
+	propagate changes from the original file to the copied file,
+	and that's why Mercurial only propagates changes across copies
+	at the first merge, and not afterwards.</para>
+    </sect2>
 
-<para>Another kind of rename conflict occurs when two people choose to
-rename different <emphasis>source</emphasis> files to the same <emphasis>destination</emphasis>.
-In this case, Mercurial runs its normal merge machinery, and lets you
-guide it to a suitable resolution.
-</para>
+    <sect2>
+      <title>How to make changes <emphasis>not</emphasis> follow a
+	copy</title>
 
-</sect2>
-<sect2>
-<title>Other name-related corner cases</title>
+      <para id="x_1cb">If, for some reason, you decide that this business of
+	automatically propagating changes across copies is not for
+	you, simply use your system's normal file copy command (on
+	Unix-like systems, that's <command>cp</command>) to make a
+	copy of a file, then <command role="hg-cmd">hg add</command>
+	the new copy by hand.  Before you do so, though, please do
+	reread <xref linkend="sec:daily:why-copy"/>, and make
+	an informed
+	decision that this behavior is not appropriate to your
+	specific case.</para>
 
-<para>Mercurial has a longstanding bug in which it fails to handle a merge
-where one side has a file with a given name, while another has a
-directory with the same name.  This is documented as <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue29">issue 29</ulink>.
-<!-- &interaction.issue29.go; -->
-</para>
+    </sect2>
+    <sect2>
+      <title>Behavior of the <command role="hg-cmd">hg copy</command>
+	command</title>
 
-</sect2>
-</sect1>
-<sect1>
-<title>Recovering from mistakes</title>
+      <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command>
+	command, Mercurial makes a copy of each source file as it
+	currently stands in the working directory.  This means that if
+	you make some modifications to a file, then <command
+	  role="hg-cmd">hg copy</command> it without first having
+	committed those changes, the new copy will also contain the
+	modifications you have made up until that point.  (I find this
+	behavior a little counterintuitive, which is why I mention it
+	here.)</para>
 
-<para>Mercurial has some useful commands that will help you to recover from
-some common mistakes.
-</para>
+      <para id="x_1cd">The <command role="hg-cmd">hg copy</command>
+	command acts similarly to the Unix <command>cp</command>
+	command (you can use the <command role="hg-cmd">hg
+	  cp</command> alias if you prefer).  We must supply two or
+	more arguments, of which the last is treated as the
+	<emphasis>destination</emphasis>, and all others are
+	<emphasis>sources</emphasis>.</para>
 
-<para>The <command role="hg-cmd">hg revert</command> command lets you undo changes that you have made to
-your working directory.  For example, if you <command role="hg-cmd">hg add</command> a file by
-accident, just run <command role="hg-cmd">hg revert</command> with the name of the file you added,
-and while the file won't be touched in any way, it won't be tracked
-for adding by Mercurial any longer, either.  You can also use
-<command role="hg-cmd">hg revert</command> to get rid of erroneous changes to a file.
-</para>
+      <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a
+	single file as the source, and the destination does not exist,
+	it creates a new file with that name.</para>
 
-<para>It's useful 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>
+      &interaction.daily.copy.simple;
+      
+      <para id="x_1ce">If the destination is a directory, Mercurial copies its
+	sources into that directory.</para>
 
-<para>For more information about the <command role="hg-cmd">hg revert</command> command, and details
-about how to deal with changes you have already committed, see
-chapter <xref linkend="chap:undo"/>.
-</para>
+      &interaction.daily.copy.dir-dest;
 
-</sect1>
+      <para id="x_1cf">Copying a directory is
+	recursive, and preserves the directory structure of the
+	source.</para>
+
+      &interaction.daily.copy.dir-src;
+
+      <para id="x_1d0">If the source and destination are both directories, the
+	source tree is recreated in the destination directory.</para>
+
+	&interaction.daily.copy.dir-src-dest;
+
+      <para id="x_1d1">As with the <command role="hg-cmd">hg remove</command>
+	command, if you copy a file manually and then want Mercurial
+	to know that you've copied the file, simply use the <option
+	  role="hg-opt-copy">--after</option> option to <command
+	  role="hg-cmd">hg copy</command>.</para>
+
+      &interaction.daily.copy.after;
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Renaming files</title>
+
+    <para id="x_1d2">It's rather more common to need to rename a file than to
+      make a copy of it.  The reason I discussed the <command
+	role="hg-cmd">hg copy</command> command before talking about
+      renaming files is that Mercurial treats a rename in essentially
+      the same way as a copy.  Therefore, knowing what Mercurial does
+      when you copy a file tells you what to expect when you rename a
+      file.</para>
+
+    <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command>
+      command, Mercurial makes a copy of each source file, then
+      deletes it and marks the file as removed.</para>
+
+      &interaction.daily.rename.rename;
+
+    <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows
+      the newly copied file as added, and the copied-from file as
+      removed.</para>
+
+    &interaction.daily.rename.status;
+
+    <para id="x_1d5">As with the results of a <command role="hg-cmd">hg
+	copy</command>, we must use the <option
+	role="hg-opt-status">-C</option> option to <command
+	role="hg-cmd">hg status</command> to see that the added file
+      is really being tracked by Mercurial as a copy of the original,
+      now removed, file.</para>
+
+    &interaction.daily.rename.status-copy;
+
+    <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and
+      <command role="hg-cmd">hg copy</command>, you can tell Mercurial
+      about a rename after the fact using the <option
+	role="hg-opt-rename">--after</option> option.  In most other
+      respects, the behavior of the <command role="hg-cmd">hg
+	rename</command> command, and the options it accepts, are
+      similar to the <command role="hg-cmd">hg copy</command>
+      command.</para>
+
+    <para id="x_686">If you're familiar with the Unix command line, you'll be
+      glad to know that <command role="hg-cmd">hg rename</command>
+      command can be invoked as <command role="hg-cmd">hg
+	mv</command>.</para>
+
+    <sect2>
+      <title>Renaming files and merging changes</title>
+
+      <para id="x_1d7">Since Mercurial's rename is implemented as
+	copy-and-remove, the same propagation of changes happens when
+	you merge after a rename as after a copy.</para>
+
+      <para id="x_1d8">If I modify a file, and you rename it to a new name, and
+	then we merge our respective changes, my modifications to the
+	file under its original name will be propagated into the file
+	under its new name. (This is something you might expect to
+	<quote>simply work,</quote> but not all revision control
+	systems actually do this.)</para>
+
+      <para id="x_1d9">Whereas having changes follow a copy is a feature where
+	you can perhaps nod and say <quote>yes, that might be
+	  useful,</quote> it should be clear that having them follow a
+	rename is definitely important.  Without this facility, it
+	would simply be too easy for changes to become orphaned when
+	files are renamed.</para>
+    </sect2>
+
+    <sect2>
+      <title>Divergent renames and merging</title>
+
+      <para id="x_1da">The case of diverging names occurs when two developers
+	start with a file&emdash;let's call it
+	<filename>foo</filename>&emdash;in their respective
+	repositories.</para>
+
+      &interaction.rename.divergent.clone;
+
+      <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para>
+
+      &interaction.rename.divergent.rename.anne;
+
+      <para id="x_1dc">Meanwhile, Bob renames it to
+	<filename>quux</filename>. (Remember that <command
+	  role="hg-cmd">hg mv</command> is an alias for <command
+	  role="hg-cmd">hg rename</command>.)</para>
+
+	&interaction.rename.divergent.rename.bob;
+
+      <para id="x_1dd">I like to think of this as a conflict because each
+	developer has expressed different intentions about what the
+	file ought to be named.</para>
+
+      <para id="x_1de">What do you think should happen when they merge their
+	work? Mercurial's actual behavior is that it always preserves
+	<emphasis>both</emphasis> names when it merges changesets that
+	contain divergent renames.</para>
+
+      &interaction.rename.divergent.merge;
+
+      <para id="x_1df">Notice that while Mercurial warns about the divergent
+	renames, it leaves it up to you to do something about the
+	divergence after the merge.</para>
+    </sect2>
+
+    <sect2>
+      <title>Convergent renames and merging</title>
+
+      <para id="x_1e0">Another kind of rename conflict occurs when two people
+	choose to rename different <emphasis>source</emphasis> files
+	to the same <emphasis>destination</emphasis>. In this case,
+	Mercurial runs its normal merge machinery, and lets you guide
+	it to a suitable resolution.</para>
+    </sect2>
+
+    <sect2>
+      <title>Other name-related corner cases</title>
+
+      <para id="x_1e1">Mercurial has a longstanding bug in which it fails to
+	handle a merge where one side has a file with a given name,
+	while another has a directory with the same name.  This is
+	documented as <ulink role="hg-bug"
+	  url="http://www.selenic.com/mercurial/bts/issue29">issue
+	  29</ulink>.</para>
+
+      &interaction.issue29.go;
+
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Recovering from mistakes</title>
+
+    <para id="x_1e2">Mercurial has some useful commands that will help you to
+      recover from some common mistakes.</para>
+
+    <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets
+      you undo changes that you have made to your working directory.
+      For example, if you <command role="hg-cmd">hg add</command> a
+      file by accident, just run <command role="hg-cmd">hg
+	revert</command> with the name of the file you added, and
+      while the file won't be touched in any way, it won't be tracked
+      for adding by Mercurial any longer, either.  You can also use
+      <command role="hg-cmd">hg revert</command> to get rid of
+      erroneous changes to a file.</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
+      how to deal with changes you have already committed, see <xref
+	linkend="chap:undo"/>.</para>
+  </sect1>
+
+  <sect1>
+    <title>Dealing with tricky merges</title>
+
+    <para id="x_687">In a complicated or large project, it's not unusual for a
+      merge of two changesets to result in some headaches.  Suppose
+      there's a big source file that's been extensively edited by each
+      side of a merge: this is almost inevitably going to result in
+      conflicts, some of which can take a few tries to sort
+      out.</para>
+
+    <para id="x_688">Let's develop a simple case of this and see how to deal with
+      it.  We'll start off with a repository containing one file, and
+      clone it twice.</para>
+
+    &interaction.ch04-resolve.init;
+
+    <para id="x_689">In one clone, we'll modify the file in one way.</para>
+
+    &interaction.ch04-resolve.left;
+
+    <para id="x_68a">In another, we'll modify the file differently.</para>
+
+    &interaction.ch04-resolve.right;
+
+    <para id="x_68b">Next, we'll pull each set of changes into our original
+      repo.</para>
+
+    &interaction.ch04-resolve.pull;
+
+    <para id="x_68c">We expect our repository to now contain two heads.</para>
+
+    &interaction.ch04-resolve.heads;
+
+    <para id="x_68d">Normally, if we run <command role="hg-cmd">hg
+	merge</command> at this point, it will drop us into a GUI that
+      will let us manually resolve the conflicting edits to
+      <filename>myfile.txt</filename>.  However, to simplify things
+      for presentation here, we'd like the merge to fail immediately
+      instead.  Here's one way we can do so.</para>
+
+    &interaction.ch04-resolve.export;
+
+    <para id="x_68e">We've told Mercurial's merge machinery to run the command
+      <command>false</command> (which, as we desire, fails
+      immediately) if it detects a merge that it can't sort out
+      automatically.</para>
+
+    <para id="x_68f">If we now fire up <command role="hg-cmd">hg
+	merge</command>, it should grind to a halt and report a
+	failure.</para>
+
+    &interaction.ch04-resolve.merge;
+
+    <para id="x_690">Even if we don't notice that the merge failed, Mercurial
+      will prevent us from accidentally committing the result of a
+      failed merge.</para>
+
+    &interaction.ch04-resolve.cifail;
+
+    <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in
+      this case, it suggests that we use the unfamiliar <command
+	role="hg-cmd">hg resolve</command> command.  As usual,
+	<command role="hg-cmd">hg help resolve</command> will print a
+      helpful synopsis.</para>
+
+    <sect2>
+      <title>File resolution states</title>
+
+      <para id="x_692">When a merge occurs, most files will usually remain
+	unmodified.  For each file where Mercurial has to do
+	something, it tracks the state of the file.</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para id="x_693">A <emphasis>resolved</emphasis> file has been
+	    successfully merged, either automatically by Mercurial or
+	    manually with human intervention.</para>
+	</listitem>
+	<listitem>
+	  <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged
+	    successfully, and needs more attention.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the
+	unresolved state after a merge, it considers the merge to have
+	failed.  Fortunately, we do not need to restart the entire
+	merge from scratch.</para>
+
+      <para id="x_696">The <option role="hg-opt-resolve">--list</option> or
+	<option role="hg-opt-resolve">-l</option> option to <command
+	  role="hg-cmd">hg resolve</command> prints out the state of
+	each merged file.</para>
+
+      &interaction.ch04-resolve.list;
+
+      <para id="x_697">In the output from <command role="hg-cmd">hg
+	  resolve</command>, a resolved file is marked with
+	<literal>R</literal>, while an unresolved file is marked with
+	<literal>U</literal>.  If any files are listed with
+	<literal>U</literal>, we know that an attempt to commit the
+	results of the merge will fail.</para>
+    </sect2>
+
+    <sect2>
+      <title>Resolving a file merge</title>
+
+      <para id="x_698">We have several options to move a file from the unresolved
+	into the resolved state.  By far the most common is to rerun
+	<command role="hg-cmd">hg resolve</command>.  If we pass the
+	names of individual files or directories, it will retry the
+	merges of any unresolved files present in those locations. We
+	can also pass the <option role="hg-opt-resolve">--all</option>
+	or <option role="hg-opt-resolve">-a</option> option, which
+	will retry the merges of <emphasis>all</emphasis> unresolved
+	files.</para>
+
+      <para id="x_699">Mercurial also lets us modify the resolution state of a
+	file directly.  We can manually mark a file as resolved using
+	the <option role="hg-opt-resolve">--mark</option> option, or
+	as unresolved using the <option
+	  role="hg-opt-resolve">--unmark</option> option.  This allows
+	us to clean up a particularly messy merge by hand, and to keep
+	track of our progress with each file as we go.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>More useful diffs</title>
+
+    <para id="x_6c7">The default output of the <command role="hg-cmd">hg
+	diff</command> command is backwards compatible with the
+      regular <command>diff</command> command, but this has some
+      drawbacks.</para>
+
+    <para id="x_6c8">Consider the case where we use <command role="hg-cmd">hg
+	rename</command> to rename a file.</para>
+
+    &interaction.ch04-diff.rename.basic;
+
+    <para id="x_6c9">The output of <command role="hg-cmd">hg diff</command> above
+      obscures the fact that we simply renamed a file.  The <command
+	role="hg-cmd">hg diff</command> command accepts an option,
+      <option>--git</option> or <option>-g</option>, to use a newer
+      diff format that displays such information in a more readable
+      form.</para>
+
+    &interaction.ch04-diff.rename.git;
+
+    <para id="x_6ca">This option also helps with a case that can otherwise be
+      confusing: a file that appears to be modified according to
+      <command role="hg-cmd">hg status</command>, but for which
+      <command role="hg-cmd">hg diff</command> prints nothing. This
+      situation can arise if we change the file's execute
+      permissions.</para>
+
+    &interaction.ch04-diff.chmod;
+
+    <para id="x_6cb">The normal <command>diff</command> command pays no attention
+      to file permissions, which is why <command role="hg-cmd">hg
+	diff</command> prints nothing by default.  If we supply it
+      with the <option>-g</option> option, it tells us what really
+      happened.</para>
+
+    &interaction.ch04-diff.chmod.git;
+  </sect1>
+
+  <sect1>
+    <title>Which files to manage, and which to avoid</title>
+
+    <para id="x_6cc">Revision control systems are generally best at managing text
+      files that are written by humans, such as source code, where the
+      files do not change much from one revision to the next.  Some
+      centralized revision control systems can also deal tolerably
+      well with binary files, such as bitmap images.</para>
+
+    <para id="x_6cd">For instance, a game development team will typically manage
+      both its source code and all of its binary assets (e.g. geometry
+      data, textures, map layouts) in a revision control
+      system.</para>
+
+    <para id="x_6ce">Because it is usually impossible to merge two conflicting
+      modifications to a binary file, centralized systems often
+      provide a file locking mechanism that allow a user to say
+      <quote>I am the only person who can edit this
+	file</quote>.</para>
+
+    <para id="x_6cf">Compared to a centralized system, a distributed revision
+      control system changes some of the factors that guide decisions
+      over which files to manage and how.</para>
+
+    <para id="x_6d0">For instance, a distributed revision control system cannot,
+      by its nature, offer a file locking facility.  There is thus no
+      built-in mechanism to prevent two people from making conflicting
+      changes to a binary file.  If you have a team where several
+      people may be editing binary files frequently, it may not be a
+      good idea to use Mercurial&emdash;or any other distributed
+      revision control system&emdash;to manage those files.</para>
+
+    <para id="x_6d1">When storing modifications to a file, Mercurial usually
+      saves only the differences between the previous and current
+      versions of the file.  For most text files, this is extremely
+      efficient. However, some files (particularly binary files) are
+      laid out in such a way that even a small change to a file's
+      logical content results in many or most of the bytes inside the
+      file changing.  For instance, compressed files are particularly
+      susceptible to this. If the differences between each successive
+      version of a file are always large, Mercurial will not be able
+      to store the file's revision history very efficiently.  This can
+      affect both local storage needs and the amount of time it takes
+      to clone a repository.</para>
+
+    <para id="x_6d2">To get an idea of how this could affect you in practice,
+      suppose you want to use Mercurial to manage an OpenOffice
+      document.  OpenOffice stores documents on disk as compressed zip
+      files. Edit even a single letter of your document in OpenOffice,
+      and almost every byte in the entire file will change when you
+      save it. Now suppose that file is 2MB in size.  Because most of
+      the file changes every time you save, Mercurial will have to
+      store all 2MB of the file every time you commit, even though
+      from your perspective, perhaps only a few words are changing
+      each time.  A single frequently-edited file that is not friendly
+      to Mercurial's storage assumptions can easily have an outsized
+      effect on the size of the repository.</para>
+
+    <para id="x_6d3">Even worse, if both you and someone else edit the OpenOffice
+      document you're working on, there is no useful way to merge your
+      work. In fact, there isn't even a good way to tell what the
+      differences are between your respective changes.</para>
+
+    <para id="x_6d4">There are thus a few clear recommendations about specific
+      kinds of files to be very careful with.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para id="x_6d5">Files that are very large and incompressible, e.g. ISO
+	  CD-ROM images, will by virtue of sheer size make clones over
+	  a network very slow.</para>
+      </listitem>
+      <listitem>
+	<para id="x_6d6">Files that change a lot from one revision to the next
+	  may be expensive to store if you edit them frequently, and
+	  conflicts due to concurrent edits may be difficult to
+	  resolve.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Backups and mirroring</title>
+
+    <para id="x_6d7">Since Mercurial maintains a complete copy of history in each
+      clone, everyone who uses Mercurial to collaborate on a project
+      can potentially act as a source of backups in the event of a
+      catastrophe.  If a central repository becomes unavailable, you
+      can construct a replacement simply by cloning a copy of the
+      repository from one contributor, and pulling any changes they
+      may not have seen from others.</para>
+
+    <para id="x_6d8">It is simple to use Mercurial to perform off-site backups
+      and remote mirrors.  Set up a periodic job (e.g. via the
+      <command>cron</command> command) on a remote server to pull
+      changes from your master repositories every hour.  This will
+      only be tricky in the unlikely case that the number of master
+      repositories you maintain changes frequently, in which case
+      you'll need to do a little scripting to refresh the list of
+      repositories to back up.</para>
+
+    <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
+	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
+      working directory after the clone completes, since that would be
+      superfluous and make the backup take longer.</para>
+
+    <para id="x_6da">If you then back up <filename>myrepo.bak</filename> instead
+      of <filename>myrepo</filename>, you will be guaranteed to have a
+      consistent snapshot of your repository that won't be pushed to
+      by an insomniac developer in mid-backup.</para>
+  </sect1>
 </chapter>
 
 <!--
 local variables: 
 sgml-parent-document: ("00book.xml" "book" "chapter")
 end:
--->
+-->

fr/ch06-collab.xml

 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<chapter>
-<title>Collaborating with other people</title>
-<para>\label{cha:collab}</para>
+<chapter id="cha:collab">
+  <?dbhtml filename="collaborating-with-other-people.html"?>
+  <title>Collaborating with other people</title>
 
-<para>As a completely decentralised tool, Mercurial doesn't impose any
-policy on how people ought to work with each other.  However, if
-you're new to distributed revision control, it helps to have some
-tools and examples in mind when you're thinking about possible
-workflow models.</para>
+  <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
+    any policy on how people ought to work with each other.  However,
+    if you're new to distributed revision control, it helps to have
+    some tools and examples in mind when you're thinking about
+    possible workflow models.</para>
 
-<sect1>
-<title>Mercurial's web interface</title>
+  <sect1>
+    <title>Mercurial's web interface</title>
 
-<para>Mercurial has a powerful web interface that provides several
-useful capabilities.</para>
+    <para id="x_44b">Mercurial has a powerful web interface that provides several
+      useful capabilities.</para>
 
-<para>For interactive use, the web interface lets you browse a single
-repository or a collection of repositories.  You can view the history
-of a repository, examine each change (comments and diffs), and view
-the contents of each directory and file.</para>
+    <para id="x_44c">For interactive use, the web interface lets you browse a
+      single repository or a collection of repositories.  You can view
+      the history of a repository, examine each change (comments and
+      diffs), and view the contents of each directory and file.  You
+      can even get a view of history that gives a graphical view of
+      the relationships between individual changes and merges.</para>
 
-<para>Also for human consumption, the web interface provides an RSS feed of
-the changes in a repository.  This lets you <quote>subscribe</quote> to a
-repository using your favourite feed reader, and be automatically
-notified of activity in that repository as soon as it happens.  I find
-this capability much more convenient than the model of subscribing to
-a mailing list to which notifications are sent, as it requires no
-additional configuration on the part of whoever is serving the
-repository.</para>
+    <para id="x_44d">Also for human consumption, the web interface provides
+      Atom and RSS feeds of the changes in a repository.  This lets you
+      <quote>subscribe</quote> to a repository using your favorite
+      feed reader, and be automatically notified of activity in that
+      repository as soon as it happens.  I find this capability much
+      more convenient than the model of subscribing to a mailing list
+      to which notifications are sent, as it requires no additional
+      configuration on the part of whoever is serving the
+      repository.</para>
 
-<para>The web interface also lets remote users clone a repository, pull
-changes from it, and (when the server is configured to permit it) push
-changes back to it.  Mercurial's HTTP tunneling protocol aggressively
-compresses data, so that it works efficiently even over low-bandwidth
-network connections.</para>
+    <para id="x_44e">The web interface also lets remote users clone a repository,
+      pull changes from it, and (when the server is configured to
+      permit it) push changes back to it.  Mercurial's HTTP tunneling
+      protocol aggressively compresses data, so that it works
+      efficiently even over low-bandwidth network connections.</para>
 
-<para>The easiest way to get started with the web interface is to use your
-web browser to visit an existing repository, such as the master
-Mercurial repository at
-<ulink url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
+    <para id="x_44f">The easiest way to get started with the web interface is to
+      use your web browser to visit an existing repository, such as
+      the master Mercurial repository at <ulink
+	url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
 
-<para>If you're interested in providing a web interface to your own
-repositories, Mercurial provides two ways to do this.  The first is
-using the <command role="hg-cmd">hg serve</command> command, which is best suited to short-term
-<quote>lightweight</quote> serving.  See section <xref linkend="sec:collab:serve"/> below for
-details of how to use this command.  If you have a long-lived
-repository that you'd like to make permanently available, Mercurial
-has built-in support for the CGI (Common Gateway Interface) standard,
-which all common web servers support.  See
-section <xref linkend="sec:collab:cgi"/> for details of CGI configuration.</para>
+    <para id="x_450">If you're interested in providing a web interface
+      to your own repositories, there are several good ways to do
+      this.</para>
 
-</sect1>
-<sect1>
-<title>Collaboration models</title>
+    <para id="x_69d">The easiest and fastest way to get started in an informal
+      environment is to use the <command role="hg-cmd">hg
+	serve</command> command, which is best suited to short-term
+      <quote>lightweight</quote> serving.  See <xref
+	linkend="sec:collab:serve"/> below for details of how to use
+      this command.</para>
 
-<para>With a suitably flexible tool, making decisions about workflow is much
-more of a social engineering challenge than a technical one.
-Mercurial imposes few limitations on how you can structure the flow of
-work in a project, so it's up to you and your group to set up and live
-with a model that matches your own particular needs.
-</para>
+    <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>
 
-<sect2>
-<title>Factors to keep in mind</title>
+    <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
+      has built-in support for several popular hosting technologies,
+      most notably CGI (Common Gateway Interface), and WSGI (Web
+      Services Gateway Interface).  See <xref
+	linkend="sec:collab:cgi"/> for details of CGI and WSGI
+      configuration.</para>
+  </sect1>
 
-<para>The most important aspect of any model that you must keep in mind is
-how well it matches the needs and capabilities of the people who will
-be using it.  This might seem self-evident; even so, you still can't
-afford to forget it for a moment.
-</para>
+  <sect1>
+    <title>Collaboration models</title>
 
-<para>I once put together a workflow model that seemed to make perfect sense
-to me, but that caused a considerable amount of consternation and
-strife within my development team.  In spite of my attempts to explain
-why we needed a complex set of branches, and how changes ought to flow
-between them, a few team members revolted.  Even though they were
-smart people, they didn't want to pay attention to the constraints we
-were operating under, or face the consequences of those constraints in
-the details of the model that I was advocating.
-</para>
+    <para id="x_451">With a suitably flexible tool, making decisions about
+      workflow is much more of a social engineering challenge than a
+      technical one. Mercurial imposes few limitations on how you can
+      structure the flow of work in a project, so it's up to you and
+      your group to set up and live with a model that matches your own
+      particular needs.</para>
 
-<para>Don't sweep foreseeable social or technical problems under the rug.
-Whatever scheme you put into effect, you should plan for mistakes and
-problem scenarios.  Consider adding automated machinery to prevent, or
-quickly recover from, trouble that you can anticipate.  As an example,
-if you intend to have a branch with not-for-release changes in it,
-you'd do well to think early about the possibility that someone might
-accidentally merge those changes into a release branch.  You could
-avoid this particular problem by writing a hook that prevents changes
-from being merged from an inappropriate branch.
-</para>
+    <sect2>
+      <title>Factors to keep in mind</title>
 
-</sect2>
-<sect2>
-<title>Informal anarchy</title>
+      <para id="x_452">The most important aspect of any model that you must keep
+	in mind is how well it matches the needs and capabilities of
+	the people who will be using it.  This might seem
+	self-evident; even so, you still can't afford to forget it for
+	a moment.</para>
 
-<para>I wouldn't suggest an <quote>anything goes</quote> approach as something
-sustainable, but it's a model that's easy to grasp, and it works
-perfectly well in a few unusual situations.
-</para>
+      <para id="x_453">I once put together a workflow model that seemed to make
+	perfect sense to me, but that caused a considerable amount of
+	consternation and strife within my development team.  In spite
+	of my attempts to explain why we needed a complex set of
+	branches, and how changes ought to flow between them, a few
+	team members revolted.  Even though they were smart people,
+	they didn't want to pay attention to the constraints we were
+	operating under, or face the consequences of those constraints
+	in the details of the model that I was advocating.</para>
 
-<para>As one example, many projects have a loose-knit group of collaborators
-who rarely physically meet each other.  Some groups like to overcome
-the isolation of working at a distance by organising occasional
-<quote>sprints</quote>.  In a sprint, a number of people get together in a single
-location (a company's conference room, a hotel meeting room, that kind
-of place) and spend several days more or less locked in there, hacking
-intensely on a handful of projects.
-</para>
+      <para id="x_454">Don't sweep foreseeable social or technical problems under
+	the rug. Whatever scheme you put into effect, you should plan
+	for mistakes and problem scenarios.  Consider adding automated
+	machinery to prevent, or quickly recover from, trouble that
+	you can anticipate.  As an example, if you intend to have a
+	branch with not-for-release changes in it, you'd do well to
+	think early about the possibility that someone might
+	accidentally merge those changes into a release branch.  You
+	could avoid this particular problem by writing a hook that
+	prevents changes from being merged from an inappropriate
+	branch.</para>
+    </sect2>
 
-<para>A sprint is the perfect place to use the <command role="hg-cmd">hg serve</command> command, since
-<command role="hg-cmd">hg serve</command> does not requires any fancy server infrastructure.  You
-can get started with <command role="hg-cmd">hg serve</command> in moments, by reading
-section <xref linkend="sec:collab:serve"/> below.  Then simply tell the person
-next to you that you're running a server, send the URL to them in an
-instant message, and you immediately have a quick-turnaround way to
-work together.  They can type your URL into their web browser and
-quickly review your changes; or they can pull a bugfix from you and
-verify it; or they can clone a branch containing a new feature and try
-it out.
-</para>
+    <sect2>
+      <title>Informal anarchy</title>
 
-<para>The charm, and the problem, with doing things in an ad hoc fashion
-like this is that only people who know about your changes, and where
-they are, can see them.  Such an informal approach simply doesn't
-scale beyond a handful people, because each individual needs to know
-about $n$ different repositories to pull from.
-</para>
+      <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
+	approach as something sustainable, but it's a model that's
+	easy to grasp, and it works perfectly well in a few unusual
+	situations.</para>
 
-</sect2>
-<sect2>
-<title>A single central repository</title>
+      <para id="x_456">As one example, many projects have a loose-knit group of
+	collaborators who rarely physically meet each other.  Some
+	groups like to overcome the isolation of working at a distance
+	by organizing occasional <quote>sprints</quote>.  In a sprint,
+	a number of people get together in a single location (a
+	company's conference room, a hotel meeting room, that kind of
+	place) and spend several days more or less locked in there,
+	hacking intensely on a handful of projects.</para>
 
-<para>For smaller projects migrating from a centralised revision control
-tool, perhaps the easiest way to get started is to have changes flow
-through a single shared central repository.  This is also the
-most common <quote>building block</quote> for more ambitious workflow schemes.
-</para>
+      <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
+	<command role="hg-cmd">hg serve</command> command, since
+	<command role="hg-cmd">hg serve</command> does not require any
+	fancy server infrastructure.  You can get started with
+	<command role="hg-cmd">hg serve</command> in moments, by
+	reading <xref linkend="sec:collab:serve"/> below.  Then simply
+	tell the person next to you that you're running a server, send
+	the URL to them in an instant message, and you immediately
+	have a quick-turnaround way to work together.  They can type
+	your URL into their web browser and quickly review your
+	changes; or they can pull a bugfix from you and verify it; or
+	they can clone a branch containing a new feature and try it
+	out.</para>
 
-<para>Contributors start by cloning a copy of this repository.  They can
-pull changes from it whenever they need to, and some (perhaps all)
-developers have permission to push a change back when they're ready
-for other people to see it.
-</para>
+      <para id="x_458">The charm, and the problem, with doing things
+	in an ad hoc fashion like this is that only people who know
+	about your changes, and where they are, can see them.  Such an
+	informal approach simply doesn't scale beyond a handful
+	people, because each individual needs to know about
+	<emphasis>n</emphasis> different repositories to pull
+	from.</para>
+    </sect2>
 
-<para>Under this model, it can still often make sense for people to pull
-changes directly from each other, without going through the central
-repository.  Consider a case in which I have a tentative bug fix, but
-I am worried that if I were to publish it to the central repository,
-it might subsequently break everyone else's trees as they pull it.  To
-reduce the potential for damage, I can ask you to clone my repository
-into a temporary repository of your own and test it.  This lets us put
-off publishing the potentially unsafe change until it has had a little
-testing.
-</para>
+    <sect2>
+      <title>A single central repository</title>
 
-<para>In this kind of scenario, people usually use the <command>ssh</command>
-protocol to securely push changes to the central repository, as
-documented in section <xref linkend="sec:collab:ssh"/>.  It's also usual to
-publish a read-only copy of the repository over HTTP using CGI, as in
-section <xref linkend="sec:collab:cgi"/>.  Publishing over HTTP satisfies the
-needs of people who don't have push access, and those who want to use
-web browsers to browse the repository's history.
-</para>
+      <para id="x_459">For smaller projects migrating from a centralised revision
+	control tool, perhaps the easiest way to get started is to
+	have changes flow through a single shared central repository.
+	This is also the most common <quote>building block</quote> for
+	more ambitious workflow schemes.</para>
 
-</sect2>
-<sect2>
-<title>Working with multiple branches</title>
+      <para id="x_45a">Contributors start by cloning a copy of this repository.
+	They can pull changes from it whenever they need to, and some
+	(perhaps all) developers have permission to push a change back
+	when they're ready for other people to see it.</para>
 
-<para>Projects of any significant size naturally tend to make progress on
-several fronts simultaneously.  In the case of software, it's common
-for a project to go through periodic official releases.  A release
-might then go into <quote>maintenance mode</quote> for a while after its first
-publication; maintenance releases tend to contain only bug fixes, not
-new features.  In parallel with these maintenance releases, one or
-more future releases may be under development.  People normally use
-the word <quote>branch</quote> to refer to one of these many slightly different
-directions in which development is proceeding.
-</para>
+      <para id="x_45b">Under this model, it can still often make sense for people
+	to pull changes directly from each other, without going
+	through the central repository.  Consider a case in which I
+	have a tentative bug fix, but I am worried that if I were to
+	publish it to the central repository, it might subsequently
+	break everyone else's trees as they pull it.  To reduce the
+	potential for damage, I can ask you to clone my repository
+	into a temporary repository of your own and test it.  This
+	lets us put off publishing the potentially unsafe change until
+	it has had a little testing.</para>
 
-<para>Mercurial is particularly well suited to managing a number of
-simultaneous, but not identical, branches.  Each <quote>development
-direction</quote> can live in its own central repository, and you can merge
-changes from one to another as the need arises.  Because repositories
-are independent of each other, unstable changes in a development
-branch will never affect a stable branch unless someone explicitly
-merges those changes in.
-</para>
+      <para id="x_45c">If a team is hosting its own repository in this
+	kind of scenario, people will usually use the
+	<command>ssh</command> protocol to securely push changes to
+	the central repository, as documented in <xref
+	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
+	read-only copy of the repository over HTTP, as in
+	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
+	satisfies the needs of people who don't have push access, and
+	those who want to use web browsers to browse the repository's
+	history.</para>
+    </sect2>
 
-<para>Here's an example of how this can work in practice.  Let's say you
-have one <quote>main branch</quote> on a central server.
-<!-- &interaction.branching.init; -->
-People clone it, make changes locally, test them, and push them back.
-</para>
+    <sect2>
+      <title>A hosted central repository</title>
 
-<para>Once the main branch reaches a release milestone, you can use the
-<command role="hg-cmd">hg tag</command> command to give a permanent name to the milestone
-revision.
-<!-- &interaction.branching.tag; -->
-Let's say some ongoing development occurs on the main branch.
-<!-- &interaction.branching.main; -->
-Using the tag that was recorded at the milestone, people who clone
-that repository at any time in the future can use <command role="hg-cmd">hg update</command> to
-get a copy of the working directory exactly as it was when that tagged
-revision was committed.
-<!-- &interaction.branching.update; -->
-</para>
+      <para id="x_6a1">A wonderful thing about public hosting services like
+	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
+	not only do they handle the fiddly server configuration
+	details, such as user accounts, authentication, and secure
+	wire protocols, they provide additional infrastructure to make
+	this model work well.</para>
 
-<para>In addition, immediately after the main branch is tagged, someone can
-then clone the main branch on the server to a new <quote>stable</quote> branch,
-also on the server.
-<!-- &interaction.branching.clone; -->
-</para>
+      <para id="x_6a2">For instance, a well-engineered hosting service will let
+	people clone their own copies of a repository with a single
+	click.  This lets people work in separate spaces and share
+	their changes when they're ready.</para>
 
-<para>Someone who needs to make a change to the stable branch can then clone
-<emphasis>that</emphasis> repository, make their changes, commit, and push their
-changes back there.
-<!-- &interaction.branching.stable; -->
-Because Mercurial repositories are independent, and Mercurial doesn't
-move changes around automatically, the stable and main branches are
-<emphasis>isolated</emphasis> from each other.  The changes that you made on the
-main branch don't <quote>leak</quote> to the stable branch, and vice versa.
-</para>
+      <para id="x_6a3">In addition, a good hosting service will let people
+	communicate with each other, for instance to say <quote>there
+	  are changes ready for you to review in this
+	  tree</quote>.</para>
+    </sect2>
 
-<para>You'll often want all of your bugfixes on the stable branch to show up
-on the main branch, too.  Rather than rewrite a bugfix on the main
-branch, you can simply pull and merge changes from the stable to the
-main branch, and Mercurial will bring those bugfixes in for you.
-<!-- &interaction.branching.merge; -->
-The main branch will still contain changes that are not on the stable
-branch, but it will also contain all of the bugfixes from the stable
-branch.  The stable branch remains unaffected by these changes.
-</para>
+    <sect2>
+      <title>Working with multiple branches</title>
 
-</sect2>
-<sect2>
-<title>Feature branches</title>
+      <para id="x_45d">Projects of any significant size naturally tend to make
+	progress on several fronts simultaneously.  In the case of
+	software, it's common for a project to go through periodic
+	official releases.  A release might then go into
+	<quote>maintenance mode</quote> for a while after its first
+	publication; maintenance releases tend to contain only bug
+	fixes, not new features.  In parallel with these maintenance
+	releases, one or more future releases may be under
+	development.  People normally use the word
+	<quote>branch</quote> to refer to one of these many slightly
+	different directions in which development is
+	proceeding.</para>
 
-<para>For larger projects, an effective way to manage change is to break up
-a team into smaller groups.  Each group has a shared branch of its
-own, cloned from a single <quote>master</quote> branch used by the entire
-project.  People working on an individual branch are typically quite
-isolated from developments on other branches.
-</para>
+      <para id="x_45e">Mercurial is particularly well suited to managing a number
+	of simultaneous, but not identical, branches.  Each
+	<quote>development direction</quote> can live in its own
+	central repository, and you can merge changes from one to
+	another as the need arises.  Because repositories are
+	independent of each other, unstable changes in a development
+	branch will never affect a stable branch unless someone
+	explicitly merges those changes into the stable branch.</para>
 
-<informalfigure>
+      <para id="x_45f">Here's an example of how this can work in practice.  Let's
+	say you have one <quote>main branch</quote> on a central
+	server.</para>
 
-<para>  <mediaobject><imageobject><imagedata fileref="feature-branches"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject>
-  <caption><para>Feature branches</para></caption>
-  \label{fig:collab:feature-branches}
-</para>
-</informalfigure>
+      &interaction.branching.init;
 
-<para>When a particular feature is deemed to be in suitable shape, someone
-on that feature team pulls and merges from the master branch into the
-feature branch, then pushes back up to the master branch.
-</para>
+      <para id="x_460">People clone it, make changes locally, test them, and push
+	them back.</para>
 
-</sect2>
-<sect2>
-<title>The release train</title>
+      <para id="x_461">Once the main branch reaches a release milestone, you can
+	use the <command role="hg-cmd">hg tag</command> command to
+	give a permanent name to the milestone revision.</para>
 
-<para>Some projects are organised on a <quote>train</quote> basis: a release is
-scheduled to happen every few months, and whatever features are ready
-when the <quote>train</quote> is ready to leave are allowed in.
-</para>
+	&interaction.branching.tag;
 
-<para>This model resembles working with feature branches.  The difference is
-that when a feature branch misses a train, someone on the feature team
-pulls and merges the changes that went out on that train release into
-the feature branch, and the team continues its work on top of that
-release so that their feature can make the next release.
-</para>
+      <para id="x_462">Let's say some ongoing
+	development occurs on the main branch.</para>
 
-</sect2>
-<sect2>
-<title>The Linux kernel model</title>
+      &interaction.branching.main;
 
-<para>The development of the Linux kernel has a shallow hierarchical
-structure, surrounded by a cloud of apparent chaos.  Because most
-Linux developers use <command>git</command>, a distributed revision control
-tool with capabilities similar to Mercurial, it's useful to describe
-the way work flows in that environment; if you like the ideas, the
-approach translates well across tools.
-</para>
+      <para id="x_463">Using the tag that was recorded at the milestone, people
+	who clone that repository at any time in the future can use
+	<command role="hg-cmd">hg update</command> to get a copy of
+	the working directory exactly as it was when that tagged
+	revision was committed.</para>
 
-<para>At the center of the community sits Linus Torvalds, the creator of
-Linux.  He publishes a single source repository that is considered the
-<quote>authoritative</quote> current tree by the entire developer community.
-Anyone can clone Linus's tree, but he is very choosy about whose trees
-he pulls from.
-</para>
+      &interaction.branching.update;
 
-<para>Linus has a number of <quote>trusted lieutenants</quote>.  As a general rule, he
-pulls whatever changes they publish, in most cases without even
-reviewing those changes.  Some of those lieutenants are generally
-agreed to be <quote>maintainers</quote>, responsible for specific subsystems
-within the kernel.  If a random kernel hacker wants to make a change
-to a subsystem that they want to end up in Linus's tree, they must
-find out who the subsystem's maintainer is, and ask that maintainer to
-take their change.  If the maintainer reviews their changes and agrees
-to take them, they'll pass them along to Linus in due course.
-</para>
+      <para id="x_464">In addition, immediately after the main branch is tagged,
+	we can then clone the main branch on the server to a new
+	<quote>stable</quote> branch, also on the server.</para>
 
-<para>Individual lieutenants have their own approaches to reviewing,
-accepting, and publishing changes; and for deciding when to feed them
-to Linus.  In addition, there are several well known branches that
-people use for different purposes.  For example, a few people maintain
-<quote>stable</quote> repositories of older versions of the kernel, to which they
-apply critical fixes as needed.  Some maintainers publish multiple
-trees: one for experimental changes; one for changes that they are
-about to feed upstream; and so on.  Others just publish a single
-tree.
-</para>
+      &interaction.branching.clone;
 
-<para>This model has two notable features.  The first is that it's <quote>pull
-only</quote>.  You have to ask, convince, or beg another developer to take a
-change from you, because there are almost no trees to which more than
-one person can push, and there's no way to push changes into a tree
-that someone else controls.
-</para>
+      <para id="x_465">If we need to make a change to the stable
+	branch, we can then clone <emphasis>that</emphasis>
+	repository, make our changes, commit, and push our changes
+	back there.</para>
 
-<para>The second is that it's based on reputation and acclaim.  If you're an
-unknown, Linus will probably ignore changes from you without even
-responding.  But a subsystem maintainer will probably review them, and
-will likely take them if they pass their criteria for suitability.
-The more <quote>good</quote> changes you contribute to a maintainer, the more
-likely they are to trust your judgment and accept your changes.  If
-you're well-known and maintain a long-lived branch for something Linus
-hasn't yet accepted, people with similar interests may pull your
-changes regularly to keep up with your work.
-</para>
+      &interaction.branching.stable;
 
-<para>Reputation and acclaim don't necessarily cross subsystem or <quote>people</quote>
-boundaries.  If you're a respected but specialised storage hacker, and
-you try to fix a networking bug, that change will receive a level of
-scrutiny from a network maintainer comparable to a change from a
-complete stranger.
-</para>
+      <para id="x_466">Because Mercurial repositories are independent, and
+	Mercurial doesn't move changes around automatically, the
+	stable and main branches are <emphasis>isolated</emphasis>
+	from each other.  The changes that we made on the main branch
+	don't <quote>leak</quote> to the stable branch, and vice
+	versa.</para>
 
-<para>To people who come from more orderly project backgrounds, the
-comparatively chaotic Linux kernel development process often seems
-completely insane.  It's subject to the whims of individuals; people
-make sweeping changes whenever they deem it appropriate; and the pace
-of development is astounding.  And yet Linux is a highly successful,
-well-regarded piece of software.
-</para>
+      <para id="x_467">We'll often want all of our bugfixes on the stable
+	branch to show up on the main branch, too.  Rather than
+	rewrite a bugfix on the main branch, we can simply pull and
+	merge changes from the stable to the main branch, and
+	Mercurial will bring those bugfixes in for us.</para>
 
-</sect2>
-<sect2>
-<title>Pull-only versus shared-push collaboration</title>
+      &interaction.branching.merge;
 
-<para>A perpetual source of heat in the open source community is whether a
-development model in which people only ever pull changes from others
-is <quote>better than</quote> one in which multiple people can push changes to a
-shared repository.
-</para>
+      <para id="x_468">The main branch will still contain changes that
+	are not on the stable branch, but it will also contain all of
+	the bugfixes from the stable branch.  The stable branch
+	remains unaffected by these changes, since changes are only
+	flowing from the stable to the main branch, and not the other
+	way.</para>
+    </sect2>
 
-<para>Typically, the backers of the shared-push model use tools that
-actively enforce this approach.  If you're using a centralised
-revision control tool such as Subversion, there's no way to make a
-choice over which model you'll use: the tool gives you shared-push,
-and if you want to do anything else, you'll have to roll your own
-approach on top (such as applying a patch by hand).
-</para>
+    <sect2>
+      <title>Feature branches</title>
 
-<para>A good distributed revision control tool, such as Mercurial, will
-support both models.  You and your collaborators can then structure
-how you work together based on your own needs and preferences, not on
-what contortions your tools force you into.
-</para>
+      <para id="x_469">For larger projects, an effective way to manage change is
+	to break up a team into smaller groups.  Each group has a
+	shared branch of its own, cloned from a single
+	<quote>master</quote> branch used by the entire project.
+	People working on an individual branch are typically quite
+	isolated from developments on other branches.</para>
 
-</sect2>
-<sect2>
-<title>Where collaboration meets branch management</title>
+      <figure id="fig:collab:feature-branches">
+	<title>Feature branches</title>
+	<mediaobject>
+	  <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
 
-<para>Once you and your team set up some shared repositories and start
-propagating changes back and forth between local and shared repos, you
-begin to face a related, but slightly different challenge: that of
-managing the multiple directions in which your team may be moving at
-once.  Even though this subject is intimately related to how your team
-collaborates, it's dense enough to merit treatment of its own, in
-chapter <xref linkend="chap:branch"/>.
-</para>
+      <para id="x_46b">When a particular feature is deemed to be in suitable
+	shape, someone on that feature team pulls and merges from the