Commits

Raphael Das Gupta  committed 743dc55 Merge

Merged upstream

  • Participants
  • Parent commits 8354057, 29f0f79

Comments (0)

Files changed (7)

File en/ch01-tour-basic.xml

 
       &interaction.tour.clone;
 
-      <para>One advantage of using <command role="hg-cmd">hg
+      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
 	  clone</command> is that, as we can see above, it lets us clone
 	repositories over the network.  Another is that it remembers
 	where we cloned from, which we'll find useful soon when we
 	  the text message that the creator of the changeset entered
 	  to describe the changeset.</para></listitem>
       <listitem>
-	<para>Some changesets, such as the first in the list above,
+	<para id="x_67d">Some changesets, such as the first in the list above,
 	  have a <literal>tag</literal> field.  A tag is another way
 	  to identify a changeset, by giving it an easy-to-remember
 	  name. (The tag named <literal>tip</literal> is special: it
 
       &interaction.tour.log-vp;
 
-      <para>The <option role="hg-opt-log">-p</option> option is
+      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
 	tremendously useful, so it's well worth remembering.</para>
 
     </sect2>
 	    role="hg-opt-log">--rev</option> arguments.</para>
       </listitem>
       <listitem>
-	<para>If you are using short options, you can save typing by
+	<para id="x_67f">If you are using short options, you can save typing by
 	  running them together. For example, the command <command
 	    role="hg-cmd">hg log -v -p -r 2</command> can be written
 	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
     <note>
       <title>Option naming consistency</title>
 
-      <para>Almost always, Mercurial commands use consistent option
+      <para id="x_680">Almost always, Mercurial commands use consistent option
 	names to refer to the same concepts.  For instance, if a
 	command deals with changesets, you'll always identify them
 	with <option role="hg-opt-log">--rev</option> or <option
       locally, we can just clone that instead.  This is much faster
       than cloning over the network, and cloning a local repository
       uses less disk space in most cases, too<footnote>
-	<para>The saving of space arises when source and destination
+	<para id="x_681">The saving of space arises when source and destination
 	  repositories are on the same filesystem, in which case
 	  Mercurial will use hardlinks to do copy-on-write sharing of
 	  its internal metadata.  If that explanation meant nothing to
 
     &interaction.tour.cat1;
 
-    <para>Let's edit this file so that it prints a second line of
+    <para id="x_682">Let's edit this file so that it prints a second line of
       output.</para>
 
     &interaction.tour.cat2;
     <tip>
       <title>Understanding patches</title>
 
-      <para>Remember to take a look at <xref
+      <para id="x_683">Remember to take a look at <xref
 	  linkend="sec:mq:patch"/> if you don't know how to read
 	output above.</para>
     </tip>
 	repository as the <emphasis>tip revision</emphasis>, or simply
 	the <emphasis>tip</emphasis>.</para>
 
-      <para>By the way, the <command role="hg-cmd">hg tip</command>
+      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
 	command accepts many of the same options as <command
 	  role="hg-cmd">hg log</command>, so <option
 	  role="hg-opt-global">-v</option> above indicates <quote>be

File en/ch02-tour-merge.xml

 	</mediaobject>
       </figure>
 
-      <para>We sometimes talk about a merge having
+      <para id="x_69c">We sometimes talk about a merge having
 	<emphasis>sides</emphasis>: the left side is the first parent
 	in the output of <command role="hg-cmd">hg parents</command>,
 	and the right side is the second.  If the working directory

File en/ch03-concepts.xml

     <sect2>
       <title>Merging and renames</title>
 
-      <para>A surprising number of revision control systems pay little
+      <para id="x_69a">A surprising number of revision control systems pay little
 	or no attention to a file's <emphasis>name</emphasis> over
 	time.  For instance, it used to be common that if a file got
 	renamed on one side of a merge, the changes from the other
 	side would be silently dropped.</para>
 
-      <para>Mercurial records metadata when you tell it to perform a
+      <para id="x_69b">Mercurial records metadata when you tell it to perform a
 	rename or copy. It uses this metadata during a merge to do the
 	right thing in the case of a merge.  For instance, if I rename
 	a file, and you edit it without renaming it, when we merge our

File en/ch04-daily.xml

 	<emphasis>destination</emphasis>, and all others are
 	<emphasis>sources</emphasis>.</para>
 
-      <para>If you pass <command role="hg-cmd">hg copy</command> a
+      <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a
 	single file as the source, and the destination does not exist,
 	it creates a new file with that name.</para>
 
       similar to the <command role="hg-cmd">hg copy</command>
       command.</para>
 
-    <para>If you're familiar with the Unix command line, you'll be
+    <para id="x_686">If you're familiar with the Unix command line, you'll be
       glad to know that <command role="hg-cmd">hg rename</command>
       command can be invoked as <command role="hg-cmd">hg
 	mv</command>.</para>
   <sect1>
     <title>Dealing with tricky merges</title>
 
-    <para>In a complicated or large project, it's not unusual for a
+    <para id="x_687">In a complicated or large project, it's not unusual for a
       merge of two changesets to result in some headaches.  Suppose
       there's a big source file that's been extensively edited by each
       side of a merge: this is almost inevitably going to result in
       conflicts, some of which can take a few tries to sort
       out.</para>
 
-    <para>Let's develop a simple case of this and see how to deal with
+    <para id="x_688">Let's develop a simple case of this and see how to deal with
       it.  We'll start off with a repository containing one file, and
       clone it twice.</para>
 
     &interaction.ch04-resolve.init;
 
-    <para>In one clone, we'll modify the file in one way.</para>
+    <para id="x_689">In one clone, we'll modify the file in one way.</para>
 
     &interaction.ch04-resolve.left;
 
-    <para>In another, we'll modify the file differently.</para>
+    <para id="x_68a">In another, we'll modify the file differently.</para>
 
     &interaction.ch04-resolve.right;
 
-    <para>Next, we'll pull each set of changes into our original
+    <para id="x_68b">Next, we'll pull each set of changes into our original
       repo.</para>
 
     &interaction.ch04-resolve.pull;
 
-    <para>We expect our repository to now contain two heads.</para>
+    <para id="x_68c">We expect our repository to now contain two heads.</para>
 
     &interaction.ch04-resolve.heads;
 
-    <para>Normally, if we run <command role="hg-cmd">hg
+    <para id="x_68d">Normally, if we run <command role="hg-cmd">hg
 	merge</command> at this point, it will drop us into a GUI that
       will let us manually resolve the conflicting edits to
       <filename>myfile.txt</filename>.  However, to simplify things
 
     &interaction.ch04-resolve.export;
 
-    <para>We've told Mercurial's merge machinery to run the command
+    <para id="x_68e">We've told Mercurial's merge machinery to run the command
       <command>false</command> (which, as we desire, fails
       immediately) if it detects a merge that it can't sort out
       automatically.</para>
 
-    <para>If we now fire up <command role="hg-cmd">hg
+    <para id="x_68f">If we now fire up <command role="hg-cmd">hg
 	merge</command>, it should grind to a halt and report a
 	failure.</para>
 
     &interaction.ch04-resolve.merge;
 
-    <para>Even if we don't notice that the merge failed, Mercurial
+    <para id="x_690">Even if we don't notice that the merge failed, Mercurial
       will prevent us from accidentally committing the result of a
       failed merge.</para>
 
     &interaction.ch04-resolve.cifail;
 
-    <para>When <command role="hg-cmd">hg commit</command> fails in
+    <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in
       this case, it suggests that we use the unfamiliar <command
 	role="hg-cmd">hg resolve</command> command.  As usual,
 	<command role="hg-cmd">hg help resolve</command> will print a
     <sect2>
       <title>File resolution states</title>
 
-      <para>When a merge occurs, most files will usually remain
+      <para id="x_692">When a merge occurs, most files will usually remain
 	unmodified.  For each file where Mercurial has to do
 	something, it tracks the state of the file.</para>
 
       <itemizedlist>
 	<listitem>
-	  <para>A <emphasis>resolved</emphasis> file has been
+	  <para id="x_693">A <emphasis>resolved</emphasis> file has been
 	    successfully merged, either automatically by Mercurial or
 	    manually with human intervention.</para>
 	</listitem>
 	<listitem>
-	  <para>An <emphasis>unresolved</emphasis> file was not merged
+	  <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged
 	    successfully, and needs more attention.</para>
 	</listitem>
       </itemizedlist>
 
-      <para>If Mercurial sees <emphasis>any</emphasis> file in the
+      <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the
 	unresolved state after a merge, it considers the merge to have
 	failed.  Fortunately, we do not need to restart the entire
 	merge from scratch.</para>
 
-      <para>The <option role="hg-opt-resolve">--list</option> or
+      <para id="x_696">The <option role="hg-opt-resolve">--list</option> or
 	<option role="hg-opt-resolve">-l</option> option to <command
 	  role="hg-cmd">hg resolve</command> prints out the state of
 	each merged file.</para>
 
       &interaction.ch04-resolve.list;
 
-      <para>In the output from <command role="hg-cmd">hg
+      <para id="x_697">In the output from <command role="hg-cmd">hg
 	  resolve</command>, a resolved file is marked with
 	<literal>R</literal>, while an unresolved file is marked with
 	<literal>U</literal>.  If any files are listed with
     <sect2>
       <title>Resolving a file merge</title>
 
-      <para>We have several options to move a file from the unresolved
+      <para id="x_698">We have several options to move a file from the unresolved
 	into the resolved state.  By far the most common is to rerun
 	<command role="hg-cmd">hg resolve</command>.  If we pass the
 	names of individual files or directories, it will retry the
 	will retry the merges of <emphasis>all</emphasis> unresolved
 	files.</para>
 
-      <para>Mercurial also lets us modify the resolution state of a
+      <para id="x_699">Mercurial also lets us modify the resolution state of a
 	file directly.  We can manually mark a file as resolved using
 	the <option role="hg-opt-resolve">--mark</option> option, or
 	as unresolved using the <option

File en/ch05-collab.xml

     <para id="x_44c">For interactive use, the web interface lets you browse a
       single repository or a collection of repositories.  You can view
       the history of a repository, examine each change (comments and
-      diffs), and view the contents of each directory and file.</para>
+      diffs), and view the contents of each directory and file.  You
+      can even get a view of history that gives a graphical view of
+      the relationships between individual changes and merges.</para>
 
