hgbook
changeset 567:8fcd44708f41
Uncomment all the mangled interaction examples.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Mar 09 23:22:09 2009 -0700 (2009-03-09) |
parents | 27043f385f3f |
children | a8160b8a4f15 |
files | en/ch03-tour-merge.xml en/ch05-daily.xml en/ch06-collab.xml en/ch07-filenames.xml en/ch08-branch.xml en/ch09-undo.xml en/ch10-hook.xml en/ch11-template.xml en/ch12-mq.xml en/ch13-mq-collab.xml en/ch14-hgext.xml |
line diff
1.1 --- a/en/ch03-tour-merge.xml Mon Mar 09 22:55:38 2009 -0700 1.2 +++ b/en/ch03-tour-merge.xml Mon Mar 09 23:22:09 2009 -0700 1.3 @@ -31,7 +31,7 @@ 1.4 begin by cloning yet another repository (see how often they 1.5 spring up?) and making a change in it.</para> 1.6 1.7 - <!-- &interaction.tour.merge.clone; --> 1.8 + &interaction.tour.merge.clone; 1.9 1.10 <para>We should now have two copies of 1.11 <filename>hello.c</filename> with different contents. The 1.12 @@ -39,7 +39,7 @@ 1.13 illustrated in figure <xref 1.14 linkend="fig:tour-merge:sep-repos"/>.</para> 1.15 1.16 - <!-- &interaction.tour.merge.cat; --> 1.17 + &interaction.tour.merge.cat; 1.18 1.19 <informalfigure id="fig:tour-merge:sep-repos"> 1.20 <mediaobject> 1.21 @@ -56,7 +56,7 @@ 1.22 class="directory">my-hello</filename> repository will have no 1.23 effect on the working directory.</para> 1.24 1.25 - <!-- &interaction.tour.merge.pull; --> 1.26 + &interaction.tour.merge.pull; 1.27 1.28 <para>However, the <command role="hg-cmd">hg pull</command> 1.29 command says something about <quote>heads</quote>.</para> 1.30 @@ -96,7 +96,7 @@ 1.31 We can view the heads in a repository using the <command 1.32 role="hg-cmd">hg heads</command> command.</para> 1.33 1.34 - <!-- &interaction.tour.merge.heads; --> 1.35 + &interaction.tour.merge.heads; 1.36 1.37 </sect2> 1.38 <sect2> 1.39 @@ -106,7 +106,7 @@ 1.40 role="hg-cmd">hg update</command> command to update to the 1.41 new tip?</para> 1.42 1.43 - <!-- &interaction.tour.merge.update; --> 1.44 + &interaction.tour.merge.update; 1.45 1.46 <para>Mercurial is telling us that the <command role="hg-cmd">hg 1.47 update</command> command won't do a merge; it won't update 1.48 @@ -115,7 +115,7 @@ 1.49 <command role="hg-cmd">hg merge</command> command to merge the 1.50 two heads.</para> 1.51 1.52 - <!-- &interaction.tour.merge.merge; --> 1.53 + &interaction.tour.merge.merge; 1.54 1.55 <informalfigure id="fig:tour-merge:merge"> 1.56 1.57 @@ -133,7 +133,7 @@ 1.58 parents</command> and the contents of 1.59 <filename>hello.c</filename>.</para> 1.60 1.61 - <!-- &interaction.tour.merge.parents; --> 1.62 + &interaction.tour.merge.parents; 1.63 1.64 </sect2> 1.65 <sect2> 1.66 @@ -144,14 +144,14 @@ 1.67 role="hg-cmd">hg commit</command> the results of the 1.68 merge.</para> 1.69 1.70 - <!-- &interaction.tour.merge.commit; --> 1.71 + &interaction.tour.merge.commit; 1.72 1.73 <para>We now have a new tip revision; notice that it has 1.74 <emphasis>both</emphasis> of our former heads as its parents. 1.75 These are the same revisions that were previously displayed by 1.76 <command role="hg-cmd">hg parents</command>.</para> 1.77 1.78 - <!-- &interaction.tour.merge.tip; --> 1.79 + &interaction.tour.merge.tip; 1.80 1.81 <para>In figure <xref 1.82 linkend="fig:tour-merge:merge"/>, you can see a 1.83 @@ -273,12 +273,12 @@ 1.84 above. Let's begin by creating a repository with a base 1.85 version of our document.</para> 1.86 1.87 - <!-- &interaction.tour-merge-conflict.wife; --> 1.88 + &interaction.tour-merge-conflict.wife; 1.89 1.90 <para>We'll clone the repository and make a change to the 1.91 file.</para> 1.92 1.93 - <!-- &interaction.tour-merge-conflict.cousin; --> 1.94 + &interaction.tour-merge-conflict.cousin; 1.95 1.96 <para>And another clone, to simulate someone else making a 1.97 change to the file. (This hints at the idea that it's not all 1.98 @@ -286,13 +286,13 @@ 1.99 separate repositories, and indeed to find and resolve 1.100 conflicts while doing so.)</para> 1.101 1.102 - <!-- &interaction.tour-merge-conflict.son; --> 1.103 + &interaction.tour-merge-conflict.son; 1.104 1.105 <para>Having created two 1.106 different versions of the file, we'll set up an environment 1.107 suitable for running our merge.</para> 1.108 1.109 - <!-- &interaction.tour-merge-conflict.pull; --> 1.110 + &interaction.tour-merge-conflict.pull; 1.111 1.112 <para>In this example, I won't use Mercurial's normal 1.113 <command>hgmerge</command> program to do the merge, because it 1.114 @@ -307,7 +307,7 @@ 1.115 <para><emphasis role="bold">XXX FIX THIS 1.116 EXAMPLE.</emphasis></para> 1.117 1.118 - <!-- &interaction.tour-merge-conflict.merge; --> 1.119 + &interaction.tour-merge-conflict.merge; 1.120 1.121 <para>Because <command>merge</command> can't resolve the 1.122 conflicting changes, it leaves <emphasis>merge 1.123 @@ -326,7 +326,7 @@ 1.124 prevent us from <quote>fixing up</quote> the affected files 1.125 ourselves, and committing the results of our merge:</para> 1.126 1.127 - <!-- &interaction.tour-merge-conflict.commit; --> 1.128 + &interaction.tour-merge-conflict.commit; 1.129 1.130 </sect2> 1.131 </sect1>
2.1 --- a/en/ch05-daily.xml Mon Mar 09 22:55:38 2009 -0700 2.2 +++ b/en/ch05-daily.xml Mon Mar 09 23:22:09 2009 -0700 2.3 @@ -18,8 +18,9 @@ 2.4 file, the entry in the output of <command role="hg-cmd">hg 2.5 status</command> for that file changes from 2.6 <quote><literal>?</literal></quote> to 2.7 - <quote><literal>A</literal></quote>. <!-- 2.8 - &interaction.daily.files.add; --></para> 2.9 + <quote><literal>A</literal></quote>.</para> 2.10 + 2.11 + &interaction.daily.files.add; 2.12 2.13 <para>After you run a <command role="hg-cmd">hg commit</command>, 2.14 the files that you added before the commit will no longer be 2.15 @@ -45,11 +46,14 @@ 2.16 <para>A useful behaviour that Mercurial has is that if you pass 2.17 the name of a directory to a command, every Mercurial command 2.18 will treat this as <quote>I want to operate on every file in 2.19 - this directory and its subdirectories</quote>. <!-- 2.20 - &interaction.daily.files.add-dir; --> Notice in this example 2.21 - that Mercurial printed the names of the files it added, 2.22 - whereas it didn't do so when we added the file named 2.23 - <filename>a</filename> in the earlier example.</para> 2.24 + this directory and its subdirectories</quote>.</para> 2.25 + 2.26 + &interaction.daily.files.add-dir; 2.27 + 2.28 + <para>Notice in this example that Mercurial printed the names of 2.29 + the files it added, whereas it didn't do so when we added the 2.30 + file named <filename>a</filename> in the earlier 2.31 + example.</para> 2.32 2.33 <para>What's going on is that in the former case, we explicitly 2.34 named the file to add on the command line, so the assumption 2.35 @@ -92,7 +96,7 @@ 2.36 most commands and GUI tools. This approach is illustrated 2.37 below.</para> 2.38 2.39 -<!-- &interaction.daily.files.hidden; --> 2.40 +&interaction.daily.files.hidden; 2.41 2.42 <para>Another way to tackle a need for an empty directory is to 2.43 simply create one in your automated build scripts before they 2.44 @@ -108,8 +112,9 @@ 2.45 command; this deletes the file, and tells Mercurial to stop 2.46 tracking it. A removed file is represented in the output of 2.47 <command role="hg-cmd">hg status</command> with a 2.48 - <quote><literal>R</literal></quote>. <!-- 2.49 - &interaction.daily.files.remove; --></para> 2.50 + <quote><literal>R</literal></quote>.</para> 2.51 + 2.52 + &interaction.daily.files.remove; 2.53 2.54 <para>After you <command role="hg-cmd">hg remove</command> a file, 2.55 Mercurial will no longer track changes to that file, even if you 2.56 @@ -152,7 +157,9 @@ 2.57 represented with <quote><literal>!</literal></quote> in the 2.58 output of <command role="hg-cmd">hg status</command>. 2.59 Mercurial commands will not generally do anything with missing 2.60 - files. <!-- &interaction.daily.files.missing; --></para> 2.61 + files.</para> 2.62 + 2.63 + &interaction.daily.files.missing; 2.64 2.65 <para>If your repository contains a file that <command 2.66 role="hg-cmd">hg status</command> reports as missing, and 2.67 @@ -160,15 +167,16 @@ 2.68 role="hg-cmd">hg remove <option 2.69 role="hg-opt-remove">--after</option></command> at any 2.70 time later on, to tell Mercurial that you really did mean to 2.71 - remove the file. <!-- &interaction.daily.files.remove-after; 2.72 - --></para> 2.73 + remove the file.</para> 2.74 + 2.75 + &interaction.daily.files.remove-after; 2.76 2.77 <para>On the other hand, if you deleted the missing file by 2.78 accident, give <command role="hg-cmd">hg revert</command> the 2.79 name of the file to recover. It will reappear, in unmodified 2.80 form.</para> 2.81 2.82 -<!-- &interaction.daily.files.recover-missing; --> 2.83 +&interaction.daily.files.recover-missing; 2.84 2.85 </sect2> 2.86 <sect2> 2.87 @@ -191,12 +199,16 @@ 2.88 2.89 <para>Mercurial offers a combination command, <command 2.90 role="hg-cmd">hg addremove</command>, that adds untracked 2.91 - files and marks missing files as removed. <!-- 2.92 - &interaction.daily.files.addremove; --> The <command 2.93 - role="hg-cmd">hg commit</command> command also provides a 2.94 - <option role="hg-opt-commit">-A</option> option that performs 2.95 - this same add-and-remove, immediately followed by a commit. 2.96 - <!-- &interaction.daily.files.commit-addremove; --></para> 2.97 + files and marks missing files as removed.</para> 2.98 + 2.99 + &interaction.daily.files.addremove; 2.100 + 2.101 + <para>The <command role="hg-cmd">hg commit</command> command 2.102 + also provides a <option role="hg-opt-commit">-A</option> 2.103 + option that performs this same add-and-remove, immediately 2.104 + followed by a commit.</para> 2.105 + 2.106 + &interaction.daily.files.commit-addremove; 2.107 2.108 </sect2> 2.109 </sect1> 2.110 @@ -216,34 +228,49 @@ 2.111 <para>What happens during a merge is that changes 2.112 <quote>follow</quote> a copy. To best illustrate what this 2.113 means, let's create an example. We'll start with the usual 2.114 - tiny repository that contains a single file. <!-- 2.115 - &interaction.daily.copy.init; --> We need to do some work in 2.116 + tiny repository that contains a single file.</para> 2.117 + 2.118 + &interaction.daily.copy.init; 2.119 + 2.120 + <para>We need to do some work in 2.121 parallel, so that we'll have something to merge. So let's 2.122 - clone our repository. <!-- &interaction.daily.copy.clone; --> 2.123 - Back in our initial repository, let's use the <command 2.124 + clone our repository.</para> 2.125 + 2.126 + &interaction.daily.copy.clone; 2.127 + 2.128 + <para>Back in our initial repository, let's use the <command 2.129 role="hg-cmd">hg copy</command> command to make a copy of 2.130 - the first file we created. <!-- &interaction.daily.copy.copy; 2.131 - --></para> 2.132 + the first file we created.</para> 2.133 + 2.134 + &interaction.daily.copy.copy; 2.135 2.136 <para>If we look at the output of the <command role="hg-cmd">hg 2.137 status</command> command afterwards, the copied file looks 2.138 - just like a normal added file. <!-- 2.139 - &interaction.daily.copy.status; --> But if we pass the <option 2.140 + just like a normal added file.</para> 2.141 + 2.142 + &interaction.daily.copy.status; 2.143 + 2.144 + <para>But if we pass the <option 2.145 role="hg-opt-status">-C</option> option to <command 2.146 role="hg-cmd">hg status</command>, it prints another line of 2.147 output: this is the file that our newly-added file was copied 2.148 - <emphasis>from</emphasis>. <!-- 2.149 - &interaction.daily.copy.status-copy; --></para> 2.150 + <emphasis>from</emphasis>.</para> 2.151 + 2.152 + &interaction.daily.copy.status-copy; 2.153 2.154 <para>Now, back in the repository we cloned, let's make a change 2.155 in parallel. We'll add a line of content to the original file 2.156 - that we created. <!-- &interaction.daily.copy.other; --> Now 2.157 - we have a modified <filename>file</filename> in this 2.158 + that we created.</para> 2.159 + 2.160 + &interaction.daily.copy.other; 2.161 + 2.162 + <para>Now we have a modified <filename>file</filename> in this 2.163 repository. When we pull the changes from the first 2.164 repository, and merge the two heads, Mercurial will propagate 2.165 the changes that we made locally to <filename>file</filename> 2.166 - into its copy, <filename>new-file</filename>. <!-- 2.167 - &interaction.daily.copy.merge; --></para> 2.168 + into its copy, <filename>new-file</filename>.</para> 2.169 + 2.170 + &interaction.daily.copy.merge; 2.171 2.172 </sect2> 2.173 <sect2 id="sec:daily:why-copy"> 2.174 @@ -327,22 +354,33 @@ 2.175 <emphasis>destination</emphasis>, and all prior arguments are 2.176 <emphasis>sources</emphasis>. If you pass it a single file as 2.177 the source, and the destination does not exist, it creates a 2.178 - new file with that name. <!-- &interaction.daily.copy.simple; 2.179 - --> If the destination is a directory, Mercurial copies its 2.180 - sources into that directory. <!-- 2.181 - &interaction.daily.copy.dir-dest; --> Copying a directory is 2.182 + new file with that name.</para> 2.183 + 2.184 + &interaction.daily.copy.simple; 2.185 + 2.186 + <para>If the destination is a directory, Mercurial copies its 2.187 + sources into that directory.</para> 2.188 + 2.189 + &interaction.daily.copy.dir-dest; 2.190 + 2.191 + <para>Copying a directory is 2.192 recursive, and preserves the directory structure of the 2.193 - source. <!-- &interaction.daily.copy.dir-src; --> If the 2.194 - source and destination are both directories, the source tree 2.195 - is recreated in the destination directory. <!-- 2.196 - &interaction.daily.copy.dir-src-dest; --></para> 2.197 + source.</para> 2.198 + 2.199 + &interaction.daily.copy.dir-src; 2.200 + 2.201 + <para>If the source and destination are both directories, the 2.202 + source tree is recreated in the destination directory.</para> 2.203 + 2.204 + &interaction.daily.copy.dir-src-dest; 2.205 2.206 <para>As with the <command role="hg-cmd">hg rename</command> 2.207 command, if you copy a file manually and then want Mercurial 2.208 to know that you've copied the file, simply use the <option 2.209 role="hg-opt-copy">--after</option> option to <command 2.210 - role="hg-cmd">hg copy</command>. <!-- 2.211 - &interaction.daily.copy.after; --></para> 2.212 + role="hg-cmd">hg copy</command>.</para> 2.213 + 2.214 + &interaction.daily.copy.after; 2.215 2.216 </sect2> 2.217 </sect1> 2.218 @@ -359,17 +397,24 @@ 2.219 2.220 <para>When you use the <command role="hg-cmd">hg rename</command> 2.221 command, Mercurial makes a copy of each source file, then 2.222 - deletes it and marks the file as removed. <!-- 2.223 - &interaction.daily.rename.rename; --> The <command 2.224 - role="hg-cmd">hg status</command> command shows the newly 2.225 - copied file as added, and the copied-from file as removed. <!-- 2.226 - &interaction.daily.rename.status; --> As with the results of a 2.227 - <command role="hg-cmd">hg copy</command>, we must use the 2.228 - <option role="hg-opt-status">-C</option> option to <command 2.229 + deletes it and marks the file as removed.</para> 2.230 + 2.231 + &interaction.daily.rename.rename; 2.232 + 2.233 + <para>The <command role="hg-cmd">hg status</command> command shows 2.234 + the newly copied file as added, and the copied-from file as 2.235 + removed.</para> 2.236 + 2.237 + &interaction.daily.rename.status; 2.238 + 2.239 + <para>As with the results of a <command role="hg-cmd">hg 2.240 + copy</command>, we must use the <option 2.241 + role="hg-opt-status">-C</option> option to <command 2.242 role="hg-cmd">hg status</command> to see that the added file 2.243 is really being tracked by Mercurial as a copy of the original, 2.244 - now removed, file. <!-- &interaction.daily.rename.status-copy; 2.245 - --></para> 2.246 + now removed, file.</para> 2.247 + 2.248 + &interaction.daily.rename.status-copy; 2.249 2.250 <para>As with <command role="hg-cmd">hg remove</command> and 2.251 <command role="hg-cmd">hg copy</command>, you can tell Mercurial 2.252 @@ -410,11 +455,16 @@ 2.253 <filename>foo</filename>&emdash;in their respective 2.254 repositories.</para> 2.255 2.256 - <para><!-- &interaction.rename.divergent.clone; --> Anne renames 2.257 - the file to <filename>bar</filename>. <!-- 2.258 - &interaction.rename.divergent.rename.anne; --> Meanwhile, Bob 2.259 - renames it to <filename>quux</filename>. <!-- 2.260 - &interaction.rename.divergent.rename.bob; --></para> 2.261 + &interaction.rename.divergent.clone; 2.262 + 2.263 + <para>Anne renames the file to <filename>bar</filename>.</para> 2.264 + 2.265 + &interaction.rename.divergent.rename.anne; 2.266 + 2.267 + <para>Meanwhile, Bob renames it to 2.268 + <filename>quux</filename>.</para> 2.269 + 2.270 + &interaction.rename.divergent.rename.bob; 2.271 2.272 <para>I like to think of this as a conflict because each 2.273 developer has expressed different intentions about what the 2.274 @@ -423,8 +473,9 @@ 2.275 <para>What do you think should happen when they merge their 2.276 work? Mercurial's actual behaviour is that it always preserves 2.277 <emphasis>both</emphasis> names when it merges changesets that 2.278 - contain divergent renames. <!-- 2.279 - &interaction.rename.divergent.merge; --></para> 2.280 + contain divergent renames.</para> 2.281 + 2.282 + &interaction.rename.divergent.merge; 2.283 2.284 <para>Notice that Mercurial does warn about the divergent 2.285 renames, but it leaves it up to you to do something about the 2.286 @@ -449,7 +500,9 @@ 2.287 while another has a directory with the same name. This is 2.288 documented as <ulink role="hg-bug" 2.289 url="http://www.selenic.com/mercurial/bts/issue29">issue 2.290 - 29</ulink>. <!-- &interaction.issue29.go; --></para> 2.291 + 29</ulink>.</para> 2.292 + 2.293 + &interaction.issue29.go; 2.294 2.295 </sect2> 2.296 </sect1>
3.1 --- a/en/ch06-collab.xml Mon Mar 09 22:55:38 2009 -0700 3.2 +++ b/en/ch06-collab.xml Mon Mar 09 23:22:09 2009 -0700 3.3 @@ -200,45 +200,63 @@ 3.4 3.5 <para>Here's an example of how this can work in practice. Let's 3.6 say you have one <quote>main branch</quote> on a central 3.7 - server. <!-- &interaction.branching.init; --> People clone it, 3.8 - make changes locally, test them, and push them back.</para> 3.9 + server.</para> 3.10 + 3.11 + &interaction.branching.init; 3.12 + 3.13 + <para>People clone it, make changes locally, test them, and push 3.14 + them back.</para> 3.15 3.16 <para>Once the main branch reaches a release milestone, you can 3.17 use the <command role="hg-cmd">hg tag</command> command to 3.18 - give a permanent name to the milestone revision. <!-- 3.19 - &interaction.branching.tag; --> Let's say some ongoing 3.20 - development occurs on the main branch. <!-- 3.21 - &interaction.branching.main; --> Using the tag that was 3.22 - recorded at the milestone, people who clone that repository at 3.23 - any time in the future can use <command role="hg-cmd">hg 3.24 - update</command> to get a copy of the working directory 3.25 - exactly as it was when that tagged revision was committed. 3.26 - <!-- &interaction.branching.update; --></para> 3.27 + give a permanent name to the milestone revision.</para> 3.28 + 3.29 + &interaction.branching.tag; 3.30 + 3.31 + <para>Let's say some ongoing 3.32 + development occurs on the main branch.</para> 3.33 + 3.34 + &interaction.branching.main; 3.35 + 3.36 + <para>Using the tag that was recorded at the milestone, people 3.37 + who clone that repository at any time in the future can use 3.38 + <command role="hg-cmd">hg update</command> to get a copy of 3.39 + the working directory exactly as it was when that tagged 3.40 + revision was committed.</para> 3.41 + 3.42 + &interaction.branching.update; 3.43 3.44 <para>In addition, immediately after the main branch is tagged, 3.45 someone can then clone the main branch on the server to a new 3.46 - <quote>stable</quote> branch, also on the server. <!-- 3.47 - &interaction.branching.clone; --></para> 3.48 + <quote>stable</quote> branch, also on the server.</para> 3.49 + 3.50 + &interaction.branching.clone; 3.51 3.52 <para>Someone who needs to make a change to the stable branch 3.53 can then clone <emphasis>that</emphasis> repository, make 3.54 - their changes, commit, and push their changes back there. <!-- 3.55 - &interaction.branching.stable; --> Because Mercurial 3.56 - repositories are independent, and Mercurial doesn't move 3.57 - changes around automatically, the stable and main branches are 3.58 - <emphasis>isolated</emphasis> from each other. The changes 3.59 - that you made on the main branch don't <quote>leak</quote> to 3.60 - the stable branch, and vice versa.</para> 3.61 + their changes, commit, and push their changes back there.</para> 3.62 + 3.63 + &interaction.branching.stable; 3.64 + 3.65 + <para>Because Mercurial repositories are independent, and 3.66 + Mercurial doesn't move changes around automatically, the 3.67 + stable and main branches are <emphasis>isolated</emphasis> 3.68 + from each other. The changes that you made on the main branch 3.69 + don't <quote>leak</quote> to the stable branch, and vice 3.70 + versa.</para> 3.71 3.72 <para>You'll often want all of your bugfixes on the stable 3.73 branch to show up on the main branch, too. Rather than 3.74 rewrite a bugfix on the main branch, you can simply pull and 3.75 merge changes from the stable to the main branch, and 3.76 - Mercurial will bring those bugfixes in for you. <!-- 3.77 - &interaction.branching.merge; --> The main branch will still 3.78 - contain changes that are not on the stable branch, but it will 3.79 - also contain all of the bugfixes from the stable branch. The 3.80 - stable branch remains unaffected by these changes.</para> 3.81 + Mercurial will bring those bugfixes in for you.</para> 3.82 + 3.83 + &interaction.branching.merge; 3.84 + 3.85 + <para>The main branch will still contain changes that are not on 3.86 + the stable branch, but it will also contain all of the 3.87 + bugfixes from the stable branch. The stable branch remains 3.88 + unaffected by these changes.</para> 3.89 3.90 </sect2> 3.91 <sect2>
4.1 --- a/en/ch07-filenames.xml Mon Mar 09 22:55:38 2009 -0700 4.2 +++ b/en/ch07-filenames.xml Mon Mar 09 23:22:09 2009 -0700 4.3 @@ -16,15 +16,16 @@ 4.4 4.5 <para>If you explicitly name real files on the command line, 4.6 Mercurial works with exactly those files, as you would expect. 4.7 - <!-- &interaction.filenames.files; --></para> 4.8 + &interaction.filenames.files;</para> 4.9 4.10 <para>When you provide a directory name, Mercurial will interpret 4.11 this as <quote>operate on every file in this directory and its 4.12 subdirectories</quote>. Mercurial traverses the files and 4.13 subdirectories in a directory in alphabetical order. When it 4.14 encounters a subdirectory, it will traverse that subdirectory 4.15 - before continuing with the current directory. <!-- 4.16 - &interaction.filenames.dirs; --></para> 4.17 + before continuing with the current directory.</para> 4.18 + 4.19 + &interaction.filenames.dirs; 4.20 4.21 </sect1> 4.22 <sect1> 4.23 @@ -53,8 +54,9 @@ 4.24 don't suit you. If a command normally operates on the whole 4.25 working directory, you can invoke it on just the current 4.26 directory and its subdirectories by giving it the name 4.27 - <quote><filename class="directory">.</filename></quote>. <!-- 4.28 - &interaction.filenames.wdir-subdir; --></para> 4.29 + <quote><filename class="directory">.</filename></quote>.</para> 4.30 + 4.31 + &interaction.filenames.wdir-subdir; 4.32 4.33 <para>Along the same lines, some commands normally print file 4.34 names relative to the root of the repository, even if you're 4.35 @@ -64,8 +66,9 @@ 4.36 status</command> from a subdirectory, and get it to operate on 4.37 the entire working directory while printing file names relative 4.38 to our subdirectory, by passing it the output of the <command 4.39 - role="hg-cmd">hg root</command> command. <!-- 4.40 - &interaction.filenames.wdir-relname; --></para> 4.41 + role="hg-cmd">hg root</command> command.</para> 4.42 + 4.43 + &interaction.filenames.wdir-relname; 4.44 4.45 </sect1> 4.46 <sect1> 4.47 @@ -139,18 +142,21 @@ 4.48 when you're matching on glob patterns.</para> 4.49 4.50 <para>The <quote><literal>*</literal></quote> character matches 4.51 - any string, within a single directory. <!-- 4.52 - &interaction.filenames.glob.star; --></para> 4.53 + any string, within a single directory.</para> 4.54 + 4.55 + &interaction.filenames.glob.star; 4.56 4.57 <para>The <quote><literal>**</literal></quote> pattern matches 4.58 any string, and crosses directory boundaries. It's not a 4.59 standard Unix glob token, but it's accepted by several popular 4.60 - Unix shells, and is very useful. <!-- 4.61 - &interaction.filenames.glob.starstar; --></para> 4.62 + Unix shells, and is very useful.</para> 4.63 + 4.64 + &interaction.filenames.glob.starstar; 4.65 4.66 <para>The <quote><literal>?</literal></quote> pattern matches 4.67 - any single character. <!-- 4.68 - &interaction.filenames.glob.question; --></para> 4.69 + any single character.</para> 4.70 + 4.71 + &interaction.filenames.glob.question; 4.72 4.73 <para>The <quote><literal>[</literal></quote> character begins a 4.74 <emphasis>character class</emphasis>. This matches any single 4.75 @@ -158,19 +164,23 @@ 4.76 <quote><literal>]</literal></quote> character. A class may 4.77 contain multiple <emphasis>range</emphasis>s of the form 4.78 <quote><literal>a-f</literal></quote>, which is shorthand for 4.79 - <quote><literal>abcdef</literal></quote>. <!-- 4.80 - &interaction.filenames.glob.range; --> If the first character 4.81 - after the <quote><literal>[</literal></quote> in a character 4.82 - class is a <quote><literal>!</literal></quote>, it 4.83 + <quote><literal>abcdef</literal></quote>.</para> 4.84 + 4.85 + &interaction.filenames.glob.range; 4.86 + 4.87 + <para>If the first character after the 4.88 + <quote><literal>[</literal></quote> in a character class is a 4.89 + <quote><literal>!</literal></quote>, it 4.90 <emphasis>negates</emphasis> the class, making it match any 4.91 single character not in the class.</para> 4.92 4.93 <para>A <quote><literal>{</literal></quote> begins a group of 4.94 subpatterns, where the whole group matches if any subpattern 4.95 in the group matches. The <quote><literal>,</literal></quote> 4.96 - character separates subpatterns, and <quote><literal>}</literal></quote> 4.97 - ends the group. <!-- &interaction.filenames.glob.group; 4.98 - --></para> 4.99 + character separates subpatterns, and 4.100 + <quote><literal>}</literal></quote> ends the group.</para> 4.101 + 4.102 + &interaction.filenames.glob.group; 4.103 4.104 <sect3> 4.105 <title>Watch out!</title> 4.106 @@ -180,8 +190,9 @@ 4.107 <quote><literal>*</literal></quote> match-any token, as this 4.108 will only match within one directory. Instead, use the 4.109 <quote><literal>**</literal></quote> token. This small 4.110 - example illustrates the difference between the two. <!-- 4.111 - &interaction.filenames.glob.star-starstar; --></para> 4.112 + example illustrates the difference between the two.</para> 4.113 + 4.114 + &interaction.filenames.glob.star-starstar; 4.115 4.116 </sect3> 4.117 </sect2> 4.118 @@ -245,11 +256,15 @@ 4.119 4.120 <para>You can read a <option role="hg-opt-global">-I</option> 4.121 filter as <quote>process only the files that match this 4.122 - filter</quote>. <!-- &interaction.filenames.filter.include; 4.123 - --> The <option role="hg-opt-global">-X</option> filter is best 4.124 + filter</quote>.</para> 4.125 + 4.126 + &interaction.filenames.filter.include; 4.127 + 4.128 + <para>The <option role="hg-opt-global">-X</option> filter is best 4.129 read as <quote>process only the files that don't match this 4.130 - pattern</quote>. <!-- &interaction.filenames.filter.exclude; 4.131 - --></para> 4.132 + pattern</quote>.</para> 4.133 + 4.134 + &interaction.filenames.filter.exclude; 4.135 4.136 </sect1> 4.137 <sect1>
5.1 --- a/en/ch08-branch.xml Mon Mar 09 22:55:38 2009 -0700 5.2 +++ b/en/ch08-branch.xml Mon Mar 09 23:22:09 2009 -0700 5.3 @@ -28,12 +28,13 @@ 5.4 the identity of that revision. This will let you reproduce that 5.5 release at a later date, for whatever purpose you might need at 5.6 the time (reproducing a bug, porting to a new platform, etc). 5.7 - <!-- &interaction.tag.init; --></para> 5.8 + &interaction.tag.init;</para> 5.9 5.10 <para>Mercurial lets you give a permanent name to any revision 5.11 using the <command role="hg-cmd">hg tag</command> command. Not 5.12 - surprisingly, these names are called <quote>tags</quote>. <!-- 5.13 - &interaction.tag.tag; --></para> 5.14 + surprisingly, these names are called <quote>tags</quote>.</para> 5.15 + 5.16 + &interaction.tag.tag; 5.17 5.18 <para>A tag is nothing more than a <quote>symbolic name</quote> 5.19 for a revision. Tags exist purely for your convenience, so that 5.20 @@ -58,11 +59,15 @@ 5.21 command to display the tags present in your repository. In the 5.22 output, each tagged revision is identified first by its name, 5.23 then by revision number, and finally by the unique hash of the 5.24 - revision. <!-- &interaction.tag.tags; --> Notice that 5.25 - <literal>tip</literal> is listed in the output of <command 5.26 - role="hg-cmd">hg tags</command>. The <literal>tip</literal> 5.27 - tag is a special <quote>floating</quote> tag, which always 5.28 - identifies the newest revision in the repository.</para> 5.29 + revision.</para> 5.30 + 5.31 + &interaction.tag.tags; 5.32 + 5.33 + <para>Notice that <literal>tip</literal> is listed in the output 5.34 + of <command role="hg-cmd">hg tags</command>. The 5.35 + <literal>tip</literal> tag is a special <quote>floating</quote> 5.36 + tag, which always identifies the newest revision in the 5.37 + repository.</para> 5.38 5.39 <para>In the output of the <command role="hg-cmd">hg 5.40 tags</command> command, tags are listed in reverse order, by 5.41 @@ -73,13 +78,16 @@ 5.42 5.43 <para>When you run <command role="hg-cmd">hg log</command>, if it 5.44 displays a revision that has tags associated with it, it will 5.45 - print those tags. <!-- &interaction.tag.log; --></para> 5.46 + print those tags.</para> 5.47 + 5.48 + &interaction.tag.log; 5.49 5.50 <para>Any time you need to provide a revision ID to a Mercurial 5.51 command, the command will accept a tag name in its place. 5.52 Internally, Mercurial will translate your tag name into the 5.53 - corresponding revision ID, then use that. <!-- 5.54 - &interaction.tag.log.v1.0; --></para> 5.55 + corresponding revision ID, then use that.</para> 5.56 + 5.57 + &interaction.tag.log.v1.0; 5.58 5.59 <para>There's no limit on the number of tags you can have in a 5.60 repository, or on the number of tags that a single revision can 5.61 @@ -98,18 +106,24 @@ 5.62 or simply not use tags to track buildability.</para> 5.63 5.64 <para>If you want to remove a tag that you no longer want, use 5.65 - <command role="hg-cmd">hg tag --remove</command>. <!-- 5.66 - &interaction.tag.remove; --> You can also modify a tag at any 5.67 - time, so that it identifies a different revision, by simply 5.68 - issuing a new <command role="hg-cmd">hg tag</command> command. 5.69 - You'll have to use the <option role="hg-opt-tag">-f</option> 5.70 - option to tell Mercurial that you <emphasis>really</emphasis> 5.71 - want to update the tag. <!-- &interaction.tag.replace; --> There 5.72 - will still be a permanent record of the previous identity of the 5.73 - tag, but Mercurial will no longer use it. There's thus no 5.74 - penalty to tagging the wrong revision; all you have to do is 5.75 - turn around and tag the correct revision once you discover your 5.76 - error.</para> 5.77 + <command role="hg-cmd">hg tag --remove</command>.</para> 5.78 + 5.79 + &interaction.tag.remove; 5.80 + 5.81 + <para>You can also modify a tag at any time, so that it identifies 5.82 + a different revision, by simply issuing a new <command 5.83 + role="hg-cmd">hg tag</command> command. You'll have to use the 5.84 + <option role="hg-opt-tag">-f</option> option to tell Mercurial 5.85 + that you <emphasis>really</emphasis> want to update the 5.86 + tag.</para> 5.87 + 5.88 + &interaction.tag.replace; 5.89 + 5.90 + <para>There will still be a permanent record of the previous 5.91 + identity of the tag, but Mercurial will no longer use it. 5.92 + There's thus no penalty to tagging the wrong revision; all you 5.93 + have to do is turn around and tag the correct revision once you 5.94 + discover your error.</para> 5.95 5.96 <para>Mercurial stores tags in a normal revision-controlled file 5.97 in your repository. If you've created any tags, you'll find 5.98 @@ -119,8 +133,9 @@ 5.99 this file, then automatically commits the change to it. This 5.100 means that every time you run <command role="hg-cmd">hg 5.101 tag</command>, you'll see a corresponding changeset in the 5.102 - output of <command role="hg-cmd">hg log</command>. <!-- 5.103 - &interaction.tag.tip; --></para> 5.104 + output of <command role="hg-cmd">hg log</command>.</para> 5.105 + 5.106 + &interaction.tag.tip; 5.107 5.108 <sect2> 5.109 <title>Handling tag conflicts during a merge</title> 5.110 @@ -247,19 +262,28 @@ 5.111 <literal>myproject</literal>&emdash;that reaches a 5.112 <quote>1.0</quote> milestone, you can start to prepare for 5.113 future maintenance releases on top of version 1.0 by tagging the 5.114 - revision from which you prepared the 1.0 release. <!-- 5.115 - &interaction.branch-repo.tag; --> You can then clone a new 5.116 - shared <literal>myproject-1.0.1</literal> repository as of that 5.117 - tag. <!-- &interaction.branch-repo.clone; --></para> 5.118 + revision from which you prepared the 1.0 release.</para> 5.119 + 5.120 + &interaction.branch-repo.tag; 5.121 + 5.122 + <para>You can then clone a new shared 5.123 + <literal>myproject-1.0.1</literal> repository as of that 5.124 + tag.</para> 5.125 + 5.126 + &interaction.branch-repo.clone; 5.127 5.128 <para>Afterwards, if someone needs to work on a bug fix that ought 5.129 to go into an upcoming 1.0.1 minor release, they clone the 5.130 <literal>myproject-1.0.1</literal> repository, make their 5.131 - changes, and push them back. <!-- 5.132 - &interaction.branch-repo.bugfix; --> Meanwhile, development for 5.133 + changes, and push them back.</para> 5.134 + 5.135 + &interaction.branch-repo.bugfix; 5.136 + 5.137 + <para>Meanwhile, development for 5.138 the next major release can continue, isolated and unabated, in 5.139 - the <literal>myproject</literal> repository. <!-- 5.140 - &interaction.branch-repo.new; --></para> 5.141 + the <literal>myproject</literal> repository.</para> 5.142 + 5.143 + &interaction.branch-repo.new; 5.144 5.145 </sect1> 5.146 <sect1> 5.147 @@ -275,9 +299,14 @@ 5.148 5.149 <para>In the simplest instance, all you need to do is pull changes 5.150 from your maintenance branch into your local clone of the target 5.151 - branch. <!-- &interaction.branch-repo.pull; --> You'll then need 5.152 - to merge the heads of the two branches, and push back to the 5.153 - main branch. <!-- &interaction.branch-repo.merge; --></para> 5.154 + branch.</para> 5.155 + 5.156 + &interaction.branch-repo.pull; 5.157 + 5.158 + <para>You'll then need to merge the heads of the two branches, and 5.159 + push back to the main branch.</para> 5.160 + 5.161 + &interaction.branch-repo.merge; 5.162 5.163 </sect1> 5.164 <sect1> 5.165 @@ -318,27 +347,34 @@ 5.166 <para>To start working with named branches, use the <command 5.167 role="hg-cmd">hg branches</command> command. This command 5.168 lists the named branches already present in your repository, 5.169 - telling you which changeset is the tip of each. <!-- 5.170 - &interaction.branch-named.branches; --> Since you haven't 5.171 - created any named branches yet, the only one that exists is 5.172 - <literal>default</literal>.</para> 5.173 + telling you which changeset is the tip of each.</para> 5.174 + 5.175 + &interaction.branch-named.branches; 5.176 + 5.177 + <para>Since you haven't created any named branches yet, the only 5.178 + one that exists is <literal>default</literal>.</para> 5.179 5.180 <para>To find out what the <quote>current</quote> branch is, run 5.181 the <command role="hg-cmd">hg branch</command> command, giving 5.182 it no arguments. This tells you what branch the parent of the 5.183 - current changeset is on. <!-- &interaction.branch-named.branch; 5.184 - --></para> 5.185 + current changeset is on.</para> 5.186 + 5.187 + &interaction.branch-named.branch; 5.188 5.189 <para>To create a new branch, run the <command role="hg-cmd">hg 5.190 branch</command> command again. This time, give it one 5.191 - argument: the name of the branch you want to create. <!-- 5.192 - &interaction.branch-named.create; --></para> 5.193 + argument: the name of the branch you want to create.</para> 5.194 + 5.195 + &interaction.branch-named.create; 5.196 5.197 <para>After you've created a branch, you might wonder what effect 5.198 the <command role="hg-cmd">hg branch</command> command has had. 5.199 What do the <command role="hg-cmd">hg status</command> and 5.200 - <command role="hg-cmd">hg tip</command> commands report? <!-- 5.201 - &interaction.branch-named.status; --> Nothing has changed in the 5.202 + <command role="hg-cmd">hg tip</command> commands report?</para> 5.203 + 5.204 + &interaction.branch-named.status; 5.205 + 5.206 + <para>Nothing has changed in the 5.207 working directory, and there's been no new history created. As 5.208 this suggests, running the <command role="hg-cmd">hg 5.209 branch</command> command has no permanent effect; it only 5.210 @@ -351,10 +387,12 @@ 5.211 you'll see the name of the new branch show up in the output of 5.212 <command role="hg-cmd">hg log</command>, <command 5.213 role="hg-cmd">hg tip</command>, and other commands that 5.214 - display the same kind of output. <!-- 5.215 - &interaction.branch-named.commit; --> The <command 5.216 - role="hg-cmd">hg log</command>-like commands will print the 5.217 - branch name of every changeset that's not on the 5.218 + display the same kind of output.</para> 5.219 + 5.220 + &interaction.branch-named.commit; 5.221 + 5.222 + <para>The <command role="hg-cmd">hg log</command>-like commands 5.223 + will print the branch name of every changeset that's not on the 5.224 <literal>default</literal> branch. As a result, if you never 5.225 use named branches, you'll never see this information.</para> 5.226 5.227 @@ -362,11 +400,13 @@ 5.228 name, every subsequent commit that descends from that change 5.229 will inherit the same branch name. You can change the name of a 5.230 branch at any time, using the <command role="hg-cmd">hg 5.231 - branch</command> command. <!-- 5.232 - &interaction.branch-named.rebranch; --> In practice, this is 5.233 - something you won't do very often, as branch names tend to have 5.234 - fairly long lifetimes. (This isn't a rule, just an 5.235 - observation.)</para> 5.236 + branch</command> command.</para> 5.237 + 5.238 + &interaction.branch-named.rebranch; 5.239 + 5.240 + <para>In practice, this is something you won't do very often, as 5.241 + branch names tend to have fairly long lifetimes. (This isn't a 5.242 + rule, just an observation.)</para> 5.243 5.244 </sect1> 5.245 <sect1> 5.246 @@ -385,28 +425,34 @@ 5.247 5.248 <para>This behaviour is a little subtle, so let's see it in 5.249 action. First, let's remind ourselves what branch we're 5.250 - currently on, and what branches are in our repository. <!-- 5.251 - &interaction.branch-named.parents; --> We're on the 5.252 - <literal>bar</literal> branch, but there also exists an older 5.253 - <command role="hg-cmd">hg foo</command> branch.</para> 5.254 + currently on, and what branches are in our repository.</para> 5.255 + 5.256 + &interaction.branch-named.parents; 5.257 + 5.258 + <para>We're on the <literal>bar</literal> branch, but there also 5.259 + exists an older <command role="hg-cmd">hg foo</command> 5.260 + branch.</para> 5.261 5.262 <para>We can <command role="hg-cmd">hg update</command> back and 5.263 forth between the tips of the <literal>foo</literal> and 5.264 <literal>bar</literal> branches without needing to use the 5.265 <option role="hg-opt-update">-C</option> option, because this 5.266 only involves going backwards and forwards linearly through our 5.267 - change history. <!-- &interaction.branch-named.update-switchy; 5.268 - --></para> 5.269 + change history.</para> 5.270 + 5.271 + &interaction.branch-named.update-switchy; 5.272 5.273 <para>If we go back to the <literal>foo</literal> branch and then 5.274 run <command role="hg-cmd">hg update</command>, it will keep us 5.275 on <literal>foo</literal>, not move us to the tip of 5.276 - <literal>bar</literal>. <!-- 5.277 - &interaction.branch-named.update-nothing; --></para> 5.278 + <literal>bar</literal>.</para> 5.279 + 5.280 + &interaction.branch-named.update-nothing; 5.281 5.282 <para>Committing a new change on the <literal>foo</literal> branch 5.283 - introduces a new head. <!-- 5.284 - &interaction.branch-named.foo-commit; --></para> 5.285 + introduces a new head.</para> 5.286 + 5.287 + &interaction.branch-named.foo-commit; 5.288 5.289 </sect1> 5.290 <sect1> 5.291 @@ -439,8 +485,9 @@ 5.292 5.293 <para>But if I'm working on the <literal>bar</literal> branch, and 5.294 I merge work from the <literal>foo</literal> branch, the result 5.295 - will remain on the <literal>bar</literal> branch. <!-- 5.296 - &interaction.branch-named.merge; --></para> 5.297 + will remain on the <literal>bar</literal> branch.</para> 5.298 + 5.299 + &interaction.branch-named.merge; 5.300 5.301 <para>To give a more concrete example, if I'm working on the 5.302 <literal>bleeding-edge</literal> branch, and I want to bring in
6.1 --- a/en/ch09-undo.xml Mon Mar 09 22:55:38 2009 -0700 6.2 +++ b/en/ch09-undo.xml Mon Mar 09 23:22:09 2009 -0700 6.3 @@ -41,32 +41,43 @@ 6.4 6.5 <para>Here's a mistake that I often find myself making: 6.6 committing a change in which I've created a new file, but 6.7 - forgotten to <command role="hg-cmd">hg add</command> it. <!-- 6.8 - &interaction.rollback.commit; --> Looking at the output of 6.9 - <command role="hg-cmd">hg status</command> after the commit 6.10 - immediately confirms the error. <!-- 6.11 - &interaction.rollback.status; --> The commit captured the 6.12 - changes to the file <filename>a</filename>, but not the new 6.13 - file <filename>b</filename>. If I were to push this changeset 6.14 - to a repository that I shared with a colleague, the chances 6.15 - are high that something in <filename>a</filename> would refer 6.16 - to <filename>b</filename>, which would not be present in their 6.17 + forgotten to <command role="hg-cmd">hg add</command> 6.18 + it.</para> 6.19 + 6.20 + &interaction.rollback.commit; 6.21 + 6.22 + <para>Looking at the output of <command role="hg-cmd">hg 6.23 + status</command> after the commit immediately confirms the 6.24 + error.</para> 6.25 + 6.26 + &interaction.rollback.status; 6.27 + 6.28 + <para>The commit captured the changes to the file 6.29 + <filename>a</filename>, but not the new file 6.30 + <filename>b</filename>. If I were to push this changeset to a 6.31 + repository that I shared with a colleague, the chances are 6.32 + high that something in <filename>a</filename> would refer to 6.33 + <filename>b</filename>, which would not be present in their 6.34 repository when they pulled my changes. I would thus become 6.35 the object of some indignation.</para> 6.36 6.37 <para>However, luck is with me&emdash;I've caught my error 6.38 before I pushed the changeset. I use the <command 6.39 role="hg-cmd">hg rollback</command> command, and Mercurial 6.40 - makes that last changeset vanish. <!-- 6.41 - &interaction.rollback.rollback; --> Notice that the changeset 6.42 - is no longer present in the repository's history, and the 6.43 - working directory once again thinks that the file 6.44 - <filename>a</filename> is modified. The commit and rollback 6.45 - have left the working directory exactly as it was prior to the 6.46 - commit; the changeset has been completely erased. I can now 6.47 - safely <command role="hg-cmd">hg add</command> the file 6.48 - <filename>b</filename>, and rerun my commit. <!-- 6.49 - &interaction.rollback.add; --></para> 6.50 + makes that last changeset vanish.</para> 6.51 + 6.52 + &interaction.rollback.rollback; 6.53 + 6.54 + <para>Notice that the changeset is no longer present in the 6.55 + repository's history, and the working directory once again 6.56 + thinks that the file <filename>a</filename> is modified. The 6.57 + commit and rollback have left the working directory exactly as 6.58 + it was prior to the commit; the changeset has been completely 6.59 + erased. I can now safely <command role="hg-cmd">hg 6.60 + add</command> the file <filename>b</filename>, and rerun my 6.61 + commit.</para> 6.62 + 6.63 + &interaction.rollback.add; 6.64 6.65 </sect2> 6.66 <sect2> 6.67 @@ -139,9 +150,12 @@ 6.68 occurred in the repository. This means that you can only roll 6.69 back one transaction. If you expect to be able to roll back 6.70 one transaction, then its predecessor, this is not the 6.71 - behaviour you will get. <!-- &interaction.rollback.twice; --> 6.72 - Once you've rolled back one transaction in a repository, you 6.73 - can't roll back again in that repository until you perform 6.74 + behaviour you will get.</para> 6.75 + 6.76 + &interaction.rollback.twice; 6.77 + 6.78 + <para>Once you've rolled back one transaction in a repository, 6.79 + you can't roll back again in that repository until you perform 6.80 another commit or pull.</para> 6.81 6.82 </sect2> 6.83 @@ -161,14 +175,22 @@ 6.84 <para>Let's illustrate how the <command role="hg-cmd">hg 6.85 revert</command> command works with yet another small example. 6.86 We'll begin by modifying a file that Mercurial is already 6.87 - tracking. <!-- &interaction.daily.revert.modify; --> If we don't 6.88 + tracking.</para> 6.89 + 6.90 + &interaction.daily.revert.modify; 6.91 + 6.92 + <para>If we don't 6.93 want that change, we can simply <command role="hg-cmd">hg 6.94 - revert</command> the file. <!-- 6.95 - &interaction.daily.revert.unmodify; --> The <command 6.96 - role="hg-cmd">hg revert</command> command provides us with an 6.97 - extra degree of safety by saving our modified file with a 6.98 - <filename>.orig</filename> extension. <!-- 6.99 - &interaction.daily.revert.status; --></para> 6.100 + revert</command> the file.</para> 6.101 + 6.102 + &interaction.daily.revert.unmodify; 6.103 + 6.104 + <para>The <command role="hg-cmd">hg revert</command> command 6.105 + provides us with an extra degree of safety by saving our 6.106 + modified file with a <filename>.orig</filename> 6.107 + extension.</para> 6.108 + 6.109 + &interaction.daily.revert.status; 6.110 6.111 <para>Here is a summary of the cases that the <command 6.112 role="hg-cmd">hg revert</command> command can deal with. We 6.113 @@ -204,25 +226,28 @@ 6.114 then decide that in fact you don't want Mercurial to track it, 6.115 use <command role="hg-cmd">hg revert</command> to undo the 6.116 add. Don't worry; Mercurial will not modify the file in any 6.117 - way. It will just <quote>unmark</quote> the file. <!-- 6.118 - &interaction.daily.revert.add; --></para> 6.119 + way. It will just <quote>unmark</quote> the file.</para> 6.120 + 6.121 + &interaction.daily.revert.add; 6.122 6.123 <para>Similarly, if you ask Mercurial to <command 6.124 role="hg-cmd">hg remove</command> a file, you can use 6.125 <command role="hg-cmd">hg revert</command> to restore it to 6.126 the contents it had as of the parent of the working directory. 6.127 - <!-- &interaction.daily.revert.remove; --> This works just as 6.128 + &interaction.daily.revert.remove; This works just as 6.129 well for a file that you deleted by hand, without telling 6.130 Mercurial (recall that in Mercurial terminology, this kind of 6.131 - file is called <quote>missing</quote>). <!-- 6.132 - &interaction.daily.revert.missing; --></para> 6.133 + file is called <quote>missing</quote>).</para> 6.134 + 6.135 + &interaction.daily.revert.missing; 6.136 6.137 <para>If you revert a <command role="hg-cmd">hg copy</command>, 6.138 the copied-to file remains in your working directory 6.139 afterwards, untracked. Since a copy doesn't affect the 6.140 copied-from file in any way, Mercurial doesn't do anything 6.141 - with the copied-from file. <!-- 6.142 - &interaction.daily.revert.copy; --></para> 6.143 + with the copied-from file.</para> 6.144 + 6.145 + &interaction.daily.revert.copy; 6.146 6.147 <sect3> 6.148 <title>A slightly special case: reverting a rename</title> 6.149 @@ -231,17 +256,23 @@ 6.150 file, there is one small detail that you should remember. 6.151 When you <command role="hg-cmd">hg revert</command> a 6.152 rename, it's not enough to provide the name of the 6.153 - renamed-to file, as you can see here. <!-- 6.154 - &interaction.daily.revert.rename; --> As you can see from 6.155 - the output of <command role="hg-cmd">hg status</command>, 6.156 - the renamed-to file is no longer identified as added, but 6.157 - the renamed-<emphasis>from</emphasis> file is still removed! 6.158 + renamed-to file, as you can see here.</para> 6.159 + 6.160 + &interaction.daily.revert.rename; 6.161 + 6.162 + <para>As you can see from the output of <command 6.163 + role="hg-cmd">hg status</command>, the renamed-to file is 6.164 + no longer identified as added, but the 6.165 + renamed-<emphasis>from</emphasis> file is still removed! 6.166 This is counter-intuitive (at least to me), but at least 6.167 - it's easy to deal with. <!-- 6.168 - &interaction.daily.revert.rename-orig; --> So remember, to 6.169 - revert a <command role="hg-cmd">hg rename</command>, you 6.170 - must provide <emphasis>both</emphasis> the source and 6.171 - destination names.</para> 6.172 + it's easy to deal with.</para> 6.173 + 6.174 + &interaction.daily.revert.rename-orig; 6.175 + 6.176 + <para>So remember, to revert a <command role="hg-cmd">hg 6.177 + rename</command>, you must provide 6.178 + <emphasis>both</emphasis> the source and destination 6.179 + names.</para> 6.180 6.181 <para>% TODO: the output doesn't look like it will be 6.182 removed!</para> 6.183 @@ -291,8 +322,9 @@ 6.184 <para>The operation of the <command role="hg-cmd">hg 6.185 backout</command> command is a little intricate, so let's 6.186 illustrate it with some examples. First, we'll create a 6.187 - repository with some simple changes. <!-- 6.188 - &interaction.backout.init; --></para> 6.189 + repository with some simple changes.</para> 6.190 + 6.191 + &interaction.backout.init; 6.192 6.193 <para>The <command role="hg-cmd">hg backout</command> command 6.194 takes a single changeset ID as its argument; this is the 6.195 @@ -308,15 +340,19 @@ 6.196 <title>Backing out the tip changeset</title> 6.197 6.198 <para>We're going to start by backing out the last changeset we 6.199 - committed. <!-- &interaction.backout.simple; --> You can see 6.200 - that the second line from <filename>myfile</filename> is no 6.201 - longer present. Taking a look at the output of <command 6.202 - role="hg-cmd">hg log</command> gives us an idea of what the 6.203 - <command role="hg-cmd">hg backout</command> command has done. 6.204 - <!-- &interaction.backout.simple.log; --> Notice that the new 6.205 - changeset that <command role="hg-cmd">hg backout</command> has 6.206 - created is a child of the changeset we backed out. It's 6.207 - easier to see this in figure <xref 6.208 + committed.</para> 6.209 + 6.210 + &interaction.backout.simple; 6.211 + 6.212 + <para>You can see that the second line from 6.213 + <filename>myfile</filename> is no longer present. Taking a 6.214 + look at the output of <command role="hg-cmd">hg log</command> 6.215 + gives us an idea of what the <command role="hg-cmd">hg 6.216 + backout</command> command has done. 6.217 + &interaction.backout.simple.log; Notice that the new changeset 6.218 + that <command role="hg-cmd">hg backout</command> has created 6.219 + is a child of the changeset we backed out. It's easier to see 6.220 + this in figure <xref 6.221 linkend="fig:undo:backout"/>, which presents a graphical 6.222 view of the change history. As you can see, the history is 6.223 nice and linear.</para> 6.224 @@ -338,16 +374,22 @@ 6.225 <para>If you want to back out a change other than the last one 6.226 you committed, pass the <option 6.227 role="hg-opt-backout">--merge</option> option to the 6.228 - <command role="hg-cmd">hg backout</command> command. <!-- 6.229 - &interaction.backout.non-tip.clone; --> This makes backing out 6.230 - any changeset a <quote>one-shot</quote> operation that's 6.231 - usually simple and fast. <!-- 6.232 - &interaction.backout.non-tip.backout; --></para> 6.233 + <command role="hg-cmd">hg backout</command> command.</para> 6.234 + 6.235 + &interaction.backout.non-tip.clone; 6.236 + 6.237 + <para>This makes backing out any changeset a 6.238 + <quote>one-shot</quote> operation that's usually simple and 6.239 + fast.</para> 6.240 + 6.241 + &interaction.backout.non-tip.backout; 6.242 6.243 <para>If you take a look at the contents of 6.244 <filename>myfile</filename> after the backout finishes, you'll 6.245 see that the first and third changes are present, but not the 6.246 - second. <!-- &interaction.backout.non-tip.cat; --></para> 6.247 + second.</para> 6.248 + 6.249 + &interaction.backout.non-tip.cat; 6.250 6.251 <para>As the graphical history in figure <xref 6.252 linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial 6.253 @@ -404,15 +446,21 @@ 6.254 clone our first repository, but omit the backout change that 6.255 it contains.</para> 6.256 6.257 - <para><!-- &interaction.backout.manual.clone; --> As with our 6.258 + &interaction.backout.manual.clone; 6.259 + 6.260 + <para>As with our 6.261 earlier example, We'll commit a third changeset, then back out 6.262 - its parent, and see what happens. <!-- 6.263 - &interaction.backout.manual.backout; --> Our new changeset is 6.264 - again a descendant of the changeset we backout out; it's thus 6.265 - a new head, <emphasis>not</emphasis> a descendant of the 6.266 - changeset that was the tip. The <command role="hg-cmd">hg 6.267 - backout</command> command was quite explicit in telling us 6.268 - this. <!-- &interaction.backout.manual.log; --></para> 6.269 + its parent, and see what happens.</para> 6.270 + 6.271 + &interaction.backout.manual.backout; 6.272 + 6.273 + <para>Our new changeset is again a descendant of the changeset 6.274 + we backout out; it's thus a new head, <emphasis>not</emphasis> 6.275 + a descendant of the changeset that was the tip. The <command 6.276 + role="hg-cmd">hg backout</command> command was quite 6.277 + explicit in telling us this.</para> 6.278 + 6.279 + &interaction.backout.manual.log; 6.280 6.281 <para>Again, it's easier to see what has happened by looking at 6.282 a graph of the revision history, in figure <xref 6.283 @@ -435,9 +483,13 @@ 6.284 <para>After the <command role="hg-cmd">hg backout</command> 6.285 command has completed, it leaves the new 6.286 <quote>backout</quote> changeset as the parent of the working 6.287 - directory. <!-- &interaction.backout.manual.parents; --> Now 6.288 - we have two isolated sets of changes. <!-- 6.289 - &interaction.backout.manual.heads; --></para> 6.290 + directory.</para> 6.291 + 6.292 + &interaction.backout.manual.parents; 6.293 + 6.294 + <para>Now we have two isolated sets of changes.</para> 6.295 + 6.296 + &interaction.backout.manual.heads; 6.297 6.298 <para>Let's think about what we expect to see as the contents of 6.299 <filename>myfile</filename> now. The first change should be 6.300 @@ -445,11 +497,17 @@ 6.301 should be missing, as that's the change we backed out. Since 6.302 the history graph shows the third change as a separate head, 6.303 we <emphasis>don't</emphasis> expect to see the third change 6.304 - present in <filename>myfile</filename>. <!-- 6.305 - &interaction.backout.manual.cat; --> To get the third change 6.306 - back into the file, we just do a normal merge of our two 6.307 - heads. <!-- &interaction.backout.manual.merge; --> Afterwards, 6.308 - the graphical history of our repository looks like figure 6.309 + present in <filename>myfile</filename>.</para> 6.310 + 6.311 + &interaction.backout.manual.cat; 6.312 + 6.313 + <para>To get the third change back into the file, we just do a 6.314 + normal merge of our two heads.</para> 6.315 + 6.316 + &interaction.backout.manual.merge; 6.317 + 6.318 + <para>Afterwards, the graphical history of our repository looks 6.319 + like figure 6.320 <xref linkend="fig:undo:backout-manual-merge"/>.</para> 6.321 6.322 <informalfigure id="fig:undo:backout-manual-merge"> 6.323 @@ -731,19 +789,26 @@ 6.324 6.325 <para>Now let's create a repository, so that we can try out the 6.326 <command role="hg-cmd">hg bisect</command> command in 6.327 - isolation. <!-- &interaction.bisect.init; --> We'll simulate a 6.328 - project that has a bug in it in a simple-minded way: create 6.329 - trivial changes in a loop, and nominate one specific change 6.330 - that will have the <quote>bug</quote>. This loop creates 35 6.331 - changesets, each adding a single file to the repository. 6.332 - We'll represent our <quote>bug</quote> with a file that 6.333 - contains the text <quote>i have a gub</quote>. <!-- 6.334 - &interaction.bisect.commits; --></para> 6.335 + isolation.</para> 6.336 + 6.337 + &interaction.bisect.init; 6.338 + 6.339 + <para>We'll simulate a project that has a bug in it in a 6.340 + simple-minded way: create trivial changes in a loop, and 6.341 + nominate one specific change that will have the 6.342 + <quote>bug</quote>. This loop creates 35 changesets, each 6.343 + adding a single file to the repository. We'll represent our 6.344 + <quote>bug</quote> with a file that contains the text <quote>i 6.345 + have a gub</quote>.</para> 6.346 + 6.347 + &interaction.bisect.commits; 6.348 6.349 <para>The next thing that we'd like to do is figure out how to 6.350 use the <command role="hg-cmd">hg bisect</command> command. 6.351 We can use Mercurial's normal built-in help mechanism for 6.352 - this. <!-- &interaction.bisect.help; --></para> 6.353 + this.</para> 6.354 + 6.355 + &interaction.bisect.help; 6.356 6.357 <para>The <command role="hg-cmd">hg bisect</command> command 6.358 works in steps. Each step proceeds as follows.</para> 6.359 @@ -771,8 +836,9 @@ 6.360 <quote>succeeding</quote> to <quote>failing</quote>.</para> 6.361 6.362 <para>To start the search, we must run the <command 6.363 - role="hg-cmd">hg bisect --reset</command> command. <!-- 6.364 - &interaction.bisect.search.init; --></para> 6.365 + role="hg-cmd">hg bisect --reset</command> command.</para> 6.366 + 6.367 + &interaction.bisect.search.init; 6.368 6.369 <para>In our case, the binary test we use is simple: we check to 6.370 see if any file in the repository contains the string <quote>i 6.371 @@ -785,8 +851,9 @@ 6.372 <para>Most of the time, the revision to which the working 6.373 directory is synced (usually the tip) already exhibits the 6.374 problem introduced by the buggy change, so we'll mark it as 6.375 - <quote>bad</quote>. <!-- &interaction.bisect.search.bad-init; 6.376 - --></para> 6.377 + <quote>bad</quote>.</para> 6.378 + 6.379 + &interaction.bisect.search.bad-init; 6.380 6.381 <para>Our next task is to nominate a changeset that we know 6.382 <emphasis>doesn't</emphasis> have the bug; the <command 6.383 @@ -794,8 +861,9 @@ 6.384 <quote>bracket</quote> its search between the first pair of 6.385 good and bad changesets. In our case, we know that revision 6.386 10 didn't have the bug. (I'll have more words about choosing 6.387 - the first <quote>good</quote> changeset later.) <!-- 6.388 - &interaction.bisect.search.good-init; --></para> 6.389 + the first <quote>good</quote> changeset later.)</para> 6.390 + 6.391 + &interaction.bisect.search.good-init; 6.392 6.393 <para>Notice that this command printed some output.</para> 6.394 <itemizedlist> 6.395 @@ -812,16 +880,21 @@ 6.396 <command>grep</command> command to see if our 6.397 <quote>bad</quote> file is present in the working directory. 6.398 If it is, this revision is bad; if not, this revision is good. 6.399 - <!-- &interaction.bisect.search.step1; --></para> 6.400 + &interaction.bisect.search.step1;</para> 6.401 6.402 <para>This test looks like a perfect candidate for automation, 6.403 - so let's turn it into a shell function. <!-- 6.404 - &interaction.bisect.search.mytest; --> We can now run an 6.405 - entire test step with a single command, 6.406 - <literal>mytest</literal>. <!-- 6.407 - &interaction.bisect.search.step2; --> A few more invocations 6.408 - of our canned test step command, and we're done. <!-- 6.409 - &interaction.bisect.search.rest; --></para> 6.410 + so let's turn it into a shell function.</para> 6.411 + &interaction.bisect.search.mytest; 6.412 + 6.413 + <para>We can now run an entire test step with a single command, 6.414 + <literal>mytest</literal>.</para> 6.415 + 6.416 + &interaction.bisect.search.step2; 6.417 + 6.418 + <para>A few more invocations of our canned test step command, 6.419 + and we're done.</para> 6.420 + 6.421 + &interaction.bisect.search.rest; 6.422 6.423 <para>Even though we had 40 changesets to search through, the 6.424 <command role="hg-cmd">hg bisect</command> command let us find 6.425 @@ -844,8 +917,9 @@ 6.426 forget to run this command. However, <command 6.427 role="hg-cmd">hg bisect</command> won't let you start a new 6.428 search in that repository until you do a <command 6.429 - role="hg-cmd">hg bisect reset</command>. <!-- 6.430 - &interaction.bisect.search.reset; --></para> 6.431 + role="hg-cmd">hg bisect reset</command>.</para> 6.432 + 6.433 + &interaction.bisect.search.reset; 6.434 6.435 </sect2> 6.436 </sect1>
7.1 --- a/en/ch10-hook.xml Mon Mar 09 22:55:38 2009 -0700 7.2 +++ b/en/ch10-hook.xml Mon Mar 09 23:22:09 2009 -0700 7.3 @@ -354,7 +354,7 @@ 7.4 7.5 <para>All hooks follow the pattern in this example.</para> 7.6 7.7 -<!-- &interaction.hook.simple.init; --> 7.8 +&interaction.hook.simple.init; 7.9 7.10 <para>You add an entry to the <literal 7.11 role="rc-hooks">hooks</literal> section of your <filename 7.12 @@ -371,7 +371,7 @@ 7.13 <para>Quite often, you will want to define more than one hook 7.14 for a particular kind of event, as shown below.</para> 7.15 7.16 -<!-- &interaction.hook.simple.ext; --> 7.17 +&interaction.hook.simple.ext; 7.18 7.19 <para>Mercurial lets you do this by adding an 7.20 <emphasis>extension</emphasis> to the end of a hook's name. 7.21 @@ -438,7 +438,7 @@ 7.22 <literal role="hook">commit</literal> hook is not run. 7.23 </para> 7.24 7.25 -<!-- &interaction.hook.simple.pretxncommit; --> 7.26 +&interaction.hook.simple.pretxncommit; 7.27 7.28 <para>The hook in the example above checks that a commit comment 7.29 contains a bug ID. If it does, the commit can complete. If 7.30 @@ -621,7 +621,7 @@ 7.31 changeset with a message that is less than ten bytes long. 7.32 </para> 7.33 7.34 -<!-- &interaction.hook.msglen.go; --> 7.35 +&interaction.hook.msglen.go; 7.36 7.37 </sect2> 7.38 <sect2> 7.39 @@ -665,7 +665,7 @@ 7.40 role="hg-cmd">hg commit</command> again. 7.41 </para> 7.42 7.43 -<!-- &interaction.hook.ws.simple; --> 7.44 +&interaction.hook.ws.simple; 7.45 7.46 <para>In this example, we introduce a simple <literal 7.47 role="hook">pretxncommit</literal> hook that checks for 7.48 @@ -690,7 +690,7 @@ 7.49 the saved commit message once you've corrected the problem. 7.50 </para> 7.51 7.52 -<!-- &interaction.hook.ws.better; --> 7.53 +&interaction.hook.ws.better; 7.54 7.55 <para>As a final aside, note in the example above the use of 7.56 <command>perl</command>'s in-place editing feature to get rid
8.1 --- a/en/ch11-template.xml Mon Mar 09 22:55:38 2009 -0700 8.2 +++ b/en/ch11-template.xml Mon Mar 09 23:22:09 2009 -0700 8.3 @@ -20,21 +20,21 @@ 8.4 <para>Before we take a look at Mercurial's bundled styles, let's 8.5 review its normal output.</para> 8.6 8.7 - <para><!-- &interaction.template.simple.normal; --></para> 8.8 + &interaction.template.simple.normal; 8.9 8.10 <para>This is somewhat informative, but it takes up a lot of 8.11 space&emdash;five lines of output per changeset. The 8.12 <literal>compact</literal> style reduces this to three lines, 8.13 presented in a sparse manner.</para> 8.14 8.15 - <para><!-- &interaction.template.simple.compact; --></para> 8.16 + &interaction.template.simple.compact; 8.17 8.18 <para>The <literal>changelog</literal> style hints at the 8.19 expressive power of Mercurial's templating engine. This style 8.20 attempts to follow the GNU Project's changelog 8.21 guidelines<citation>web:changelog</citation>.</para> 8.22 8.23 - <para><!-- &interaction.template.simple.changelog; --></para> 8.24 + &interaction.template.simple.changelog; 8.25 8.26 <para>You will not be shocked to learn that Mercurial's default 8.27 output style is named <literal>default</literal>.</para> 8.28 @@ -85,12 +85,12 @@ 8.29 <para>Before we continue, let's look again at a simple example of 8.30 Mercurial's normal output.</para> 8.31 8.32 - <para><!-- &interaction.template.simple.normal; --></para> 8.33 + &interaction.template.simple.normal; 8.34 8.35 <para>Now, let's run the same command, but using a template to 8.36 change its output.</para> 8.37 8.38 - <para><!-- &interaction.template.simple.simplest; --></para> 8.39 + &interaction.template.simple.simplest; 8.40 8.41 <para>The example above illustrates the simplest possible 8.42 template; it's just a piece of static text, printed once for 8.43 @@ -112,7 +112,7 @@ 8.44 isn't very useful; let's try something a bit more 8.45 complex.</para> 8.46 8.47 - <para><!-- &interaction.template.simple.simplesub; --></para> 8.48 + &interaction.template.simple.simplesub; 8.49 8.50 <para>As you can see, the string 8.51 <quote><literal>{desc}</literal></quote> in the template has 8.52 @@ -190,7 +190,7 @@ 8.53 <para>A few simple experiments will show us what to expect when we 8.54 use these keywords; you can see the results below.</para> 8.55 8.56 -<!-- &interaction.template.simple.keywords; --> 8.57 +&interaction.template.simple.keywords; 8.58 8.59 <para>As we noted above, the date keyword does not produce 8.60 human-readable output, so we must treat it specially. This 8.61 @@ -198,7 +198,7 @@ 8.62 in section <xref 8.63 linkend="sec:template:filter"/>.</para> 8.64 8.65 - <para><!-- &interaction.template.simple.datekeyword; --></para> 8.66 + &interaction.template.simple.datekeyword; 8.67 8.68 </sect1> 8.69 <sect1 id="sec:template:escape"> 8.70 @@ -410,7 +410,7 @@ 8.71 <quote><literal>bos</literal></quote>.</para> 8.72 </listitem></itemizedlist> 8.73 8.74 -<!-- &interaction.template.simple.manyfilters; --> 8.75 +&interaction.template.simple.manyfilters; 8.76 8.77 <note> 8.78 <para> If you try to apply a filter to a piece of data that it 8.79 @@ -431,7 +431,7 @@ 8.80 on Unix-like systems, where a tab is conventionally 8 8.81 characters wide).</para> 8.82 8.83 - <para><!-- &interaction.template.simple.combine; --></para> 8.84 + &interaction.template.simple.combine; 8.85 8.86 <para>Note the use of <quote><literal>\t</literal></quote> (a 8.87 tab character) in the template to force the first line to be 8.88 @@ -467,7 +467,7 @@ 8.89 8.90 <para>Our simple style file contains just one line:</para> 8.91 8.92 - <para><!-- &interaction.template.simple.rev; --></para> 8.93 + &interaction.template.simple.rev; 8.94 8.95 <para>This tells Mercurial, <quote>if you're printing a 8.96 changeset, use the text on the right as the 8.97 @@ -532,15 +532,14 @@ 8.98 working on, it prints a terse error message that, once you 8.99 figure out what it means, is actually quite useful.</para> 8.100 8.101 -<!-- &interaction.template.svnstyle.syntax.input; --> 8.102 +&interaction.template.svnstyle.syntax.input; 8.103 8.104 <para>Notice that <filename>broken.style</filename> attempts to 8.105 define a <literal>changeset</literal> keyword, but forgets to 8.106 give any content for it. When instructed to use this style 8.107 file, Mercurial promptly complains.</para> 8.108 8.109 - <para><!-- &interaction.template.svnstyle.syntax.error; 8.110 - --></para> 8.111 + &interaction.template.svnstyle.syntax.error; 8.112 8.113 <para>This error message looks intimidating, but it is not too 8.114 hard to follow.</para> 8.115 @@ -580,9 +579,12 @@ 8.116 <para>If you would like to be able to identify a Mercurial 8.117 repository <quote>fairly uniquely</quote> using a short string 8.118 as an identifier, you can use the first revision in the 8.119 - repository. <!-- &interaction.template.svnstyle.id; --> This 8.120 - is not guaranteed to be unique, but it is nevertheless useful 8.121 - in many cases.</para> 8.122 + repository.</para> 8.123 + 8.124 + &interaction.template.svnstyle.id; 8.125 + 8.126 + <para>This is not guaranteed to be unique, but it is 8.127 + nevertheless useful in many cases.</para> 8.128 <itemizedlist> 8.129 <listitem><para>It will not work in a completely empty 8.130 repository, because such a repository does not have a 8.131 @@ -611,14 +613,16 @@ 8.132 <title>Mimicking Subversion's output</title> 8.133 8.134 <para>Let's try to emulate the default output format used by 8.135 - another revision control tool, Subversion. <!-- 8.136 - &interaction.template.svnstyle.short; --></para> 8.137 + another revision control tool, Subversion.</para> 8.138 + 8.139 + &interaction.template.svnstyle.short; 8.140 8.141 <para>Since Subversion's output style is fairly simple, it is 8.142 easy to copy-and-paste a hunk of its output into a file, and 8.143 replace the text produced above by Subversion with the 8.144 - template values we'd like to see expanded. <!-- 8.145 - &interaction.template.svnstyle.template; --></para> 8.146 + template values we'd like to see expanded.</para> 8.147 + 8.148 + &interaction.template.svnstyle.template; 8.149 8.150 <para>There are a few small ways in which this template deviates 8.151 from the output produced by Subversion.</para> 8.152 @@ -648,8 +652,9 @@ 8.153 <para>It took me no more than a minute or two of work to replace 8.154 literal text from an example of Subversion's output with some 8.155 keywords and filters to give the template above. The style 8.156 - file simply refers to the template. <!-- 8.157 - &interaction.template.svnstyle.style; --></para> 8.158 + file simply refers to the template.</para> 8.159 + 8.160 + &interaction.template.svnstyle.style; 8.161 8.162 <para>We could have included the text of the template file 8.163 directly in the style file by enclosing it in quotes and
9.1 --- a/en/ch12-mq.xml Mon Mar 09 22:55:38 2009 -0700 9.2 +++ b/en/ch12-mq.xml Mon Mar 09 23:22:09 2009 -0700 9.3 @@ -196,7 +196,7 @@ 9.4 file. Take a look below for a simple example of these commands 9.5 in action.</para> 9.6 9.7 -<!-- &interaction.mq.dodiff.diff; --> 9.8 +&interaction.mq.dodiff.diff; 9.9 9.10 <para>The type of file that <command>diff</command> generates (and 9.11 <command>patch</command> takes as input) is called a 9.12 @@ -263,14 +263,14 @@ 9.13 the <command role="hg-ext-mq">qinit</command> command is now 9.14 available.</para> 9.15 9.16 -<!-- &interaction.mq.qinit-help.help; --> 9.17 +&interaction.mq.qinit-help.help; 9.18 9.19 <para>You can use MQ with <emphasis>any</emphasis> Mercurial 9.20 repository, and its commands only operate within that 9.21 repository. To get started, simply prepare the repository using 9.22 the <command role="hg-ext-mq">qinit</command> command.</para> 9.23 9.24 -<!-- &interaction.mq.tutorial.qinit; --> 9.25 +&interaction.mq.tutorial.qinit; 9.26 9.27 <para>This command creates an empty directory called <filename 9.28 role="special" class="directory">.hg/patches</filename>, where 9.29 @@ -290,7 +290,7 @@ 9.30 class="directory">.hg/patches</filename> directory, as you 9.31 can see below.</para> 9.32 9.33 -<!-- &interaction.mq.tutorial.qnew; --> 9.34 +&interaction.mq.tutorial.qnew; 9.35 9.36 <para>Also newly present in the <filename role="special" 9.37 class="directory">.hg/patches</filename> directory are two 9.38 @@ -327,7 +327,7 @@ 9.39 use the <command role="hg-ext-mq">qrefresh</command> command 9.40 to update the patch you are working on.</para> 9.41 9.42 -<!-- &interaction.mq.tutorial.qrefresh; --> 9.43 +&interaction.mq.tutorial.qrefresh; 9.44 9.45 <para>This command folds the changes you have made in the 9.46 working directory into your patch, and updates its 9.47 @@ -340,7 +340,7 @@ 9.48 doesn't work out, <command role="hg-cmd">hg revert</command> 9.49 your modifications back to the last time you refreshed.</para> 9.50 9.51 -<!-- &interaction.mq.tutorial.qrefresh2; --> 9.52 +&interaction.mq.tutorial.qrefresh2; 9.53 9.54 </sect2> 9.55 <sect2> 9.56 @@ -352,7 +352,7 @@ 9.57 new patch. Mercurial will apply this patch on top of your 9.58 existing patch.</para> 9.59 9.60 -<!-- &interaction.mq.tutorial.qnew2; --> 9.61 +&interaction.mq.tutorial.qnew2; 9.62 <para>Notice that the patch contains the changes in our prior 9.63 patch as part of its context (you can see this more clearly in 9.64 the output of <command role="hg-cmd">hg 9.65 @@ -365,7 +365,7 @@ 9.66 many commands that are easier to use when you are thinking 9.67 about patches, as illustrated below.</para> 9.68 9.69 -<!-- &interaction.mq.tutorial.qseries; --> 9.70 +&interaction.mq.tutorial.qseries; 9.71 9.72 <itemizedlist> 9.73 <listitem><para>The <command 9.74 @@ -417,7 +417,7 @@ 9.75 directory. See below for examples of <command 9.76 role="hg-ext-mq">qpop</command> and <command 9.77 role="hg-ext-mq">qpush</command> in action.</para> 9.78 -<!-- &interaction.mq.tutorial.qpop; --> 9.79 +&interaction.mq.tutorial.qpop; 9.80 9.81 <para>Notice that once we have popped a patch or two patches, 9.82 the output of <command role="hg-ext-mq">qseries</command> 9.83 @@ -442,7 +442,7 @@ 9.84 see section <xref linkend="sec:mq:perf"/> 9.85 below.)</para> 9.86 9.87 -<!-- &interaction.mq.tutorial.qpush-a; --> 9.88 +&interaction.mq.tutorial.qpush-a; 9.89 9.90 </sect2> 9.91 <sect2> 9.92 @@ -458,7 +458,7 @@ 9.93 case by the <command role="hg-cmd">hg add</command> of 9.94 <filename>file3</filename>.</para> 9.95 9.96 -<!-- &interaction.mq.tutorial.add; --> 9.97 +&interaction.mq.tutorial.add; 9.98 9.99 <para>Commands that check the working directory all take an 9.100 <quote>I know what I'm doing</quote> option, which is always 9.101 @@ -969,7 +969,7 @@ 9.102 few normal Mercurial commands in use with applied 9.103 patches.</para> 9.104 9.105 -<!-- &interaction.mq.id.output; --> 9.106 +&interaction.mq.id.output; 9.107 9.108 </sect1> 9.109 <sect1> 9.110 @@ -1126,7 +1126,7 @@ 9.111 prefixes of file names that inevitably confuse at least 9.112 me.)</para> 9.113 9.114 -<!-- &interaction.mq.tools.tools; --> 9.115 +&interaction.mq.tools.tools; 9.116 9.117 <para>The <literal role="package">patchutils</literal> package 9.118 <citation>web:patchutils</citation> is invaluable. It provides a 9.119 @@ -1196,16 +1196,22 @@ 9.120 changes to a source tarball that you downloaded.</para> 9.121 9.122 <para>Begin by downloading and unpacking the source tarball, and 9.123 - turning it into a Mercurial repository. <!-- 9.124 - &interaction.mq.tarball.download; --></para> 9.125 + turning it into a Mercurial repository.</para> 9.126 + 9.127 + &interaction.mq.tarball.download; 9.128 9.129 <para>Continue by creating a patch stack and making your 9.130 - changes. <!-- &interaction.mq.tarball.qinit; --></para> 9.131 + changes.</para> 9.132 + 9.133 + &interaction.mq.tarball.qinit; 9.134 9.135 <para>Let's say a few weeks or months pass, and your package 9.136 author releases a new version. First, bring their changes 9.137 - into the repository. <!-- &interaction.mq.tarball.newsource; 9.138 - --> The pipeline starting with <command role="hg-cmd">hg 9.139 + into the repository.</para> 9.140 + 9.141 + &interaction.mq.tarball.newsource; 9.142 + 9.143 + <para>The pipeline starting with <command role="hg-cmd">hg 9.144 locate</command> above deletes all files in the working 9.145 directory, so that <command role="hg-cmd">hg 9.146 commit</command>'s <option 9.147 @@ -1214,7 +1220,9 @@ 9.148 newer version of the source.</para> 9.149 9.150 <para>Finally, you can apply your patches on top of the new 9.151 - tree. <!-- &interaction.mq.tarball.repush; --></para> 9.152 + tree.</para> 9.153 + 9.154 + &interaction.mq.tarball.repush; 9.155 9.156 </sect2> 9.157 <sect2 id="sec:mq:combine"> 9.158 @@ -1262,7 +1270,9 @@ 9.159 file, and you only want to move a few of those hunks, the job 9.160 becomes more messy, but you can still partly automate it. Use 9.161 <command>lsdiff -nvv</command> to print some metadata about 9.162 - the patch. <!-- &interaction.mq.tools.lsdiff; --></para> 9.163 + the patch.</para> 9.164 + 9.165 + &interaction.mq.tools.lsdiff; 9.166 9.167 <para>This command prints three different kinds of 9.168 number:</para>
10.1 --- a/en/ch13-mq-collab.xml Mon Mar 09 22:55:38 2009 -0700 10.2 +++ b/en/ch13-mq-collab.xml Mon Mar 09 23:22:09 2009 -0700 10.3 @@ -108,10 +108,13 @@ 10.4 situation. MQ provides a feature called <quote>guards</quote> 10.5 (which originates with quilt's <literal>guards</literal> 10.6 command) that does just this. To start off, let's create a 10.7 - simple repository for experimenting in. <!-- 10.8 - &interaction.mq.guards.init; --> This gives us a tiny repository 10.9 - that contains two patches that don't have any dependencies on 10.10 - each other, because they touch different files.</para> 10.11 + simple repository for experimenting in.</para> 10.12 + 10.13 + &interaction.mq.guards.init; 10.14 + 10.15 + <para>This gives us a tiny repository that contains two patches 10.16 + that don't have any dependencies on each other, because they 10.17 + touch different files.</para> 10.18 10.19 <para>The idea behind conditional application is that you can 10.20 <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, 10.21 @@ -133,14 +136,20 @@ 10.22 <para>The <command role="hg-ext-mq">qguard</command> command lets 10.23 you determine which guards should apply to a patch, or display 10.24 the guards that are already in effect. Without any arguments, it 10.25 - displays the guards on the current topmost patch. <!-- 10.26 - &interaction.mq.guards.qguard; --> To set a positive guard on a 10.27 - patch, prefix the name of the guard with a 10.28 - <quote><literal>+</literal></quote>. <!-- 10.29 - &interaction.mq.guards.qguard.pos; --> To set a negative guard 10.30 + displays the guards on the current topmost patch.</para> 10.31 + 10.32 + &interaction.mq.guards.qguard; 10.33 + 10.34 + <para>To set a positive guard on a patch, prefix the name of the 10.35 + guard with a <quote><literal>+</literal></quote>.</para> 10.36 + 10.37 + &interaction.mq.guards.qguard.pos; 10.38 + 10.39 + <para>To set a negative guard 10.40 on a patch, prefix the name of the guard with a 10.41 - <quote><literal>-</literal></quote>. <!-- 10.42 - &interaction.mq.guards.qguard.neg; --></para> 10.43 + <quote><literal>-</literal></quote>.</para> 10.44 + 10.45 + &interaction.mq.guards.qguard.neg; 10.46 10.47 <note> 10.48 <para> The <command role="hg-ext-mq">qguard</command> command 10.49 @@ -158,8 +167,9 @@ 10.50 other words, you don't have to use the <command 10.51 role="hg-ext-mq">qguard</command> command if you don't want 10.52 to; it's okay to simply edit the <filename 10.53 - role="special">series</filename> file.) <!-- 10.54 - &interaction.mq.guards.series; --></para> 10.55 + role="special">series</filename> file.)</para> 10.56 + 10.57 + &interaction.mq.guards.series; 10.58 10.59 </sect1> 10.60 <sect1> 10.61 @@ -175,26 +185,38 @@ 10.62 <para>With no arguments, the <command 10.63 role="hg-ext-mq">qselect</command> command lists the guards 10.64 currently in effect, one per line of output. Each argument is 10.65 - treated as the name of a guard to apply. <!-- 10.66 - &interaction.mq.guards.qselect.foo; --> In case you're 10.67 - interested, the currently selected guards are stored in the 10.68 - <filename role="special">guards</filename> file. <!-- 10.69 - &interaction.mq.guards.qselect.cat; --> We can see the effect 10.70 - the selected guards have when we run <command 10.71 - role="hg-ext-mq">qpush</command>. <!-- 10.72 - &interaction.mq.guards.qselect.qpush; --></para> 10.73 + treated as the name of a guard to apply.</para> 10.74 + 10.75 + &interaction.mq.guards.qselect.foo; 10.76 + 10.77 + <para>In case you're interested, the currently selected guards are 10.78 + stored in the <filename role="special">guards</filename> file.</para> 10.79 + 10.80 + &interaction.mq.guards.qselect.cat; 10.81 + 10.82 + <para>We can see the effect the selected guards have when we run 10.83 + <command role="hg-ext-mq">qpush</command>.</para> 10.84 + 10.85 + &interaction.mq.guards.qselect.qpush; 10.86 10.87 <para>A guard cannot start with a 10.88 <quote><literal>+</literal></quote> or 10.89 <quote><literal>-</literal></quote> character. The name of a 10.90 guard must not contain white space, but most other characters 10.91 are acceptable. If you try to use a guard with an invalid name, 10.92 - MQ will complain: <!-- &interaction.mq.guards.qselect.error; --> 10.93 - Changing the selected guards changes the patches that are 10.94 - applied. <!-- &interaction.mq.guards.qselect.quux; --> You can 10.95 - see in the example below that negative guards take precedence 10.96 - over positive guards. <!-- 10.97 - &interaction.mq.guards.qselect.foobar; --></para> 10.98 + MQ will complain:</para> 10.99 + 10.100 + &interaction.mq.guards.qselect.error; 10.101 + 10.102 + <para>Changing the selected guards changes the patches that are 10.103 + applied.</para> 10.104 + 10.105 + &interaction.mq.guards.qselect.quux; 10.106 + 10.107 + <para>You can see in the example below that negative guards take 10.108 + precedence over positive guards.</para> 10.109 + 10.110 + &interaction.mq.guards.qselect.foobar; 10.111 10.112 </sect1> 10.113 <sect1>
11.1 --- a/en/ch14-hgext.xml Mon Mar 09 22:55:38 2009 -0700 11.2 +++ b/en/ch14-hgext.xml Mon Mar 09 23:22:09 2009 -0700 11.3 @@ -267,11 +267,14 @@ 11.4 role="hg-ext">extdiff</literal> extension</title> 11.5 11.6 <para>Mercurial's built-in <command role="hg-cmd">hg 11.7 - diff</command> command outputs plaintext unified diffs. <!-- 11.8 - &interaction.extdiff.diff; --> If you would like to use an 11.9 - external tool to display modifications, you'll want to use the 11.10 - <literal role="hg-ext">extdiff</literal> extension. This will 11.11 - let you use, for example, a graphical diff tool.</para> 11.12 + diff</command> command outputs plaintext unified diffs.</para> 11.13 + 11.14 + &interaction.extdiff.diff; 11.15 + 11.16 + <para>If you would like to use an external tool to display 11.17 + modifications, you'll want to use the <literal 11.18 + role="hg-ext">extdiff</literal> extension. This will let you 11.19 + use, for example, a graphical diff tool.</para> 11.20 11.21 <para>The <literal role="hg-ext">extdiff</literal> extension is 11.22 bundled with Mercurial, so it's easy to set up. In the <literal 11.23 @@ -283,12 +286,14 @@ 11.24 role="hg-ext-extdiff">extdiff</command>, which by default uses 11.25 your system's <command>diff</command> command to generate a 11.26 unified diff in the same form as the built-in <command 11.27 - role="hg-cmd">hg diff</command> command. <!-- 11.28 - &interaction.extdiff.extdiff; --> The result won't be exactly 11.29 - the same as with the built-in <command role="hg-cmd">hg 11.30 - diff</command> variations, because the output of 11.31 - <command>diff</command> varies from one system to another, even 11.32 - when passed the same options.</para> 11.33 + role="hg-cmd">hg diff</command> command.</para> 11.34 + 11.35 + &interaction.extdiff.extdiff; 11.36 + 11.37 + <para>The result won't be exactly the same as with the built-in 11.38 + <command role="hg-cmd">hg diff</command> variations, because the 11.39 + output of <command>diff</command> varies from one system to 11.40 + another, even when passed the same options.</para> 11.41 11.42 <para>As the <quote><literal>making snapshot</literal></quote> 11.43 lines of output above imply, the <command 11.44 @@ -341,8 +346,9 @@ 11.45 diffs (using the <option role="cmd-opt-diff">-c</option> option) 11.46 instead of unified diffs, and five lines of context instead of 11.47 the default three (passing <literal>5</literal> as the argument 11.48 - to the <option role="cmd-opt-diff">-C</option> option). <!-- 11.49 - &interaction.extdiff.extdiff-ctx; --></para> 11.50 + to the <option role="cmd-opt-diff">-C</option> option).</para> 11.51 + 11.52 + &interaction.extdiff.extdiff-ctx; 11.53 11.54 <para>Launching a visual diff tool is just as easy. Here's how to 11.55 launch the <command>kdiff3</command> viewer.</para>