diff en/ch08-branch.xml @ 666:8fcd44708f41

Uncomment all the mangled interaction examples.

--- a/en/ch08-branch.xml	Mon Mar 09 22:55:38 2009 -0700
+++ b/en/ch08-branch.xml	Mon Mar 09 23:22:09 2009 -0700
@@ -28,12 +28,13 @@
       the identity of that revision. This will let you reproduce that
       release at a later date, for whatever purpose you might need at
       the time (reproducing a bug, porting to a new platform, etc).
-      <!-- &interaction.tag.init; --></para>
+      &interaction.tag.init;</para>
 
     <para>Mercurial lets you give a permanent name to any revision
       using the <command role="hg-cmd">hg tag</command> command.  Not
-      surprisingly, these names are called <quote>tags</quote>. <!--
-      &interaction.tag.tag; --></para>
+      surprisingly, these names are called <quote>tags</quote>.</para>
+
+    &interaction.tag.tag;
 
     <para>A tag is nothing more than a <quote>symbolic name</quote>
       for a revision.  Tags exist purely for your convenience, so that
@@ -58,11 +59,15 @@
       command to display the tags present in your repository.  In the
       output, each tagged revision is identified first by its name,
       then by revision number, and finally by the unique hash of the
-      revision. <!-- &interaction.tag.tags; --> Notice that
-      <literal>tip</literal> is listed in the output of <command
-	role="hg-cmd">hg tags</command>.  The <literal>tip</literal>
-      tag is a special <quote>floating</quote> tag, which always
-      identifies the newest revision in the repository.</para>
+      revision.</para>
+
+    &interaction.tag.tags;
+
+    <para>Notice that <literal>tip</literal> is listed in the output
+      of <command role="hg-cmd">hg tags</command>.  The
+      <literal>tip</literal> tag is a special <quote>floating</quote>
+      tag, which always identifies the newest revision in the
+      repository.</para>
 
     <para>In the output of the <command role="hg-cmd">hg
 	tags</command> command, tags are listed in reverse order, by
@@ -73,13 +78,16 @@
 
     <para>When you run <command role="hg-cmd">hg log</command>, if it
       displays a revision that has tags associated with it, it will
-      print those tags. <!-- &interaction.tag.log; --></para>
+      print those tags.</para>
+
+    &interaction.tag.log;
 
     <para>Any time you need to provide a revision ID to a Mercurial
       command, the command will accept a tag name in its place.
       Internally, Mercurial will translate your tag name into the
-      corresponding revision ID, then use that. <!--
-      &interaction.tag.log.v1.0; --></para>
+      corresponding revision ID, then use that.</para>
+
+    &interaction.tag.log.v1.0;
 
     <para>There's no limit on the number of tags you can have in a
       repository, or on the number of tags that a single revision can
@@ -98,18 +106,24 @@
       or simply not use tags to track buildability.</para>
 
     <para>If you want to remove a tag that you no longer want, use
-      <command role="hg-cmd">hg tag --remove</command>. <!--
-      &interaction.tag.remove; --> You can also modify a tag at any
-      time, so that it identifies a different revision, by simply
-      issuing a new <command role="hg-cmd">hg tag</command> command.
-      You'll have to use the <option role="hg-opt-tag">-f</option>
-      option to tell Mercurial that you <emphasis>really</emphasis>
-      want to update the tag. <!-- &interaction.tag.replace; --> There
-      will still be a permanent record of the previous identity of the
-      tag, but Mercurial will no longer use it.  There's thus no
-      penalty to tagging the wrong revision; all you have to do is
-      turn around and tag the correct revision once you discover your
-      error.</para>
+      <command role="hg-cmd">hg tag --remove</command>.</para>
+
+    &interaction.tag.remove;
+
+    <para>You can also modify a tag at any time, so that it identifies
+      a different revision, by simply issuing a new <command
+	role="hg-cmd">hg tag</command> command. You'll have to use the
+      <option role="hg-opt-tag">-f</option> option to tell Mercurial
+      that you <emphasis>really</emphasis> want to update the
+      tag.</para>
+
+    &interaction.tag.replace;
+
+    <para>There will still be a permanent record of the previous
+      identity of the tag, but Mercurial will no longer use it.
+      There's thus no penalty to tagging the wrong revision; all you
+      have to do is turn around and tag the correct revision once you
+      discover your error.</para>
 
     <para>Mercurial stores tags in a normal revision-controlled file
       in your repository.  If you've created any tags, you'll find