-    <para id="x_44d">Also for human consumption, the web interface provides an
-      RSS feed of the changes in a repository.  This lets you
+    <para id="x_44d">Also for human consumption, the web interface provides
+      Atom and RSS feeds of the changes in a repository.  This lets you
       <quote>subscribe</quote> to a repository using your favorite
       feed reader, and be automatically notified of activity in that
       repository as soon as it happens.  I find this capability much
     <para id="x_44f">The easiest way to get started with the web interface is to
       use your web browser to visit an existing repository, such as
       the master Mercurial repository at <ulink
-	url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
+	url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
 
     <para id="x_450">If you're interested in providing a web interface
-      to your own repositories, Mercurial provides two ways to do
-      this.  The first is using the <command role="hg-cmd">hg
+      to your own repositories, there are several good ways to do
+      this.</para>
+
+    <para id="x_69d">The easiest and fastest way to get started in an informal
+      environment is to use the <command role="hg-cmd">hg
 	serve</command> command, which is best suited to short-term
       <quote>lightweight</quote> serving.  See <xref
 	linkend="sec:collab:serve"/> below for details of how to use
-      this command.  If you have a long-lived repository that you'd
-      like to make permanently available, Mercurial has built-in
-      support for the CGI (Common Gateway Interface) standard, which
-      all common web servers support.  See <xref
-	linkend="sec:collab:cgi"/> for details of CGI
+      this command.</para>
+
+    <para id="x_69e">For longer-lived repositories that you'd like to have
+      permanently available, there are several public hosting services
+      available.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para id="x_69f">Bitbucket, at <ulink
+	    url="http://bitbucket.org/">http://bitbucket.org/</ulink>,
+	  provides free hosting for open source projects, and paid
+	  hosting for commercial projects.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
+      has built-in support for several popular hosting technologies,
+      most notably CGI (Common Gateway Interface), and WSGI (Web
+      Services Gateway Interface).  See <xref
+	linkend="sec:collab:cgi"/> for details of CGI and WSGI
       configuration.</para>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Collaboration models</title>
 
 	could avoid this particular problem by writing a hook that
 	prevents changes from being merged from an inappropriate
 	branch.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Informal anarchy</title>
 
 	place) and spend several days more or less locked in there,
 	hacking intensely on a handful of projects.</para>
 
