1.1 --- a/en/ch05-collab.xml	Sun Apr 12 00:05:30 2009 -0700
     1.2 +++ b/en/ch05-collab.xml	Thu Apr 16 23:45:07 2009 -0700
     1.3 @@ -19,10 +19,12 @@
     1.4      <para id="x_44c">For interactive use, the web interface lets you browse a
     1.5        single repository or a collection of repositories.  You can view
     1.6        the history of a repository, examine each change (comments and
     1.7 -      diffs), and view the contents of each directory and file.</para>
     1.8 -
     1.9 -    <para id="x_44d">Also for human consumption, the web interface provides an
    1.10 -      RSS feed of the changes in a repository.  This lets you
    1.11 +      diffs), and view the contents of each directory and file.  You
    1.12 +      can even get a view of history that gives a graphical view of
    1.13 +      the relationships between individual changes and merges.</para>
    1.14 +
    1.15 +    <para id="x_44d">Also for human consumption, the web interface provides
    1.16 +      Atom and RSS feeds of the changes in a repository.  This lets you
    1.17        <quote>subscribe</quote> to a repository using your favorite
    1.18        feed reader, and be automatically notified of activity in that
    1.19        repository as soon as it happens.  I find this capability much
    1.20 @@ -40,22 +42,40 @@
    1.21      <para id="x_44f">The easiest way to get started with the web interface is to
    1.22        use your web browser to visit an existing repository, such as
    1.23        the master Mercurial repository at <ulink
    1.24 -	url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
    1.25 +	url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
    1.26  
    1.27      <para id="x_450">If you're interested in providing a web interface
    1.28 -      to your own repositories, Mercurial provides two ways to do
    1.29 -      this.  The first is using the <command role="hg-cmd">hg
    1.30 +      to your own repositories, there are several good ways to do
    1.31 +      this.</para>
    1.32 +
    1.33 +    <para>The easiest and fastest way to get started in an informal
    1.34 +      environment is to use the <command role="hg-cmd">hg
    1.35  	serve</command> command, which is best suited to short-term
    1.36        <quote>lightweight</quote> serving.  See <xref
    1.37  	linkend="sec:collab:serve"/> below for details of how to use
    1.38 -      this command.  If you have a long-lived repository that you'd
    1.39 -      like to make permanently available, Mercurial has built-in
    1.40 -      support for the CGI (Common Gateway Interface) standard, which
    1.41 -      all common web servers support.  See <xref
    1.42 -	linkend="sec:collab:cgi"/> for details of CGI
    1.43 +      this command.</para>
    1.44 +
    1.45 +    <para>For longer-lived repositories that you'd like to have
    1.46 +      permanently available, there are several public hosting services
    1.47 +      available.</para>
    1.48 +
    1.49 +    <itemizedlist>
    1.50 +      <listitem>
    1.51 +	<para>Bitbucket, at <ulink
    1.52 +	    url="http://bitbucket.org/">http://bitbucket.org/</ulink>,
    1.53 +	  provides free hosting for open source projects, and paid
    1.54 +	  hosting for commercial projects.</para>
    1.55 +      </listitem>
    1.56 +    </itemizedlist>
    1.57 +
    1.58 +    <para>If you would prefer to host your own repositories, Mercurial
    1.59 +      has built-in support for several popular hosting technologies,
    1.60 +      most notably CGI (Common Gateway Interface), and WSGI (Web
    1.61 +      Services Gateway Interface).  See <xref
    1.62 +	linkend="sec:collab:cgi"/> for details of CGI and WSGI
    1.63        configuration.</para>
    1.64 -
    1.65    </sect1>
    1.66 +
    1.67    <sect1>
    1.68      <title>Collaboration models</title>
    1.69  
    1.70 @@ -96,8 +116,8 @@
    1.71  	could avoid this particular problem by writing a hook that
    1.72  	prevents changes from being merged from an inappropriate
    1.73  	branch.</para>
    1.74 -
    1.75 -    </sect2>
    1.76 +    </sect2>
    1.77 +
    1.78      <sect2>
    1.79        <title>Informal anarchy</title>
    1.80  
    1.81 @@ -115,7 +135,7 @@
    1.82  	place) and spend several days more or less locked in there,
    1.83  	hacking intensely on a handful of projects.</para>
    1.84  
    1.85 -      <para id="x_457">A sprint is the perfect place to use the
    1.86 +      <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
    1.87  	<command role="hg-cmd">hg serve</command> command, since
    1.88  	<command role="hg-cmd">hg serve</command> does not require any
    1.89  	fancy server infrastructure.  You can get started with
    1.90 @@ -129,14 +149,15 @@
    1.91  	they can clone a branch containing a new feature and try it
    1.92  	out.</para>
    1.93  
    1.94 -      <para id="x_458">The charm, and the problem, with doing things in an ad hoc
    1.95 -	fashion like this is that only people who know about your
    1.96 -	changes, and where they are, can see them.  Such an informal
    1.97 -	approach simply doesn't scale beyond a handful people, because
    1.98 -	each individual needs to know about $n$ different repositories
    1.99 -	to pull from.</para>
   1.100 -
   1.101 -    </sect2>
   1.102 +      <para id="x_458">The charm, and the problem, with doing things
   1.103 +	in an ad hoc fashion like this is that only people who know
   1.104 +	about your changes, and where they are, can see them.  Such an
   1.105 +	informal approach simply doesn't scale beyond a handful
   1.106 +	people, because each individual needs to know about
   1.107 +	<emphasis>n</emphasis> different repositories to pull
   1.108 +	from.</para>
   1.109 +    </sect2>
   1.110 +
   1.111      <sect2>
   1.112        <title>A single central repository</title>
   1.113  
   1.114 @@ -162,17 +183,39 @@
   1.115  	lets us put off publishing the potentially unsafe change until
   1.116  	it has had a little testing.</para>
   1.117  
   1.118 -      <para id="x_45c">In this kind of scenario, people usually use
   1.119 -	the <command>ssh</command> protocol to securely push changes
   1.120 -	to the central repository, as documented in <xref
   1.121 +      <para id="x_45c">If a team is hosting its own repository in this
   1.122 +	kind of scenario, people will usually use the
   1.123 +	<command>ssh</command> protocol to securely push changes to
   1.124 +	the central repository, as documented in <xref
   1.125  	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
   1.126 -	read-only copy of the repository over HTTP using CGI, as in
   1.127 -	<xref linkend="sec:collab:cgi"/>. Publishing
   1.128 -	over HTTP satisfies the needs of people who don't have push
   1.129 -	access, and those who want to use web browsers to browse the
   1.130 -	repository's history.</para>
   1.131 -
   1.132 -    </sect2>
   1.133 +	read-only copy of the repository over HTTP, as in
   1.134 +	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
   1.135 +	satisfies the needs of people who don't have push access, and
   1.136 +	those who want to use web browsers to browse the repository's
   1.137 +	history.</para>
   1.138 +    </sect2>
   1.139 +
   1.140 +    <sect2>
   1.141 +      <title>A hosted central repository</title>
   1.142 +
   1.143 +      <para>A wonderful thing about public hosting services like
   1.144 +	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
   1.145 +	not only do they handle the fiddly server configuration
   1.146 +	details, such as user accounts, authentication, and secure
   1.147 +	wire protocols, they provide additional infrastructure to make
   1.148 +	this model work well.</para>
   1.149 +
   1.150 +      <para>For instance, a well-engineered hosting service will let
   1.151 +	people clone their own copies of a repository with a single
   1.152 +	click.  This lets people work in separate spaces and share
   1.153 +	their changes when they're ready.</para>
   1.154 +
   1.155 +      <para>In addition, a good hosting service will let people
   1.156 +	communicate with each other, for instance to say <quote>there
   1.157 +	  are changes ready for you to review in this
   1.158 +	  tree</quote>.</para>
   1.159 +    </sect2>
   1.160 +
   1.161      <sect2>
   1.162        <title>Working with multiple branches</title>
   1.163  
   1.164 @@ -196,7 +239,7 @@
   1.165  	another as the need arises.  Because repositories are
   1.166  	independent of each other, unstable changes in a development
   1.167  	branch will never affect a stable branch unless someone
   1.168 -	explicitly merges those changes in.</para>
   1.169 +	explicitly merges those changes into the stable branch.</para>
   1.170  
   1.171        <para id="x_45f">Here's an example of how this can work in practice.  Let's
   1.172  	say you have one <quote>main branch</quote> on a central
   1.173 @@ -227,38 +270,41 @@
   1.174        &interaction.branching.update;
   1.175  
   1.176        <para id="x_464">In addition, immediately after the main branch is tagged,
   1.177 -	someone can then clone the main branch on the server to a new
   1.178 +	we can then clone the main branch on the server to a new
   1.179  	<quote>stable</quote> branch, also on the server.</para>
   1.180  
   1.181        &interaction.branching.clone;
   1.182  
   1.183 -      <para id="x_465">Someone who needs to make a change to the stable branch
   1.184 -	can then clone <emphasis>that</emphasis> repository, make
   1.185 -	their changes, commit, and push their changes back there.</para>
   1.186 +      <para id="x_465">If we need to make a change to the stable
   1.187 +	branch, we can then clone <emphasis>that</emphasis>
   1.188 +	repository, make our changes, commit, and push our changes
   1.189 +	back there.</para>
   1.190  
   1.191        &interaction.branching.stable;
   1.192  
   1.193        <para id="x_466">Because Mercurial repositories are independent, and
   1.194  	Mercurial doesn't move changes around automatically, the
   1.195  	stable and main branches are <emphasis>isolated</emphasis>
   1.196 -	from each other.  The changes that you made on the main branch
   1.197 +	from each other.  The changes that we made on the main branch
   1.198  	don't <quote>leak</quote> to the stable branch, and vice
   1.199  	versa.</para>
   1.200  
   1.201 -      <para id="x_467">You'll often want all of your bugfixes on the stable
   1.202 +      <para id="x_467">We'll often want all of our bugfixes on the stable
   1.203  	branch to show up on the main branch, too.  Rather than
   1.204 -	rewrite a bugfix on the main branch, you can simply pull and
   1.205 +	rewrite a bugfix on the main branch, we can simply pull and
   1.206  	merge changes from the stable to the main branch, and
   1.207 -	Mercurial will bring those bugfixes in for you.</para>
   1.208 -
   1.209 -	&interaction.branching.merge;
   1.210 -
   1.211 -      <para id="x_468">The main branch will still contain changes that are not on
   1.212 -	the stable branch, but it will also contain all of the
   1.213 -	bugfixes from the stable branch.  The stable branch remains
   1.214 -	unaffected by these changes.</para>
   1.215 -
   1.216 -    </sect2>
   1.217 +	Mercurial will bring those bugfixes in for us.</para>
   1.218 +
   1.219 +      &interaction.branching.merge;
   1.220 +
   1.221 +      <para id="x_468">The main branch will still contain changes that
   1.222 +	are not on the stable branch, but it will also contain all of
   1.223 +	the bugfixes from the stable branch.  The stable branch
   1.224 +	remains unaffected by these changes, since changes are only
   1.225 +	flowing from the stable to the main branch, and not the other
   1.226 +	way.</para>
   1.227 +    </sect2>
   1.228 +
   1.229      <sect2>
   1.230        <title>Feature branches</title>
   1.231  
   1.232 @@ -281,8 +327,8 @@
   1.233  	shape, someone on that feature team pulls and merges from the
   1.234  	master branch into the feature branch, then pushes back up to
   1.235  	the master branch.</para>
   1.236 -
   1.237 -    </sect2>
   1.238 +    </sect2>
   1.239 +
   1.240      <sect2>
   1.241        <title>The release train</title>
   1.242  
   1.243 @@ -297,8 +343,8 @@
   1.244  	went out on that train release into the feature branch, and
   1.245  	the team continues its work on top of that release so that
   1.246  	their feature can make the next release.</para>
   1.247 -
   1.248 -    </sect2>
   1.249 +    </sect2>
   1.250 +
   1.251      <sect2>
   1.252        <title>The Linux kernel model</title>
   1.253  
   1.254 @@ -372,8 +418,8 @@
   1.255  	it appropriate; and the pace of development is astounding.
   1.256  	And yet Linux is a highly successful, well-regarded piece of
   1.257  	software.</para>
   1.258 -
   1.259 -    </sect2>
   1.260 +    </sect2>
   1.261 +
   1.262      <sect2>
   1.263        <title>Pull-only versus shared-push collaboration</title>
   1.264  
   1.265 @@ -391,12 +437,11 @@
   1.266  	you'll have to roll your own approach on top (such as applying
   1.267  	a patch by hand).</para>
   1.268  
   1.269 -      <para id="x_478">A good distributed revision control tool, such as
   1.270 -	Mercurial, will support both models.  You and your
   1.271 -	collaborators can then structure how you work together based
   1.272 -	on your own needs and preferences, not on what contortions
   1.273 -	your tools force you into.</para>
   1.274 -
   1.275 +      <para id="x_478">A good distributed revision control tool will
   1.276 +	support both models.  You and your collaborators can then
   1.277 +	structure how you work together based on your own needs and
   1.278 +	preferences, not on what contortions your tools force you
   1.279 +	into.</para>
   1.280      </sect2>
   1.281      <sect2>
   1.282        <title>Where collaboration meets branch management</title>
   1.283 @@ -409,16 +454,16 @@
   1.284  	Even though this subject is intimately related to how your
   1.285  	team collaborates, it's dense enough to merit treatment of its
   1.286  	own, in <xref linkend="chap:branch"/>.</para>
   1.287 -
   1.288      </sect2>
   1.289    </sect1>
   1.290 +
   1.291    <sect1>
   1.292      <title>The technical side of sharing</title>
   1.293  
   1.294      <para id="x_47a">The remainder of this chapter is devoted to the question of
   1.295 -      serving data to your collaborators.</para>
   1.296 -
   1.297 +      sharing changes with your collaborators.</para>
   1.298    </sect1>
   1.299 +
   1.300    <sect1 id="sec:collab:serve">
   1.301      <title>Informal sharing with <command role="hg-cmd">hg
   1.302  	serve</command></title>
   1.303 @@ -495,9 +540,9 @@
   1.304  	find out what URL you should send to your collaborators, start
   1.305  	it with the <option role="hg-opt-global">-v</option>
   1.306  	option.</para>
   1.307 -
   1.308      </sect2>
   1.309    </sect1>
   1.310 +
   1.311    <sect1 id="sec:collab:ssh">
   1.312      <title>Using the Secure Shell (ssh) protocol</title>
   1.313  
   1.314 @@ -506,11 +551,11 @@
   1.315        protocol.  To use this successfully, you may have to do a little
   1.316        bit of configuration on the client or server sides.</para>
   1.317  
   1.318 -    <para id="x_487">If you're not familiar with ssh, it's a network protocol
   1.319 -      that lets you securely communicate with another computer.  To
   1.320 -      use it with Mercurial, you'll be setting up one or more user
   1.321 -      accounts on a server so that remote users can log in and execute
   1.322 -      commands.</para>
   1.323 +    <para id="x_487">If you're not familiar with ssh, it's the name of
   1.324 +      both a command and a network protocol that let you securely
   1.325 +      communicate with another computer.  To use it with Mercurial,
   1.326 +      you'll be setting up one or more user accounts on a server so
   1.327 +      that remote users can log in and execute commands.</para>
   1.328  
   1.329      <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
   1.330        probably find some of the material that follows to be elementary
   1.331 @@ -569,8 +614,8 @@
   1.332  	<emphasis>absolute</emphasis> path on the server, begin the
   1.333  	path component with two slashes, as in this example.</para>
   1.334        <programlisting>ssh://server//absolute/path</programlisting>
   1.335 -
   1.336 -    </sect2>
   1.337 +    </sect2>
   1.338 +
   1.339      <sect2>
   1.340        <title>Finding an ssh client for your system</title>
   1.341  
   1.342 @@ -582,44 +627,44 @@
   1.343  	unlikely event that it isn't present, take a look at your
   1.344  	system documentation to figure out how to install it.</para>
   1.345  
   1.346 -      <para id="x_494">On Windows, you'll first need to download a suitable ssh
   1.347 -	client.  There are two alternatives.</para>
   1.348 +      <para id="x_494">On Windows, the TortoiseHg package is bundled
   1.349 +	with a version of Simon Tatham's excellent
   1.350 +	<command>plink</command> command, and you should not need to
   1.351 +	do any further configuration.</para>
   1.352 +    </sect2>
   1.353 +
   1.354 +    <sect2>
   1.355 +      <title>Generating a key pair</title>
   1.356 +
   1.357 +      <para id="x_499">To avoid the need to repetitively type a
   1.358 +	password every time you need to use your ssh client, I
   1.359 +	recommend generating a key pair.</para>
   1.360 +
   1.361 +      <tip>
   1.362 +	<title>Key pairs are not mandatory</title>
   1.363 +
   1.364 +	<para>Mercurial knows nothing about ssh authentication or key
   1.365 +	  pairs.  You can, if you like, safely ignore this section and
   1.366 +	  the one that follows until you grow tired of repeatedly
   1.367 +	  typing ssh passwords.</para>
   1.368 +      </tip>
   1.369 +
   1.370        <itemizedlist>
   1.371 -	<listitem><para id="x_495">Simon Tatham's excellent PuTTY package
   1.372 -	    <citation>web:putty</citation> provides a complete suite
   1.373 -	    of ssh client commands.</para>
   1.374 -	</listitem>
   1.375 -	<listitem><para id="x_496">If you have a high tolerance for pain, you can
   1.376 -	    use the Cygwin port of OpenSSH.</para>
   1.377 -	</listitem></itemizedlist>
   1.378 -      <para id="x_497">In either case, you'll need to edit your <filename
   1.379 -      role="special">hg.ini</filename> file to
   1.380 -	tell Mercurial where to find the actual client command.  For
   1.381 -	example, if you're using PuTTY, you'll need to use the
   1.382 -	<command>plink</command> command as a command-line ssh
   1.383 -	client.</para>
   1.384 -      <programlisting>[ui]
   1.385 -ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"</programlisting>
   1.386 -
   1.387 -      <note>
   1.388 -	<para id="x_498">  The path to <command>plink</command> shouldn't contain
   1.389 -	  any whitespace characters, or Mercurial may not be able to
   1.390 -	  run it correctly (so putting it in <filename
   1.391 -	    class="directory">C:\Program Files</filename> is probably
   1.392 -	  not a good idea).</para>
   1.393 -      </note>
   1.394 -
   1.395 -    </sect2>
   1.396 -    <sect2>
   1.397 -      <title>Generating a key pair</title>
   1.398 -
   1.399 -      <para id="x_499">To avoid the need to repetitively type a password every
   1.400 -	time you need to use your ssh client, I recommend generating a
   1.401 -	key pair.  On a Unix-like system, the
   1.402 -	<command>ssh-keygen</command> command will do the trick. On
   1.403 -	Windows, if you're using PuTTY, the
   1.404 -	<command>puttygen</command> command is what you'll
   1.405 -	need.</para>
   1.406 +	<listitem>
   1.407 +	  <para>On a Unix-like system, the
   1.408 +	    <command>ssh-keygen</command> command will do the
   1.409 +	    trick.</para>
   1.410 +	  <para>On Windows, if you're using TortoiseHg, you may need
   1.411 +	    to download a command named <command>puttygen</command>
   1.412 +	    from <ulink
   1.413 +	      url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
   1.414 +	      PuTTY web site</ulink> to generate a key pair.  See
   1.415 +	    <ulink
   1.416 +	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 
   1.417 +	      <command>puttygen</command> documentation</ulink> for
   1.418 +	    details of how use the command.</para>
   1.419 +	</listitem>
   1.420 +      </itemizedlist>
   1.421  
   1.422        <para id="x_49a">When you generate a key pair, it's usually
   1.423  	<emphasis>highly</emphasis> advisable to protect it with a
   1.424 @@ -642,7 +687,6 @@
   1.425  	public key to a file of your choosing, or paste it from the
   1.426  	window it's displayed in straight into the <filename
   1.427  	  role="special">authorized_keys</filename> file.</para>
   1.428 -
   1.429      </sect2>
   1.430      <sect2>
   1.431        <title>Using an authentication agent</title>
   1.432 @@ -663,21 +707,34 @@
   1.433  	judgment as to whether this is an acceptable risk.  It
   1.434  	certainly saves a lot of repeated typing.</para>
   1.435  
   1.436 -      <para id="x_49f">On Unix-like systems, the agent is called
   1.437 -	<command>ssh-agent</command>, and it's often run automatically
   1.438 -	for you when you log in.  You'll need to use the
   1.439 -	<command>ssh-add</command> command to add passphrases to the
   1.440 -	agent's store.  On Windows, if you're using PuTTY, the
   1.441 -	<command>pageant</command> command acts as the agent.  It adds
   1.442 -	an icon to your system tray that will let you manage stored
   1.443 -	passphrases.</para>
   1.444 -
   1.445 -    </sect2>
   1.446 +      <itemizedlist>
   1.447 +	<listitem>
   1.448 +	  <para id="x_49f">On Unix-like systems, the agent is called
   1.449 +	    <command>ssh-agent</command>, and it's often run
   1.450 +	    automatically for you when you log in.  You'll need to use
   1.451 +	    the <command>ssh-add</command> command to add passphrases
   1.452 +	    to the agent's store.</para>
   1.453 +	</listitem>
   1.454 +	<listitem>
   1.455 +	  <para>On Windows, if you're using TortoiseHg, the
   1.456 +	    <command>pageant</command> command acts as the agent.  As
   1.457 +	    with <command>puttygen</command>, you'll need to <ulink
   1.458 +	      url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
   1.459 +	      <command>pageant</command></ulink> from the PuTTY web
   1.460 +	    site and read <ulink
   1.461 +	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 
   1.462 +	      documentation</ulink>.  The <command>pageant</command>
   1.463 +	    command adds an icon to your system tray that will let you
   1.464 +	    manage stored passphrases.</para>
   1.465 +	</listitem>
   1.466 +      </itemizedlist>
   1.467 +    </sect2>
   1.468 +
   1.469      <sect2>
   1.470        <title>Configuring the server side properly</title>
   1.471  
   1.472        <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
   1.473 -	there's a variety of things that can go wrong.  Add Mercurial
   1.474 +	a variety of things can go wrong.  Add Mercurial
   1.475  	on top, and there's plenty more scope for head-scratching.
   1.476  	Most of these potential problems occur on the server side, not
   1.477  	the client side.  The good news is that once you've gotten a
   1.478 @@ -821,7 +878,6 @@
   1.479  	If you run into problems with Mercurial and ssh at this point,
   1.480  	try using the <option role="hg-opt-global">--debug</option>
   1.481  	option to get a clearer picture of what's going on.</para>
   1.482 -
   1.483      </sect2>
   1.484      <sect2>
   1.485        <title>Using compression with ssh</title>
   1.486 @@ -842,31 +898,40 @@
   1.487  	accept a <option role="cmd-opt-ssh">-C</option> option which
   1.488  	turns on compression.  You can easily edit your <filename
   1.489  	  role="special">~/.hgrc</filename> to enable compression for
   1.490 -	all of Mercurial's uses of the ssh protocol.</para>
   1.491 +	all of Mercurial's uses of the ssh protocol.  Here is how to
   1.492 +	do so for regular <command>ssh</command> on Unix-like systems,
   1.493 +	for example.</para>
   1.494        <programlisting>[ui]
   1.495  ssh = ssh -C</programlisting>
   1.496  
   1.497 -      <para id="x_4b9">If you use <command>ssh</command>, you can configure it to
   1.498 -	always use compression when talking to your server.  To do
   1.499 -	this, edit your <filename
   1.500 -	  role="special">.ssh/config</filename> file (which may not
   1.501 -	yet exist), as follows.</para>
   1.502 +      <para id="x_4b9">If you use <command>ssh</command> on a
   1.503 +	Unix-like system, you can configure it to always use
   1.504 +	compression when talking to your server.  To do this, edit
   1.505 +	your <filename role="special">.ssh/config</filename> file
   1.506 +	(which may not yet exist), as follows.</para>
   1.507 +
   1.508        <programlisting>Host hg
   1.509    Compression yes
   1.510    HostName hg.example.com</programlisting>
   1.511 -      <para id="x_4ba">This defines an alias, <literal>hg</literal>.  When you
   1.512 -	use it on the <command>ssh</command> command line or in a
   1.513 -	Mercurial <literal>ssh</literal>-protocol URL, it will cause
   1.514 +
   1.515 +      <para id="x_4ba">This defines a hostname alias,
   1.516 +	<literal>hg</literal>.  When you use that hostname on the
   1.517 +	<command>ssh</command> command line or in a Mercurial
   1.518 +	<literal>ssh</literal>-protocol URL, it will cause
   1.519  	<command>ssh</command> to connect to
   1.520  	<literal>hg.example.com</literal> and use compression.  This
   1.521  	gives you both a shorter name to type and compression, each of
   1.522  	which is a good thing in its own right.</para>
   1.523 -
   1.524      </sect2>
   1.525    </sect1>
   1.526 +
   1.527    <sect1 id="sec:collab:cgi">
   1.528      <title>Serving over HTTP using CGI</title>
   1.529  
   1.530 +    <para>The simplest way to host one or more repositories in a
   1.531 +      permanent way is to use a web server and Mercurial's CGI
   1.532 +      support.</para>
   1.533 +
   1.534      <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
   1.535        CGI interface can take anything from a few moments to several
   1.536        hours.</para>
   1.537 @@ -877,13 +942,20 @@
   1.538        your web server's configuration.</para>
   1.539  
   1.540      <note>
   1.541 -      <para id="x_4bd">  Configuring a web server is a complex, fiddly, and
   1.542 -	highly system-dependent activity.  I can't possibly give you
   1.543 -	instructions that will cover anything like all of the cases
   1.544 -	you will encounter. Please use your discretion and judgment in
   1.545 -	following the sections below.  Be prepared to make plenty of
   1.546 -	mistakes, and to spend a lot of time reading your server's
   1.547 -	error logs.</para>
   1.548 +      <title>High pain tolerance required</title>
   1.549 +
   1.550 +      <para id="x_4bd">Configuring a web server is a complex, fiddly,
   1.551 +	and highly system-dependent activity.  I can't possibly give
   1.552 +	you instructions that will cover anything like all of the
   1.553 +	cases you will encounter. Please use your discretion and
   1.554 +	judgment in following the sections below.  Be prepared to make
   1.555 +	plenty of mistakes, and to spend a lot of time reading your
   1.556 +	server's error logs.</para>
   1.557 +
   1.558 +      <para>If you don't have a strong stomach for tweaking
   1.559 +	configurations over and over, or a compelling need to host
   1.560 +	your own services, you might want to try one of the public
   1.561 +	hosting services that I mentioned earlier.</para>
   1.562      </note>
   1.563  
   1.564      <sect2>
   1.565 @@ -893,9 +965,10 @@
   1.566  	aspects of your system's setup.</para>
   1.567  
   1.568        <orderedlist>
   1.569 -	<listitem><para id="x_4bf">Do you have a web server installed at all?
   1.570 -	    Mac OS X ships with Apache, but many other systems may not
   1.571 -	    have a web server installed.</para>
   1.572 +	<listitem><para id="x_4bf">Do you have a web server installed
   1.573 +	    at all? Mac OS X and some Linux distributions ship with
   1.574 +	    Apache, but many other systems may not have a web server
   1.575 +	    installed.</para>
   1.576  	</listitem>
   1.577  	<listitem><para id="x_4c0">If you have a web server installed, is it
   1.578  	    actually running?  On most systems, even if one is
   1.579 @@ -917,8 +990,8 @@
   1.580  	repositories.  And <literal>lighttpd</literal> is undeniably
   1.581  	<emphasis>much</emphasis> easier to get started with than
   1.582  	Apache.</para>
   1.583 -
   1.584 -    </sect2>
   1.585 +    </sect2>
   1.586 +
   1.587      <sect2>
   1.588        <title>Basic CGI configuration</title>
   1.589  
   1.590 @@ -1048,8 +1121,8 @@
   1.591  	<para id="x_4d0">At this point, when you try to reload the page, you
   1.592  	  should be presented with a nice HTML view of your
   1.593  	  repository's history.  Whew!</para>
   1.594 -
   1.595        </sect3>
   1.596 +
   1.597        <sect3>
   1.598  	<title>Configuring lighttpd</title>
   1.599  
   1.600 @@ -1084,9 +1157,9 @@
   1.601  	  configure than Apache, even though I've used Apache for over
   1.602  	  a decade, and this was my first exposure to
   1.603  	  <literal>lighttpd</literal>.</para>
   1.604 -
   1.605        </sect3>
   1.606      </sect2>
   1.607 +
   1.608      <sect2>
   1.609        <title>Sharing multiple repositories with one CGI script</title>
   1.610  
   1.611 @@ -1214,14 +1287,16 @@
   1.612  	  file.</para>
   1.613  
   1.614  	<note>
   1.615 -	  <para id="x_4e2">  If multiple repositories have the same virtual path,
   1.616 -	    <filename role="special">hgwebdir.cgi</filename> will not
   1.617 -	    report an error.  Instead, it will behave
   1.618 -	    unpredictably.</para>
   1.619 +	  <title>Beware duplicate virtual paths</title>
   1.620 +
   1.621 +	  <para id="x_4e2">  If several repositories have the same
   1.622 +	    virtual path, <filename
   1.623 +	      role="special">hgwebdir.cgi</filename> will not report
   1.624 +	    an error.  Instead, it will behave unpredictably.</para>
   1.625  	</note>
   1.626 -
   1.627        </sect3>
   1.628      </sect2>
   1.629 +
   1.630      <sect2>
   1.631        <title>Downloading source archives</title>
   1.632  
   1.633 @@ -1234,8 +1309,7 @@
   1.634  	you'll need to add an <envar
   1.635  	  role="rc-item-web">allow_archive</envar> item to the
   1.636  	<literal role="rc-web">web</literal> section of your <filename
   1.637 -	  role="special">~/.hgrc</filename>.</para>
   1.638 -
   1.639 +	  role="special">~/.hgrc</filename>; see below for details.</para>
   1.640      </sect2>
   1.641      <sect2>
   1.642        <title>Web configuration options</title>
   1.643 @@ -1317,9 +1391,28 @@
   1.644  	<listitem><para id="x_4f0"><envar
   1.645  	      role="rc-item-web">style</envar>: Controls the template
   1.646  	    Mercurial uses to display the web interface.  Mercurial
   1.647 -	    ships with two web templates, named
   1.648 -	    <literal>default</literal> and <literal>gitweb</literal>
   1.649 -	    (the latter is much more visually attractive).  You can
   1.650 +	    ships with several web templates.</para>
   1.651 +	  <itemizedlist>
   1.652 +	    <listitem>
   1.653 +	      <para><literal>coal</literal> is monochromatic.</para>
   1.654 +	    </listitem>
   1.655 +	    <listitem>
   1.656 +	      <para><literal>gitweb</literal> emulates the visual
   1.657 +		style of git's web interface.</para>
   1.658 +	    </listitem>
   1.659 +	    <listitem>
   1.660 +	      <para><literal>monoblue</literal> uses solid blues and
   1.661 +		greys.</para>
   1.662 +	    </listitem>
   1.663 +	    <listitem>
   1.664 +	      <para><literal>paper</literal> is the default.</para>
   1.665 +	    </listitem>
   1.666 +	    <listitem>
   1.667 +	      <para><literal>spartan</literal> was the default for a
   1.668 +		long time.</para>
   1.669 +	    </listitem>
   1.670 +	  </itemizedlist>
   1.671 +	  <para>You can
   1.672  	    also specify a custom template of your own; see 
   1.673  	    <xref linkend="chap:template"/> for details. Here, you can
   1.674  	    see how to enable the <literal>gitweb</literal>
   1.675 @@ -1360,8 +1453,8 @@
   1.676  	      interface.  This overrides the default name, which is
   1.677  	      the last component of the repository's path.</para>
   1.678  	  </listitem></itemizedlist>
   1.679 -
   1.680        </sect3>
   1.681 +
   1.682        <sect3>
   1.683  	<title>Options specific to the <command role="hg-cmd">hg
   1.684  	    serve</command> command</title>
   1.685 @@ -1399,8 +1492,8 @@
   1.686  	      Integer.  The TCP port number on which the server should
   1.687  	      listen.  The default port number used is 8000.</para>
   1.688  	  </listitem></itemizedlist>
   1.689 -
   1.690        </sect3>
   1.691 +
   1.692        <sect3>
   1.693  	<title>Choosing the right <filename
   1.694  	    role="special">~/.hgrc</filename> file to add <literal
   1.695 @@ -1422,12 +1515,57 @@
   1.696  	  <filename role="special">~/.hgrc</filename> file in the
   1.697  	  home directory of the user ID that runs your web server, or
   1.698  	  add those settings to a system-wide <filename
   1.699 -	    role="special">~/.hgrc</filename> file.</para>
   1.700 -
   1.701 -
   1.702 +	    role="special">hgrc</filename> file.</para>
   1.703        </sect3>
   1.704      </sect2>
   1.705    </sect1>
   1.706 +
   1.707 +  <sect1>
   1.708 +    <title>System-wide configuration</title>
   1.709 +
   1.710 +    <para>On Unix-like systems shared by multiple users (such as a
   1.711 +      server to which people publish changes), it often makes sense to
   1.712 +      set up some global default behaviors, such as what theme to use
   1.713 +      in web interfaces.</para>
   1.714 +
   1.715 +    <para>If a file named <filename>/etc/mercurial/hgrc</filename>
   1.716 +      exists, Mercurial will read it at startup time and apply any
   1.717 +      configuration settings it finds in that file.  It will also look
   1.718 +      for files ending in a <literal>.rc</literal> extension in a
   1.719 +      directory named <filename>/etc/mercurial/hgrc.d</filename>, and
   1.720 +      apply any configuration settings it finds in each of those
   1.721 +      files.</para>
   1.722 +
   1.723 +    <sect2>
   1.724 +      <title>Making Mercurial more trusting</title>
   1.725 +
   1.726 +      <para>One situation in which a global <filename>hgrc</filename>
   1.727 +	can be useful is if users are pulling changes owned by other
   1.728 +	users.  By default, Mercurial will not trust most of the
   1.729 +	configuration items in a <filename>.hg/hgrc</filename> file
   1.730 +	inside a repository that is owned by a different user. If we
   1.731 +	clone or pull changes from such a repository, Mercurial will
   1.732 +	print a warning stating that it does not trust their
   1.733 +	<filename>.hg/hgrc</filename>.</para>
   1.734 +
   1.735 +      <para>If everyone in a particular Unix group is on the same team
   1.736 +	and <emphasis>should</emphasis> trust each other's
   1.737 +	configuration settings, or we want to trust particular users,
   1.738 +	we can override Mercurial's skeptical defaults by creating a
   1.739 +	system-wide <filename>hgrc</filename> file such as the
   1.740 +	following:</para>
   1.741 +
   1.742 +    <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
   1.743 +[trusted]
   1.744 +# Trust all entries in any hgrc file owned by the "editors" or
   1.745 +# "www-data" groups.
   1.746 +groups = editors, www-data
   1.747 +
   1.748 +# Trust entries in hgrc files owned by the following users.
   1.749 +users = apache, bobo
   1.750 +</programlisting>
   1.751 +    </sect2>
   1.752 +  </sect1>
   1.753  </chapter>
   1.754  
   1.755  <!--

     2.1 --- a/en/ch06-filenames.xml	Sun Apr 12 00:05:30 2009 -0700
     2.2 +++ b/en/ch06-filenames.xml	Thu Apr 16 23:45:07 2009 -0700
     2.3 @@ -27,8 +27,8 @@
     2.4        before continuing with the current directory.</para>
     2.5  
     2.6        &interaction.filenames.dirs;
     2.7 -
     2.8 -  </sect1>
     2.9 +  </sect1>
    2.10 +
    2.11    <sect1>
    2.12      <title>Running commands without any file names</title>
    2.13  
    2.14 @@ -70,8 +70,8 @@
    2.15  	role="hg-cmd">hg root</command> command.</para>
    2.16  
    2.17        &interaction.filenames.wdir-relname;
    2.18 -
    2.19 -  </sect1>
    2.20 +  </sect1>
    2.21 +
    2.22    <sect1>
    2.23      <title>Telling you what's going on</title>
    2.24  
    2.25 @@ -85,17 +85,17 @@
    2.26      <para id="x_54d">The principle here is of <emphasis>least
    2.27  	surprise</emphasis>.  If you've exactly named a file on the
    2.28        command line, there's no point in repeating it back at you.  If
    2.29 -      Mercurial is acting on a file <emphasis>implicitly</emphasis>,
    2.30 +      Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g.
    2.31        because you provided no names, or a directory, or a pattern (see
    2.32 -      below), it's safest to tell you what it's doing.</para>
    2.33 +      below), it is safest to tell you what files it's operating on.</para>
    2.34  
    2.35      <para id="x_54e">For commands that behave this way, you can silence them
    2.36        using the <option role="hg-opt-global">-q</option> option.  You
    2.37        can also get them to print the name of every file, even those
    2.38        you've named explicitly, using the <option
    2.39  	role="hg-opt-global">-v</option> option.</para>
    2.40 -
    2.41 -  </sect1>
    2.42 +  </sect1>
    2.43 +
    2.44    <sect1>
    2.45      <title>Using patterns to identify files</title>
    2.46  
    2.47 @@ -194,9 +194,9 @@
    2.48  	  example illustrates the difference between the two.</para>
    2.49  
    2.50  	  &interaction.filenames.glob.star-starstar;
    2.51 -
    2.52        </sect3>
    2.53      </sect2>
    2.54 +
    2.55      <sect2>
    2.56        <title>Regular expression matching with <literal>re</literal>
    2.57  	patterns</title>
    2.58 @@ -227,9 +227,9 @@
    2.59  	string; it doesn't look for a match anywhere within the
    2.60  	string.  To match anywhere in a string, start your pattern
    2.61  	with <quote><literal>.*</literal></quote>.</para>
    2.62 -
    2.63      </sect2>
    2.64    </sect1>
    2.65 +
    2.66    <sect1>
    2.67      <title>Filtering files</title>
    2.68  
    2.69 @@ -266,14 +266,65 @@
    2.70  	pattern</quote>.</para>
    2.71  
    2.72      &interaction.filenames.filter.exclude;
    2.73 -
    2.74 -  </sect1>
    2.75 -  <sect1>
    2.76 -    <title>Ignoring unwanted files and directories</title>
    2.77 -
    2.78 -    <para id="x_569">XXX.</para>
    2.79 -
    2.80 -  </sect1>
    2.81 +  </sect1>
    2.82 +
    2.83 +  <sect1>
    2.84 +    <title>Permanently ignoring unwanted files and directories</title>
    2.85 +
    2.86 +    <para id="x_569">When you create a new repository, the chances are
    2.87 +      that over time it will grow to contain files that ought to
    2.88 +      <emphasis>not</emphasis> be managed by Mercurial, but which you
    2.89 +      don't want to see listed every time you run <command>hg
    2.90 +	status</command>.  For instance, <quote>build products</quote>
    2.91 +      are files that are created as part of a build but which should
    2.92 +      not be managed by a revision control system.  The most common
    2.93 +      build products are output files produced by software tools such
    2.94 +      as compilers.  As another example, many text editors litter a
    2.95 +      directory with lock files, temporary working files, and backup
    2.96 +      files, which it also makes no sense to manage.</para>
    2.97 +
    2.98 +    <para>To have Mercurial permanently ignore such files, create a
    2.99 +      file named <filename>.hgignore</filename> in the root of your
   2.100 +      repository.  You <emphasis>should</emphasis> <command>hg
   2.101 +      add</command> this file so that it gets tracked with the rest of
   2.102 +      your repository contents, since your collaborators will probably
   2.103 +      find it useful too.</para>
   2.104 +
   2.105 +    <para>By default, the <filename>.hgignore</filename> file should
   2.106 +      contain a list of regular expressions, one per line.  Empty
   2.107 +      lines are skipped. Most people prefer to describe the files they
   2.108 +      want to ignore using the <quote>glob</quote> syntax that we
   2.109 +      described above, so a typical <filename>.hgignore</filename>
   2.110 +      file will start with this directive:</para>
   2.111 +
   2.112 +    <programlisting>syntax: glob</programlisting>
   2.113 +
   2.114 +    <para>This tells Mercurial to interpret the lines that follow as
   2.115 +      glob patterns, not regular expressions.</para>
   2.116 +
   2.117 +    <para>Here is a typical-looking <filename>.hgignore</filename>
   2.118 +      file.</para>
   2.119 +
   2.120 +    <programlisting>syntax: glob
   2.121 +# This line is a comment, and will be skipped.
   2.122 +# Empty lines are skipped too.
   2.123 +
   2.124 +# Backup files left behind by the Emacs editor.
   2.125 +*~
   2.126 +
   2.127 +# Lock files used by the Emacs editor.
   2.128 +# Notice that the "#" character is quoted with a backslash.
   2.129 +# This prevents it from being interpreted as starting a comment.
   2.130 +.\#*
   2.131 +
   2.132 +# Temporary files used by the vim editor.
   2.133 +.*.swp
   2.134 +
   2.135 +# A hidden file created by the Mac OS X Finder.
   2.136 +.DS_Store
   2.137 +</programlisting>
   2.138 +  </sect1>
   2.139 +
   2.140    <sect1 id="sec:names:case">
   2.141      <title>Case sensitivity</title>
   2.142  
   2.143 @@ -361,8 +412,8 @@
   2.144  	conflict between the two file names that the filesystem would
   2.145  	treat as the same, and forbid the update or merge from
   2.146  	occurring.</para>
   2.147 -
   2.148      </sect2>
   2.149 +
   2.150      <sect2>
   2.151        <title>Fixing a case conflict</title>
   2.152  
   2.153 @@ -388,15 +439,6 @@
   2.154  	<command role="hg-cmd">hg update</command> your working
   2.155  	directory to that changeset on a Windows or MacOS system, but
   2.156  	you can continue development unimpeded.</para>
   2.157 -
   2.158 -      <note>
   2.159 -	<para id="x_577">  Prior to version 0.9.3, Mercurial did not use a case
   2.160 -	  safe repository storage mechanism, and did not detect case
   2.161 -	  folding conflicts.  If you are using an older version of
   2.162 -	  Mercurial on Windows or MacOS, I strongly recommend that you
   2.163 -	  upgrade.</para>
   2.164 -      </note>
   2.165 -
   2.166      </sect2>
   2.167    </sect1>
   2.168  </chapter>

     3.1 --- a/en/ch07-branch.xml	Sun Apr 12 00:05:30 2009 -0700
     3.2 +++ b/en/ch07-branch.xml	Thu Apr 16 23:45:07 2009 -0700
     3.3 @@ -128,7 +128,7 @@
     3.4  
     3.5      <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
     3.6        in your repository.  If you've created any tags, you'll find
     3.7 -      them in a file named <filename
     3.8 +      them in a file in the root of your repository named <filename
     3.9  	role="special">.hgtags</filename>.  When you run the <command
    3.10  	role="hg-cmd">hg tag</command> command, Mercurial modifies
    3.11        this file, then automatically commits the change to it.  This
    3.12 @@ -170,8 +170,8 @@
    3.13  	location of the error, which you can then fix and commit.  You
    3.14  	should then run <command role="hg-cmd">hg tags</command>
    3.15  	again, just to be sure that your fix is correct.</para>
    3.16 -
    3.17      </sect2>
    3.18 +
    3.19      <sect2>
    3.20        <title>Tags and cloning</title>
    3.21  
    3.22 @@ -195,8 +195,8 @@
    3.23  	project's history in the new repository, but
    3.24  	<emphasis>not</emphasis> the tag you might have
    3.25  	expected.</para>
    3.26 -
    3.27      </sect2>
    3.28 +
    3.29      <sect2>
    3.30        <title>When permanent tags are too much</title>
    3.31  
    3.32 @@ -221,9 +221,9 @@
    3.33  	controlled.  Any tags you create using <option
    3.34  	  role="hg-opt-tag">-l</option> remain strictly local to the
    3.35  	repository you're currently working in.</para>
    3.36 -
    3.37      </sect2>
    3.38    </sect1>
    3.39 +
    3.40    <sect1>
    3.41      <title>The flow of changes&emdash;big picture vs. little</title>
    3.42  
    3.43 @@ -252,8 +252,8 @@
    3.44  	  merging changes.  They expose the narrative of how the code
    3.45  	  was developed.</para>
    3.46        </listitem></itemizedlist>
    3.47 -
    3.48 -  </sect1>
    3.49 +  </sect1>
    3.50 +
    3.51    <sect1>
    3.52      <title>Managing big-picture branches in repositories</title>
    3.53  
    3.54 @@ -285,8 +285,8 @@
    3.55        the <literal>myproject</literal> repository.</para>
    3.56  
    3.57      &interaction.branch-repo.new;
    3.58 -
    3.59 -  </sect1>
    3.60 +  </sect1>
    3.61 +
    3.62    <sect1>
    3.63      <title>Don't repeat yourself: merging across branches</title>
    3.64  
    3.65 @@ -308,8 +308,8 @@
    3.66        push back to the main branch.</para>
    3.67  
    3.68      &interaction.branch-repo.merge;
    3.69 -
    3.70 -  </sect1>
    3.71 +  </sect1>
    3.72 +
    3.73    <sect1>
    3.74      <title>Naming branches within one repository</title>
    3.75  
    3.76 @@ -408,8 +408,8 @@
    3.77      <para id="x_39d">In practice, this is something you won't do very often, as
    3.78        branch names tend to have fairly long lifetimes.  (This isn't a
    3.79        rule, just an observation.)</para>
    3.80 -
    3.81 -  </sect1>
    3.82 +  </sect1>
    3.83 +
    3.84    <sect1>
    3.85      <title>Dealing with multiple named branches in a
    3.86        repository</title>
    3.87 @@ -454,8 +454,8 @@
    3.88        introduces a new head.</para>
    3.89  
    3.90      &interaction.branch-named.foo-commit;
    3.91 -
    3.92 -  </sect1>
    3.93 +  </sect1>
    3.94 +
    3.95    <sect1>
    3.96      <title>Branch names and merging</title>
    3.97  
    3.98 @@ -496,8 +496,8 @@
    3.99        Mercurial will choose the <quote>right</quote>
   3.100        (<literal>bleeding-edge</literal>) branch name when I pull and
   3.101        merge from <literal>stable</literal>.</para>
   3.102 -
   3.103 -  </sect1>
   3.104 +  </sect1>
   3.105 +
   3.106    <sect1>
   3.107      <title>Branch naming is generally useful</title>
   3.108  
   3.109 @@ -522,7 +522,6 @@
   3.110  	/.hgrc</filename>.</para>
   3.111      <programlisting>[hooks]
   3.112  pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
   3.113 -
   3.114    </sect1>
   3.115  </chapter>
   3.116