@@ -119,8 +133,9 @@
       this file, then automatically commits the change to it.  This
       means that every time you run <command role="hg-cmd">hg
 	tag</command>, you'll see a corresponding changeset in the
-      output of <command role="hg-cmd">hg log</command>. <!--
-      &interaction.tag.tip; --></para>
+      output of <command role="hg-cmd">hg log</command>.</para>
+
+    &interaction.tag.tip;
 
     <sect2>
       <title>Handling tag conflicts during a merge</title>
@@ -247,19 +262,28 @@
       <literal>myproject</literal>&emdash;that reaches a
       <quote>1.0</quote> milestone, you can start to prepare for
       future maintenance releases on top of version 1.0 by tagging the
-      revision from which you prepared the 1.0 release. <!--
-      &interaction.branch-repo.tag; --> You can then clone a new
-      shared <literal>myproject-1.0.1</literal> repository as of that
-      tag. <!-- &interaction.branch-repo.clone; --></para>
+      revision from which you prepared the 1.0 release.</para>
+
+    &interaction.branch-repo.tag;
+
+    <para>You can then clone a new shared
+      <literal>myproject-1.0.1</literal> repository as of that
+      tag.</para>
+
+    &interaction.branch-repo.clone;
 
     <para>Afterwards, if someone needs to work on a bug fix that ought
       to go into an upcoming 1.0.1 minor release, they clone the
       <literal>myproject-1.0.1</literal> repository, make their
-      changes, and push them back. <!--
-      &interaction.branch-repo.bugfix; --> Meanwhile, development for
+      changes, and push them back.</para>
+
+    &interaction.branch-repo.bugfix;
+
+    <para>Meanwhile, development for
       the next major release can continue, isolated and unabated, in
-      the <literal>myproject</literal> repository. <!--
-      &interaction.branch-repo.new; --></para>
+      the <literal>myproject</literal> repository.</para>
+
+    &interaction.branch-repo.new;
 
   </sect1>
   <sect1>
@@ -275,9 +299,14 @@
 
     <para>In the simplest instance, all you need to do is pull changes
       from your maintenance branch into your local clone of the target
-      branch. <!-- &interaction.branch-repo.pull; --> You'll then need
-      to merge the heads of the two branches, and push back to the
-      main branch. <!-- &interaction.branch-repo.merge; --></para>
+      branch.</para>
+
+    &interaction.branch-repo.pull;
+
+    <para>You'll then need to merge the heads of the two branches, and
+      push back to the main branch.</para>
+
+    &interaction.branch-repo.merge;
 
   </sect1>
   <sect1>
@@ -318,27 +347,34 @@
     <para>To start working with named branches, use the <command
 	role="hg-cmd">hg branches</command> command.  This command
       lists the named branches already present in your repository,
-      telling you which changeset is the tip of each. <!--
-      &interaction.branch-named.branches; --> Since you haven't
-      created any named branches yet, the only one that exists is
-      <literal>default</literal>.</para>
+      telling you which changeset is the tip of each.</para>
+
+    &interaction.branch-named.branches;
+
+    <para>Since you haven't created any named branches yet, the only
+      one that exists is <literal>default</literal>.</para>
 
     <para>To find out what the <quote>current</quote> branch is, run
       the <command role="hg-cmd">hg branch</command> command, giving
       it no arguments.  This tells you what branch the parent of the
-      current changeset is on. <!-- &interaction.branch-named.branch;
-      --></para>
+      current changeset is on.</para>
+
+    &interaction.branch-named.branch;
 
     <para>To create a new branch, run the <command role="hg-cmd">hg
 	branch</command> command again.  This time, give it one
-      argument: the name of the branch you want to create. <!--
-      &interaction.branch-named.create; --></para>
+      argument: the name of the branch you want to create.</para>
+
+    &interaction.branch-named.create;
 
     <para>After you've created a branch, you might wonder what effect
       the <command role="hg-cmd">hg branch</command> command has had.
       What do the <command role="hg-cmd">hg status</command> and
