comparison en/ch03-concepts.xml @ 691:4ce9d0754af3

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

690:b788b405e141

	(<quote><literal>.i</literal></quote> suffix) files.  For
	small files without much history, the revision data and index
	are combined in a single <quote><literal>.i</literal></quote>
	file.  The correspondence between a file in the working
	directory and the filelog that tracks its history in the
	repository is illustrated in figure <xref
	  linkend="fig:concepts:filelog"/>.</para>

      <figure id="fig:concepts:filelog">
	<title>Relationships between files in working directory and
	  filelogs in repository</title>

      <para id="x_2f1">For every changeset in a repository, there is exactly one
	revision stored in the changelog.  Each revision of the
	changelog contains a pointer to a single revision of the
	manifest.  A revision of the manifest stores a pointer to a
	single revision of each filelog tracked when that changeset
	was created.  These relationships are illustrated in figure
	<xref linkend="fig:concepts:metadata"/>.</para>

      <figure id="fig:concepts:metadata">
	<title>Metadata relationships</title>
	<mediaobject>

	instead of another delta.  This makes it possible to
	reconstruct <emphasis>any</emphasis> revision of a file
	quickly.  This approach works so well that it has since been
	copied by several other revision control systems.</para>

      <para id="x_2fd">Figure <xref linkend="fig:concepts:snapshot"/> illustrates
	the idea.  In an entry in a revlog's index file, Mercurial
	stores the range of entries from the data file that it must
	read to reconstruct a particular revision.</para>

      <sect3>

      for not one parent, but two.  Mercurial uses a special hash,
      called the <quote>null ID</quote>, to represent the idea
      <quote>there is no parent here</quote>.  This hash is simply a
      string of zeroes.</para>

    <para id="x_305">In figure <xref linkend="fig:concepts:revlog"/>, you can see
      an example of the conceptual structure of a revlog.  Filelogs,
      manifests, and changelogs all have this same structure; they
      differ only in the kind of data stored in each delta or
      snapshot.</para>

	  <imageobject><imagedata fileref="wdir"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para id="x_30d">Figure <xref linkend="fig:concepts:wdir"/> shows the
	normal state of the working directory, where it has a single
	changeset as parent.  That changeset is the
	<emphasis>tip</emphasis>, the newest changeset in the
	repository that has no children.</para>

	or copied will be reflected in that changeset, as will
	modifications to any files that Mercurial is already tracking;
	the new changeset will have the parents of the working
	directory as its parents.</para>

      <para id="x_310">After a commit, Mercurial will update the parents of the
	working directory, so that the first parent is the ID of the
	new changeset, and the second is the null ID.  This is shown
	in figure <xref linkend="fig:concepts:wdir-after-commit"/>.
	Mercurial
	doesn't touch any of the files in the working directory when
	you commit; it just modifies the dirstate to note its new
	parents.</para>

    </sect2>

	introduced a bug.  In cases like this, the natural thing to do
	is update the working directory to the changeset you're
	interested in, and then examine the files in the working
	directory directly to see their contents as they were when you
	committed that changeset.  The effect of this is shown in
	figure <xref linkend="fig:concepts:wdir-pre-branch"/>.</para>

      <figure id="fig:concepts:wdir-pre-branch">
	<title>The working directory, updated to an older
	  changeset</title>
	<mediaobject>
	  <imageobject><imagedata fileref="wdir-pre-branch"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para id="x_313">Having updated the working directory to an older
	changeset, what happens if you make some changes, and then
	commit?  Mercurial behaves in the same way as I outlined
	above.  The parents of the working directory become the
	parents of the new changeset.  This new changeset has no
	children, so it becomes the new tip.  And the repository now
	contains two changesets that have no children; we call these
	<emphasis>heads</emphasis>.  You can see the structure that
	this creates in figure <xref
	  linkend="fig:concepts:wdir-branch"/>.</para>

      <figure id="fig:concepts:wdir-branch">
	<title>After a commit made while synced to an older
	  changeset</title>

    </sect2>
    <sect2>
      <title>Merging heads</title>

      <para id="x_317">When you run the <command role="hg-cmd">hg merge</command>
	command, Mercurial leaves the first parent of the working
	directory unchanged, and sets the second parent to the
	changeset you're merging with, as shown in figure <xref
	  linkend="fig:concepts:wdir-merge"/>.</para>

      <figure id="fig:concepts:wdir-merge">
	<title>Merging two heads</title>
	<mediaobject>

      </sect3>
    </sect2>
    <sect2>
      <title>Read/write ordering and atomicity</title>

      <para id="x_32a">Appending to files isn't the whole story when it comes to
	guaranteeing that a reader won't see a partial write.  If you
	recall figure <xref linkend="fig:concepts:metadata"/>,
	revisions in the
	changelog point to revisions in the manifest, and revisions in
	the manifest point to revisions in filelogs.  This hierarchy
	is deliberate.</para>

      <para id="x_32b">A writer starts a transaction by writing filelog and
	manifest data, and doesn't write any changelog data until
	those are finished.  A reader starts by reading changelog
	data, then manifest data, followed by filelog data.</para>

