1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/ch06-collab.xml	Mon Sep 07 23:16:08 2009 +0200
     1.3 @@ -0,0 +1,1405 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<chapter>
     1.7 +<title>Collaborating with other people</title>
     1.8 +<para>\label{cha:collab}</para>
     1.9 +
    1.10 +<para>As a completely decentralised tool, Mercurial doesn't impose any
    1.11 +policy on how people ought to work with each other.  However, if
    1.12 +you're new to distributed revision control, it helps to have some
    1.13 +tools and examples in mind when you're thinking about possible
    1.14 +workflow models.</para>
    1.15 +
    1.16 +<sect1>
    1.17 +<title>Mercurial's web interface</title>
    1.18 +
    1.19 +<para>Mercurial has a powerful web interface that provides several
    1.20 +useful capabilities.</para>
    1.21 +
    1.22 +<para>For interactive use, the web interface lets you browse a single
    1.23 +repository or a collection of repositories.  You can view the history
    1.24 +of a repository, examine each change (comments and diffs), and view
    1.25 +the contents of each directory and file.</para>
    1.26 +
    1.27 +<para>Also for human consumption, the web interface provides an RSS feed of
    1.28 +the changes in a repository.  This lets you <quote>subscribe</quote> to a
    1.29 +repository using your favourite feed reader, and be automatically
    1.30 +notified of activity in that repository as soon as it happens.  I find
    1.31 +this capability much more convenient than the model of subscribing to
    1.32 +a mailing list to which notifications are sent, as it requires no
    1.33 +additional configuration on the part of whoever is serving the
    1.34 +repository.</para>
    1.35 +
    1.36 +<para>The web interface also lets remote users clone a repository, pull
    1.37 +changes from it, and (when the server is configured to permit it) push
    1.38 +changes back to it.  Mercurial's HTTP tunneling protocol aggressively
    1.39 +compresses data, so that it works efficiently even over low-bandwidth
    1.40 +network connections.</para>
    1.41 +
    1.42 +<para>The easiest way to get started with the web interface is to use your
    1.43 +web browser to visit an existing repository, such as the master
    1.44 +Mercurial repository at
    1.45 +<ulink url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
    1.46 +
    1.47 +<para>If you're interested in providing a web interface to your own
    1.48 +repositories, Mercurial provides two ways to do this.  The first is
    1.49 +using the <command role="hg-cmd">hg serve</command> command, which is best suited to short-term
    1.50 +<quote>lightweight</quote> serving.  See section <xref linkend="sec:collab:serve"/> below for
    1.51 +details of how to use this command.  If you have a long-lived
    1.52 +repository that you'd like to make permanently available, Mercurial
    1.53 +has built-in support for the CGI (Common Gateway Interface) standard,
    1.54 +which all common web servers support.  See
    1.55 +section <xref linkend="sec:collab:cgi"/> for details of CGI configuration.</para>
    1.56 +
    1.57 +</sect1>
    1.58 +<sect1>
    1.59 +<title>Collaboration models</title>
    1.60 +
    1.61 +<para>With a suitably flexible tool, making decisions about workflow is much
    1.62 +more of a social engineering challenge than a technical one.
    1.63 +Mercurial imposes few limitations on how you can structure the flow of
    1.64 +work in a project, so it's up to you and your group to set up and live
    1.65 +with a model that matches your own particular needs.
    1.66 +</para>
    1.67 +
    1.68 +<sect2>
    1.69 +<title>Factors to keep in mind</title>
    1.70 +
    1.71 +<para>The most important aspect of any model that you must keep in mind is
    1.72 +how well it matches the needs and capabilities of the people who will
    1.73 +be using it.  This might seem self-evident; even so, you still can't
    1.74 +afford to forget it for a moment.
    1.75 +</para>
    1.76 +
    1.77 +<para>I once put together a workflow model that seemed to make perfect sense
    1.78 +to me, but that caused a considerable amount of consternation and
    1.79 +strife within my development team.  In spite of my attempts to explain
    1.80 +why we needed a complex set of branches, and how changes ought to flow
    1.81 +between them, a few team members revolted.  Even though they were
    1.82 +smart people, they didn't want to pay attention to the constraints we
    1.83 +were operating under, or face the consequences of those constraints in
    1.84 +the details of the model that I was advocating.
    1.85 +</para>
    1.86 +
    1.87 +<para>Don't sweep foreseeable social or technical problems under the rug.
    1.88 +Whatever scheme you put into effect, you should plan for mistakes and
    1.89 +problem scenarios.  Consider adding automated machinery to prevent, or
    1.90 +quickly recover from, trouble that you can anticipate.  As an example,
    1.91 +if you intend to have a branch with not-for-release changes in it,
    1.92 +you'd do well to think early about the possibility that someone might
    1.93 +accidentally merge those changes into a release branch.  You could
    1.94 +avoid this particular problem by writing a hook that prevents changes
    1.95 +from being merged from an inappropriate branch.
    1.96 +</para>
    1.97 +
    1.98 +</sect2>
    1.99 +<sect2>
   1.100 +<title>Informal anarchy</title>
   1.101 +
   1.102 +<para>I wouldn't suggest an <quote>anything goes</quote> approach as something
   1.103 +sustainable, but it's a model that's easy to grasp, and it works
   1.104 +perfectly well in a few unusual situations.
   1.105 +</para>
   1.106 +
   1.107 +<para>As one example, many projects have a loose-knit group of collaborators
   1.108 +who rarely physically meet each other.  Some groups like to overcome
   1.109 +the isolation of working at a distance by organising occasional
   1.110 +<quote>sprints</quote>.  In a sprint, a number of people get together in a single
   1.111 +location (a company's conference room, a hotel meeting room, that kind
   1.112 +of place) and spend several days more or less locked in there, hacking
   1.113 +intensely on a handful of projects.
   1.114 +</para>
   1.115 +
   1.116 +<para>A sprint is the perfect place to use the <command role="hg-cmd">hg serve</command> command, since
   1.117 +<command role="hg-cmd">hg serve</command> does not requires any fancy server infrastructure.  You
   1.118 +can get started with <command role="hg-cmd">hg serve</command> in moments, by reading
   1.119 +section <xref linkend="sec:collab:serve"/> below.  Then simply tell the person
   1.120 +next to you that you're running a server, send the URL to them in an
   1.121 +instant message, and you immediately have a quick-turnaround way to
   1.122 +work together.  They can type your URL into their web browser and
   1.123 +quickly review your changes; or they can pull a bugfix from you and
   1.124 +verify it; or they can clone a branch containing a new feature and try
   1.125 +it out.
   1.126 +</para>
   1.127 +
   1.128 +<para>The charm, and the problem, with doing things in an ad hoc fashion
   1.129 +like this is that only people who know about your changes, and where
   1.130 +they are, can see them.  Such an informal approach simply doesn't
   1.131 +scale beyond a handful people, because each individual needs to know
   1.132 +about $n$ different repositories to pull from.
   1.133 +</para>
   1.134 +
   1.135 +</sect2>
   1.136 +<sect2>
   1.137 +<title>A single central repository</title>
   1.138 +
   1.139 +<para>For smaller projects migrating from a centralised revision control
   1.140 +tool, perhaps the easiest way to get started is to have changes flow
   1.141 +through a single shared central repository.  This is also the
   1.142 +most common <quote>building block</quote> for more ambitious workflow schemes.
   1.143 +</para>
   1.144 +
   1.145 +<para>Contributors start by cloning a copy of this repository.  They can
   1.146 +pull changes from it whenever they need to, and some (perhaps all)
   1.147 +developers have permission to push a change back when they're ready
   1.148 +for other people to see it.
   1.149 +</para>
   1.150 +
   1.151 +<para>Under this model, it can still often make sense for people to pull
   1.152 +changes directly from each other, without going through the central
   1.153 +repository.  Consider a case in which I have a tentative bug fix, but
   1.154 +I am worried that if I were to publish it to the central repository,
   1.155 +it might subsequently break everyone else's trees as they pull it.  To
   1.156 +reduce the potential for damage, I can ask you to clone my repository
   1.157 +into a temporary repository of your own and test it.  This lets us put
   1.158 +off publishing the potentially unsafe change until it has had a little
   1.159 +testing.
   1.160 +</para>
   1.161 +
   1.162 +<para>In this kind of scenario, people usually use the <command>ssh</command>
   1.163 +protocol to securely push changes to the central repository, as
   1.164 +documented in section <xref linkend="sec:collab:ssh"/>.  It's also usual to
   1.165 +publish a read-only copy of the repository over HTTP using CGI, as in
   1.166 +section <xref linkend="sec:collab:cgi"/>.  Publishing over HTTP satisfies the
   1.167 +needs of people who don't have push access, and those who want to use
   1.168 +web browsers to browse the repository's history.
   1.169 +</para>
   1.170 +
   1.171 +</sect2>
   1.172 +<sect2>
   1.173 +<title>Working with multiple branches</title>
   1.174 +
   1.175 +<para>Projects of any significant size naturally tend to make progress on
   1.176 +several fronts simultaneously.  In the case of software, it's common
   1.177 +for a project to go through periodic official releases.  A release
   1.178 +might then go into <quote>maintenance mode</quote> for a while after its first
   1.179 +publication; maintenance releases tend to contain only bug fixes, not
   1.180 +new features.  In parallel with these maintenance releases, one or
   1.181 +more future releases may be under development.  People normally use
   1.182 +the word <quote>branch</quote> to refer to one of these many slightly different
   1.183 +directions in which development is proceeding.
   1.184 +</para>
   1.185 +
   1.186 +<para>Mercurial is particularly well suited to managing a number of
   1.187 +simultaneous, but not identical, branches.  Each <quote>development
   1.188 +direction</quote> can live in its own central repository, and you can merge
   1.189 +changes from one to another as the need arises.  Because repositories
   1.190 +are independent of each other, unstable changes in a development
   1.191 +branch will never affect a stable branch unless someone explicitly
   1.192 +merges those changes in.
   1.193 +</para>
   1.194 +
   1.195 +<para>Here's an example of how this can work in practice.  Let's say you
   1.196 +have one <quote>main branch</quote> on a central server.
   1.197 +<!-- &interaction.branching.init; -->
   1.198 +People clone it, make changes locally, test them, and push them back.
   1.199 +</para>
   1.200 +
   1.201 +<para>Once the main branch reaches a release milestone, you can use the
   1.202 +<command role="hg-cmd">hg tag</command> command to give a permanent name to the milestone
   1.203 +revision.
   1.204 +<!-- &interaction.branching.tag; -->
   1.205 +Let's say some ongoing development occurs on the main branch.
   1.206 +<!-- &interaction.branching.main; -->
   1.207 +Using the tag that was recorded at the milestone, people who clone
   1.208 +that repository at any time in the future can use <command role="hg-cmd">hg update</command> to
   1.209 +get a copy of the working directory exactly as it was when that tagged
   1.210 +revision was committed.
   1.211 +<!-- &interaction.branching.update; -->
   1.212 +</para>
   1.213 +
   1.214 +<para>In addition, immediately after the main branch is tagged, someone can
   1.215 +then clone the main branch on the server to a new <quote>stable</quote> branch,
   1.216 +also on the server.
   1.217 +<!-- &interaction.branching.clone; -->
   1.218 +</para>
   1.219 +
   1.220 +<para>Someone who needs to make a change to the stable branch can then clone
   1.221 +<emphasis>that</emphasis> repository, make their changes, commit, and push their
   1.222 +changes back there.
   1.223 +<!-- &interaction.branching.stable; -->
   1.224 +Because Mercurial repositories are independent, and Mercurial doesn't
   1.225 +move changes around automatically, the stable and main branches are
   1.226 +<emphasis>isolated</emphasis> from each other.  The changes that you made on the
   1.227 +main branch don't <quote>leak</quote> to the stable branch, and vice versa.
   1.228 +</para>
   1.229 +
   1.230 +<para>You'll often want all of your bugfixes on the stable branch to show up
   1.231 +on the main branch, too.  Rather than rewrite a bugfix on the main
   1.232 +branch, you can simply pull and merge changes from the stable to the
   1.233 +main branch, and Mercurial will bring those bugfixes in for you.
   1.234 +<!-- &interaction.branching.merge; -->
   1.235 +The main branch will still contain changes that are not on the stable
   1.236 +branch, but it will also contain all of the bugfixes from the stable
   1.237 +branch.  The stable branch remains unaffected by these changes.
   1.238 +</para>
   1.239 +
   1.240 +</sect2>
   1.241 +<sect2>
   1.242 +<title>Feature branches</title>
   1.243 +
   1.244 +<para>For larger projects, an effective way to manage change is to break up
   1.245 +a team into smaller groups.  Each group has a shared branch of its
   1.246 +own, cloned from a single <quote>master</quote> branch used by the entire
   1.247 +project.  People working on an individual branch are typically quite
   1.248 +isolated from developments on other branches.
   1.249 +</para>
   1.250 +
   1.251 +<informalfigure>
   1.252 +
   1.253 +<para>  <mediaobject><imageobject><imagedata fileref="feature-branches"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject>
   1.254 +  <caption><para>Feature branches</para></caption>
   1.255 +  \label{fig:collab:feature-branches}
   1.256 +</para>
   1.257 +</informalfigure>
   1.258 +
   1.259 +<para>When a particular feature is deemed to be in suitable shape, someone
   1.260 +on that feature team pulls and merges from the master branch into the
   1.261 +feature branch, then pushes back up to the master branch.
   1.262 +</para>
   1.263 +
   1.264 +</sect2>
   1.265 +<sect2>
   1.266 +<title>The release train</title>
   1.267 +
   1.268 +<para>Some projects are organised on a <quote>train</quote> basis: a release is
   1.269 +scheduled to happen every few months, and whatever features are ready
   1.270 +when the <quote>train</quote> is ready to leave are allowed in.
   1.271 +</para>
   1.272 +
   1.273 +<para>This model resembles working with feature branches.  The difference is
   1.274 +that when a feature branch misses a train, someone on the feature team
   1.275 +pulls and merges the changes that went out on that train release into
   1.276 +the feature branch, and the team continues its work on top of that
   1.277 +release so that their feature can make the next release.
   1.278 +</para>
   1.279 +
   1.280 +</sect2>
   1.281 +<sect2>
   1.282 +<title>The Linux kernel model</title>
   1.283 +
   1.284 +<para>The development of the Linux kernel has a shallow hierarchical
   1.285 +structure, surrounded by a cloud of apparent chaos.  Because most
   1.286 +Linux developers use <command>git</command>, a distributed revision control
   1.287 +tool with capabilities similar to Mercurial, it's useful to describe
   1.288 +the way work flows in that environment; if you like the ideas, the
   1.289 +approach translates well across tools.
   1.290 +</para>
   1.291 +
   1.292 +<para>At the center of the community sits Linus Torvalds, the creator of
   1.293 +Linux.  He publishes a single source repository that is considered the
   1.294 +<quote>authoritative</quote> current tree by the entire developer community.
   1.295 +Anyone can clone Linus's tree, but he is very choosy about whose trees
   1.296 +he pulls from.
   1.297 +</para>
   1.298 +
   1.299 +<para>Linus has a number of <quote>trusted lieutenants</quote>.  As a general rule, he
   1.300 +pulls whatever changes they publish, in most cases without even
   1.301 +reviewing those changes.  Some of those lieutenants are generally
   1.302 +agreed to be <quote>maintainers</quote>, responsible for specific subsystems
   1.303 +within the kernel.  If a random kernel hacker wants to make a change
   1.304 +to a subsystem that they want to end up in Linus's tree, they must
   1.305 +find out who the subsystem's maintainer is, and ask that maintainer to
   1.306 +take their change.  If the maintainer reviews their changes and agrees
   1.307 +to take them, they'll pass them along to Linus in due course.
   1.308 +</para>
   1.309 +
   1.310 +<para>Individual lieutenants have their own approaches to reviewing,
   1.311 +accepting, and publishing changes; and for deciding when to feed them
   1.312 +to Linus.  In addition, there are several well known branches that
   1.313 +people use for different purposes.  For example, a few people maintain
   1.314 +<quote>stable</quote> repositories of older versions of the kernel, to which they
   1.315 +apply critical fixes as needed.  Some maintainers publish multiple
   1.316 +trees: one for experimental changes; one for changes that they are
   1.317 +about to feed upstream; and so on.  Others just publish a single
   1.318 +tree.
   1.319 +</para>
   1.320 +
   1.321 +<para>This model has two notable features.  The first is that it's <quote>pull
   1.322 +only</quote>.  You have to ask, convince, or beg another developer to take a
   1.323 +change from you, because there are almost no trees to which more than
   1.324 +one person can push, and there's no way to push changes into a tree
   1.325 +that someone else controls.
   1.326 +</para>
   1.327 +
   1.328 +<para>The second is that it's based on reputation and acclaim.  If you're an
   1.329 +unknown, Linus will probably ignore changes from you without even
   1.330 +responding.  But a subsystem maintainer will probably review them, and
   1.331 +will likely take them if they pass their criteria for suitability.
   1.332 +The more <quote>good</quote> changes you contribute to a maintainer, the more
   1.333 +likely they are to trust your judgment and accept your changes.  If
   1.334 +you're well-known and maintain a long-lived branch for something Linus
   1.335 +hasn't yet accepted, people with similar interests may pull your
   1.336 +changes regularly to keep up with your work.
   1.337 +</para>
   1.338 +
   1.339 +<para>Reputation and acclaim don't necessarily cross subsystem or <quote>people</quote>
   1.340 +boundaries.  If you're a respected but specialised storage hacker, and
   1.341 +you try to fix a networking bug, that change will receive a level of
   1.342 +scrutiny from a network maintainer comparable to a change from a
   1.343 +complete stranger.
   1.344 +</para>
   1.345 +
   1.346 +<para>To people who come from more orderly project backgrounds, the
   1.347 +comparatively chaotic Linux kernel development process often seems
   1.348 +completely insane.  It's subject to the whims of individuals; people
   1.349 +make sweeping changes whenever they deem it appropriate; and the pace
   1.350 +of development is astounding.  And yet Linux is a highly successful,
   1.351 +well-regarded piece of software.
   1.352 +</para>
   1.353 +
   1.354 +</sect2>
   1.355 +<sect2>
   1.356 +<title>Pull-only versus shared-push collaboration</title>
   1.357 +
   1.358 +<para>A perpetual source of heat in the open source community is whether a
   1.359 +development model in which people only ever pull changes from others
   1.360 +is <quote>better than</quote> one in which multiple people can push changes to a
   1.361 +shared repository.
   1.362 +</para>
   1.363 +
   1.364 +<para>Typically, the backers of the shared-push model use tools that
   1.365 +actively enforce this approach.  If you're using a centralised
   1.366 +revision control tool such as Subversion, there's no way to make a
   1.367 +choice over which model you'll use: the tool gives you shared-push,
   1.368 +and if you want to do anything else, you'll have to roll your own
   1.369 +approach on top (such as applying a patch by hand).
   1.370 +</para>
   1.371 +
   1.372 +<para>A good distributed revision control tool, such as Mercurial, will
   1.373 +support both models.  You and your collaborators can then structure
   1.374 +how you work together based on your own needs and preferences, not on
   1.375 +what contortions your tools force you into.
   1.376 +</para>
   1.377 +
   1.378 +</sect2>
   1.379 +<sect2>
   1.380 +<title>Where collaboration meets branch management</title>
   1.381 +
   1.382 +<para>Once you and your team set up some shared repositories and start
   1.383 +propagating changes back and forth between local and shared repos, you
   1.384 +begin to face a related, but slightly different challenge: that of
   1.385 +managing the multiple directions in which your team may be moving at
   1.386 +once.  Even though this subject is intimately related to how your team
   1.387 +collaborates, it's dense enough to merit treatment of its own, in
   1.388 +chapter <xref linkend="chap:branch"/>.
   1.389 +</para>
   1.390 +
   1.391 +</sect2>
   1.392 +</sect1>
   1.393 +<sect1>
   1.394 +<title>The technical side of sharing</title>
   1.395 +
   1.396 +<para>The remainder of this chapter is devoted to the question of serving
   1.397 +data to your collaborators.
   1.398 +</para>
   1.399 +
   1.400 +</sect1>
   1.401 +<sect1>
   1.402 +<title>Informal sharing with <command role="hg-cmd">hg serve</command></title>
   1.403 +<para>\label{sec:collab:serve}
   1.404 +</para>
   1.405 +
   1.406 +<para>Mercurial's <command role="hg-cmd">hg serve</command> command is wonderfully suited to small,
   1.407 +tight-knit, and fast-paced group environments.  It also provides a
   1.408 +great way to get a feel for using Mercurial commands over a network.
   1.409 +</para>
   1.410 +
   1.411 +<para>Run <command role="hg-cmd">hg serve</command> inside a repository, and in under a second it will
   1.412 +bring up a specialised HTTP server; this will accept connections from
   1.413 +any client, and serve up data for that repository until you terminate
   1.414 +it.  Anyone who knows the URL of the server you just started, and can
   1.415 +talk to your computer over the network, can then use a web browser or
   1.416 +Mercurial to read data from that repository.  A URL for a
   1.417 +<command role="hg-cmd">hg serve</command> instance running on a laptop is likely to look something
   1.418 +like <literal>http://my-laptop.local:8000/</literal>.
   1.419 +</para>
   1.420 +
   1.421 +<para>The <command role="hg-cmd">hg serve</command> command is <emphasis>not</emphasis> a general-purpose web server.
   1.422 +It can do only two things:
   1.423 +</para>
   1.424 +<itemizedlist>
   1.425 +<listitem><para>Allow people to browse the history of the repository it's
   1.426 +  serving, from their normal web browsers.
   1.427 +</para>
   1.428 +</listitem>
   1.429 +<listitem><para>Speak Mercurial's wire protocol, so that people can
   1.430 +  <command role="hg-cmd">hg clone</command> or <command role="hg-cmd">hg pull</command> changes from that repository.
   1.431 +</para>
   1.432 +</listitem></itemizedlist>
   1.433 +<para>In particular, <command role="hg-cmd">hg serve</command> won't allow remote users to <emphasis>modify</emphasis>
   1.434 +your repository.  It's intended for read-only use.
   1.435 +</para>
   1.436 +
   1.437 +<para>If you're getting started with Mercurial, there's nothing to prevent
   1.438 +you from using <command role="hg-cmd">hg serve</command> to serve up a repository on your own
   1.439 +computer, then use commands like <command role="hg-cmd">hg clone</command>, <command role="hg-cmd">hg incoming</command>, and
   1.440 +so on to talk to that server as if the repository was hosted remotely.
   1.441 +This can help you to quickly get acquainted with using commands on
   1.442 +network-hosted repositories.
   1.443 +</para>
   1.444 +
   1.445 +<sect2>
   1.446 +<title>A few things to keep in mind</title>
   1.447 +
   1.448 +<para>Because it provides unauthenticated read access to all clients, you
   1.449 +should only use <command role="hg-cmd">hg serve</command> in an environment where you either don't
   1.450 +care, or have complete control over, who can access your network and
   1.451 +pull data from your repository.
   1.452 +</para>
   1.453 +
   1.454 +<para>The <command role="hg-cmd">hg serve</command> command knows nothing about any firewall software
   1.455 +you might have installed on your system or network.  It cannot detect
   1.456 +or control your firewall software.  If other people are unable to talk
   1.457 +to a running <command role="hg-cmd">hg serve</command> instance, the second thing you should do
   1.458 +(<emphasis>after</emphasis> you make sure that they're using the correct URL) is
   1.459 +check your firewall configuration.
   1.460 +</para>
   1.461 +
   1.462 +<para>By default, <command role="hg-cmd">hg serve</command> listens for incoming connections on
   1.463 +port 8000.  If another process is already listening on the port you
   1.464 +want to use, you can specify a different port to listen on using the
   1.465 +<option role="hg-opt-serve">-p</option> option.
   1.466 +</para>
   1.467 +
   1.468 +<para>Normally, when <command role="hg-cmd">hg serve</command> starts, it prints no output, which can be
   1.469 +a bit unnerving.  If you'd like to confirm that it is indeed running
   1.470 +correctly, and find out what URL you should send to your
   1.471 +collaborators, start it with the <option role="hg-opt-global">-v</option> option.
   1.472 +</para>
   1.473 +
   1.474 +</sect2>
   1.475 +</sect1>
   1.476 +<sect1>
   1.477 +<title>Using the Secure Shell (ssh) protocol</title>
   1.478 +<para>\label{sec:collab:ssh}
   1.479 +</para>
   1.480 +
   1.481 +<para>You can pull and push changes securely over a network connection using
   1.482 +the Secure Shell (<literal>ssh</literal>) protocol.  To use this successfully,
   1.483 +you may have to do a little bit of configuration on the client or
   1.484 +server sides.
   1.485 +</para>
   1.486 +
   1.487 +<para>If you're not familiar with ssh, it's a network protocol that lets you
   1.488 +securely communicate with another computer.  To use it with Mercurial,
   1.489 +you'll be setting up one or more user accounts on a server so that
   1.490 +remote users can log in and execute commands.
   1.491 +</para>
   1.492 +
   1.493 +<para>(If you <emphasis>are</emphasis> familiar with ssh, you'll probably find some of the
   1.494 +material that follows to be elementary in nature.)
   1.495 +</para>
   1.496 +
   1.497 +<sect2>
   1.498 +<title>How to read and write ssh URLs</title>
   1.499 +
   1.500 +<para>An ssh URL tends to look like this:
   1.501 +</para>
   1.502 +<programlisting>
   1.503 +<para>  ssh://bos@hg.serpentine.com:22/hg/hgbook
   1.504 +</para>
   1.505 +</programlisting>
   1.506 +<orderedlist>
   1.507 +<listitem><para>The <quote><literal>ssh://</literal></quote> part tells Mercurial to use the ssh
   1.508 +  protocol.
   1.509 +</para>
   1.510 +</listitem>
   1.511 +<listitem><para>The <quote><literal>bos@</literal></quote> component indicates what username to log
   1.512 +  into the server as.  You can leave this out if the remote username
   1.513 +  is the same as your local username.
   1.514 +</para>
   1.515 +</listitem>
   1.516 +<listitem><para>The <quote><literal>hg.serpentine.com</literal></quote> gives the hostname of the
   1.517 +  server to log into.
   1.518 +</para>
   1.519 +</listitem>
   1.520 +<listitem><para>The <quote>:22</quote> identifies the port number to connect to the server
   1.521 +  on.  The default port is 22, so you only need to specify this part
   1.522 +  if you're <emphasis>not</emphasis> using port 22.
   1.523 +</para>
   1.524 +</listitem>
   1.525 +<listitem><para>The remainder of the URL is the local path to the repository on
   1.526 +  the server.
   1.527 +</para>
   1.528 +</listitem></orderedlist>
   1.529 +
   1.530 +<para>There's plenty of scope for confusion with the path component of ssh
   1.531 +URLs, as there is no standard way for tools to interpret it.  Some
   1.532 +programs behave differently than others when dealing with these paths.
   1.533 +This isn't an ideal situation, but it's unlikely to change.  Please
   1.534 +read the following paragraphs carefully.
   1.535 +</para>
   1.536 +
   1.537 +<para>Mercurial treats the path to a repository on the server as relative to
   1.538 +the remote user's home directory.  For example, if user <literal>foo</literal>
   1.539 +on the server has a home directory of <filename class="directory">/home/foo</filename>, then an ssh
   1.540 +URL that contains a path component of <filename class="directory">bar</filename>
   1.541 +<emphasis>really</emphasis> refers to the directory <filename class="directory">/home/foo/bar</filename>.
   1.542 +</para>
   1.543 +
   1.544 +<para>If you want to specify a path relative to another user's home
   1.545 +directory, you can use a path that starts with a tilde character
   1.546 +followed by the user's name (let's call them <literal>otheruser</literal>), like
   1.547 +this.
   1.548 +</para>
   1.549 +<programlisting>
   1.550 +<para>  ssh://server/ otheruser/hg/repo
   1.551 +</para>
   1.552 +</programlisting>
   1.553 +
   1.554 +<para>And if you really want to specify an <emphasis>absolute</emphasis> path on the
   1.555 +server, begin the path component with two slashes, as in this example.
   1.556 +</para>
   1.557 +<programlisting>
   1.558 +<para>  ssh://server//absolute/path
   1.559 +</para>
   1.560 +</programlisting>
   1.561 +
   1.562 +</sect2>
   1.563 +<sect2>
   1.564 +<title>Finding an ssh client for your system</title>
   1.565 +
   1.566 +<para>Almost every Unix-like system comes with OpenSSH preinstalled.  If
   1.567 +you're using such a system, run <literal>which ssh</literal> to find out if
   1.568 +the <command>ssh</command> command is installed (it's usually in
   1.569 +<filename class="directory">/usr/bin</filename>).  In the unlikely event that it isn't present,
   1.570 +take a look at your system documentation to figure out how to install
   1.571 +it.
   1.572 +</para>
   1.573 +
   1.574 +<para>On Windows, you'll first need to download a suitable ssh
   1.575 +client.  There are two alternatives.
   1.576 +</para>
   1.577 +<itemizedlist>
   1.578 +<listitem><para>Simon Tatham's excellent PuTTY package <citation>web:putty</citation> provides
   1.579 +  a complete suite of ssh client commands.
   1.580 +</para>
   1.581 +</listitem>
   1.582 +<listitem><para>If you have a high tolerance for pain, you can use the Cygwin
   1.583 +  port of OpenSSH.
   1.584 +</para>
   1.585 +</listitem></itemizedlist>
   1.586 +<para>In either case, you'll need to edit your \hgini\ file to tell
   1.587 +Mercurial where to find the actual client command.  For example, if
   1.588 +you're using PuTTY, you'll need to use the <command>plink</command> command as
   1.589 +a command-line ssh client.
   1.590 +</para>
   1.591 +<programlisting>
   1.592 +<para>  [ui]
   1.593 +  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
   1.594 +</para>
   1.595 +</programlisting>
   1.596 +
   1.597 +<note>
   1.598 +<para>  The path to <command>plink</command> shouldn't contain any whitespace
   1.599 +  characters, or Mercurial may not be able to run it correctly (so
   1.600 +  putting it in <filename class="directory">C:\\Program Files</filename> is probably not a good
   1.601 +  idea).
   1.602 +</para>
   1.603 +</note>
   1.604 +
   1.605 +</sect2>
   1.606 +<sect2>
   1.607 +<title>Generating a key pair</title>
   1.608 +
   1.609 +<para>To avoid the need to repetitively type a password every time you need
   1.610 +to use your ssh client, I recommend generating a key pair.  On a
   1.611 +Unix-like system, the <command>ssh-keygen</command> command will do the trick.
   1.612 +On Windows, if you're using PuTTY, the <command>puttygen</command> command is
   1.613 +what you'll need.
   1.614 +</para>
   1.615 +
   1.616 +<para>When you generate a key pair, it's usually <emphasis>highly</emphasis> advisable to
   1.617 +protect it with a passphrase.  (The only time that you might not want
   1.618 +to do this is when you're using the ssh protocol for automated tasks
   1.619 +on a secure network.)
   1.620 +</para>
   1.621 +
   1.622 +<para>Simply generating a key pair isn't enough, however.  You'll need to
   1.623 +add the public key to the set of authorised keys for whatever user
   1.624 +you're logging in remotely as.  For servers using OpenSSH (the vast
   1.625 +majority), this will mean adding the public key to a list in a file
   1.626 +called <filename role="special">authorized_keys</filename> in their <filename role="special" class="directory">.ssh</filename>
   1.627 +directory.
   1.628 +</para>
   1.629 +
   1.630 +<para>On a Unix-like system, your public key will have a <filename>.pub</filename>
   1.631 +extension.  If you're using <command>puttygen</command> on Windows, you can
   1.632 +save the public key to a file of your choosing, or paste it from the
   1.633 +window it's displayed in straight into the
   1.634 +<filename role="special">authorized_keys</filename> file.
   1.635 +</para>
   1.636 +
   1.637 +</sect2>
   1.638 +<sect2>
   1.639 +<title>Using an authentication agent</title>
   1.640 +
   1.641 +<para>An authentication agent is a daemon that stores passphrases in memory
   1.642 +(so it will forget passphrases if you log out and log back in again).
   1.643 +An ssh client will notice if it's running, and query it for a
   1.644 +passphrase.  If there's no authentication agent running, or the agent
   1.645 +doesn't store the necessary passphrase, you'll have to type your
   1.646 +passphrase every time Mercurial tries to communicate with a server on
   1.647 +your behalf (e.g. whenever you pull or push changes).
   1.648 +</para>
   1.649 +
   1.650 +<para>The downside of storing passphrases in an agent is that it's possible
   1.651 +for a well-prepared attacker to recover the plain text of your
   1.652 +passphrases, in some cases even if your system has been power-cycled.
   1.653 +You should make your own judgment as to whether this is an acceptable
   1.654 +risk.  It certainly saves a lot of repeated typing.
   1.655 +</para>
   1.656 +
   1.657 +<para>On Unix-like systems, the agent is called <command>ssh-agent</command>, and
   1.658 +it's often run automatically for you when you log in.  You'll need to
   1.659 +use the <command>ssh-add</command> command to add passphrases to the agent's
   1.660 +store.  On Windows, if you're using PuTTY, the <command>pageant</command>
   1.661 +command acts as the agent.  It adds an icon to your system tray that
   1.662 +will let you manage stored passphrases.
   1.663 +</para>
   1.664 +
   1.665 +</sect2>
   1.666 +<sect2>
   1.667 +<title>Configuring the server side properly</title>
   1.668 +
   1.669 +<para>Because ssh can be fiddly to set up if you're new to it, there's a
   1.670 +variety of things that can go wrong.  Add Mercurial on top, and
   1.671 +there's plenty more scope for head-scratching.  Most of these
   1.672 +potential problems occur on the server side, not the client side.  The
   1.673 +good news is that once you've gotten a configuration working, it will
   1.674 +usually continue to work indefinitely.
   1.675 +</para>
   1.676 +
   1.677 +<para>Before you try using Mercurial to talk to an ssh server, it's best to
   1.678 +make sure that you can use the normal <command>ssh</command> or <command>putty</command>
   1.679 +command to talk to the server first.  If you run into problems with
   1.680 +using these commands directly, Mercurial surely won't work.  Worse, it
   1.681 +will obscure the underlying problem.  Any time you want to debug
   1.682 +ssh-related Mercurial problems, you should drop back to making sure
   1.683 +that plain ssh client commands work first, <emphasis>before</emphasis> you worry
   1.684 +about whether there's a problem with Mercurial.
   1.685 +</para>
   1.686 +
   1.687 +<para>The first thing to be sure of on the server side is that you can
   1.688 +actually log in from another machine at all.  If you can't use
   1.689 +<command>ssh</command> or <command>putty</command> to log in, the error message you get
   1.690 +may give you a few hints as to what's wrong.  The most common problems
   1.691 +are as follows.
   1.692 +</para>
   1.693 +<itemizedlist>
   1.694 +<listitem><para>If you get a <quote>connection refused</quote> error, either there isn't an
   1.695 +  SSH daemon running on the server at all, or it's inaccessible due to
   1.696 +  firewall configuration.
   1.697 +</para>
   1.698 +</listitem>
   1.699 +<listitem><para>If you get a <quote>no route to host</quote> error, you either have an
   1.700 +  incorrect address for the server or a seriously locked down firewall
   1.701 +  that won't admit its existence at all.
   1.702 +</para>
   1.703 +</listitem>
   1.704 +<listitem><para>If you get a <quote>permission denied</quote> error, you may have mistyped
   1.705 +  the username on the server, or you could have mistyped your key's
   1.706 +  passphrase or the remote user's password.
   1.707 +</para>
   1.708 +</listitem></itemizedlist>
   1.709 +<para>In summary, if you're having trouble talking to the server's ssh
   1.710 +daemon, first make sure that one is running at all.  On many systems
   1.711 +it will be installed, but disabled, by default.  Once you're done with
   1.712 +this step, you should then check that the server's firewall is
   1.713 +configured to allow incoming connections on the port the ssh daemon is
   1.714 +listening on (usually 22).  Don't worry about more exotic
   1.715 +possibilities for misconfiguration until you've checked these two
   1.716 +first.
   1.717 +</para>
   1.718 +
   1.719 +<para>If you're using an authentication agent on the client side to store
   1.720 +passphrases for your keys, you ought to be able to log into the server
   1.721 +without being prompted for a passphrase or a password.  If you're
   1.722 +prompted for a passphrase, there are a few possible culprits.
   1.723 +</para>
   1.724 +<itemizedlist>
   1.725 +<listitem><para>You might have forgotten to use <command>ssh-add</command> or
   1.726 +  <command>pageant</command> to store the passphrase.
   1.727 +</para>
   1.728 +</listitem>
   1.729 +<listitem><para>You might have stored the passphrase for the wrong key.
   1.730 +</para>
   1.731 +</listitem></itemizedlist>
   1.732 +<para>If you're being prompted for the remote user's password, there are
   1.733 +another few possible problems to check.
   1.734 +</para>
   1.735 +<itemizedlist>
   1.736 +<listitem><para>Either the user's home directory or their <filename role="special" class="directory">.ssh</filename>
   1.737 +  directory might have excessively liberal permissions.  As a result,
   1.738 +  the ssh daemon will not trust or read their
   1.739 +  <filename role="special">authorized_keys</filename> file.  For example, a group-writable
   1.740 +  home or <filename role="special" class="directory">.ssh</filename> directory will often cause this symptom.
   1.741 +</para>
   1.742 +</listitem>
   1.743 +<listitem><para>The user's <filename role="special">authorized_keys</filename> file may have a problem.
   1.744 +  If anyone other than the user owns or can write to that file, the
   1.745 +  ssh daemon will not trust or read it.
   1.746 +</para>
   1.747 +</listitem></itemizedlist>
   1.748 +
   1.749 +<para>In the ideal world, you should be able to run the following command
   1.750 +successfully, and it should print exactly one line of output, the
   1.751 +current date and time.
   1.752 +</para>
   1.753 +<programlisting>
   1.754 +<para>  ssh myserver date
   1.755 +</para>
   1.756 +</programlisting>
   1.757 +
   1.758 +<para>If, on your server, you have login scripts that print banners or other
   1.759 +junk even when running non-interactive commands like this, you should
   1.760 +fix them before you continue, so that they only print output if
   1.761 +they're run interactively.  Otherwise these banners will at least
   1.762 +clutter up Mercurial's output.  Worse, they could potentially cause
   1.763 +problems with running Mercurial commands remotely.  Mercurial makes
   1.764 +tries to detect and ignore banners in non-interactive <command>ssh</command>
   1.765 +sessions, but it is not foolproof.  (If you're editing your login
   1.766 +scripts on your server, the usual way to see if a login script is
   1.767 +running in an interactive shell is to check the return code from the
   1.768 +command <literal>tty -s</literal>.)
   1.769 +</para>
   1.770 +
   1.771 +<para>Once you've verified that plain old ssh is working with your server,
   1.772 +the next step is to ensure that Mercurial runs on the server.  The
   1.773 +following command should run successfully:
   1.774 +</para>
   1.775 +<programlisting>
   1.776 +<para>  ssh myserver hg version
   1.777 +</para>
   1.778 +</programlisting>
   1.779 +<para>If you see an error message instead of normal <command role="hg-cmd">hg version</command> output,
   1.780 +this is usually because you haven't installed Mercurial to
   1.781 +<filename class="directory">/usr/bin</filename>.  Don't worry if this is the case; you don't need
   1.782 +to do that.  But you should check for a few possible problems.
   1.783 +</para>
   1.784 +<itemizedlist>
   1.785 +<listitem><para>Is Mercurial really installed on the server at all?  I know this
   1.786 +  sounds trivial, but it's worth checking!
   1.787 +</para>
   1.788 +</listitem>
   1.789 +<listitem><para>Maybe your shell's search path (usually set via the <envar>PATH</envar>
   1.790 +  environment variable) is simply misconfigured.
   1.791 +</para>
   1.792 +</listitem>
   1.793 +<listitem><para>Perhaps your <envar>PATH</envar> environment variable is only being set
   1.794 +  to point to the location of the <command>hg</command> executable if the login
   1.795 +  session is interactive.  This can happen if you're setting the path
   1.796 +  in the wrong shell login script.  See your shell's documentation for
   1.797 +  details.
   1.798 +</para>
   1.799 +</listitem>
   1.800 +<listitem><para>The <envar>PYTHONPATH</envar> environment variable may need to contain
   1.801 +  the path to the Mercurial Python modules.  It might not be set at
   1.802 +  all; it could be incorrect; or it may be set only if the login is
   1.803 +  interactive.
   1.804 +</para>
   1.805 +</listitem></itemizedlist>
   1.806 +
   1.807 +<para>If you can run <command role="hg-cmd">hg version</command> over an ssh connection, well done!
   1.808 +You've got the server and client sorted out.  You should now be able
   1.809 +to use Mercurial to access repositories hosted by that username on
   1.810 +that server.  If you run into problems with Mercurial and ssh at this
   1.811 +point, try using the <option role="hg-opt-global">--debug</option> option to get a clearer picture
   1.812 +of what's going on.
   1.813 +</para>
   1.814 +
   1.815 +</sect2>
   1.816 +<sect2>
   1.817 +<title>Using compression with ssh</title>
   1.818 +
   1.819 +<para>Mercurial does not compress data when it uses the ssh protocol,
   1.820 +because the ssh protocol can transparently compress data.  However,
   1.821 +the default behaviour of ssh clients is <emphasis>not</emphasis> to request
   1.822 +compression.
   1.823 +</para>
   1.824 +
   1.825 +<para>Over any network other than a fast LAN (even a wireless network),
   1.826 +using compression is likely to significantly speed up Mercurial's
   1.827 +network operations.  For example, over a WAN, someone measured
   1.828 +compression as reducing the amount of time required to clone a
   1.829 +particularly large repository from 51 minutes to 17 minutes.
   1.830 +</para>
   1.831 +
   1.832 +<para>Both <command>ssh</command> and <command>plink</command> accept a <option role="cmd-opt-ssh">-C</option>
   1.833 +option which turns on compression.  You can easily edit your <filename role="special"> /.hgrc</filename>\ to
   1.834 +enable compression for all of Mercurial's uses of the ssh protocol.
   1.835 +</para>
   1.836 +<programlisting>
   1.837 +<para>  [ui]
   1.838 +  ssh = ssh -C
   1.839 +</para>
   1.840 +</programlisting>
   1.841 +
   1.842 +<para>If you use <command>ssh</command>, you can configure it to always use
   1.843 +compression when talking to your server.  To do this, edit your
   1.844 +<filename role="special">.ssh/config</filename> file (which may not yet exist), as follows.
   1.845 +</para>
   1.846 +<programlisting>
   1.847 +<para>  Host hg
   1.848 +    Compression yes
   1.849 +    HostName hg.example.com
   1.850 +</para>
   1.851 +</programlisting>
   1.852 +<para>This defines an alias, <literal>hg</literal>.  When you use it on the
   1.853 +<command>ssh</command> command line or in a Mercurial <literal>ssh</literal>-protocol
   1.854 +URL, it will cause <command>ssh</command> to connect to <literal>hg.example.com</literal>
   1.855 +and use compression.  This gives you both a shorter name to type and
   1.856 +compression, each of which is a good thing in its own right.
   1.857 +</para>
   1.858 +
   1.859 +</sect2>
   1.860 +</sect1>
   1.861 +<sect1>
   1.862 +<title>Serving over HTTP using CGI</title>
   1.863 +<para>\label{sec:collab:cgi}
   1.864 +</para>
   1.865 +
   1.866 +<para>Depending on how ambitious you are, configuring Mercurial's CGI
   1.867 +interface can take anything from a few moments to several hours.
   1.868 +</para>
   1.869 +
   1.870 +<para>We'll begin with the simplest of examples, and work our way towards a
   1.871 +more complex configuration.  Even for the most basic case, you're
   1.872 +almost certainly going to need to read and modify your web server's
   1.873 +configuration.
   1.874 +</para>
   1.875 +
   1.876 +<note>
   1.877 +<para>  Configuring a web server is a complex, fiddly, and highly
   1.878 +  system-dependent activity.  I can't possibly give you instructions
   1.879 +  that will cover anything like all of the cases you will encounter.
   1.880 +  Please use your discretion and judgment in following the sections
   1.881 +  below.  Be prepared to make plenty of mistakes, and to spend a lot
   1.882 +  of time reading your server's error logs.
   1.883 +</para>
   1.884 +</note>
   1.885 +
   1.886 +<sect2>
   1.887 +<title>Web server configuration checklist</title>
   1.888 +
   1.889 +<para>Before you continue, do take a few moments to check a few aspects of
   1.890 +your system's setup.
   1.891 +</para>
   1.892 +
   1.893 +<orderedlist>
   1.894 +<listitem><para>Do you have a web server installed at all?  Mac OS X ships with
   1.895 +  Apache, but many other systems may not have a web server installed.
   1.896 +</para>
   1.897 +</listitem>
   1.898 +<listitem><para>If you have a web server installed, is it actually running?  On
   1.899 +  most systems, even if one is present, it will be disabled by
   1.900 +  default.
   1.901 +</para>
   1.902 +</listitem>
   1.903 +<listitem><para>Is your server configured to allow you to run CGI programs in
   1.904 +  the directory where you plan to do so?  Most servers default to
   1.905 +  explicitly disabling the ability to run CGI programs.
   1.906 +</para>
   1.907 +</listitem></orderedlist>
   1.908 +
   1.909 +<para>If you don't have a web server installed, and don't have substantial
   1.910 +experience configuring Apache, you should consider using the
   1.911 +<literal>lighttpd</literal> web server instead of Apache.  Apache has a
   1.912 +well-deserved reputation for baroque and confusing configuration.
   1.913 +While <literal>lighttpd</literal> is less capable in some ways than Apache, most
   1.914 +of these capabilities are not relevant to serving Mercurial
   1.915 +repositories.  And <literal>lighttpd</literal> is undeniably <emphasis>much</emphasis> easier
   1.916 +to get started with than Apache.
   1.917 +</para>
   1.918 +
   1.919 +</sect2>
   1.920 +<sect2>
   1.921 +<title>Basic CGI configuration</title>
   1.922 +
   1.923 +<para>On Unix-like systems, it's common for users to have a subdirectory
   1.924 +named something like <filename class="directory">public_html</filename> in their home directory,
   1.925 +from which they can serve up web pages.  A file named <filename>foo</filename>
   1.926 +in this directory will be accessible at a URL of the form
   1.927 +<literal>http://www.example.com/\ {</literal>username/foo}.
   1.928 +</para>
   1.929 +
   1.930 +<para>To get started, find the <filename role="special">hgweb.cgi</filename> script that should be
   1.931 +present in your Mercurial installation.  If you can't quickly find a
   1.932 +local copy on your system, simply download one from the master
   1.933 +Mercurial repository at
   1.934 +<ulink url="http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>.
   1.935 +</para>
   1.936 +
   1.937 +<para>You'll need to copy this script into your <filename class="directory">public_html</filename>
   1.938 +directory, and ensure that it's executable.
   1.939 +</para>
   1.940 +<programlisting>
   1.941 +<para>  cp .../hgweb.cgi  /public_html
   1.942 +  chmod 755  /public_html/hgweb.cgi
   1.943 +</para>
   1.944 +</programlisting>
   1.945 +<para>The <literal>755</literal> argument to <command>chmod</command> is a little more general
   1.946 +than just making the script executable: it ensures that the script is
   1.947 +executable by anyone, and that <quote>group</quote> and <quote>other</quote> write
   1.948 +permissions are <emphasis>not</emphasis> set.  If you were to leave those write
   1.949 +permissions enabled, Apache's <literal>suexec</literal> subsystem would likely
   1.950 +refuse to execute the script.  In fact, <literal>suexec</literal> also insists
   1.951 +that the <emphasis>directory</emphasis> in which the script resides must not be
   1.952 +writable by others.
   1.953 +</para>
   1.954 +<programlisting>
   1.955 +<para>  chmod 755  /public_html
   1.956 +</para>
   1.957 +</programlisting>
   1.958 +
   1.959 +<sect3>
   1.960 +<title>What could <emphasis>possibly</emphasis> go wrong?</title>
   1.961 +<para>\label{sec:collab:wtf}
   1.962 +</para>
   1.963 +
   1.964 +<para>Once you've copied the CGI script into place, go into a web browser,
   1.965 +and try to open the URL <ulink url="http://myhostname/ myuser/hgweb.cgi">http://myhostname/ myuser/hgweb.cgi</ulink>,
   1.966 +<emphasis>but</emphasis> brace yourself for instant failure.  There's a high
   1.967 +probability that trying to visit this URL will fail, and there are
   1.968 +many possible reasons for this.  In fact, you're likely to stumble
   1.969 +over almost every one of the possible errors below, so please read
   1.970 +carefully.  The following are all of the problems I ran into on a
   1.971 +system running Fedora 7, with a fresh installation of Apache, and a
   1.972 +user account that I created specially to perform this exercise.
   1.973 +</para>
   1.974 +
   1.975 +<para>Your web server may have per-user directories disabled.  If you're
   1.976 +using Apache, search your config file for a <literal>UserDir</literal>
   1.977 +directive.  If there's none present, per-user directories will be
   1.978 +disabled.  If one exists, but its value is <literal>disabled</literal>, then
   1.979 +per-user directories will be disabled.  Otherwise, the string after
   1.980 +<literal>UserDir</literal> gives the name of the subdirectory that Apache will
   1.981 +look in under your home directory, for example <filename class="directory">public_html</filename>.
   1.982 +</para>
   1.983 +
   1.984 +<para>Your file access permissions may be too restrictive.  The web server
   1.985 +must be able to traverse your home directory and directories under
   1.986 +your <filename class="directory">public_html</filename> directory, and read files under the latter
   1.987 +too.  Here's a quick recipe to help you to make your permissions more
   1.988 +appropriate.
   1.989 +</para>
   1.990 +<programlisting>
   1.991 +<para>  chmod 755  
   1.992 +  find  /public_html -type d -print0 | xargs -0r chmod 755
   1.993 +  find  /public_html -type f -print0 | xargs -0r chmod 644
   1.994 +</para>
   1.995 +</programlisting>
   1.996 +
   1.997 +<para>The other possibility with permissions is that you might get a
   1.998 +completely empty window when you try to load the script.  In this
   1.999 +case, it's likely that your access permissions are \emph{too
  1.1000 +  permissive}.  Apache's <literal>suexec</literal> subsystem won't execute a
  1.1001 +script that's group- or world-writable, for example.
  1.1002 +</para>
  1.1003 +
  1.1004 +<para>Your web server may be configured to disallow execution of CGI
  1.1005 +programs in your per-user web directory.  Here's Apache's
  1.1006 +default per-user configuration from my Fedora system.
  1.1007 +</para>
  1.1008 +<programlisting>
  1.1009 +<para>  &lt;Directory /home/*/public_html&gt;
  1.1010 +      AllowOverride FileInfo AuthConfig Limit
  1.1011 +      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
  1.1012 +      &lt;Limit GET POST OPTIONS&gt;
  1.1013 +          Order allow,deny
  1.1014 +          Allow from all
  1.1015 +      &lt;/Limit&gt;
  1.1016 +      &lt;LimitExcept GET POST OPTIONS&gt;
  1.1017 +          Order deny,allow
  1.1018 +          Deny from all
  1.1019 +      &lt;/LimitExcept&gt;
  1.1020 +  &lt;/Directory&gt;
  1.1021 +</para>
  1.1022 +</programlisting>
  1.1023 +<para>If you find a similar-looking <literal>Directory</literal> group in your Apache
  1.1024 +configuration, the directive to look at inside it is <literal>Options</literal>.
  1.1025 +Add <literal>ExecCGI</literal> to the end of this list if it's missing, and
  1.1026 +restart the web server.
  1.1027 +</para>
  1.1028 +
  1.1029 +<para>If you find that Apache serves you the text of the CGI script instead
  1.1030 +of executing it, you may need to either uncomment (if already present)
  1.1031 +or add a directive like this.
  1.1032 +</para>
  1.1033 +<programlisting>
  1.1034 +<para>  AddHandler cgi-script .cgi
  1.1035 +</para>
  1.1036 +</programlisting>
  1.1037 +
  1.1038 +<para>The next possibility is that you might be served with a colourful
  1.1039 +Python backtrace claiming that it can't import a
  1.1040 +<literal>mercurial</literal>-related module.  This is actually progress!  The
  1.1041 +server is now capable of executing your CGI script.  This error is
  1.1042 +only likely to occur if you're running a private installation of
  1.1043 +Mercurial, instead of a system-wide version.  Remember that the web
  1.1044 +server runs the CGI program without any of the environment variables
  1.1045 +that you take for granted in an interactive session.  If this error
  1.1046 +happens to you, edit your copy of <filename role="special">hgweb.cgi</filename> and follow the
  1.1047 +directions inside it to correctly set your <envar>PYTHONPATH</envar>
  1.1048 +environment variable.
  1.1049 +</para>
  1.1050 +
  1.1051 +<para>Finally, you are <emphasis>certain</emphasis> to by served with another colourful
  1.1052 +Python backtrace: this one will complain that it can't find
  1.1053 +<filename class="directory">/path/to/repository</filename>.  Edit your <filename role="special">hgweb.cgi</filename> script
  1.1054 +and replace the <filename class="directory">/path/to/repository</filename> string with the complete
  1.1055 +path to the repository you want to serve up.
  1.1056 +</para>
  1.1057 +
  1.1058 +<para>At this point, when you try to reload the page, you should be
  1.1059 +presented with a nice HTML view of your repository's history.  Whew!
  1.1060 +</para>
  1.1061 +
  1.1062 +</sect3>
  1.1063 +<sect3>
  1.1064 +<title>Configuring lighttpd</title>
  1.1065 +
  1.1066 +<para>To be exhaustive in my experiments, I tried configuring the
  1.1067 +increasingly popular <literal>lighttpd</literal> web server to serve the same
  1.1068 +repository as I described with Apache above.  I had already overcome
  1.1069 +all of the problems I outlined with Apache, many of which are not
  1.1070 +server-specific.  As a result, I was fairly sure that my file and
  1.1071 +directory permissions were good, and that my <filename role="special">hgweb.cgi</filename>
  1.1072 +script was properly edited.
  1.1073 +</para>
  1.1074 +
  1.1075 +<para>Once I had Apache running, getting <literal>lighttpd</literal> to serve the
  1.1076 +repository was a snap (in other words, even if you're trying to use
  1.1077 +<literal>lighttpd</literal>, you should read the Apache section).  I first had
  1.1078 +to edit the <literal>mod_access</literal> section of its config file to enable
  1.1079 +<literal>mod_cgi</literal> and <literal>mod_userdir</literal>, both of which were
  1.1080 +disabled by default on my system.  I then added a few lines to the end
  1.1081 +of the config file, to configure these modules.
  1.1082 +</para>
  1.1083 +<programlisting>
  1.1084 +<para>  userdir.path = "public_html"
  1.1085 +  cgi.assign = ( ".cgi" =&gt; "" )
  1.1086 +</para>
  1.1087 +</programlisting>
  1.1088 +<para>With this done, <literal>lighttpd</literal> ran immediately for me.  If I had
  1.1089 +configured <literal>lighttpd</literal> before Apache, I'd almost certainly have
  1.1090 +run into many of the same system-level configuration problems as I did
  1.1091 +with Apache.  However, I found <literal>lighttpd</literal> to be noticeably
  1.1092 +easier to configure than Apache, even though I've used Apache for over
  1.1093 +a decade, and this was my first exposure to <literal>lighttpd</literal>.
  1.1094 +</para>
  1.1095 +
  1.1096 +</sect3>
  1.1097 +</sect2>
  1.1098 +<sect2>
  1.1099 +<title>Sharing multiple repositories with one CGI script</title>
  1.1100 +
  1.1101 +<para>The <filename role="special">hgweb.cgi</filename> script only lets you publish a single
  1.1102 +repository, which is an annoying restriction.  If you want to publish
  1.1103 +more than one without wracking yourself with multiple copies of the
  1.1104 +same script, each with different names, a better choice is to use the
  1.1105 +<filename role="special">hgwebdir.cgi</filename> script.
  1.1106 +</para>
  1.1107 +
  1.1108 +<para>The procedure to configure <filename role="special">hgwebdir.cgi</filename> is only a little
  1.1109 +more involved than for <filename role="special">hgweb.cgi</filename>.  First, you must obtain
  1.1110 +a copy of the script.  If you don't have one handy, you can download a
  1.1111 +copy from the master Mercurial repository at
  1.1112 +<ulink url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.
  1.1113 +</para>
  1.1114 +
  1.1115 +<para>You'll need to copy this script into your <filename class="directory">public_html</filename>
  1.1116 +directory, and ensure that it's executable.
  1.1117 +</para>
  1.1118 +<programlisting>
  1.1119 +<para>  cp .../hgwebdir.cgi  /public_html
  1.1120 +  chmod 755  /public_html  /public_html/hgwebdir.cgi
  1.1121 +</para>
  1.1122 +</programlisting>
  1.1123 +<para>With basic configuration out of the way, try to visit
  1.1124 +<ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink> in your browser.  It
  1.1125 +should display an empty list of repositories.  If you get a blank
  1.1126 +window or error message, try walking through the list of potential
  1.1127 +problems in section <xref linkend="sec:collab:wtf"/>.
  1.1128 +</para>
  1.1129 +
  1.1130 +<para>The <filename role="special">hgwebdir.cgi</filename> script relies on an external
  1.1131 +configuration file.  By default, it searches for a file named
  1.1132 +<filename role="special">hgweb.config</filename> in the same directory as itself.  You'll need
  1.1133 +to create this file, and make it world-readable.  The format of the
  1.1134 +file is similar to a Windows <quote>ini</quote> file, as understood by Python's
  1.1135 +<literal>ConfigParser</literal> <citation>web:configparser</citation> module.
  1.1136 +</para>
  1.1137 +
  1.1138 +<para>The easiest way to configure <filename role="special">hgwebdir.cgi</filename> is with a
  1.1139 +section named <literal>collections</literal>.  This will automatically publish
  1.1140 +<emphasis>every</emphasis> repository under the directories you name.  The section
  1.1141 +should look like this:
  1.1142 +</para>
  1.1143 +<programlisting>
  1.1144 +<para>  [collections]
  1.1145 +  /my/root = /my/root
  1.1146 +</para>
  1.1147 +</programlisting>
  1.1148 +<para>Mercurial interprets this by looking at the directory name on the
  1.1149 +<emphasis>right</emphasis> hand side of the <quote><literal>=</literal></quote> sign; finding
  1.1150 +repositories in that directory hierarchy; and using the text on the
  1.1151 +<emphasis>left</emphasis> to strip off matching text from the names it will actually
  1.1152 +list in the web interface.  The remaining component of a path after
  1.1153 +this stripping has occurred is called a <quote>virtual path</quote>.
  1.1154 +</para>
  1.1155 +
  1.1156 +<para>Given the example above, if we have a repository whose local path is
  1.1157 +<filename class="directory">/my/root/this/repo</filename>, the CGI script will strip the leading
  1.1158 +<filename class="directory">/my/root</filename> from the name, and publish the repository with a
  1.1159 +virtual path of <filename class="directory">this/repo</filename>.  If the base URL for our CGI
  1.1160 +script is <ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink>, the complete
  1.1161 +URL for that repository will be
  1.1162 +<ulink url="http://myhostname/ myuser/hgwebdir.cgi/this/repo">http://myhostname/ myuser/hgwebdir.cgi/this/repo</ulink>.
  1.1163 +</para>
  1.1164 +
  1.1165 +<para>If we replace <filename class="directory">/my/root</filename> on the left hand side of this example
  1.1166 +with <filename class="directory">/my</filename>, then <filename role="special">hgwebdir.cgi</filename> will only strip off
  1.1167 +<filename class="directory">/my</filename> from the repository name, and will give us a virtual
  1.1168 +path of <filename class="directory">root/this/repo</filename> instead of <filename class="directory">this/repo</filename>.
  1.1169 +</para>
  1.1170 +
  1.1171 +<para>The <filename role="special">hgwebdir.cgi</filename> script will recursively search each
  1.1172 +directory listed in the <literal>collections</literal> section of its
  1.1173 +configuration file, but it will <literal>not</literal> recurse into the
  1.1174 +repositories it finds.
  1.1175 +</para>
  1.1176 +
  1.1177 +<para>The <literal>collections</literal> mechanism makes it easy to publish many
  1.1178 +repositories in a <quote>fire and forget</quote> manner.  You only need to set up
  1.1179 +the CGI script and configuration file one time.  Afterwards, you can
  1.1180 +publish or unpublish a repository at any time by simply moving it
  1.1181 +into, or out of, the directory hierarchy in which you've configured
  1.1182 +<filename role="special">hgwebdir.cgi</filename> to look.
  1.1183 +</para>
  1.1184 +
  1.1185 +<sect3>
  1.1186 +<title>Explicitly specifying which repositories to publish</title>
  1.1187 +
  1.1188 +<para>In addition to the <literal>collections</literal> mechanism, the
  1.1189 +<filename role="special">hgwebdir.cgi</filename> script allows you to publish a specific list
  1.1190 +of repositories.  To do so, create a <literal>paths</literal> section, with
  1.1191 +contents of the following form.
  1.1192 +</para>
  1.1193 +<programlisting>
  1.1194 +<para>  [paths]
  1.1195 +  repo1 = /my/path/to/some/repo
  1.1196 +  repo2 = /some/path/to/another
  1.1197 +</para>
  1.1198 +</programlisting>
  1.1199 +<para>In this case, the virtual path (the component that will appear in a
  1.1200 +URL) is on the left hand side of each definition, while the path to
  1.1201 +the repository is on the right.  Notice that there does not need to be
  1.1202 +any relationship between the virtual path you choose and the location
  1.1203 +of a repository in your filesystem.
  1.1204 +</para>
  1.1205 +
  1.1206 +<para>If you wish, you can use both the <literal>collections</literal> and
  1.1207 +<literal>paths</literal> mechanisms simultaneously in a single configuration
  1.1208 +file.
  1.1209 +</para>
  1.1210 +
  1.1211 +<note>
  1.1212 +<para>  If multiple repositories have the same virtual path,
  1.1213 +  <filename role="special">hgwebdir.cgi</filename> will not report an error.  Instead, it will
  1.1214 +  behave unpredictably.
  1.1215 +</para>
  1.1216 +</note>
  1.1217 +
  1.1218 +</sect3>
  1.1219 +</sect2>
  1.1220 +<sect2>
  1.1221 +<title>Downloading source archives</title>
  1.1222 +
  1.1223 +<para>Mercurial's web interface lets users download an archive of any
  1.1224 +revision.  This archive will contain a snapshot of the working
  1.1225 +directory as of that revision, but it will not contain a copy of the
  1.1226 +repository data.
  1.1227 +</para>
  1.1228 +
  1.1229 +<para>By default, this feature is not enabled.  To enable it, you'll need to
  1.1230 +add an <envar role="rc-item-web">allow_archive</envar> item to the <literal role="rc-web">web</literal>
  1.1231 +section of your <filename role="special"> /.hgrc</filename>.
  1.1232 +</para>
  1.1233 +
  1.1234 +</sect2>
  1.1235 +<sect2>
  1.1236 +<title>Web configuration options</title>
  1.1237 +
  1.1238 +<para>Mercurial's web interfaces (the <command role="hg-cmd">hg serve</command> command, and the
  1.1239 +<filename role="special">hgweb.cgi</filename> and <filename role="special">hgwebdir.cgi</filename> scripts) have a
  1.1240 +number of configuration options that you can set.  These belong in a
  1.1241 +section named <literal role="rc-web">web</literal>.
  1.1242 +</para>
  1.1243 +<itemizedlist>
  1.1244 +<listitem><para><envar role="rc-item-web">allow_archive</envar>: Determines which (if any) archive
  1.1245 +  download mechanisms Mercurial supports.  If you enable this
  1.1246 +  feature, users of the web interface will be able to download an
  1.1247 +  archive of whatever revision of a repository they are viewing.
  1.1248 +  To enable the archive feature, this item must take the form of a
  1.1249 +  sequence of words drawn from the list below.
  1.1250 +</para>
  1.1251 +</listitem><itemizedlist>
  1.1252 +<listitem><para>  \item <literal>bz2</literal>: A <command>tar</command> archive, compressed using
  1.1253 +    <literal>bzip2</literal> compression.  This has the best compression ratio,
  1.1254 +    but uses the most CPU time on the server.
  1.1255 +  \item <literal>gz</literal>: A <command>tar</command> archive, compressed using
  1.1256 +    <literal>gzip</literal> compression.
  1.1257 +  \item <literal>zip</literal>: A <command>zip</command> archive, compressed using LZW
  1.1258 +    compression.  This format has the worst compression ratio, but is
  1.1259 +    widely used in the Windows world.
  1.1260 +</para>
  1.1261 +</listitem></itemizedlist>
  1.1262 +<para>  If you provide an empty list, or don't have an
  1.1263 +  <envar role="rc-item-web">allow_archive</envar> entry at all, this feature will be
  1.1264 +  disabled.  Here is an example of how to enable all three supported
  1.1265 +  formats.
  1.1266 +</para>
  1.1267 +<programlisting>
  1.1268 +<para>    [web]
  1.1269 +    allow_archive = bz2 gz zip
  1.1270 +</para>
  1.1271 +</programlisting>
  1.1272 +<listitem><para><envar role="rc-item-web">allowpull</envar>: Boolean.  Determines whether the web
  1.1273 +  interface allows remote users to <command role="hg-cmd">hg pull</command> and <command role="hg-cmd">hg clone</command> this
  1.1274 +  repository over HTTP.  If set to <literal>no</literal> or <literal>false</literal>, only
  1.1275 +  the <quote>human-oriented</quote> portion of the web interface is available.
  1.1276 +</para>
  1.1277 +</listitem>
  1.1278 +<listitem><para><envar role="rc-item-web">contact</envar>: String.  A free-form (but preferably
  1.1279 +  brief) string identifying the person or group in charge of the
  1.1280 +  repository.  This often contains the name and email address of a
  1.1281 +  person or mailing list.  It often makes sense to place this entry in
  1.1282 +  a repository's own <filename role="special">.hg/hgrc</filename> file, but it can make sense
  1.1283 +  to use in a global <filename role="special"> /.hgrc</filename>\ if every repository has a single
  1.1284 +  maintainer.
  1.1285 +</para>
  1.1286 +</listitem>
  1.1287 +<listitem><para><envar role="rc-item-web">maxchanges</envar>: Integer.  The default maximum number
  1.1288 +  of changesets to display in a single page of output.
  1.1289 +</para>
  1.1290 +</listitem>
  1.1291 +<listitem><para><envar role="rc-item-web">maxfiles</envar>: Integer.  The default maximum number
  1.1292 +  of modified files to display in a single page of output.
  1.1293 +</para>
  1.1294 +</listitem>
  1.1295 +<listitem><para><envar role="rc-item-web">stripes</envar>: Integer.  If the web interface displays
  1.1296 +  alternating <quote>stripes</quote> to make it easier to visually align rows
  1.1297 +  when you are looking at a table, this number controls the number of
  1.1298 +  rows in each stripe.
  1.1299 +</para>
  1.1300 +</listitem>
  1.1301 +<listitem><para><envar role="rc-item-web">style</envar>: Controls the template Mercurial uses to
  1.1302 +  display the web interface.  Mercurial ships with two web templates,
  1.1303 +  named <literal>default</literal> and <literal>gitweb</literal> (the latter is much more
  1.1304 +  visually attractive).  You can also specify a custom template of
  1.1305 +  your own; see chapter <xref linkend="chap:template"/> for details.  Here, you
  1.1306 +  can see how to enable the <literal>gitweb</literal> style.
  1.1307 +</para>
  1.1308 +</listitem><programlisting>
  1.1309 +<listitem><para>    [web]
  1.1310 +    style = gitweb
  1.1311 +</para>
  1.1312 +</listitem></programlisting>
  1.1313 +</para>
  1.1314 +</listitem>
  1.1315 +<listitem><para><envar role="rc-item-web">templates</envar>: Path.  The directory in which to search
  1.1316 +  for template files.  By default, Mercurial searches in the directory
  1.1317 +  in which it was installed.
  1.1318 +</para>
  1.1319 +</listitem></itemizedlist>
  1.1320 +<para>If you are using <filename role="special">hgwebdir.cgi</filename>, you can place a few
  1.1321 +configuration items in a <literal role="rc-web">web</literal> section of the
  1.1322 +<filename role="special">hgweb.config</filename> file instead of a <filename role="special"> /.hgrc</filename>\ file, for
  1.1323 +convenience.  These items are <envar role="rc-item-web">motd</envar> and
  1.1324 +<envar role="rc-item-web">style</envar>.
  1.1325 +</para>
  1.1326 +
  1.1327 +<sect3>
  1.1328 +<title>Options specific to an individual repository</title>
  1.1329 +
  1.1330 +<para>A few <literal role="rc-web">web</literal> configuration items ought to be placed in a
  1.1331 +repository's local <filename role="special">.hg/hgrc</filename>, rather than a user's or
  1.1332 +global <filename role="special"> /.hgrc</filename>.
  1.1333 +</para>
  1.1334 +<itemizedlist>
  1.1335 +<listitem><para><envar role="rc-item-web">description</envar>: String.  A free-form (but preferably
  1.1336 +  brief) string that describes the contents or purpose of the
  1.1337 +  repository.
  1.1338 +</para>
  1.1339 +</listitem>
  1.1340 +<listitem><para><envar role="rc-item-web">name</envar>: String.  The name to use for the repository
  1.1341 +  in the web interface.  This overrides the default name, which is the
  1.1342 +  last component of the repository's path.
  1.1343 +</para>
  1.1344 +</listitem></itemizedlist>
  1.1345 +
  1.1346 +</sect3>
  1.1347 +<sect3>
  1.1348 +<title>Options specific to the <command role="hg-cmd">hg serve</command> command</title>
  1.1349 +
  1.1350 +<para>Some of the items in the <literal role="rc-web">web</literal> section of a <filename role="special"> /.hgrc</filename>\ file are
  1.1351 +only for use with the <command role="hg-cmd">hg serve</command> command.
  1.1352 +</para>
  1.1353 +<itemizedlist>
  1.1354 +<listitem><para><envar role="rc-item-web">accesslog</envar>: Path.  The name of a file into which to
  1.1355 +  write an access log.  By default, the <command role="hg-cmd">hg serve</command> command writes
  1.1356 +  this information to standard output, not to a file.  Log entries are
  1.1357 +  written in the standard <quote>combined</quote> file format used by almost all
  1.1358 +  web servers.
  1.1359 +</para>
  1.1360 +</listitem>
  1.1361 +<listitem><para><envar role="rc-item-web">address</envar>: String.  The local address on which the
  1.1362 +  server should listen for incoming connections.  By default, the
  1.1363 +  server listens on all addresses.
  1.1364 +</para>
  1.1365 +</listitem>
  1.1366 +<listitem><para><envar role="rc-item-web">errorlog</envar>: Path.  The name of a file into which to
  1.1367 +  write an error log.  By default, the <command role="hg-cmd">hg serve</command> command writes this
  1.1368 +  information to standard error, not to a file.
  1.1369 +</para>
  1.1370 +</listitem>
  1.1371 +<listitem><para><envar role="rc-item-web">ipv6</envar>: Boolean.  Whether to use the IPv6 protocol.
  1.1372 +  By default, IPv6 is not used.
  1.1373 +</para>
  1.1374 +</listitem>
  1.1375 +<listitem><para><envar role="rc-item-web">port</envar>: Integer.  The TCP port number on which the
  1.1376 +  server should listen.  The default port number used is 8000.
  1.1377 +</para>
  1.1378 +</listitem></itemizedlist>
  1.1379 +
  1.1380 +<para>\subsubsection{Choosing the right <filename role="special"> /.hgrc</filename>\ file to add <literal role="rc-web">web</literal>
  1.1381 +  items to}
  1.1382 +</para>
  1.1383 +
  1.1384 +<para>It is important to remember that a web server like Apache or
  1.1385 +<literal>lighttpd</literal> will run under a user ID that is different to yours.
  1.1386 +CGI scripts run by your server, such as <filename role="special">hgweb.cgi</filename>, will
  1.1387 +usually also run under that user ID.
  1.1388 +</para>
  1.1389 +
  1.1390 +<para>If you add <literal role="rc-web">web</literal> items to your own personal <filename role="special"> /.hgrc</filename>\ file, CGI
  1.1391 +scripts won't read that <filename role="special"> /.hgrc</filename>\ file.  Those settings will thus only
  1.1392 +affect the behaviour of the <command role="hg-cmd">hg serve</command> command when you run it.  To
  1.1393 +cause CGI scripts to see your settings, either create a <filename role="special"> /.hgrc</filename>\ file in
  1.1394 +the home directory of the user ID that runs your web server, or add
  1.1395 +those settings to a system-wide <filename role="special"> /.hgrc</filename>\ file.
  1.1396 +</para>
  1.1397 +
  1.1398 +
  1.1399 +</sect3>
  1.1400 +</sect2>
  1.1401 +</sect1>
  1.1402 +</chapter>
  1.1403 +
  1.1404 +<!--
  1.1405 +local variables: 
  1.1406 +sgml-parent-document: ("00book.xml" "book" "chapter")
  1.1407 +end:
  1.1408 +-->
  1.1409 \ No newline at end of file