-      <para id="x_457">A sprint is the perfect place to use the
+      <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
 	<command role="hg-cmd">hg serve</command> command, since
 	<command role="hg-cmd">hg serve</command> does not require any
 	fancy server infrastructure.  You can get started with
 	they can clone a branch containing a new feature and try it
 	out.</para>
 
-      <para id="x_458">The charm, and the problem, with doing things in an ad hoc
-	fashion like this is that only people who know about your
-	changes, and where they are, can see them.  Such an informal
-	approach simply doesn't scale beyond a handful people, because
-	each individual needs to know about $n$ different repositories
-	to pull from.</para>
+      <para id="x_458">The charm, and the problem, with doing things
+	in an ad hoc fashion like this is that only people who know
+	about your changes, and where they are, can see them.  Such an
+	informal approach simply doesn't scale beyond a handful
+	people, because each individual needs to know about
+	<emphasis>n</emphasis> different repositories to pull
+	from.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>A single central repository</title>
 
 	lets us put off publishing the potentially unsafe change until
 	it has had a little testing.</para>
 
-      <para id="x_45c">In this kind of scenario, people usually use
-	the <command>ssh</command> protocol to securely push changes
-	to the central repository, as documented in <xref
+      <para id="x_45c">If a team is hosting its own repository in this
+	kind of scenario, people will usually use the
+	<command>ssh</command> protocol to securely push changes to
+	the central repository, as documented in <xref
 	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
-	read-only copy of the repository over HTTP using CGI, as in
-	<xref linkend="sec:collab:cgi"/>. Publishing
-	over HTTP satisfies the needs of people who don't have push
-	access, and those who want to use web browsers to browse the
-	repository's history.</para>
+	read-only copy of the repository over HTTP, as in
+	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
+	satisfies the needs of people who don't have push access, and
+	those who want to use web browsers to browse the repository's
+	history.</para>
+    </sect2>
 
+    <sect2>
+      <title>A hosted central repository</title>
+
+      <para id="x_6a1">A wonderful thing about public hosting services like
+	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
+	not only do they handle the fiddly server configuration
+	details, such as user accounts, authentication, and secure
+	wire protocols, they provide additional infrastructure to make
+	this model work well.</para>
+
+      <para id="x_6a2">For instance, a well-engineered hosting service will let
+	people clone their own copies of a repository with a single
+	click.  This lets people work in separate spaces and share
+	their changes when they're ready.</para>
+
+      <para id="x_6a3">In addition, a good hosting service will let people
+	communicate with each other, for instance to say <quote>there
+	  are changes ready for you to review in this
+	  tree</quote>.</para>
     </sect2>
+
     <sect2>
       <title>Working with multiple branches</title>
 
 	another as the need arises.  Because repositories are
 	independent of each other, unstable changes in a development
 	branch will never affect a stable branch unless someone