-      <command role="hg-cmd">hg tip</command> commands report? <!--
-      &interaction.branch-named.status; --> Nothing has changed in the
+      <command role="hg-cmd">hg tip</command> commands report?</para>
+
+    &interaction.branch-named.status;
+
+    <para>Nothing has changed in the
       working directory, and there's been no new history created.  As
       this suggests, running the <command role="hg-cmd">hg
 	branch</command> command has no permanent effect; it only
@@ -351,10 +387,12 @@
       you'll see the name of the new branch show up in the output of
       <command role="hg-cmd">hg log</command>, <command
 	role="hg-cmd">hg tip</command>, and other commands that
-      display the same kind of output. <!--
-      &interaction.branch-named.commit; --> The <command
-	role="hg-cmd">hg log</command>-like commands will print the
-      branch name of every changeset that's not on the
+      display the same kind of output.</para>
+
+    &interaction.branch-named.commit;
+
+    <para>The <command role="hg-cmd">hg log</command>-like commands
+      will print the branch name of every changeset that's not on the
       <literal>default</literal> branch.  As a result, if you never
       use named branches, you'll never see this information.</para>
 
@@ -362,11 +400,13 @@
       name, every subsequent commit that descends from that change
       will inherit the same branch name.  You can change the name of a
       branch at any time, using the <command role="hg-cmd">hg
-	branch</command> command. <!--
-      &interaction.branch-named.rebranch; --> In practice, this is
-      something you won't do very often, as branch names tend to have
-      fairly long lifetimes.  (This isn't a rule, just an
-      observation.)</para>
+	branch</command> command.</para>
+
+    &interaction.branch-named.rebranch;
+
+    <para>In practice, this is something you won't do very often, as
+      branch names tend to have fairly long lifetimes.  (This isn't a
+      rule, just an observation.)</para>
 
   </sect1>
   <sect1>
@@ -385,28 +425,34 @@
 
     <para>This behaviour is a little subtle, so let's see it in
       action.  First, let's remind ourselves what branch we're
-      currently on, and what branches are in our repository. <!--
-      &interaction.branch-named.parents; --> We're on the
-      <literal>bar</literal> branch, but there also exists an older
-      <command role="hg-cmd">hg foo</command> branch.</para>
+      currently on, and what branches are in our repository.</para>
+
+    &interaction.branch-named.parents;
+
+    <para>We're on the <literal>bar</literal> branch, but there also
+      exists an older <command role="hg-cmd">hg foo</command>
+      branch.</para>
 
     <para>We can <command role="hg-cmd">hg update</command> back and
       forth between the tips of the <literal>foo</literal> and
       <literal>bar</literal> branches without needing to use the
       <option role="hg-opt-update">-C</option> option, because this
       only involves going backwards and forwards linearly through our
-      change history. <!-- &interaction.branch-named.update-switchy;
-      --></para>
+      change history.</para>
+
+    &interaction.branch-named.update-switchy;
 
     <para>If we go back to the <literal>foo</literal> branch and then
       run <command role="hg-cmd">hg update</command>, it will keep us
       on <literal>foo</literal>, not move us to the tip of
-      <literal>bar</literal>. <!--
-      &interaction.branch-named.update-nothing; --></para>
+      <literal>bar</literal>.</para>
+
+    &interaction.branch-named.update-nothing;
 
     <para>Committing a new change on the <literal>foo</literal> branch
-      introduces a new head. <!--
-      &interaction.branch-named.foo-commit; --></para>
+      introduces a new head.</para>
+
+    &interaction.branch-named.foo-commit;
 
   </sect1>
   <sect1>
@@ -439,8 +485,9 @@
 
     <para>But if I'm working on the <literal>bar</literal> branch, and
       I merge work from the <literal>foo</literal> branch, the result
-      will remain on the <literal>bar</literal> branch. <!--
-      &interaction.branch-named.merge; --></para>
+      will remain on the <literal>bar</literal> branch.</para>
+
+    &interaction.branch-named.merge;
 
     <para>To give a more concrete example, if I'm working on the
       <literal>bleeding-edge</literal> branch, and I want to bring in