1.1 --- a/en/ch08-branch.xml	Wed Feb 18 00:22:09 2009 -0800
     1.2 +++ b/en/ch08-branch.xml	Mon Mar 09 23:22:09 2009 -0700
     1.3 @@ -28,12 +28,13 @@
     1.4        the identity of that revision. This will let you reproduce that
     1.5        release at a later date, for whatever purpose you might need at
     1.6        the time (reproducing a bug, porting to a new platform, etc).
     1.7 -      <!-- &interaction.tag.init; --></para>
     1.8 +      &interaction.tag.init;</para>
     1.9  
    1.10      <para>Mercurial lets you give a permanent name to any revision
    1.11        using the <command role="hg-cmd">hg tag</command> command.  Not
    1.12 -      surprisingly, these names are called <quote>tags</quote>. <!--
    1.13 -      &interaction.tag.tag; --></para>
    1.14 +      surprisingly, these names are called <quote>tags</quote>.</para>
    1.15 +
    1.16 +    &interaction.tag.tag;
    1.17  
    1.18      <para>A tag is nothing more than a <quote>symbolic name</quote>
    1.19        for a revision.  Tags exist purely for your convenience, so that
    1.20 @@ -58,11 +59,15 @@
    1.21        command to display the tags present in your repository.  In the
    1.22        output, each tagged revision is identified first by its name,
    1.23        then by revision number, and finally by the unique hash of the
    1.24 -      revision. <!-- &interaction.tag.tags; --> Notice that
    1.25 -      <literal>tip</literal> is listed in the output of <command
    1.26 -	role="hg-cmd">hg tags</command>.  The <literal>tip</literal>
    1.27 -      tag is a special <quote>floating</quote> tag, which always
    1.28 -      identifies the newest revision in the repository.</para>
    1.29 +      revision.</para>
    1.30 +
    1.31 +    &interaction.tag.tags;
    1.32 +
    1.33 +    <para>Notice that <literal>tip</literal> is listed in the output
    1.34 +      of <command role="hg-cmd">hg tags</command>.  The
    1.35 +      <literal>tip</literal> tag is a special <quote>floating</quote>
    1.36 +      tag, which always identifies the newest revision in the
    1.37 +      repository.</para>
    1.38  
    1.39      <para>In the output of the <command role="hg-cmd">hg
    1.40  	tags</command> command, tags are listed in reverse order, by
    1.41 @@ -73,13 +78,16 @@
    1.42  
    1.43      <para>When you run <command role="hg-cmd">hg log</command>, if it
    1.44        displays a revision that has tags associated with it, it will
    1.45 -      print those tags. <!-- &interaction.tag.log; --></para>
    1.46 +      print those tags.</para>
    1.47 +
    1.48 +    &interaction.tag.log;
    1.49  
    1.50      <para>Any time you need to provide a revision ID to a Mercurial
    1.51        command, the command will accept a tag name in its place.
    1.52        Internally, Mercurial will translate your tag name into the
    1.53 -      corresponding revision ID, then use that. <!--
    1.54 -      &interaction.tag.log.v1.0; --></para>
    1.55 +      corresponding revision ID, then use that.</para>
    1.56 +
    1.57 +    &interaction.tag.log.v1.0;
    1.58  
    1.59      <para>There's no limit on the number of tags you can have in a
    1.60        repository, or on the number of tags that a single revision can
    1.61 @@ -98,18 +106,24 @@
    1.62        or simply not use tags to track buildability.</para>
    1.63  
    1.64      <para>If you want to remove a tag that you no longer want, use
    1.65 -      <command role="hg-cmd">hg tag --remove</command>. <!--
    1.66 -      &interaction.tag.remove; --> You can also modify a tag at any
    1.67 -      time, so that it identifies a different revision, by simply
    1.68 -      issuing a new <command role="hg-cmd">hg tag</command> command.
    1.69 -      You'll have to use the <option role="hg-opt-tag">-f</option>
    1.70 -      option to tell Mercurial that you <emphasis>really</emphasis>
    1.71 -      want to update the tag. <!-- &interaction.tag.replace; --> There
    1.72 -      will still be a permanent record of the previous identity of the
    1.73 -      tag, but Mercurial will no longer use it.  There's thus no
    1.74 -      penalty to tagging the wrong revision; all you have to do is
    1.75 -      turn around and tag the correct revision once you discover your
    1.76 -      error.</para>
    1.77 +      <command role="hg-cmd">hg tag --remove</command>.</para>
    1.78 +
    1.79 +    &interaction.tag.remove;
    1.80 +
    1.81 +    <para>You can also modify a tag at any time, so that it identifies
    1.82 +      a different revision, by simply issuing a new <command
    1.83 +	role="hg-cmd">hg tag</command> command. You'll have to use the
    1.84 +      <option role="hg-opt-tag">-f</option> option to tell Mercurial
    1.85 +      that you <emphasis>really</emphasis> want to update the
    1.86 +      tag.</para>
    1.87 +
    1.88 +    &interaction.tag.replace;
    1.89 +
    1.90 +    <para>There will still be a permanent record of the previous
    1.91 +      identity of the tag, but Mercurial will no longer use it.
    1.92 +      There's thus no penalty to tagging the wrong revision; all you
    1.93 +      have to do is turn around and tag the correct revision once you
    1.94 +      discover your error.</para>
    1.95  
    1.96      <para>Mercurial stores tags in a normal revision-controlled file
    1.97        in your repository.  If you've created any tags, you'll find
    1.98 @@ -119,8 +133,9 @@
    1.99        this file, then automatically commits the change to it.  This
   1.100        means that every time you run <command role="hg-cmd">hg
   1.101  	tag</command>, you'll see a corresponding changeset in the
   1.102 -      output of <command role="hg-cmd">hg log</command>. <!--
   1.103 -      &interaction.tag.tip; --></para>
   1.104 +      output of <command role="hg-cmd">hg log</command>.</para>
   1.105 +
   1.106 +    &interaction.tag.tip;
   1.107  
   1.108      <sect2>
   1.109        <title>Handling tag conflicts during a merge</title>
   1.110 @@ -247,19 +262,28 @@
   1.111        <literal>myproject</literal>&emdash;that reaches a
   1.112        <quote>1.0</quote> milestone, you can start to prepare for
   1.113        future maintenance releases on top of version 1.0 by tagging the
   1.114 -      revision from which you prepared the 1.0 release. <!--
   1.115 -      &interaction.branch-repo.tag; --> You can then clone a new
   1.116 -      shared <literal>myproject-1.0.1</literal> repository as of that
   1.117 -      tag. <!-- &interaction.branch-repo.clone; --></para>
   1.118 +      revision from which you prepared the 1.0 release.</para>
   1.119 +
   1.120 +    &interaction.branch-repo.tag;
   1.121 +
   1.122 +    <para>You can then clone a new shared
   1.123 +      <literal>myproject-1.0.1</literal> repository as of that
   1.124 +      tag.</para>
   1.125 +
   1.126 +    &interaction.branch-repo.clone;
   1.127  
   1.128      <para>Afterwards, if someone needs to work on a bug fix that ought
   1.129        to go into an upcoming 1.0.1 minor release, they clone the
   1.130        <literal>myproject-1.0.1</literal> repository, make their
   1.131 -      changes, and push them back. <!--
   1.132 -      &interaction.branch-repo.bugfix; --> Meanwhile, development for
   1.133 +      changes, and push them back.</para>
   1.134 +
   1.135 +    &interaction.branch-repo.bugfix;
   1.136 +
   1.137 +    <para>Meanwhile, development for
   1.138        the next major release can continue, isolated and unabated, in
   1.139 -      the <literal>myproject</literal> repository. <!--
   1.140 -      &interaction.branch-repo.new; --></para>
   1.141 +      the <literal>myproject</literal> repository.</para>
   1.142 +
   1.143 +    &interaction.branch-repo.new;
   1.144  
   1.145    </sect1>
   1.146    <sect1>
   1.147 @@ -275,9 +299,14 @@
   1.148  
   1.149      <para>In the simplest instance, all you need to do is pull changes
   1.150        from your maintenance branch into your local clone of the target
   1.151 -      branch. <!-- &interaction.branch-repo.pull; --> You'll then need
   1.152 -      to merge the heads of the two branches, and push back to the
   1.153 -      main branch. <!-- &interaction.branch-repo.merge; --></para>
   1.154 +      branch.</para>
   1.155 +
   1.156 +    &interaction.branch-repo.pull;
   1.157 +
   1.158 +    <para>You'll then need to merge the heads of the two branches, and
   1.159 +      push back to the main branch.</para>
   1.160 +
   1.161 +    &interaction.branch-repo.merge;
   1.162  
   1.163    </sect1>
   1.164    <sect1>
   1.165 @@ -318,27 +347,34 @@
   1.166      <para>To start working with named branches, use the <command
   1.167  	role="hg-cmd">hg branches</command> command.  This command
   1.168        lists the named branches already present in your repository,
   1.169 -      telling you which changeset is the tip of each. <!--
   1.170 -      &interaction.branch-named.branches; --> Since you haven't
   1.171 -      created any named branches yet, the only one that exists is
   1.172 -      <literal>default</literal>.</para>
   1.173 +      telling you which changeset is the tip of each.</para>
   1.174 +
   1.175 +    &interaction.branch-named.branches;
   1.176 +
   1.177 +    <para>Since you haven't created any named branches yet, the only
   1.178 +      one that exists is <literal>default</literal>.</para>
   1.179  
   1.180      <para>To find out what the <quote>current</quote> branch is, run
   1.181        the <command role="hg-cmd">hg branch</command> command, giving
   1.182        it no arguments.  This tells you what branch the parent of the
   1.183 -      current changeset is on. <!-- &interaction.branch-named.branch;
   1.184 -      --></para>
   1.185 +      current changeset is on.</para>
   1.186 +
   1.187 +    &interaction.branch-named.branch;
   1.188  
   1.189      <para>To create a new branch, run the <command role="hg-cmd">hg
   1.190  	branch</command> command again.  This time, give it one
   1.191 -      argument: the name of the branch you want to create. <!--
   1.192 -      &interaction.branch-named.create; --></para>
   1.193 +      argument: the name of the branch you want to create.</para>
   1.194 +
   1.195 +    &interaction.branch-named.create;
   1.196  
   1.197      <para>After you've created a branch, you might wonder what effect
   1.198        the <command role="hg-cmd">hg branch</command> command has had.
   1.199        What do the <command role="hg-cmd">hg status</command> and
   1.200 -      <command role="hg-cmd">hg tip</command> commands report? <!--
   1.201 -      &interaction.branch-named.status; --> Nothing has changed in the
   1.202 +      <command role="hg-cmd">hg tip</command> commands report?</para>
   1.203 +
   1.204 +    &interaction.branch-named.status;
   1.205 +
   1.206 +    <para>Nothing has changed in the
   1.207        working directory, and there's been no new history created.  As
   1.208        this suggests, running the <command role="hg-cmd">hg
   1.209  	branch</command> command has no permanent effect; it only
   1.210 @@ -351,10 +387,12 @@
   1.211        you'll see the name of the new branch show up in the output of
   1.212        <command role="hg-cmd">hg log</command>, <command
   1.213  	role="hg-cmd">hg tip</command>, and other commands that
   1.214 -      display the same kind of output. <!--
   1.215 -      &interaction.branch-named.commit; --> The <command
   1.216 -	role="hg-cmd">hg log</command>-like commands will print the
   1.217 -      branch name of every changeset that's not on the
   1.218 +      display the same kind of output.</para>
   1.219 +
   1.220 +    &interaction.branch-named.commit;
   1.221 +
   1.222 +    <para>The <command role="hg-cmd">hg log</command>-like commands
   1.223 +      will print the branch name of every changeset that's not on the
   1.224        <literal>default</literal> branch.  As a result, if you never
   1.225        use named branches, you'll never see this information.</para>
   1.226  
   1.227 @@ -362,11 +400,13 @@
   1.228        name, every subsequent commit that descends from that change
   1.229        will inherit the same branch name.  You can change the name of a
   1.230        branch at any time, using the <command role="hg-cmd">hg
   1.231 -	branch</command> command. <!--
   1.232 -      &interaction.branch-named.rebranch; --> In practice, this is
   1.233 -      something you won't do very often, as branch names tend to have
   1.234 -      fairly long lifetimes.  (This isn't a rule, just an
   1.235 -      observation.)</para>
   1.236 +	branch</command> command.</para>
   1.237 +
   1.238 +    &interaction.branch-named.rebranch;
   1.239 +
   1.240 +    <para>In practice, this is something you won't do very often, as
   1.241 +      branch names tend to have fairly long lifetimes.  (This isn't a
   1.242 +      rule, just an observation.)</para>
   1.243  
   1.244    </sect1>
   1.245    <sect1>
   1.246 @@ -385,28 +425,34 @@
   1.247  
   1.248      <para>This behaviour is a little subtle, so let's see it in
   1.249        action.  First, let's remind ourselves what branch we're
   1.250 -      currently on, and what branches are in our repository. <!--
   1.251 -      &interaction.branch-named.parents; --> We're on the
   1.252 -      <literal>bar</literal> branch, but there also exists an older
   1.253 -      <command role="hg-cmd">hg foo</command> branch.</para>
   1.254 +      currently on, and what branches are in our repository.</para>
   1.255 +
   1.256 +    &interaction.branch-named.parents;
   1.257 +
   1.258 +    <para>We're on the <literal>bar</literal> branch, but there also
   1.259 +      exists an older <command role="hg-cmd">hg foo</command>
   1.260 +      branch.</para>
   1.261  
   1.262      <para>We can <command role="hg-cmd">hg update</command> back and
   1.263        forth between the tips of the <literal>foo</literal> and
   1.264        <literal>bar</literal> branches without needing to use the
   1.265        <option role="hg-opt-update">-C</option> option, because this
   1.266        only involves going backwards and forwards linearly through our
   1.267 -      change history. <!-- &interaction.branch-named.update-switchy;
   1.268 -      --></para>
   1.269 +      change history.</para>
   1.270 +
   1.271 +    &interaction.branch-named.update-switchy;
   1.272  
   1.273      <para>If we go back to the <literal>foo</literal> branch and then
   1.274        run <command role="hg-cmd">hg update</command>, it will keep us
   1.275        on <literal>foo</literal>, not move us to the tip of
   1.276 -      <literal>bar</literal>. <!--
   1.277 -      &interaction.branch-named.update-nothing; --></para>
   1.278 +      <literal>bar</literal>.</para>
   1.279 +
   1.280 +    &interaction.branch-named.update-nothing;
   1.281  
   1.282      <para>Committing a new change on the <literal>foo</literal> branch
   1.283 -      introduces a new head. <!--
   1.284 -      &interaction.branch-named.foo-commit; --></para>
   1.285 +      introduces a new head.</para>
   1.286 +
   1.287 +    &interaction.branch-named.foo-commit;
   1.288  
   1.289    </sect1>
   1.290    <sect1>
   1.291 @@ -439,8 +485,9 @@
   1.292  
   1.293      <para>But if I'm working on the <literal>bar</literal> branch, and
   1.294        I merge work from the <literal>foo</literal> branch, the result
   1.295 -      will remain on the <literal>bar</literal> branch. <!--
   1.296 -      &interaction.branch-named.merge; --></para>
   1.297 +      will remain on the <literal>bar</literal> branch.</para>
   1.298 +
   1.299 +    &interaction.branch-named.merge;
   1.300  
   1.301      <para>To give a more concrete example, if I'm working on the
   1.302        <literal>bleeding-edge</literal> branch, and I want to bring in