-	explicitly merges those changes in.</para>
+	explicitly merges those changes into the stable branch.</para>
 
       <para id="x_45f">Here's an example of how this can work in practice.  Let's
 	say you have one <quote>main branch</quote> on a central
       &interaction.branching.update;
 
       <para id="x_464">In addition, immediately after the main branch is tagged,
-	someone can then clone the main branch on the server to a new
+	we can then clone the main branch on the server to a new
 	<quote>stable</quote> branch, also on the server.</para>
 
       &interaction.branching.clone;
 
-      <para id="x_465">Someone who needs to make a change to the stable branch
-	can then clone <emphasis>that</emphasis> repository, make
-	their changes, commit, and push their changes back there.</para>
+      <para id="x_465">If we need to make a change to the stable
+	branch, we can then clone <emphasis>that</emphasis>
+	repository, make our changes, commit, and push our changes
+	back there.</para>
 
       &interaction.branching.stable;
 
       <para id="x_466">Because Mercurial repositories are independent, and
 	Mercurial doesn't move changes around automatically, the
 	stable and main branches are <emphasis>isolated</emphasis>
-	from each other.  The changes that you made on the main branch
+	from each other.  The changes that we made on the main branch
 	don't <quote>leak</quote> to the stable branch, and vice
 	versa.</para>
 
-      <para id="x_467">You'll often want all of your bugfixes on the stable
+      <para id="x_467">We'll often want all of our bugfixes on the stable
 	branch to show up on the main branch, too.  Rather than
-	rewrite a bugfix on the main branch, you can simply pull and
+	rewrite a bugfix on the main branch, we can simply pull and
 	merge changes from the stable to the main branch, and
-	Mercurial will bring those bugfixes in for you.</para>
+	Mercurial will bring those bugfixes in for us.</para>
 
-	&interaction.branching.merge;
+      &interaction.branching.merge;
 
-      <para id="x_468">The main branch will still contain changes that are not on
-	the stable branch, but it will also contain all of the
-	bugfixes from the stable branch.  The stable branch remains
-	unaffected by these changes.</para>
+      <para id="x_468">The main branch will still contain changes that
+	are not on the stable branch, but it will also contain all of
+	the bugfixes from the stable branch.  The stable branch
+	remains unaffected by these changes, since changes are only
+	flowing from the stable to the main branch, and not the other
+	way.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Feature branches</title>
 
 	shape, someone on that feature team pulls and merges from the
 	master branch into the feature branch, then pushes back up to
 	the master branch.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>The release train</title>
 
 	went out on that train release into the feature branch, and
 	the team continues its work on top of that release so that
 	their feature can make the next release.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>The Linux kernel model</title>
 
 	it appropriate; and the pace of development is astounding.
 	And yet Linux is a highly successful, well-regarded piece of
 	software.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Pull-only versus shared-push collaboration</title>
 
 	you'll have to roll your own approach on top (such as applying
 	a patch by hand).</para>
 
-      <para id="x_478">A good distributed revision control tool, such as
-	Mercurial, will support both models.  You and your
-	collaborators can then structure how you work together based
-	on your own needs and preferences, not on what contortions
-	your tools force you into.</para>
-
+      <para id="x_478">A good distributed revision control tool will
+	support both models.  You and your collaborators can then
+	structure how you work together based on your own needs and
+	preferences, not on what contortions your tools force you
+	into.</para>
     </sect2>
     <sect2>
       <title>Where collaboration meets branch management</title>
 	Even though this subject is intimately related to how your
 	team collaborates, it's dense enough to merit treatment of its
 	own, in <xref linkend="chap:branch"/>.</para>
-
     </sect2>
   </sect1>
+
   <sect1>
     <title>The technical side of sharing</title>
 
     <para id="x_47a">The remainder of this chapter is devoted to the question of
-      serving data to your collaborators.</para>
+      sharing changes with your collaborators.</para>
+  </sect1>
 
-  </sect1>
   <sect1 id="sec:collab:serve">
     <title>Informal sharing with <command role="hg-cmd">hg
 	serve</command></title>
 	find out what URL you should send to your collaborators, start
 	it with the <option role="hg-opt-global">-v</option>
 	option.</para>
-
     </sect2>
   </sect1>
+
   <sect1 id="sec:collab:ssh">
     <title>Using the Secure Shell (ssh) protocol</title>
 
       protocol.  To use this successfully, you may have to do a little
       bit of configuration on the client or server sides.</para>
 
-    <para id="x_487">If you're not familiar with ssh, it's a network protocol
-      that lets you securely communicate with another computer.  To
-      use it with Mercurial, you'll be setting up one or more user
-      accounts on a server so that remote users can log in and execute
-      commands.</para>
+    <para id="x_487">If you're not familiar with ssh, it's the name of
+      both a command and a network protocol that let you securely
+      communicate with another computer.  To use it with Mercurial,
+      you'll be setting up one or more user accounts on a server so
+      that remote users can log in and execute commands.</para>
 
     <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
       probably find some of the material that follows to be elementary
 	<emphasis>absolute</emphasis> path on the server, begin the
 	path component with two slashes, as in this example.</para>
       <programlisting>ssh://server//absolute/path</programlisting>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Finding an ssh client for your system</title>
 
 	unlikely event that it isn't present, take a look at your
 	system documentation to figure out how to install it.</para>
 
