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