691:4ce9d0754af3

	(<quote><literal>.i</literal></quote> suffix) files.  For
	small files without much history, the revision data and index
	are combined in a single <quote><literal>.i</literal></quote>
	file.  The correspondence between a file in the working
	directory and the filelog that tracks its history in the
	repository is illustrated in <xref
	  linkend="fig:concepts:filelog"/>.</para>

      <figure id="fig:concepts:filelog">
	<title>Relationships between files in working directory and
	  filelogs in repository</title>

      <para id="x_2f1">For every changeset in a repository, there is exactly one
	revision stored in the changelog.  Each revision of the
	changelog contains a pointer to a single revision of the
	manifest.  A revision of the manifest stores a pointer to a
	single revision of each filelog tracked when that changeset
	was created.  These relationships are illustrated in
	<xref linkend="fig:concepts:metadata"/>.</para>

      <figure id="fig:concepts:metadata">
	<title>Metadata relationships</title>
	<mediaobject>

	instead of another delta.  This makes it possible to
	reconstruct <emphasis>any</emphasis> revision of a file
	quickly.  This approach works so well that it has since been
	copied by several other revision control systems.</para>

      <para id="x_2fd"><xref linkend="fig:concepts:snapshot"/> illustrates
	the idea.  In an entry in a revlog's index file, Mercurial
	stores the range of entries from the data file that it must
	read to reconstruct a particular revision.</para>

      <sect3>

      for not one parent, but two.  Mercurial uses a special hash,
      called the <quote>null ID</quote>, to represent the idea
      <quote>there is no parent here</quote>.  This hash is simply a
      string of zeroes.</para>

    <para id="x_305">In <xref linkend="fig:concepts:revlog"/>, you can see
      an example of the conceptual structure of a revlog.  Filelogs,
      manifests, and changelogs all have this same structure; they
      differ only in the kind of data stored in each delta or
      snapshot.</para>

	  <imageobject><imagedata fileref="wdir"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para id="x_30d"><xref linkend="fig:concepts:wdir"/> shows the
	normal state of the working directory, where it has a single
	changeset as parent.  That changeset is the
	<emphasis>tip</emphasis>, the newest changeset in the
	repository that has no children.</para>

	or copied will be reflected in that changeset, as will
	modifications to any files that Mercurial is already tracking;
	the new changeset will have the parents of the working
	directory as its parents.</para>

      <para id="x_310">After a commit, Mercurial will update the
	parents of the working directory, so that the first parent is
	the ID of the new changeset, and the second is the null ID.
	This is shown in <xref
	  linkend="fig:concepts:wdir-after-commit"/>. Mercurial
	doesn't touch any of the files in the working directory when
	you commit; it just modifies the dirstate to note its new
	parents.</para>

    </sect2>

	introduced a bug.  In cases like this, the natural thing to do
	is update the working directory to the changeset you're
	interested in, and then examine the files in the working
	directory directly to see their contents as they were when you
	committed that changeset.  The effect of this is shown in
	<xref linkend="fig:concepts:wdir-pre-branch"/>.</para>

      <figure id="fig:concepts:wdir-pre-branch">
	<title>The working directory, updated to an older
	  changeset</title>
	<mediaobject>
	  <imageobject><imagedata fileref="wdir-pre-branch"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para id="x_313">Having updated the working directory to an
	older changeset, what happens if you make some changes, and
	then commit?  Mercurial behaves in the same way as I outlined
	above.  The parents of the working directory become the
	parents of the new changeset.  This new changeset has no
	children, so it becomes the new tip.  And the repository now
	contains two changesets that have no children; we call these
	<emphasis>heads</emphasis>.  You can see the structure that
	this creates in <xref
	  linkend="fig:concepts:wdir-branch"/>.</para>

      <figure id="fig:concepts:wdir-branch">
	<title>After a commit made while synced to an older
	  changeset</title>

    </sect2>
    <sect2>
      <title>Merging heads</title>

      <para id="x_317">When you run the <command role="hg-cmd">hg
	  merge</command> command, Mercurial leaves the first parent
	of the working directory unchanged, and sets the second parent
	to the changeset you're merging with, as shown in <xref
	  linkend="fig:concepts:wdir-merge"/>.</para>

      <figure id="fig:concepts:wdir-merge">
	<title>Merging two heads</title>
	<mediaobject>

      </sect3>
    </sect2>
    <sect2>
      <title>Read/write ordering and atomicity</title>

      <para id="x_32a">Appending to files isn't the whole story when
	it comes to guaranteeing that a reader won't see a partial
	write.  If you recall <xref linkend="fig:concepts:metadata"/>,
	revisions in
	the changelog point to revisions in the manifest, and
	revisions in the manifest point to revisions in filelogs.
	This hierarchy is deliberate.</para>

      <para id="x_32b">A writer starts a transaction by writing filelog and
	manifest data, and doesn't write any changelog data until
	those are finished.  A reader starts by reading changelog
	data, then manifest data, followed by filelog data.</para>