-      <para id="x_494">On Windows, you'll first need to download a suitable ssh
-	client.  There are two alternatives.</para>
-      <itemizedlist>
-	<listitem><para id="x_495">Simon Tatham's excellent PuTTY package
-	    <citation>web:putty</citation> provides a complete suite
-	    of ssh client commands.</para>
-	</listitem>
-	<listitem><para id="x_496">If you have a high tolerance for pain, you can
-	    use the Cygwin port of OpenSSH.</para>
-	</listitem></itemizedlist>
-      <para id="x_497">In either case, you'll need to edit your <filename
-      role="special">hg.ini</filename> file to
-	tell Mercurial where to find the actual client command.  For
-	example, if you're using PuTTY, you'll need to use the
-	<command>plink</command> command as a command-line ssh
-	client.</para>
-      <programlisting>[ui]
-ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"</programlisting>
+      <para id="x_494">On Windows, the TortoiseHg package is bundled
+	with a version of Simon Tatham's excellent
+	<command>plink</command> command, and you should not need to
+	do any further configuration.</para>
+    </sect2>
 
-      <note>
-	<para id="x_498">  The path to <command>plink</command> shouldn't contain
-	  any whitespace characters, or Mercurial may not be able to
-	  run it correctly (so putting it in <filename
-	    class="directory">C:\Program Files</filename> is probably
-	  not a good idea).</para>
-      </note>
-
-    </sect2>
     <sect2>
       <title>Generating a key pair</title>
 
-      <para id="x_499">To avoid the need to repetitively type a password every
-	time you need to use your ssh client, I recommend generating a
-	key pair.  On a Unix-like system, the
-	<command>ssh-keygen</command> command will do the trick. On
-	Windows, if you're using PuTTY, the
-	<command>puttygen</command> command is what you'll
-	need.</para>
+      <para id="x_499">To avoid the need to repetitively type a
+	password every time you need to use your ssh client, I
+	recommend generating a key pair.</para>
+
+      <tip>
+	<title>Key pairs are not mandatory</title>
+
+	<para id="x_6a4">Mercurial knows nothing about ssh authentication or key
+	  pairs.  You can, if you like, safely ignore this section and
+	  the one that follows until you grow tired of repeatedly
+	  typing ssh passwords.</para>
+      </tip>
+
+      <itemizedlist>
+	<listitem>
+	  <para id="x_6a5">On a Unix-like system, the
+	    <command>ssh-keygen</command> command will do the
+	    trick.</para>
+	  <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
+	    to download a command named <command>puttygen</command>
+	    from <ulink
+	      url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
+	      PuTTY web site</ulink> to generate a key pair.  See
+	    <ulink
+	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 
+	      <command>puttygen</command> documentation</ulink> for
+	    details of how use the command.</para>
+	</listitem>
+      </itemizedlist>
 
       <para id="x_49a">When you generate a key pair, it's usually
 	<emphasis>highly</emphasis> advisable to protect it with a
 	public key to a file of your choosing, or paste it from the
 	window it's displayed in straight into the <filename
 	  role="special">authorized_keys</filename> file.</para>
-
     </sect2>
     <sect2>
       <title>Using an authentication agent</title>
 	judgment as to whether this is an acceptable risk.  It
 	certainly saves a lot of repeated typing.</para>
 
-      <para id="x_49f">On Unix-like systems, the agent is called
-	<command>ssh-agent</command>, and it's often run automatically
-	for you when you log in.  You'll need to use the
-	<command>ssh-add</command> command to add passphrases to the
-	agent's store.  On Windows, if you're using PuTTY, the
-	<command>pageant</command> command acts as the agent.  It adds
-	an icon to your system tray that will let you manage stored
-	passphrases.</para>
+      <itemizedlist>
+	<listitem>
+	  <para id="x_49f">On Unix-like systems, the agent is called
+	    <command>ssh-agent</command>, and it's often run
+	    automatically for you when you log in.  You'll need to use
+	    the <command>ssh-add</command> command to add passphrases
+	    to the agent's store.</para>
+	</listitem>
+	<listitem>
+	  <para id="x_6a7">On Windows, if you're using TortoiseHg, the
+	    <command>pageant</command> command acts as the agent.  As
+	    with <command>puttygen</command>, you'll need to <ulink
+	      url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
+	      <command>pageant</command></ulink> from the PuTTY web
+	    site and read <ulink
+	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 
+	      documentation</ulink>.  The <command>pageant</command>
+	    command adds an icon to your system tray that will let you
+	    manage stored passphrases.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Configuring the server side properly</title>
 
       <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
-	there's a variety of things that can go wrong.  Add Mercurial
+	a variety of things can go wrong.  Add Mercurial
 	on top, and there's plenty more scope for head-scratching.
 	Most of these potential problems occur on the server side, not
 	the client side.  The good news is that once you've gotten a
 	If you run into problems with Mercurial and ssh at this point,
 	try using the <option role="hg-opt-global">--debug</option>
 	option to get a clearer picture of what's going on.</para>
-
     </sect2>
     <sect2>
       <title>Using compression with ssh</title>
 	accept a <option role="cmd-opt-ssh">-C</option> option which
 	turns on compression.  You can easily edit your <filename
 	  role="special">~/.hgrc</filename> to enable compression for
