comparison en/ch02-tour-merge.xml @ 691:4ce9d0754af3

Remove the words "section", "chapter", etc from in front of xref tags.

690:b788b405e141

    &interaction.tour.merge.clone;

    <para id="x_33d">We should now have two copies of
      <filename>hello.c</filename> with different contents.  The
      histories of the two repositories have also diverged, as
      illustrated in figure <xref
	linkend="fig:tour-merge:sep-repos"/>.</para>

    &interaction.tour.merge.cat;

    <figure id="fig:tour-merge:sep-repos">

	  </imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para id="x_343">In figure <xref linkend="fig:tour-merge:pull"/>, you can
	see the effect of the pull from <filename
	  class="directory">my-hello</filename> into <filename
	  class="directory">my-new-hello</filename>.  The history that
	was already present in <filename
	  class="directory">my-new-hello</filename> is untouched, but
	a new revision has been added.  By referring to figure <xref
	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
	<emphasis>changeset ID</emphasis> remains the same in the new
	repository, but the <emphasis>revision number</emphasis> has
	changed.  (This, incidentally, is a fine example of why it's
	not safe to use revision numbers when discussing changesets.)

	These are the same revisions that were previously displayed by
	<command role="hg-cmd">hg parents</command>.</para>

      &interaction.tour.merge.tip;

      <para id="x_34a">In figure <xref
	  linkend="fig:tour-merge:merge"/>, you can see a
	representation of what happens to the working directory during
	the merge, and how this affects the repository when the commit
	happens.  During the merge, the working directory has two
	parent changesets, and these become the parents of the new

	<imageobject><imagedata fileref="tour-merge-conflict"/></imageobject>
	<textobject><phrase>XXX add text</phrase></textobject>
      </mediaobject>
    </figure>

    <para id="x_34d">Figure <xref linkend="fig:tour-merge:conflict"/> illustrates
      an instance of two conflicting changes to a document.  We
      started with a single version of the file; then we made some
      changes; while someone else made different changes to the same
      text.  Our task in resolving the conflicting changes is to
      decide what the file should look like.</para>

      <para id="x_350">My preferred graphical merge tool is
	<command>kdiff3</command>, which I'll use to describe the
	features that are common to graphical file merging tools.  You
	can see a screenshot of <command>kdiff3</command> in action in
	figure <xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
	merge it is performing is called a <emphasis>three-way
	  merge</emphasis>, because there are three different versions
	of the file of interest to us.  The tool thus splits the upper
	portion of the window into three panes:</para>
      <itemizedlist>

    </sect2>
    <sect2>
      <title>A worked example</title>

      <para id="x_359">In this example, we will reproduce the file modification
	history of figure <xref linkend="fig:tour-merge:conflict"/>
	above.  Let's begin by creating a repository with a base
	version of our document.</para>

      &interaction.tour-merge-conflict.wife;

691:4ce9d0754af3

    &interaction.tour.merge.clone;

    <para id="x_33d">We should now have two copies of
      <filename>hello.c</filename> with different contents.  The
      histories of the two repositories have also diverged, as
      illustrated in <xref
	linkend="fig:tour-merge:sep-repos"/>.</para>

    &interaction.tour.merge.cat;

    <figure id="fig:tour-merge:sep-repos">

	  </imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para id="x_343">In <xref linkend="fig:tour-merge:pull"/>, you can
	see the effect of the pull from <filename
	  class="directory">my-hello</filename> into <filename
	  class="directory">my-new-hello</filename>.  The history that
	was already present in <filename
	  class="directory">my-new-hello</filename> is untouched, but
	a new revision has been added.  By referring to <xref
	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
	<emphasis>changeset ID</emphasis> remains the same in the new
	repository, but the <emphasis>revision number</emphasis> has
	changed.  (This, incidentally, is a fine example of why it's
	not safe to use revision numbers when discussing changesets.)

	These are the same revisions that were previously displayed by
	<command role="hg-cmd">hg parents</command>.</para>

      &interaction.tour.merge.tip;

      <para id="x_34a">In <xref
	  linkend="fig:tour-merge:merge"/>, you can see a
	representation of what happens to the working directory during
	the merge, and how this affects the repository when the commit
	happens.  During the merge, the working directory has two
	parent changesets, and these become the parents of the new

	<imageobject><imagedata fileref="tour-merge-conflict"/></imageobject>
	<textobject><phrase>XXX add text</phrase></textobject>
      </mediaobject>
    </figure>

    <para id="x_34d"><xref linkend="fig:tour-merge:conflict"/> illustrates
      an instance of two conflicting changes to a document.  We
      started with a single version of the file; then we made some
      changes; while someone else made different changes to the same
      text.  Our task in resolving the conflicting changes is to
      decide what the file should look like.</para>

      <para id="x_350">My preferred graphical merge tool is
	<command>kdiff3</command>, which I'll use to describe the
	features that are common to graphical file merging tools.  You
	can see a screenshot of <command>kdiff3</command> in action in
	<xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
	merge it is performing is called a <emphasis>three-way
	  merge</emphasis>, because there are three different versions
	of the file of interest to us.  The tool thus splits the upper
	portion of the window into three panes:</para>
      <itemizedlist>

    </sect2>
    <sect2>
      <title>A worked example</title>

      <para id="x_359">In this example, we will reproduce the file modification
	history of <xref linkend="fig:tour-merge:conflict"/>
	above.  Let's begin by creating a repository with a base
	version of our document.</para>

      &interaction.tour-merge-conflict.wife;