-	all of Mercurial's uses of the ssh protocol.</para>
+	all of Mercurial's uses of the ssh protocol.  Here is how to
+	do so for regular <command>ssh</command> on Unix-like systems,
+	for example.</para>
       <programlisting>[ui]
 ssh = ssh -C</programlisting>
 
-      <para id="x_4b9">If you use <command>ssh</command>, you can configure it to
-	always use compression when talking to your server.  To do
-	this, edit your <filename
-	  role="special">.ssh/config</filename> file (which may not
-	yet exist), as follows.</para>
+      <para id="x_4b9">If you use <command>ssh</command> on a
+	Unix-like system, you can configure it to always use
+	compression when talking to your server.  To do this, edit
+	your <filename role="special">.ssh/config</filename> file
+	(which may not yet exist), as follows.</para>
+
       <programlisting>Host hg
   Compression yes
   HostName hg.example.com</programlisting>
-      <para id="x_4ba">This defines an alias, <literal>hg</literal>.  When you
-	use it on the <command>ssh</command> command line or in a
-	Mercurial <literal>ssh</literal>-protocol URL, it will cause
+
+      <para id="x_4ba">This defines a hostname alias,
+	<literal>hg</literal>.  When you use that hostname on the
+	<command>ssh</command> command line or in a Mercurial
+	<literal>ssh</literal>-protocol URL, it will cause
 	<command>ssh</command> to connect to
 	<literal>hg.example.com</literal> and use compression.  This
 	gives you both a shorter name to type and compression, each of
 	which is a good thing in its own right.</para>
-
     </sect2>
   </sect1>
+
   <sect1 id="sec:collab:cgi">
     <title>Serving over HTTP using CGI</title>
 
+    <para id="x_6a8">The simplest way to host one or more repositories in a
+      permanent way is to use a web server and Mercurial's CGI
+      support.</para>
+
     <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
       CGI interface can take anything from a few moments to several
       hours.</para>
       your web server's configuration.</para>
 
     <note>
-      <para id="x_4bd">  Configuring a web server is a complex, fiddly, and
-	highly system-dependent activity.  I can't possibly give you
-	instructions that will cover anything like all of the cases
-	you will encounter. Please use your discretion and judgment in
-	following the sections below.  Be prepared to make plenty of
-	mistakes, and to spend a lot of time reading your server's
-	error logs.</para>
+      <title>High pain tolerance required</title>
+
+      <para id="x_4bd">Configuring a web server is a complex, fiddly,
+	and highly system-dependent activity.  I can't possibly give
+	you instructions that will cover anything like all of the
+	cases you will encounter. Please use your discretion and
+	judgment in following the sections below.  Be prepared to make
+	plenty of mistakes, and to spend a lot of time reading your
+	server's error logs.</para>
+
+      <para id="x_6a9">If you don't have a strong stomach for tweaking
+	configurations over and over, or a compelling need to host
+	your own services, you might want to try one of the public
+	hosting services that I mentioned earlier.</para>
     </note>
 
     <sect2>
 	aspects of your system's setup.</para>
 
       <orderedlist>
-	<listitem><para id="x_4bf">Do you have a web server installed at all?
-	    Mac OS X ships with Apache, but many other systems may not
-	    have a web server installed.</para>
+	<listitem><para id="x_4bf">Do you have a web server installed
+	    at all? Mac OS X and some Linux distributions ship with
+	    Apache, but many other systems may not have a web server
+	    installed.</para>
 	</listitem>
 	<listitem><para id="x_4c0">If you have a web server installed, is it
 	    actually running?  On most systems, even if one is
 	repositories.  And <literal>lighttpd</literal> is undeniably
 	<emphasis>much</emphasis> easier to get started with than
 	Apache.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Basic CGI configuration</title>
 
 	<para id="x_4d0">At this point, when you try to reload the page, you
 	  should be presented with a nice HTML view of your
 	  repository's history.  Whew!</para>
+      </sect3>
 
-      </sect3>
       <sect3>
 	<title>Configuring lighttpd</title>
 
 	  configure than Apache, even though I've used Apache for over
 	  a decade, and this was my first exposure to
 	  <literal>lighttpd</literal>.</para>
-
       </sect3>
     </sect2>
+
     <sect2>
       <title>Sharing multiple repositories with one CGI script</title>
 
 	  file.</para>
 
 	<note>
-	  <para id="x_4e2">  If multiple repositories have the same virtual path,
-	    <filename role="special">hgwebdir.cgi</filename> will not
-	    report an error.  Instead, it will behave
-	    unpredictably.</para>
+	  <title>Beware duplicate virtual paths</title>
+
+	  <para id="x_4e2">  If several repositories have the same
+	    virtual path, <filename
+	      role="special">hgwebdir.cgi</filename> will not report
+	    an error.  Instead, it will behave unpredictably.</para>
 	</note>
-
       </sect3>
     </sect2>
+
     <sect2>
       <title>Downloading source archives</title>
 
 	you'll need to add an <envar
 	  role="rc-item-web">allow_archive</envar> item to the
 	<literal role="rc-web">web</literal> section of your <filename
-	  role="special">~/.hgrc</filename>.</para>
-
+	  role="special">~/.hgrc</filename>; see below for details.</para>
     </sect2>
     <sect2>
       <title>Web configuration options</title>
 	<listitem><para id="x_4f0"><envar
 	      role="rc-item-web">style</envar>: Controls the template
 	    Mercurial uses to display the web interface.  Mercurial
-	    ships with two web templates, named
-	    <literal>default</literal> and <literal>gitweb</literal>
-	    (the latter is much more visually attractive).  You can
+	    ships with several web templates.</para>
+	  <itemizedlist>
+	    <listitem>
+	      <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ab"><literal>gitweb</literal> emulates the visual
+		style of git's web interface.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
+		greys.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ad"><literal>paper</literal> is the default.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ae"><literal>spartan</literal> was the default for a
+		long time.</para>
+	    </listitem>
+	  </itemizedlist>
+	  <para id="x_6af">You can
 	    also specify a custom template of your own; see 
 	    <xref linkend="chap:template"/> for details. Here, you can
 	    see how to enable the <literal>gitweb</literal>
 	      interface.  This overrides the default name, which is
 	      the last component of the repository's path.</para>
 	  </listitem></itemizedlist>
+      </sect3>
 
-      </sect3>
       <sect3>
 	<title>Options specific to the <command role="hg-cmd">hg
 	    serve</command> command</title>
 	      Integer.  The TCP port number on which the server should
 	      listen.  The default port number used is 8000.</para>
 	  </listitem></itemizedlist>
+      </sect3>
 
-      </sect3>
       <sect3>
 	<title>Choosing the right <filename
 	    role="special">~/.hgrc</filename> file to add <literal
 	  <filename role="special">~/.hgrc</filename> file in the
 	  home directory of the user ID that runs your web server, or
 	  add those settings to a system-wide <filename
-	    role="special">~/.hgrc</filename> file.</para>
+	    role="special">hgrc</filename> file.</para>
+      </sect3>
+    </sect2>
+  </sect1>
 
+  <sect1>
+    <title>System-wide configuration</title>
 
-      </sect3>
+    <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
+      server to which people publish changes), it often makes sense to
+      set up some global default behaviors, such as what theme to use
+      in web interfaces.</para>
+
+    <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
+      exists, Mercurial will read it at startup time and apply any
+      configuration settings it finds in that file.  It will also look
+      for files ending in a <literal>.rc</literal> extension in a
+      directory named <filename>/etc/mercurial/hgrc.d</filename>, and
+      apply any configuration settings it finds in each of those
+      files.</para>
+
+    <sect2>
+      <title>Making Mercurial more trusting</title>
+
+      <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
+	can be useful is if users are pulling changes owned by other
+	users.  By default, Mercurial will not trust most of the
+	configuration items in a <filename>.hg/hgrc</filename> file
+	inside a repository that is owned by a different user. If we
+	clone or pull changes from such a repository, Mercurial will
+	print a warning stating that it does not trust their
+	<filename>.hg/hgrc</filename>.</para>
+
+      <para id="x_6b3">If everyone in a particular Unix group is on the same team
+	and <emphasis>should</emphasis> trust each other's
+	configuration settings, or we want to trust particular users,
+	we can override Mercurial's skeptical defaults by creating a
+	system-wide <filename>hgrc</filename> file such as the
+	following:</para>
+
+    <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
+[trusted]
+# Trust all entries in any hgrc file owned by the "editors" or
+# "www-data" groups.
+groups = editors, www-data
+
+# Trust entries in hgrc files owned by the following users.
+users = apache, bobo
+</programlisting>
     </sect2>
   </sect1>
 </chapter>

File en/ch06-filenames.xml

       before continuing with the current directory.</para>
 
       &interaction.filenames.dirs;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Running commands without any file names</title>
 
 	role="hg-cmd">hg root</command> command.</para>
 
       &interaction.filenames.wdir-relname;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Telling you what's going on</title>
 
     <para id="x_54d">The principle here is of <emphasis>least
 	surprise</emphasis>.  If you've exactly named a file on the
       command line, there's no point in repeating it back at you.  If
-      Mercurial is acting on a file <emphasis>implicitly</emphasis>,
+      Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g.
       because you provided no names, or a directory, or a pattern (see
-      below), it's safest to tell you what it's doing.</para>
+      below), it is safest to tell you what files it's operating on.</para>
 
     <para id="x_54e">For commands that behave this way, you can silence them
       using the <option role="hg-opt-global">-q</option> option.  You
       can also get them to print the name of every file, even those
       you've named explicitly, using the <option
 	role="hg-opt-global">-v</option> option.</para>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Using patterns to identify files</title>
 
 	  example illustrates the difference between the two.</para>
 
 	  &interaction.filenames.glob.star-starstar;
-
       </sect3>
     </sect2>
+
     <sect2>
       <title>Regular expression matching with <literal>re</literal>
 	patterns</title>
 	string; it doesn't look for a match anywhere within the
 	string.  To match anywhere in a string, start your pattern
 	with <quote><literal>.*</literal></quote>.</para>
-
     </sect2>
   </sect1>
+
   <sect1>
     <title>Filtering files</title>
 
 	pattern</quote>.</para>
 
     &interaction.filenames.filter.exclude;
+  </sect1>
 
+  <sect1>
+    <title>Permanently ignoring unwanted files and directories</title>
+
+    <para id="x_569">When you create a new repository, the chances are
+      that over time it will grow to contain files that ought to
+      <emphasis>not</emphasis> be managed by Mercurial, but which you
+      don't want to see listed every time you run <command>hg
+	status</command>.  For instance, <quote>build products</quote>
+      are files that are created as part of a build but which should
+      not be managed by a revision control system.  The most common
+      build products are output files produced by software tools such
+      as compilers.  As another example, many text editors litter a
+      directory with lock files, temporary working files, and backup
+      files, which it also makes no sense to manage.</para>
+
+    <para id="x_6b4">To have Mercurial permanently ignore such files, create a
+      file named <filename>.hgignore</filename> in the root of your
+      repository.  You <emphasis>should</emphasis> <command>hg
+      add</command> this file so that it gets tracked with the rest of
+      your repository contents, since your collaborators will probably
+      find it useful too.</para>
+
+    <para id="x_6b5">By default, the <filename>.hgignore</filename> file should
+      contain a list of regular expressions, one per line.  Empty
+      lines are skipped. Most people prefer to describe the files they
+      want to ignore using the <quote>glob</quote> syntax that we
+      described above, so a typical <filename>.hgignore</filename>
+      file will start with this directive:</para>
+
+    <programlisting>syntax: glob</programlisting>
+
+    <para id="x_6b6">This tells Mercurial to interpret the lines that follow as
+      glob patterns, not regular expressions.</para>
+
+    <para id="x_6b7">Here is a typical-looking <filename>.hgignore</filename>
+      file.</para>
+
+    <programlisting>syntax: glob
+# This line is a comment, and will be skipped.
+# Empty lines are skipped too.
+
+# Backup files left behind by the Emacs editor.
+*~
+
+# Lock files used by the Emacs editor.
+# Notice that the "#" character is quoted with a backslash.
+# This prevents it from being interpreted as starting a comment.
+.\#*
+
+# Temporary files used by the vim editor.
+.*.swp
+
+# A hidden file created by the Mac OS X Finder.
+.DS_Store
+</programlisting>
   </sect1>
-  <sect1>
-    <title>Ignoring unwanted files and directories</title>
 
-    <para id="x_569">XXX.</para>
-
-  </sect1>
   <sect1 id="sec:names:case">
     <title>Case sensitivity</title>
 
 	conflict between the two file names that the filesystem would
 	treat as the same, and forbid the update or merge from
 	occurring.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Fixing a case conflict</title>
 
 	<command role="hg-cmd">hg update</command> your working
 	directory to that changeset on a Windows or MacOS system, but
 	you can continue development unimpeded.</para>
-
-      <note>
-	<para id="x_577">  Prior to version 0.9.3, Mercurial did not use a case
-	  safe repository storage mechanism, and did not detect case
-	  folding conflicts.  If you are using an older version of
-	  Mercurial on Windows or MacOS, I strongly recommend that you
-	  upgrade.</para>
-      </note>
-
     </sect2>
   </sect1>
 </chapter>

File en/ch07-branch.xml

 
     <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
       in your repository.  If you've created any tags, you'll find
-      them in a file named <filename
+      them in a file in the root of your repository named <filename
 	role="special">.hgtags</filename>.  When you run the <command
 	role="hg-cmd">hg tag</command> command, Mercurial modifies
       this file, then automatically commits the change to it.  This
 	location of the error, which you can then fix and commit.  You
 	should then run <command role="hg-cmd">hg tags</command>
 	again, just to be sure that your fix is correct.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Tags and cloning</title>
 
 	project's history in the new repository, but
 	<emphasis>not</emphasis> the tag you might have
 	expected.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>When permanent tags are too much</title>
 
 	controlled.  Any tags you create using <option
 	  role="hg-opt-tag">-l</option> remain strictly local to the
 	repository you're currently working in.</para>
-
     </sect2>
   </sect1>
+
   <sect1>
     <title>The flow of changes&emdash;big picture vs. little</title>
 
 	  merging changes.  They expose the narrative of how the code
 	  was developed.</para>
       </listitem></itemizedlist>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Managing big-picture branches in repositories</title>
 
       the <literal>myproject</literal> repository.</para>
 
     &interaction.branch-repo.new;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Don't repeat yourself: merging across branches</title>
 
       push back to the main branch.</para>
 
     &interaction.branch-repo.merge;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Naming branches within one repository</title>
 
     <para id="x_39d">In practice, this is something you won't do very often, as
       branch names tend to have fairly long lifetimes.  (This isn't a
       rule, just an observation.)</para>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Dealing with multiple named branches in a
       repository</title>
       introduces a new head.</para>
 
     &interaction.branch-named.foo-commit;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Branch names and merging</title>
 
       Mercurial will choose the <quote>right</quote>
       (<literal>bleeding-edge</literal>) branch name when I pull and
       merge from <literal>stable</literal>.</para>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Branch naming is generally useful</title>
 
 	/.hgrc</filename>.</para>
     <programlisting>[hooks]
 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
-
   </sect1>
 </chapter>