1.1 --- a/es/Leame.1st	Fri Nov 07 21:33:22 2008 -0500
     1.2 +++ b/es/Leame.1st	Fri Nov 07 21:42:57 2008 -0500
     1.3 @@ -102,6 +102,7 @@
     1.4  || undo.tex        || Igor Támara   ||    100%    || 26/10/2008 ||  07/11/2008 ||
     1.5  || tour-merge.tex  || Javier Rojas  ||    100%    || 28/10/2008 ||  03/11/2008 ||
     1.6  || concepts.tex    || Javier Rojas  ||      7%    || 03/11/2008 ||             ||
     1.7 +|| intro.tex	   || Igor Támara   ||	    0%	  || 08/11/2008	||	       ||
     1.8  
     1.9  == Archivos en proceso de revisión ==
    1.10  ||'''archivo'''   || '''revisor''' ||'''Estado'''||'''Inicio'''||  '''Fin'''  ||

     2.1 --- a/es/cmdref.tex	Fri Nov 07 21:33:22 2008 -0500
     2.2 +++ b/es/cmdref.tex	Fri Nov 07 21:42:57 2008 -0500
     2.3 @@ -0,0 +1,176 @@
     2.4 +\chapter{Command reference}
     2.5 +\label{cmdref}
     2.6 +
     2.7 +\cmdref{add}{add files at the next commit}
     2.8 +\optref{add}{I}{include}
     2.9 +\optref{add}{X}{exclude}
    2.10 +\optref{add}{n}{dry-run}
    2.11 +
    2.12 +\cmdref{diff}{print changes in history or working directory}
    2.13 +
    2.14 +Show differences between revisions for the specified files or
    2.15 +directories, using the unified diff format.  For a description of the
    2.16 +unified diff format, see section~\ref{sec:mq:patch}.
    2.17 +
    2.18 +By default, this command does not print diffs for files that Mercurial
    2.19 +considers to contain binary data.  To control this behaviour, see the
    2.20 +\hgopt{diff}{-a} and \hgopt{diff}{--git} options.
    2.21 +
    2.22 +\subsection{Options}
    2.23 +
    2.24 +\loptref{diff}{nodates}
    2.25 +
    2.26 +Omit date and time information when printing diff headers.
    2.27 +
    2.28 +\optref{diff}{B}{ignore-blank-lines}
    2.29 +
    2.30 +Do not print changes that only insert or delete blank lines.  A line
    2.31 +that contains only whitespace is not considered blank.
    2.32 +
    2.33 +\optref{diff}{I}{include}
    2.34 +
    2.35 +Include files and directories whose names match the given patterns.
    2.36 +
    2.37 +\optref{diff}{X}{exclude}
    2.38 +
    2.39 +Exclude files and directories whose names match the given patterns.
    2.40 +
    2.41 +\optref{diff}{a}{text}
    2.42 +
    2.43 +If this option is not specified, \hgcmd{diff} will refuse to print
    2.44 +diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
    2.45 +forces \hgcmd{diff} to treat all files as text, and generate diffs for
    2.46 +all of them.
    2.47 +
    2.48 +This option is useful for files that are ``mostly text'' but have a
    2.49 +few embedded NUL characters.  If you use it on files that contain a
    2.50 +lot of binary data, its output will be incomprehensible.
    2.51 +
    2.52 +\optref{diff}{b}{ignore-space-change}
    2.53 +
    2.54 +Do not print a line if the only change to that line is in the amount
    2.55 +of white space it contains.
    2.56 +
    2.57 +\optref{diff}{g}{git}
    2.58 +
    2.59 +Print \command{git}-compatible diffs.  XXX reference a format
    2.60 +description.
    2.61 +
    2.62 +\optref{diff}{p}{show-function}
    2.63 +
    2.64 +Display the name of the enclosing function in a hunk header, using a
    2.65 +simple heuristic.  This functionality is enabled by default, so the
    2.66 +\hgopt{diff}{-p} option has no effect unless you change the value of
    2.67 +the \rcitem{diff}{showfunc} config item, as in the following example.
    2.68 +\interaction{cmdref.diff-p}
    2.69 +
    2.70 +\optref{diff}{r}{rev}
    2.71 +
    2.72 +Specify one or more revisions to compare.  The \hgcmd{diff} command
    2.73 +accepts up to two \hgopt{diff}{-r} options to specify the revisions to
    2.74 +compare.
    2.75 +
    2.76 +\begin{enumerate}
    2.77 +\setcounter{enumi}{0}
    2.78 +\item Display the differences between the parent revision of the
    2.79 +  working directory and the working directory.
    2.80 +\item Display the differences between the specified changeset and the
    2.81 +  working directory.
    2.82 +\item Display the differences between the two specified changesets.
    2.83 +\end{enumerate}
    2.84 +
    2.85 +You can specify two revisions using either two \hgopt{diff}{-r}
    2.86 +options or revision range notation.  For example, the two revision
    2.87 +specifications below are equivalent.
    2.88 +\begin{codesample2}
    2.89 +  hg diff -r 10 -r 20
    2.90 +  hg diff -r10:20
    2.91 +\end{codesample2}
    2.92 +
    2.93 +When you provide two revisions, Mercurial treats the order of those
    2.94 +revisions as significant.  Thus, \hgcmdargs{diff}{-r10:20} will
    2.95 +produce a diff that will transform files from their contents as of
    2.96 +revision~10 to their contents as of revision~20, while
    2.97 +\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will
    2.98 +transform files from their revision~20 contents to their revision~10
    2.99 +contents.  You cannot reverse the ordering in this way if you are
   2.100 +diffing against the working directory.
   2.101 +
   2.102 +\optref{diff}{w}{ignore-all-space}
   2.103 +
   2.104 +\cmdref{version}{print version and copyright information}
   2.105 +
   2.106 +This command displays the version of Mercurial you are running, and
   2.107 +its copyright license.  There are four kinds of version string that
   2.108 +you may see.
   2.109 +\begin{itemize}
   2.110 +\item The string ``\texttt{unknown}''. This version of Mercurial was
   2.111 +  not built in a Mercurial repository, and cannot determine its own
   2.112 +  version.
   2.113 +\item A short numeric string, such as ``\texttt{1.1}''. This is a
   2.114 +  build of a revision of Mercurial that was identified by a specific
   2.115 +  tag in the repository where it was built.  (This doesn't necessarily
   2.116 +  mean that you're running an official release; someone else could
   2.117 +  have added that tag to any revision in the repository where they
   2.118 +  built Mercurial.)
   2.119 +\item A hexadecimal string, such as ``\texttt{875489e31abe}''.  This
   2.120 +  is a build of the given revision of Mercurial.
   2.121 +\item A hexadecimal string followed by a date, such as
   2.122 +  ``\texttt{875489e31abe+20070205}''.  This is a build of the given
   2.123 +  revision of Mercurial, where the build repository contained some
   2.124 +  local changes that had not been committed.
   2.125 +\end{itemize}
   2.126 +
   2.127 +\subsection{Tips and tricks}
   2.128 +
   2.129 +\subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
   2.130 +  differ?}
   2.131 +\label{cmdref:diff-vs-status}
   2.132 +
   2.133 +When you run the \hgcmd{status} command, you'll see a list of files
   2.134 +that Mercurial will record changes for the next time you perform a
   2.135 +commit.  If you run the \hgcmd{diff} command, you may notice that it
   2.136 +prints diffs for only a \emph{subset} of the files that \hgcmd{status}
   2.137 +listed.  There are two possible reasons for this.
   2.138 +
   2.139 +The first is that \hgcmd{status} prints some kinds of modifications
   2.140 +that \hgcmd{diff} doesn't normally display.  The \hgcmd{diff} command
   2.141 +normally outputs unified diffs, which don't have the ability to
   2.142 +represent some changes that Mercurial can track.  Most notably,
   2.143 +traditional diffs can't represent a change in whether or not a file is
   2.144 +executable, but Mercurial records this information.
   2.145 +
   2.146 +If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
   2.147 +display \command{git}-compatible diffs that \emph{can} display this
   2.148 +extra information.
   2.149 +
   2.150 +The second possible reason that \hgcmd{diff} might be printing diffs
   2.151 +for a subset of the files displayed by \hgcmd{status} is that if you
   2.152 +invoke it without any arguments, \hgcmd{diff} prints diffs against the
   2.153 +first parent of the working directory.  If you have run \hgcmd{merge}
   2.154 +to merge two changesets, but you haven't yet committed the results of
   2.155 +the merge, your working directory has two parents (use \hgcmd{parents}
   2.156 +to see them).  While \hgcmd{status} prints modifications relative to
   2.157 +\emph{both} parents after an uncommitted merge, \hgcmd{diff} still
   2.158 +operates relative only to the first parent.  You can get it to print
   2.159 +diffs relative to the second parent by specifying that parent with the
   2.160 +\hgopt{diff}{-r} option.  There is no way to print diffs relative to
   2.161 +both parents.
   2.162 +
   2.163 +\subsubsection{Generating safe binary diffs}
   2.164 +
   2.165 +If you use the \hgopt{diff}{-a} option to force Mercurial to print
   2.166 +diffs of files that are either ``mostly text'' or contain lots of
   2.167 +binary data, those diffs cannot subsequently be applied by either
   2.168 +Mercurial's \hgcmd{import} command or the system's \command{patch}
   2.169 +command.  
   2.170 +
   2.171 +If you want to generate a diff of a binary file that is safe to use as
   2.172 +input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
   2.173 +generate the patch.  The system \command{patch} command cannot handle
   2.174 +binary patches at all.
   2.175 +
   2.176 +%%% Local Variables: 
   2.177 +%%% mode: latex
   2.178 +%%% TeX-master: "00book"
   2.179 +%%% End: 

     3.1 --- a/es/collab.tex	Fri Nov 07 21:33:22 2008 -0500
     3.2 +++ b/es/collab.tex	Fri Nov 07 21:42:57 2008 -0500
     3.3 @@ -0,0 +1,1118 @@
     3.4 +\chapter{Collaborating with other people}
     3.5 +\label{cha:collab}
     3.6 +
     3.7 +As a completely decentralised tool, Mercurial doesn't impose any
     3.8 +policy on how people ought to work with each other.  However, if
     3.9 +you're new to distributed revision control, it helps to have some
    3.10 +tools and examples in mind when you're thinking about possible
    3.11 +workflow models.
    3.12 +
    3.13 +\section{Mercurial's web interface}
    3.14 +
    3.15 +Mercurial has a powerful web interface that provides several 
    3.16 +useful capabilities.
    3.17 +
    3.18 +For interactive use, the web interface lets you browse a single
    3.19 +repository or a collection of repositories.  You can view the history
    3.20 +of a repository, examine each change (comments and diffs), and view
    3.21 +the contents of each directory and file.
    3.22 +
    3.23 +Also for human consumption, the web interface provides an RSS feed of
    3.24 +the changes in a repository.  This lets you ``subscribe'' to a
    3.25 +repository using your favourite feed reader, and be automatically
    3.26 +notified of activity in that repository as soon as it happens.  I find
    3.27 +this capability much more convenient than the model of subscribing to
    3.28 +a mailing list to which notifications are sent, as it requires no
    3.29 +additional configuration on the part of whoever is serving the
    3.30 +repository.
    3.31 +
    3.32 +The web interface also lets remote users clone a repository, pull
    3.33 +changes from it, and (when the server is configured to permit it) push
    3.34 +changes back to it.  Mercurial's HTTP tunneling protocol aggressively
    3.35 +compresses data, so that it works efficiently even over low-bandwidth
    3.36 +network connections.
    3.37 +
    3.38 +The easiest way to get started with the web interface is to use your
    3.39 +web browser to visit an existing repository, such as the master
    3.40 +Mercurial repository at
    3.41 +\url{http://www.selenic.com/repo/hg?style=gitweb}.
    3.42 +
    3.43 +If you're interested in providing a web interface to your own
    3.44 +repositories, Mercurial provides two ways to do this.  The first is
    3.45 +using the \hgcmd{serve} command, which is best suited to short-term
    3.46 +``lightweight'' serving.  See section~\ref{sec:collab:serve} below for
    3.47 +details of how to use this command.  If you have a long-lived
    3.48 +repository that you'd like to make permanently available, Mercurial
    3.49 +has built-in support for the CGI (Common Gateway Interface) standard,
    3.50 +which all common web servers support.  See
    3.51 +section~\ref{sec:collab:cgi} for details of CGI configuration.
    3.52 +
    3.53 +\section{Collaboration models}
    3.54 +
    3.55 +With a suitably flexible tool, making decisions about workflow is much
    3.56 +more of a social engineering challenge than a technical one.
    3.57 +Mercurial imposes few limitations on how you can structure the flow of
    3.58 +work in a project, so it's up to you and your group to set up and live
    3.59 +with a model that matches your own particular needs.
    3.60 +
    3.61 +\subsection{Factors to keep in mind}
    3.62 +
    3.63 +The most important aspect of any model that you must keep in mind is
    3.64 +how well it matches the needs and capabilities of the people who will
    3.65 +be using it.  This might seem self-evident; even so, you still can't
    3.66 +afford to forget it for a moment.
    3.67 +
    3.68 +I once put together a workflow model that seemed to make perfect sense
    3.69 +to me, but that caused a considerable amount of consternation and
    3.70 +strife within my development team.  In spite of my attempts to explain
    3.71 +why we needed a complex set of branches, and how changes ought to flow
    3.72 +between them, a few team members revolted.  Even though they were
    3.73 +smart people, they didn't want to pay attention to the constraints we
    3.74 +were operating under, or face the consequences of those constraints in
    3.75 +the details of the model that I was advocating.
    3.76 +
    3.77 +Don't sweep foreseeable social or technical problems under the rug.
    3.78 +Whatever scheme you put into effect, you should plan for mistakes and
    3.79 +problem scenarios.  Consider adding automated machinery to prevent, or
    3.80 +quickly recover from, trouble that you can anticipate.  As an example,
    3.81 +if you intend to have a branch with not-for-release changes in it,
    3.82 +you'd do well to think early about the possibility that someone might
    3.83 +accidentally merge those changes into a release branch.  You could
    3.84 +avoid this particular problem by writing a hook that prevents changes
    3.85 +from being merged from an inappropriate branch.
    3.86 +
    3.87 +\subsection{Informal anarchy}
    3.88 +
    3.89 +I wouldn't suggest an ``anything goes'' approach as something
    3.90 +sustainable, but it's a model that's easy to grasp, and it works
    3.91 +perfectly well in a few unusual situations.
    3.92 +
    3.93 +As one example, many projects have a loose-knit group of collaborators
    3.94 +who rarely physically meet each other.  Some groups like to overcome
    3.95 +the isolation of working at a distance by organising occasional
    3.96 +``sprints''.  In a sprint, a number of people get together in a single
    3.97 +location (a company's conference room, a hotel meeting room, that kind
    3.98 +of place) and spend several days more or less locked in there, hacking
    3.99 +intensely on a handful of projects.
   3.100 +
   3.101 +A sprint is the perfect place to use the \hgcmd{serve} command, since
   3.102 +\hgcmd{serve} does not requires any fancy server infrastructure.  You
   3.103 +can get started with \hgcmd{serve} in moments, by reading
   3.104 +section~\ref{sec:collab:serve} below.  Then simply tell the person
   3.105 +next to you that you're running a server, send the URL to them in an
   3.106 +instant message, and you immediately have a quick-turnaround way to
   3.107 +work together.  They can type your URL into their web browser and
   3.108 +quickly review your changes; or they can pull a bugfix from you and
   3.109 +verify it; or they can clone a branch containing a new feature and try
   3.110 +it out.
   3.111 +
   3.112 +The charm, and the problem, with doing things in an ad hoc fashion
   3.113 +like this is that only people who know about your changes, and where
   3.114 +they are, can see them.  Such an informal approach simply doesn't
   3.115 +scale beyond a handful people, because each individual needs to know
   3.116 +about $n$ different repositories to pull from.
   3.117 +
   3.118 +\subsection{A single central repository}
   3.119 +
   3.120 +For smaller projects migrating from a centralised revision control
   3.121 +tool, perhaps the easiest way to get started is to have changes flow
   3.122 +through a single shared central repository.  This is also the
   3.123 +most common ``building block'' for more ambitious workflow schemes.
   3.124 +
   3.125 +Contributors start by cloning a copy of this repository.  They can
   3.126 +pull changes from it whenever they need to, and some (perhaps all)
   3.127 +developers have permission to push a change back when they're ready
   3.128 +for other people to see it.
   3.129 +
   3.130 +Under this model, it can still often make sense for people to pull
   3.131 +changes directly from each other, without going through the central
   3.132 +repository.  Consider a case in which I have a tentative bug fix, but
   3.133 +I am worried that if I were to publish it to the central repository,
   3.134 +it might subsequently break everyone else's trees as they pull it.  To
   3.135 +reduce the potential for damage, I can ask you to clone my repository
   3.136 +into a temporary repository of your own and test it.  This lets us put
   3.137 +off publishing the potentially unsafe change until it has had a little
   3.138 +testing.
   3.139 +
   3.140 +In this kind of scenario, people usually use the \command{ssh}
   3.141 +protocol to securely push changes to the central repository, as
   3.142 +documented in section~\ref{sec:collab:ssh}.  It's also usual to
   3.143 +publish a read-only copy of the repository over HTTP using CGI, as in
   3.144 +section~\ref{sec:collab:cgi}.  Publishing over HTTP satisfies the
   3.145 +needs of people who don't have push access, and those who want to use
   3.146 +web browsers to browse the repository's history.
   3.147 +
   3.148 +\subsection{Working with multiple branches}
   3.149 +
   3.150 +Projects of any significant size naturally tend to make progress on
   3.151 +several fronts simultaneously.  In the case of software, it's common
   3.152 +for a project to go through periodic official releases.  A release
   3.153 +might then go into ``maintenance mode'' for a while after its first
   3.154 +publication; maintenance releases tend to contain only bug fixes, not
   3.155 +new features.  In parallel with these maintenance releases, one or
   3.156 +more future releases may be under development.  People normally use
   3.157 +the word ``branch'' to refer to one of these many slightly different
   3.158 +directions in which development is proceeding.
   3.159 +
   3.160 +Mercurial is particularly well suited to managing a number of
   3.161 +simultaneous, but not identical, branches.  Each ``development
   3.162 +direction'' can live in its own central repository, and you can merge
   3.163 +changes from one to another as the need arises.  Because repositories
   3.164 +are independent of each other, unstable changes in a development
   3.165 +branch will never affect a stable branch unless someone explicitly
   3.166 +merges those changes in.
   3.167 +
   3.168 +Here's an example of how this can work in practice.  Let's say you
   3.169 +have one ``main branch'' on a central server.
   3.170 +\interaction{branching.init}
   3.171 +People clone it, make changes locally, test them, and push them back.
   3.172 +
   3.173 +Once the main branch reaches a release milestone, you can use the
   3.174 +\hgcmd{tag} command to give a permanent name to the milestone
   3.175 +revision.
   3.176 +\interaction{branching.tag}
   3.177 +Let's say some ongoing development occurs on the main branch.
   3.178 +\interaction{branching.main}
   3.179 +Using the tag that was recorded at the milestone, people who clone
   3.180 +that repository at any time in the future can use \hgcmd{update} to
   3.181 +get a copy of the working directory exactly as it was when that tagged
   3.182 +revision was committed.  
   3.183 +\interaction{branching.update}
   3.184 +
   3.185 +In addition, immediately after the main branch is tagged, someone can
   3.186 +then clone the main branch on the server to a new ``stable'' branch,
   3.187 +also on the server.
   3.188 +\interaction{branching.clone}
   3.189 +
   3.190 +Someone who needs to make a change to the stable branch can then clone
   3.191 +\emph{that} repository, make their changes, commit, and push their
   3.192 +changes back there.
   3.193 +\interaction{branching.stable}
   3.194 +Because Mercurial repositories are independent, and Mercurial doesn't
   3.195 +move changes around automatically, the stable and main branches are
   3.196 +\emph{isolated} from each other.  The changes that you made on the
   3.197 +main branch don't ``leak'' to the stable branch, and vice versa.
   3.198 +
   3.199 +You'll often want all of your bugfixes on the stable branch to show up
   3.200 +on the main branch, too.  Rather than rewrite a bugfix on the main
   3.201 +branch, you can simply pull and merge changes from the stable to the
   3.202 +main branch, and Mercurial will bring those bugfixes in for you.
   3.203 +\interaction{branching.merge}
   3.204 +The main branch will still contain changes that are not on the stable
   3.205 +branch, but it will also contain all of the bugfixes from the stable
   3.206 +branch.  The stable branch remains unaffected by these changes.
   3.207 +
   3.208 +\subsection{Feature branches}
   3.209 +
   3.210 +For larger projects, an effective way to manage change is to break up
   3.211 +a team into smaller groups.  Each group has a shared branch of its
   3.212 +own, cloned from a single ``master'' branch used by the entire
   3.213 +project.  People working on an individual branch are typically quite
   3.214 +isolated from developments on other branches.
   3.215 +
   3.216 +\begin{figure}[ht]
   3.217 +  \centering
   3.218 +  \grafix{feature-branches}
   3.219 +  \caption{Feature branches}
   3.220 +  \label{fig:collab:feature-branches}
   3.221 +\end{figure}
   3.222 +
   3.223 +When a particular feature is deemed to be in suitable shape, someone
   3.224 +on that feature team pulls and merges from the master branch into the
   3.225 +feature branch, then pushes back up to the master branch.
   3.226 +
   3.227 +\subsection{The release train}
   3.228 +
   3.229 +Some projects are organised on a ``train'' basis: a release is
   3.230 +scheduled to happen every few months, and whatever features are ready
   3.231 +when the ``train'' is ready to leave are allowed in.
   3.232 +
   3.233 +This model resembles working with feature branches.  The difference is
   3.234 +that when a feature branch misses a train, someone on the feature team
   3.235 +pulls and merges the changes that went out on that train release into
   3.236 +the feature branch, and the team continues its work on top of that
   3.237 +release so that their feature can make the next release.
   3.238 +
   3.239 +\subsection{The Linux kernel model}
   3.240 +
   3.241 +The development of the Linux kernel has a shallow hierarchical
   3.242 +structure, surrounded by a cloud of apparent chaos.  Because most
   3.243 +Linux developers use \command{git}, a distributed revision control
   3.244 +tool with capabilities similar to Mercurial, it's useful to describe
   3.245 +the way work flows in that environment; if you like the ideas, the
   3.246 +approach translates well across tools.
   3.247 +
   3.248 +At the center of the community sits Linus Torvalds, the creator of
   3.249 +Linux.  He publishes a single source repository that is considered the
   3.250 +``authoritative'' current tree by the entire developer community.
   3.251 +Anyone can clone Linus's tree, but he is very choosy about whose trees
   3.252 +he pulls from.
   3.253 +
   3.254 +Linus has a number of ``trusted lieutenants''.  As a general rule, he
   3.255 +pulls whatever changes they publish, in most cases without even
   3.256 +reviewing those changes.  Some of those lieutenants are generally
   3.257 +agreed to be ``maintainers'', responsible for specific subsystems
   3.258 +within the kernel.  If a random kernel hacker wants to make a change
   3.259 +to a subsystem that they want to end up in Linus's tree, they must
   3.260 +find out who the subsystem's maintainer is, and ask that maintainer to
   3.261 +take their change.  If the maintainer reviews their changes and agrees
   3.262 +to take them, they'll pass them along to Linus in due course.
   3.263 +
   3.264 +Individual lieutenants have their own approaches to reviewing,
   3.265 +accepting, and publishing changes; and for deciding when to feed them
   3.266 +to Linus.  In addition, there are several well known branches that
   3.267 +people use for different purposes.  For example, a few people maintain
   3.268 +``stable'' repositories of older versions of the kernel, to which they
   3.269 +apply critical fixes as needed.  Some maintainers publish multiple
   3.270 +trees: one for experimental changes; one for changes that they are
   3.271 +about to feed upstream; and so on.  Others just publish a single
   3.272 +tree.
   3.273 +
   3.274 +This model has two notable features.  The first is that it's ``pull
   3.275 +only''.  You have to ask, convince, or beg another developer to take a
   3.276 +change from you, because there are almost no trees to which more than
   3.277 +one person can push, and there's no way to push changes into a tree
   3.278 +that someone else controls.
   3.279 +
   3.280 +The second is that it's based on reputation and acclaim.  If you're an
   3.281 +unknown, Linus will probably ignore changes from you without even
   3.282 +responding.  But a subsystem maintainer will probably review them, and
   3.283 +will likely take them if they pass their criteria for suitability.
   3.284 +The more ``good'' changes you contribute to a maintainer, the more
   3.285 +likely they are to trust your judgment and accept your changes.  If
   3.286 +you're well-known and maintain a long-lived branch for something Linus
   3.287 +hasn't yet accepted, people with similar interests may pull your
   3.288 +changes regularly to keep up with your work.
   3.289 +
   3.290 +Reputation and acclaim don't necessarily cross subsystem or ``people''
   3.291 +boundaries.  If you're a respected but specialised storage hacker, and
   3.292 +you try to fix a networking bug, that change will receive a level of
   3.293 +scrutiny from a network maintainer comparable to a change from a
   3.294 +complete stranger.
   3.295 +
   3.296 +To people who come from more orderly project backgrounds, the
   3.297 +comparatively chaotic Linux kernel development process often seems
   3.298 +completely insane.  It's subject to the whims of individuals; people
   3.299 +make sweeping changes whenever they deem it appropriate; and the pace
   3.300 +of development is astounding.  And yet Linux is a highly successful,
   3.301 +well-regarded piece of software.
   3.302 +
   3.303 +\subsection{Pull-only versus shared-push collaboration}
   3.304 +
   3.305 +A perpetual source of heat in the open source community is whether a
   3.306 +development model in which people only ever pull changes from others
   3.307 +is ``better than'' one in which multiple people can push changes to a
   3.308 +shared repository.
   3.309 +
   3.310 +Typically, the backers of the shared-push model use tools that
   3.311 +actively enforce this approach.  If you're using a centralised
   3.312 +revision control tool such as Subversion, there's no way to make a
   3.313 +choice over which model you'll use: the tool gives you shared-push,
   3.314 +and if you want to do anything else, you'll have to roll your own
   3.315 +approach on top (such as applying a patch by hand).
   3.316 +
   3.317 +A good distributed revision control tool, such as Mercurial, will
   3.318 +support both models.  You and your collaborators can then structure
   3.319 +how you work together based on your own needs and preferences, not on
   3.320 +what contortions your tools force you into.
   3.321 +
   3.322 +\subsection{Where collaboration meets branch management}
   3.323 +
   3.324 +Once you and your team set up some shared repositories and start
   3.325 +propagating changes back and forth between local and shared repos, you
   3.326 +begin to face a related, but slightly different challenge: that of
   3.327 +managing the multiple directions in which your team may be moving at
   3.328 +once.  Even though this subject is intimately related to how your team
   3.329 +collaborates, it's dense enough to merit treatment of its own, in
   3.330 +chapter~\ref{chap:branch}.
   3.331 +
   3.332 +\section{The technical side of sharing}
   3.333 +
   3.334 +The remainder of this chapter is devoted to the question of serving
   3.335 +data to your collaborators.
   3.336 +
   3.337 +\section{Informal sharing with \hgcmd{serve}}
   3.338 +\label{sec:collab:serve}
   3.339 +
   3.340 +Mercurial's \hgcmd{serve} command is wonderfully suited to small,
   3.341 +tight-knit, and fast-paced group environments.  It also provides a
   3.342 +great way to get a feel for using Mercurial commands over a network.
   3.343 +
   3.344 +Run \hgcmd{serve} inside a repository, and in under a second it will
   3.345 +bring up a specialised HTTP server; this will accept connections from
   3.346 +any client, and serve up data for that repository until you terminate
   3.347 +it.  Anyone who knows the URL of the server you just started, and can
   3.348 +talk to your computer over the network, can then use a web browser or
   3.349 +Mercurial to read data from that repository.  A URL for a
   3.350 +\hgcmd{serve} instance running on a laptop is likely to look something
   3.351 +like \Verb|http://my-laptop.local:8000/|.
   3.352 +
   3.353 +The \hgcmd{serve} command is \emph{not} a general-purpose web server.
   3.354 +It can do only two things:
   3.355 +\begin{itemize}
   3.356 +\item Allow people to browse the history of the repository it's
   3.357 +  serving, from their normal web browsers.
   3.358 +\item Speak Mercurial's wire protocol, so that people can
   3.359 +  \hgcmd{clone} or \hgcmd{pull} changes from that repository.
   3.360 +\end{itemize}
   3.361 +In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
   3.362 +your repository.  It's intended for read-only use.
   3.363 +
   3.364 +If you're getting started with Mercurial, there's nothing to prevent
   3.365 +you from using \hgcmd{serve} to serve up a repository on your own
   3.366 +computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
   3.367 +so on to talk to that server as if the repository was hosted remotely.
   3.368 +This can help you to quickly get acquainted with using commands on
   3.369 +network-hosted repositories.
   3.370 +
   3.371 +\subsection{A few things to keep in mind}
   3.372 +
   3.373 +Because it provides unauthenticated read access to all clients, you
   3.374 +should only use \hgcmd{serve} in an environment where you either don't
   3.375 +care, or have complete control over, who can access your network and
   3.376 +pull data from your repository.
   3.377 +
   3.378 +The \hgcmd{serve} command knows nothing about any firewall software
   3.379 +you might have installed on your system or network.  It cannot detect
   3.380 +or control your firewall software.  If other people are unable to talk
   3.381 +to a running \hgcmd{serve} instance, the second thing you should do
   3.382 +(\emph{after} you make sure that they're using the correct URL) is
   3.383 +check your firewall configuration.
   3.384 +
   3.385 +By default, \hgcmd{serve} listens for incoming connections on
   3.386 +port~8000.  If another process is already listening on the port you
   3.387 +want to use, you can specify a different port to listen on using the
   3.388 +\hgopt{serve}{-p} option.
   3.389 +
   3.390 +Normally, when \hgcmd{serve} starts, it prints no output, which can be
   3.391 +a bit unnerving.  If you'd like to confirm that it is indeed running
   3.392 +correctly, and find out what URL you should send to your
   3.393 +collaborators, start it with the \hggopt{-v} option.
   3.394 +
   3.395 +\section{Using the Secure Shell (ssh) protocol}
   3.396 +\label{sec:collab:ssh}
   3.397 +
   3.398 +You can pull and push changes securely over a network connection using
   3.399 +the Secure Shell (\texttt{ssh}) protocol.  To use this successfully,
   3.400 +you may have to do a little bit of configuration on the client or
   3.401 +server sides.
   3.402 +
   3.403 +If you're not familiar with ssh, it's a network protocol that lets you
   3.404 +securely communicate with another computer.  To use it with Mercurial,
   3.405 +you'll be setting up one or more user accounts on a server so that
   3.406 +remote users can log in and execute commands.
   3.407 +
   3.408 +(If you \emph{are} familiar with ssh, you'll probably find some of the
   3.409 +material that follows to be elementary in nature.)
   3.410 +
   3.411 +\subsection{How to read and write ssh URLs}
   3.412 +
   3.413 +An ssh URL tends to look like this:
   3.414 +\begin{codesample2}
   3.415 +  ssh://bos@hg.serpentine.com:22/hg/hgbook
   3.416 +\end{codesample2}
   3.417 +\begin{enumerate}
   3.418 +\item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh
   3.419 +  protocol.
   3.420 +\item The ``\texttt{bos@}'' component indicates what username to log
   3.421 +  into the server as.  You can leave this out if the remote username
   3.422 +  is the same as your local username.
   3.423 +\item The ``\texttt{hg.serpentine.com}'' gives the hostname of the
   3.424 +  server to log into.
   3.425 +\item The ``:22'' identifies the port number to connect to the server
   3.426 +  on.  The default port is~22, so you only need to specify this part
   3.427 +  if you're \emph{not} using port~22.
   3.428 +\item The remainder of the URL is the local path to the repository on
   3.429 +  the server.
   3.430 +\end{enumerate}
   3.431 +
   3.432 +There's plenty of scope for confusion with the path component of ssh
   3.433 +URLs, as there is no standard way for tools to interpret it.  Some
   3.434 +programs behave differently than others when dealing with these paths.
   3.435 +This isn't an ideal situation, but it's unlikely to change.  Please
   3.436 +read the following paragraphs carefully.
   3.437 +
   3.438 +Mercurial treats the path to a repository on the server as relative to
   3.439 +the remote user's home directory.  For example, if user \texttt{foo}
   3.440 +on the server has a home directory of \dirname{/home/foo}, then an ssh
   3.441 +URL that contains a path component of \dirname{bar}
   3.442 +\emph{really} refers to the directory \dirname{/home/foo/bar}.
   3.443 +
   3.444 +If you want to specify a path relative to another user's home
   3.445 +directory, you can use a path that starts with a tilde character
   3.446 +followed by the user's name (let's call them \texttt{otheruser}), like
   3.447 +this.
   3.448 +\begin{codesample2}
   3.449 +  ssh://server/~otheruser/hg/repo
   3.450 +\end{codesample2}
   3.451 +
   3.452 +And if you really want to specify an \emph{absolute} path on the
   3.453 +server, begin the path component with two slashes, as in this example.
   3.454 +\begin{codesample2}
   3.455 +  ssh://server//absolute/path
   3.456 +\end{codesample2}
   3.457 +
   3.458 +\subsection{Finding an ssh client for your system}
   3.459 +
   3.460 +Almost every Unix-like system comes with OpenSSH preinstalled.  If
   3.461 +you're using such a system, run \Verb|which ssh| to find out if
   3.462 +the \command{ssh} command is installed (it's usually in
   3.463 +\dirname{/usr/bin}).  In the unlikely event that it isn't present,
   3.464 +take a look at your system documentation to figure out how to install
   3.465 +it.
   3.466 +
   3.467 +On Windows, you'll first need to choose download a suitable ssh
   3.468 +client.  There are two alternatives.
   3.469 +\begin{itemize}
   3.470 +\item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides
   3.471 +  a complete suite of ssh client commands.
   3.472 +\item If you have a high tolerance for pain, you can use the Cygwin
   3.473 +  port of OpenSSH.
   3.474 +\end{itemize}
   3.475 +In either case, you'll need to edit your \hgini\ file to tell
   3.476 +Mercurial where to find the actual client command.  For example, if
   3.477 +you're using PuTTY, you'll need to use the \command{plink} command as
   3.478 +a command-line ssh client.
   3.479 +\begin{codesample2}
   3.480 +  [ui]
   3.481 +  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
   3.482 +\end{codesample2}
   3.483 +
   3.484 +\begin{note}
   3.485 +  The path to \command{plink} shouldn't contain any whitespace
   3.486 +  characters, or Mercurial may not be able to run it correctly (so
   3.487 +  putting it in \dirname{C:\\Program Files} is probably not a good
   3.488 +  idea).
   3.489 +\end{note}
   3.490 +
   3.491 +\subsection{Generating a key pair}
   3.492 +
   3.493 +To avoid the need to repetitively type a password every time you need
   3.494 +to use your ssh client, I recommend generating a key pair.  On a
   3.495 +Unix-like system, the \command{ssh-keygen} command will do the trick.
   3.496 +On Windows, if you're using PuTTY, the \command{puttygen} command is
   3.497 +what you'll need.
   3.498 +
   3.499 +When you generate a key pair, it's usually \emph{highly} advisable to
   3.500 +protect it with a passphrase.  (The only time that you might not want
   3.501 +to do this id when you're using the ssh protocol for automated tasks
   3.502 +on a secure network.)
   3.503 +
   3.504 +Simply generating a key pair isn't enough, however.  You'll need to
   3.505 +add the public key to the set of authorised keys for whatever user
   3.506 +you're logging in remotely as.  For servers using OpenSSH (the vast
   3.507 +majority), this will mean adding the public key to a list in a file
   3.508 +called \sfilename{authorized\_keys} in their \sdirname{.ssh}
   3.509 +directory.
   3.510 +
   3.511 +On a Unix-like system, your public key will have a \filename{.pub}
   3.512 +extension.  If you're using \command{puttygen} on Windows, you can
   3.513 +save the public key to a file of your choosing, or paste it from the
   3.514 +window it's displayed in straight into the
   3.515 +\sfilename{authorized\_keys} file.
   3.516 +
   3.517 +\subsection{Using an authentication agent}
   3.518 +
   3.519 +An authentication agent is a daemon that stores passphrases in memory
   3.520 +(so it will forget passphrases if you log out and log back in again).
   3.521 +An ssh client will notice if it's running, and query it for a
   3.522 +passphrase.  If there's no authentication agent running, or the agent
   3.523 +doesn't store the necessary passphrase, you'll have to type your
   3.524 +passphrase every time Mercurial tries to communicate with a server on
   3.525 +your behalf (e.g.~whenever you pull or push changes).
   3.526 +
   3.527 +The downside of storing passphrases in an agent is that it's possible
   3.528 +for a well-prepared attacker to recover the plain text of your
   3.529 +passphrases, in some cases even if your system has been power-cycled.
   3.530 +You should make your own judgment as to whether this is an acceptable
   3.531 +risk.  It certainly saves a lot of repeated typing.
   3.532 +
   3.533 +On Unix-like systems, the agent is called \command{ssh-agent}, and
   3.534 +it's often run automatically for you when you log in.  You'll need to
   3.535 +use the \command{ssh-add} command to add passphrases to the agent's
   3.536 +store.  On Windows, if you're using PuTTY, the \command{pageant}
   3.537 +command acts as the agent.  It adds an icon to your system tray that
   3.538 +will let you manage stored passphrases.
   3.539 +
   3.540 +\subsection{Configuring the server side properly}
   3.541 +
   3.542 +Because ssh can be fiddly to set up if you're new to it, there's a
   3.543 +variety of things that can go wrong.  Add Mercurial on top, and
   3.544 +there's plenty more scope for head-scratching.  Most of these
   3.545 +potential problems occur on the server side, not the client side.  The
   3.546 +good news is that once you've gotten a configuration working, it will
   3.547 +usually continue to work indefinitely.
   3.548 +
   3.549 +Before you try using Mercurial to talk to an ssh server, it's best to
   3.550 +make sure that you can use the normal \command{ssh} or \command{putty}
   3.551 +command to talk to the server first.  If you run into problems with
   3.552 +using these commands directly, Mercurial surely won't work.  Worse, it
   3.553 +will obscure the underlying problem.  Any time you want to debug
   3.554 +ssh-related Mercurial problems, you should drop back to making sure
   3.555 +that plain ssh client commands work first, \emph{before} you worry
   3.556 +about whether there's a problem with Mercurial.
   3.557 +
   3.558 +The first thing to be sure of on the server side is that you can
   3.559 +actually log in from another machine at all.  If you can't use
   3.560 +\command{ssh} or \command{putty} to log in, the error message you get
   3.561 +may give you a few hints as to what's wrong.  The most common problems
   3.562 +are as follows.
   3.563 +\begin{itemize}
   3.564 +\item If you get a ``connection refused'' error, either there isn't an
   3.565 +  SSH daemon running on the server at all, or it's inaccessible due to
   3.566 +  firewall configuration.
   3.567 +\item If you get a ``no route to host'' error, you either have an
   3.568 +  incorrect address for the server or a seriously locked down firewall
   3.569 +  that won't admit its existence at all.
   3.570 +\item If you get a ``permission denied'' error, you may have mistyped
   3.571 +  the username on the server, or you could have mistyped your key's
   3.572 +  passphrase or the remote user's password.
   3.573 +\end{itemize}
   3.574 +In summary, if you're having trouble talking to the server's ssh
   3.575 +daemon, first make sure that one is running at all.  On many systems
   3.576 +it will be installed, but disabled, by default.  Once you're done with
   3.577 +this step, you should then check that the server's firewall is
   3.578 +configured to allow incoming connections on the port the ssh daemon is
   3.579 +listening on (usually~22).  Don't worry about more exotic
   3.580 +possibilities for misconfiguration until you've checked these two
   3.581 +first.
   3.582 +
   3.583 +If you're using an authentication agent on the client side to store
   3.584 +passphrases for your keys, you ought to be able to log into the server
   3.585 +without being prompted for a passphrase or a password.  If you're
   3.586 +prompted for a passphrase, there are a few possible culprits.
   3.587 +\begin{itemize}
   3.588 +\item You might have forgotten to use \command{ssh-add} or
   3.589 +  \command{pageant} to store the passphrase.
   3.590 +\item You might have stored the passphrase for the wrong key.
   3.591 +\end{itemize}
   3.592 +If you're being prompted for the remote user's password, there are
   3.593 +another few possible problems to check.
   3.594 +\begin{itemize}
   3.595 +\item Either the user's home directory or their \sdirname{.ssh}
   3.596 +  directory might have excessively liberal permissions.  As a result,
   3.597 +  the ssh daemon will not trust or read their
   3.598 +  \sfilename{authorized\_keys} file.  For example, a group-writable
   3.599 +  home or \sdirname{.ssh} directory will often cause this symptom.
   3.600 +\item The user's \sfilename{authorized\_keys} file may have a problem.
   3.601 +  If anyone other than the user owns or can write to that file, the
   3.602 +  ssh daemon will not trust or read it.
   3.603 +\end{itemize}
   3.604 +
   3.605 +In the ideal world, you should be able to run the following command
   3.606 +successfully, and it should print exactly one line of output, the
   3.607 +current date and time.
   3.608 +\begin{codesample2}
   3.609 +  ssh myserver date
   3.610 +\end{codesample2}
   3.611 +
   3.612 +If, on your server, you have login scripts that print banners or other
   3.613 +junk even when running non-interactive commands like this, you should
   3.614 +fix them before you continue, so that they only print output if
   3.615 +they're run interactively.  Otherwise these banners will at least
   3.616 +clutter up Mercurial's output.  Worse, they could potentially cause
   3.617 +problems with running Mercurial commands remotely.  Mercurial makes
   3.618 +tries to detect and ignore banners in non-interactive \command{ssh}
   3.619 +sessions, but it is not foolproof.  (If you're editing your login
   3.620 +scripts on your server, the usual way to see if a login script is
   3.621 +running in an interactive shell is to check the return code from the
   3.622 +command \Verb|tty -s|.)
   3.623 +
   3.624 +Once you've verified that plain old ssh is working with your server,
   3.625 +the next step is to ensure that Mercurial runs on the server.  The
   3.626 +following command should run successfully:
   3.627 +\begin{codesample2}
   3.628 +  ssh myserver hg version
   3.629 +\end{codesample2}
   3.630 +If you see an error message instead of normal \hgcmd{version} output,
   3.631 +this is usually because you haven't installed Mercurial to
   3.632 +\dirname{/usr/bin}.  Don't worry if this is the case; you don't need
   3.633 +to do that.  But you should check for a few possible problems.
   3.634 +\begin{itemize}
   3.635 +\item Is Mercurial really installed on the server at all?  I know this
   3.636 +  sounds trivial, but it's worth checking!
   3.637 +\item Maybe your shell's search path (usually set via the \envar{PATH}
   3.638 +  environment variable) is simply misconfigured.
   3.639 +\item Perhaps your \envar{PATH} environment variable is only being set
   3.640 +  to point to the location of the \command{hg} executable if the login
   3.641 +  session is interactive.  This can happen if you're setting the path
   3.642 +  in the wrong shell login script.  See your shell's documentation for
   3.643 +  details.
   3.644 +\item The \envar{PYTHONPATH} environment variable may need to contain
   3.645 +  the path to the Mercurial Python modules.  It might not be set at
   3.646 +  all; it could be incorrect; or it may be set only if the login is
   3.647 +  interactive.
   3.648 +\end{itemize}
   3.649 +
   3.650 +If you can run \hgcmd{version} over an ssh connection, well done!
   3.651 +You've got the server and client sorted out.  You should now be able
   3.652 +to use Mercurial to access repositories hosted by that username on
   3.653 +that server.  If you run into problems with Mercurial and ssh at this
   3.654 +point, try using the \hggopt{--debug} option to get a clearer picture
   3.655 +of what's going on.
   3.656 +
   3.657 +\subsection{Using compression with ssh}
   3.658 +
   3.659 +Mercurial does not compress data when it uses the ssh protocol,
   3.660 +because the ssh protocol can transparently compress data.  However,
   3.661 +the default behaviour of ssh clients is \emph{not} to request
   3.662 +compression.
   3.663 +
   3.664 +Over any network other than a fast LAN (even a wireless network),
   3.665 +using compression is likely to significantly speed up Mercurial's
   3.666 +network operations.  For example, over a WAN, someone measured
   3.667 +compression as reducing the amount of time required to clone a
   3.668 +particularly large repository from~51 minutes to~17 minutes.
   3.669 +
   3.670 +Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
   3.671 +option which turns on compression.  You can easily edit your \hgrc\ to
   3.672 +enable compression for all of Mercurial's uses of the ssh protocol.
   3.673 +\begin{codesample2}
   3.674 +  [ui]
   3.675 +  ssh = ssh -C
   3.676 +\end{codesample2}
   3.677 +
   3.678 +If you use \command{ssh}, you can configure it to always use
   3.679 +compression when talking to your server.  To do this, edit your
   3.680 +\sfilename{.ssh/config} file (which may not yet exist), as follows.
   3.681 +\begin{codesample2}
   3.682 +  Host hg
   3.683 +    Compression yes
   3.684 +    HostName hg.example.com
   3.685 +\end{codesample2}
   3.686 +This defines an alias, \texttt{hg}.  When you use it on the
   3.687 +\command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
   3.688 +URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
   3.689 +and use compression.  This gives you both a shorter name to type and
   3.690 +compression, each of which is a good thing in its own right.
   3.691 +
   3.692 +\section{Serving over HTTP using CGI}
   3.693 +\label{sec:collab:cgi}
   3.694 +
   3.695 +Depending on how ambitious you are, configuring Mercurial's CGI
   3.696 +interface can take anything from a few moments to several hours.
   3.697 +
   3.698 +We'll begin with the simplest of examples, and work our way towards a
   3.699 +more complex configuration.  Even for the most basic case, you're
   3.700 +almost certainly going to need to read and modify your web server's
   3.701 +configuration.
   3.702 +
   3.703 +\begin{note}
   3.704 +  Configuring a web server is a complex, fiddly, and highly
   3.705 +  system-dependent activity.  I can't possibly give you instructions
   3.706 +  that will cover anything like all of the cases you will encounter.
   3.707 +  Please use your discretion and judgment in following the sections
   3.708 +  below.  Be prepared to make plenty of mistakes, and to spend a lot
   3.709 +  of time reading your server's error logs.
   3.710 +\end{note}
   3.711 +
   3.712 +\subsection{Web server configuration checklist}
   3.713 +
   3.714 +Before you continue, do take a few moments to check a few aspects of
   3.715 +your system's setup.
   3.716 +
   3.717 +\begin{enumerate}
   3.718 +\item Do you have a web server installed at all?  Mac OS X ships with
   3.719 +  Apache, but many other systems may not have a web server installed.
   3.720 +\item If you have a web server installed, is it actually running?  On
   3.721 +  most systems, even if one is present, it will be disabled by
   3.722 +  default.
   3.723 +\item Is your server configured to allow you to run CGI programs in
   3.724 +  the directory where you plan to do so?  Most servers default to
   3.725 +  explicitly disabling the ability to run CGI programs.
   3.726 +\end{enumerate}
   3.727 +
   3.728 +If you don't have a web server installed, and don't have substantial
   3.729 +experience configuring Apache, you should consider using the
   3.730 +\texttt{lighttpd} web server instead of Apache.  Apache has a
   3.731 +well-deserved reputation for baroque and confusing configuration.
   3.732 +While \texttt{lighttpd} is less capable in some ways than Apache, most
   3.733 +of these capabilities are not relevant to serving Mercurial
   3.734 +repositories.  And \texttt{lighttpd} is undeniably \emph{much} easier
   3.735 +to get started with than Apache.
   3.736 +
   3.737 +\subsection{Basic CGI configuration}
   3.738 +
   3.739 +On Unix-like systems, it's common for users to have a subdirectory
   3.740 +named something like \dirname{public\_html} in their home directory,
   3.741 +from which they can serve up web pages.  A file named \filename{foo}
   3.742 +in this directory will be accessible at a URL of the form
   3.743 +\texttt{http://www.example.com/\~username/foo}.
   3.744 +
   3.745 +To get started, find the \sfilename{hgweb.cgi} script that should be
   3.746 +present in your Mercurial installation.  If you can't quickly find a
   3.747 +local copy on your system, simply download one from the master
   3.748 +Mercurial repository at
   3.749 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
   3.750 +
   3.751 +You'll need to copy this script into your \dirname{public\_html}
   3.752 +directory, and ensure that it's executable.
   3.753 +\begin{codesample2}
   3.754 +  cp .../hgweb.cgi ~/public_html
   3.755 +  chmod 755 ~/public_html/hgweb.cgi
   3.756 +\end{codesample2}
   3.757 +The \texttt{755} argument to \command{chmod} is a little more general
   3.758 +than just making the script executable: it ensures that the script is
   3.759 +executable by anyone, and that ``group'' and ``other'' write
   3.760 +permissions are \emph{not} set.  If you were to leave those write
   3.761 +permissions enabled, Apache's \texttt{suexec} subsystem would likely
   3.762 +refuse to execute the script.  In fact, \texttt{suexec} also insists
   3.763 +that the \emph{directory} in which the script resides must not be
   3.764 +writable by others.
   3.765 +\begin{codesample2}
   3.766 +  chmod 755 ~/public_html
   3.767 +\end{codesample2}
   3.768 +
   3.769 +\subsubsection{What could \emph{possibly} go wrong?}
   3.770 +\label{sec:collab:wtf}
   3.771 +
   3.772 +Once you've copied the CGI script into place, go into a web browser,
   3.773 +and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
   3.774 +\emph{but} brace yourself for instant failure.  There's a high
   3.775 +probability that trying to visit this URL will fail, and there are
   3.776 +many possible reasons for this.  In fact, you're likely to stumble
   3.777 +over almost every one of the possible errors below, so please read
   3.778 +carefully.  The following are all of the problems I ran into on a
   3.779 +system running Fedora~7, with a fresh installation of Apache, and a
   3.780 +user account that I created specially to perform this exercise.
   3.781 +
   3.782 +Your web server may have per-user directories disabled.  If you're
   3.783 +using Apache, search your config file for a \texttt{UserDir}
   3.784 +directive.  If there's none present, per-user directories will be
   3.785 +disabled.  If one exists, but its value is \texttt{disabled}, then
   3.786 +per-user directories will be disabled.  Otherwise, the string after
   3.787 +\texttt{UserDir} gives the name of the subdirectory that Apache will
   3.788 +look in under your home directory, for example \dirname{public\_html}.
   3.789 +
   3.790 +Your file access permissions may be too restrictive.  The web server
   3.791 +must be able to traverse your home directory and directories under
   3.792 +your \dirname{public\_html} directory, and read files under the latter
   3.793 +too.  Here's a quick recipe to help you to make your permissions more
   3.794 +appropriate.
   3.795 +\begin{codesample2}
   3.796 +  chmod 755 ~
   3.797 +  find ~/public_html -type d -print0 | xargs -0r chmod 755
   3.798 +  find ~/public_html -type f -print0 | xargs -0r chmod 644
   3.799 +\end{codesample2}
   3.800 +
   3.801 +The other possibility with permissions is that you might get a
   3.802 +completely empty window when you try to load the script.  In this
   3.803 +case, it's likely that your access permissions are \emph{too
   3.804 +  permissive}.  Apache's \texttt{suexec} subsystem won't execute a
   3.805 +script that's group-~or world-writable, for example.
   3.806 +
   3.807 +Your web server may be configured to disallow execution of CGI
   3.808 +programs in your per-user web directory.  Here's Apache's
   3.809 +default per-user configuration from my Fedora system.
   3.810 +\begin{codesample2}
   3.811 +  <Directory /home/*/public_html>
   3.812 +      AllowOverride FileInfo AuthConfig Limit
   3.813 +      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
   3.814 +      <Limit GET POST OPTIONS>
   3.815 +          Order allow,deny
   3.816 +          Allow from all
   3.817 +      </Limit>
   3.818 +      <LimitExcept GET POST OPTIONS>
   3.819 +          Order deny,allow
   3.820 +          Deny from all
   3.821 +      </LimitExcept>
   3.822 +  </Directory>
   3.823 +\end{codesample2}
   3.824 +If you find a similar-looking \texttt{Directory} group in your Apache
   3.825 +configuration, the directive to look at inside it is \texttt{Options}.
   3.826 +Add \texttt{ExecCGI} to the end of this list if it's missing, and
   3.827 +restart the web server.
   3.828 +
   3.829 +If you find that Apache serves you the text of the CGI script instead
   3.830 +of executing it, you may need to either uncomment (if already present)
   3.831 +or add a directive like this.
   3.832 +\begin{codesample2}
   3.833 +  AddHandler cgi-script .cgi
   3.834 +\end{codesample2}
   3.835 +
   3.836 +The next possibility is that you might be served with a colourful
   3.837 +Python backtrace claiming that it can't import a
   3.838 +\texttt{mercurial}-related module.  This is actually progress!  The
   3.839 +server is now capable of executing your CGI script.  This error is
   3.840 +only likely to occur if you're running a private installation of
   3.841 +Mercurial, instead of a system-wide version.  Remember that the web
   3.842 +server runs the CGI program without any of the environment variables
   3.843 +that you take for granted in an interactive session.  If this error
   3.844 +happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
   3.845 +directions inside it to correctly set your \envar{PYTHONPATH}
   3.846 +environment variable.
   3.847 +
   3.848 +Finally, you are \emph{certain} to by served with another colourful
   3.849 +Python backtrace: this one will complain that it can't find
   3.850 +\dirname{/path/to/repository}.  Edit your \sfilename{hgweb.cgi} script
   3.851 +and replace the \dirname{/path/to/repository} string with the complete
   3.852 +path to the repository you want to serve up.
   3.853 +
   3.854 +At this point, when you try to reload the page, you should be
   3.855 +presented with a nice HTML view of your repository's history.  Whew!
   3.856 +
   3.857 +\subsubsection{Configuring lighttpd}
   3.858 +
   3.859 +To be exhaustive in my experiments, I tried configuring the
   3.860 +increasingly popular \texttt{lighttpd} web server to serve the same
   3.861 +repository as I described with Apache above.  I had already overcome
   3.862 +all of the problems I outlined with Apache, many of which are not
   3.863 +server-specific.  As a result, I was fairly sure that my file and
   3.864 +directory permissions were good, and that my \sfilename{hgweb.cgi}
   3.865 +script was properly edited.
   3.866 +
   3.867 +Once I had Apache running, getting \texttt{lighttpd} to serve the
   3.868 +repository was a snap (in other words, even if you're trying to use
   3.869 +\texttt{lighttpd}, you should read the Apache section).  I first had
   3.870 +to edit the \texttt{mod\_access} section of its config file to enable
   3.871 +\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
   3.872 +disabled by default on my system.  I then added a few lines to the end
   3.873 +of the config file, to configure these modules.
   3.874 +\begin{codesample2}
   3.875 +  userdir.path = "public_html"
   3.876 +  cgi.assign = ( ".cgi" => "" )
   3.877 +\end{codesample2}
   3.878 +With this done, \texttt{lighttpd} ran immediately for me.  If I had
   3.879 +configured \texttt{lighttpd} before Apache, I'd almost certainly have
   3.880 +run into many of the same system-level configuration problems as I did
   3.881 +with Apache.  However, I found \texttt{lighttpd} to be noticeably
   3.882 +easier to configure than Apache, even though I've used Apache for over
   3.883 +a decade, and this was my first exposure to \texttt{lighttpd}.
   3.884 +
   3.885 +\subsection{Sharing multiple repositories with one CGI script}
   3.886 +
   3.887 +The \sfilename{hgweb.cgi} script only lets you publish a single
   3.888 +repository, which is an annoying restriction.  If you want to publish
   3.889 +more than one without wracking yourself with multiple copies of the
   3.890 +same script, each with different names, a better choice is to use the
   3.891 +\sfilename{hgwebdir.cgi} script.
   3.892 +
   3.893 +The procedure to configure \sfilename{hgwebdir.cgi} is only a little
   3.894 +more involved than for \sfilename{hgweb.cgi}.  First, you must obtain
   3.895 +a copy of the script.  If you don't have one handy, you can download a
   3.896 +copy from the master Mercurial repository at
   3.897 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
   3.898 +
   3.899 +You'll need to copy this script into your \dirname{public\_html}
   3.900 +directory, and ensure that it's executable.
   3.901 +\begin{codesample2}
   3.902 +  cp .../hgwebdir.cgi ~/public_html
   3.903 +  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
   3.904 +\end{codesample2}
   3.905 +With basic configuration out of the way, try to visit
   3.906 +\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser.  It
   3.907 +should display an empty list of repositories.  If you get a blank
   3.908 +window or error message, try walking through the list of potential
   3.909 +problems in section~\ref{sec:collab:wtf}.
   3.910 +
   3.911 +The \sfilename{hgwebdir.cgi} script relies on an external
   3.912 +configuration file.  By default, it searches for a file named
   3.913 +\sfilename{hgweb.config} in the same directory as itself.  You'll need
   3.914 +to create this file, and make it world-readable.  The format of the
   3.915 +file is similar to a Windows ``ini'' file, as understood by Python's
   3.916 +\texttt{ConfigParser}~\cite{web:configparser} module.
   3.917 +
   3.918 +The easiest way to configure \sfilename{hgwebdir.cgi} is with a
   3.919 +section named \texttt{collections}.  This will automatically publish
   3.920 +\emph{every} repository under the directories you name.  The section
   3.921 +should look like this:
   3.922 +\begin{codesample2}
   3.923 +  [collections]
   3.924 +  /my/root = /my/root
   3.925 +\end{codesample2}
   3.926 +Mercurial interprets this by looking at the directory name on the
   3.927 +\emph{right} hand side of the ``\texttt{=}'' sign; finding
   3.928 +repositories in that directory hierarchy; and using the text on the
   3.929 +\emph{left} to strip off matching text from the names it will actually
   3.930 +list in the web interface.  The remaining component of a path after
   3.931 +this stripping has occurred is called a ``virtual path''.
   3.932 +
   3.933 +Given the example above, if we have a repository whose local path is
   3.934 +\dirname{/my/root/this/repo}, the CGI script will strip the leading
   3.935 +\dirname{/my/root} from the name, and publish the repository with a
   3.936 +virtual path of \dirname{this/repo}.  If the base URL for our CGI
   3.937 +script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
   3.938 +URL for that repository will be
   3.939 +\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
   3.940 +
   3.941 +If we replace \dirname{/my/root} on the left hand side of this example
   3.942 +with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
   3.943 +\dirname{/my} from the repository name, and will give us a virtual
   3.944 +path of \dirname{root/this/repo} instead of \dirname{this/repo}.
   3.945 +
   3.946 +The \sfilename{hgwebdir.cgi} script will recursively search each
   3.947 +directory listed in the \texttt{collections} section of its
   3.948 +configuration file, but it will \texttt{not} recurse into the
   3.949 +repositories it finds.
   3.950 +
   3.951 +The \texttt{collections} mechanism makes it easy to publish many
   3.952 +repositories in a ``fire and forget'' manner.  You only need to set up
   3.953 +the CGI script and configuration file one time.  Afterwards, you can
   3.954 +publish or unpublish a repository at any time by simply moving it
   3.955 +into, or out of, the directory hierarchy in which you've configured
   3.956 +\sfilename{hgwebdir.cgi} to look.
   3.957 +
   3.958 +\subsubsection{Explicitly specifying which repositories to publish}
   3.959 +
   3.960 +In addition to the \texttt{collections} mechanism, the
   3.961 +\sfilename{hgwebdir.cgi} script allows you to publish a specific list
   3.962 +of repositories.  To do so, create a \texttt{paths} section, with
   3.963 +contents of the following form.
   3.964 +\begin{codesample2}
   3.965 +  [paths]
   3.966 +  repo1 = /my/path/to/some/repo
   3.967 +  repo2 = /some/path/to/another
   3.968 +\end{codesample2}
   3.969 +In this case, the virtual path (the component that will appear in a
   3.970 +URL) is on the left hand side of each definition, while the path to
   3.971 +the repository is on the right.  Notice that there does not need to be
   3.972 +any relationship between the virtual path you choose and the location
   3.973 +of a repository in your filesystem.
   3.974 +
   3.975 +If you wish, you can use both the \texttt{collections} and
   3.976 +\texttt{paths} mechanisms simultaneously in a single configuration
   3.977 +file.
   3.978 +
   3.979 +\begin{note}
   3.980 +  If multiple repositories have the same virtual path,
   3.981 +  \sfilename{hgwebdir.cgi} will not report an error.  Instead, it will
   3.982 +  behave unpredictably.
   3.983 +\end{note}
   3.984 +
   3.985 +\subsection{Downloading source archives}
   3.986 +
   3.987 +Mercurial's web interface lets users download an archive of any
   3.988 +revision.  This archive will contain a snapshot of the working
   3.989 +directory as of that revision, but it will not contain a copy of the
   3.990 +repository data.
   3.991 +
   3.992 +By default, this feature is not enabled.  To enable it, you'll need to
   3.993 +add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
   3.994 +section of your \hgrc.
   3.995 +
   3.996 +\subsection{Web configuration options}
   3.997 +
   3.998 +Mercurial's web interfaces (the \hgcmd{serve} command, and the
   3.999 +\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
  3.1000 +number of configuration options that you can set.  These belong in a
  3.1001 +section named \rcsection{web}.
  3.1002 +\begin{itemize}
  3.1003 +\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
  3.1004 +  download mechanisms Mercurial supports.  If you enable this
  3.1005 +  feature, users of the web interface will be able to download an
  3.1006 +  archive of whatever revision of a repository they are viewing.
  3.1007 +  To enable the archive feature, this item must take the form of a
  3.1008 +  sequence of words drawn from the list below.
  3.1009 +  \begin{itemize}
  3.1010 +  \item[\texttt{bz2}] A \command{tar} archive, compressed using
  3.1011 +    \texttt{bzip2} compression.  This has the best compression ratio,
  3.1012 +    but uses the most CPU time on the server.
  3.1013 +  \item[\texttt{gz}] A \command{tar} archive, compressed using
  3.1014 +    \texttt{gzip} compression.
  3.1015 +  \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
  3.1016 +    compression.  This format has the worst compression ratio, but is
  3.1017 +    widely used in the Windows world.
  3.1018 +  \end{itemize}
  3.1019 +  If you provide an empty list, or don't have an
  3.1020 +  \rcitem{web}{allow\_archive} entry at all, this feature will be
  3.1021 +  disabled.  Here is an example of how to enable all three supported
  3.1022 +  formats.
  3.1023 +  \begin{codesample4}
  3.1024 +    [web]
  3.1025 +    allow_archive = bz2 gz zip
  3.1026 +  \end{codesample4}
  3.1027 +\item[\rcitem{web}{allowpull}] Boolean.  Determines whether the web
  3.1028 +  interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
  3.1029 +  repository over~HTTP.  If set to \texttt{no} or \texttt{false}, only
  3.1030 +  the ``human-oriented'' portion of the web interface is available.
  3.1031 +\item[\rcitem{web}{contact}] String.  A free-form (but preferably
  3.1032 +  brief) string identifying the person or group in charge of the
  3.1033 +  repository.  This often contains the name and email address of a
  3.1034 +  person or mailing list.  It often makes sense to place this entry in
  3.1035 +  a repository's own \sfilename{.hg/hgrc} file, but it can make sense
  3.1036 +  to use in a global \hgrc\ if every repository has a single
  3.1037 +  maintainer.
  3.1038 +\item[\rcitem{web}{maxchanges}] Integer.  The default maximum number
  3.1039 +  of changesets to display in a single page of output.
  3.1040 +\item[\rcitem{web}{maxfiles}] Integer.  The default maximum number
  3.1041 +  of modified files to display in a single page of output.
  3.1042 +\item[\rcitem{web}{stripes}] Integer.  If the web interface displays
  3.1043 +  alternating ``stripes'' to make it easier to visually align rows
  3.1044 +  when you are looking at a table, this number controls the number of
  3.1045 +  rows in each stripe.
  3.1046 +\item[\rcitem{web}{style}] Controls the template Mercurial uses to
  3.1047 +  display the web interface.  Mercurial ships with two web templates,
  3.1048 +  named \texttt{default} and \texttt{gitweb} (the latter is much more
  3.1049 +  visually attractive).  You can also specify a custom template of
  3.1050 +  your own; see chapter~\ref{chap:template} for details.  Here, you
  3.1051 +  can see how to enable the \texttt{gitweb} style.
  3.1052 +  \begin{codesample4}
  3.1053 +    [web]
  3.1054 +    style = gitweb
  3.1055 +  \end{codesample4}
  3.1056 +\item[\rcitem{web}{templates}] Path.  The directory in which to search
  3.1057 +  for template files.  By default, Mercurial searches in the directory
  3.1058 +  in which it was installed.
  3.1059 +\end{itemize}
  3.1060 +If you are using \sfilename{hgwebdir.cgi}, you can place a few
  3.1061 +configuration items in a \rcsection{web} section of the
  3.1062 +\sfilename{hgweb.config} file instead of a \hgrc\ file, for
  3.1063 +convenience.  These items are \rcitem{web}{motd} and
  3.1064 +\rcitem{web}{style}.
  3.1065 +
  3.1066 +\subsubsection{Options specific to an individual repository}
  3.1067 +
  3.1068 +A few \rcsection{web} configuration items ought to be placed in a
  3.1069 +repository's local \sfilename{.hg/hgrc}, rather than a user's or
  3.1070 +global \hgrc.
  3.1071 +\begin{itemize}
  3.1072 +\item[\rcitem{web}{description}] String.  A free-form (but preferably
  3.1073 +  brief) string that describes the contents or purpose of the
  3.1074 +  repository.
  3.1075 +\item[\rcitem{web}{name}] String.  The name to use for the repository
  3.1076 +  in the web interface.  This overrides the default name, which is the
  3.1077 +  last component of the repository's path.
  3.1078 +\end{itemize}
  3.1079 +
  3.1080 +\subsubsection{Options specific to the \hgcmd{serve} command}
  3.1081 +
  3.1082 +Some of the items in the \rcsection{web} section of a \hgrc\ file are
  3.1083 +only for use with the \hgcmd{serve} command.
  3.1084 +\begin{itemize}
  3.1085 +\item[\rcitem{web}{accesslog}] Path.  The name of a file into which to
  3.1086 +  write an access log.  By default, the \hgcmd{serve} command writes
  3.1087 +  this information to standard output, not to a file.  Log entries are
  3.1088 +  written in the standard ``combined'' file format used by almost all
  3.1089 +  web servers.
  3.1090 +\item[\rcitem{web}{address}] String.  The local address on which the
  3.1091 +  server should listen for incoming connections.  By default, the
  3.1092 +  server listens on all addresses.
  3.1093 +\item[\rcitem{web}{errorlog}] Path.  The name of a file into which to
  3.1094 +  write an error log.  By default, the \hgcmd{serve} command writes this
  3.1095 +  information to standard error, not to a file.
  3.1096 +\item[\rcitem{web}{ipv6}] Boolean.  Whether to use the IPv6 protocol.
  3.1097 +  By default, IPv6 is not used. 
  3.1098 +\item[\rcitem{web}{port}] Integer.  The TCP~port number on which the
  3.1099 +  server should listen.  The default port number used is~8000.
  3.1100 +\end{itemize}
  3.1101 +
  3.1102 +\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
  3.1103 +  items to}
  3.1104 +
  3.1105 +It is important to remember that a web server like Apache or
  3.1106 +\texttt{lighttpd} will run under a user~ID that is different to yours.
  3.1107 +CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
  3.1108 +usually also run under that user~ID.
  3.1109 +
  3.1110 +If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
  3.1111 +scripts won't read that \hgrc\ file.  Those settings will thus only
  3.1112 +affect the behaviour of the \hgcmd{serve} command when you run it.  To
  3.1113 +cause CGI scripts to see your settings, either create a \hgrc\ file in
  3.1114 +the home directory of the user ID that runs your web server, or add
  3.1115 +those settings to a system-wide \hgrc\ file.
  3.1116 +
  3.1117 +
  3.1118 +%%% Local Variables: 
  3.1119 +%%% mode: latex
  3.1120 +%%% TeX-master: "00book"
  3.1121 +%%% End: 

     4.1 --- a/es/filenames.tex	Fri Nov 07 21:33:22 2008 -0500
     4.2 +++ b/es/filenames.tex	Fri Nov 07 21:42:57 2008 -0500
     4.3 @@ -0,0 +1,306 @@
     4.4 +\chapter{File names and pattern matching}
     4.5 +\label{chap:names}
     4.6 +
     4.7 +Mercurial provides mechanisms that let you work with file names in a
     4.8 +consistent and expressive way.
     4.9 +
    4.10 +\section{Simple file naming}
    4.11 +
    4.12 +Mercurial uses a unified piece of machinery ``under the hood'' to
    4.13 +handle file names.  Every command behaves uniformly with respect to
    4.14 +file names.  The way in which commands work with file names is as
    4.15 +follows.
    4.16 +
    4.17 +If you explicitly name real files on the command line, Mercurial works
    4.18 +with exactly those files, as you would expect.
    4.19 +\interaction{filenames.files}
    4.20 +
    4.21 +When you provide a directory name, Mercurial will interpret this as
    4.22 +``operate on every file in this directory and its subdirectories''.
    4.23 +Mercurial traverses the files and subdirectories in a directory in
    4.24 +alphabetical order.  When it encounters a subdirectory, it will
    4.25 +traverse that subdirectory before continuing with the current
    4.26 +directory.
    4.27 +\interaction{filenames.dirs}
    4.28 +
    4.29 +\section{Running commands without any file names}
    4.30 +
    4.31 +Mercurial's commands that work with file names have useful default
    4.32 +behaviours when you invoke them without providing any file names or
    4.33 +patterns.  What kind of behaviour you should expect depends on what
    4.34 +the command does.  Here are a few rules of thumb you can use to
    4.35 +predict what a command is likely to do if you don't give it any names
    4.36 +to work with.
    4.37 +\begin{itemize}
    4.38 +\item Most commands will operate on the entire working directory.
    4.39 +  This is what the \hgcmd{add} command does, for example.
    4.40 +\item If the command has effects that are difficult or impossible to
    4.41 +  reverse, it will force you to explicitly provide at least one name
    4.42 +  or pattern (see below).  This protects you from accidentally
    4.43 +  deleting files by running \hgcmd{remove} with no arguments, for
    4.44 +  example.
    4.45 +\end{itemize}
    4.46 +
    4.47 +It's easy to work around these default behaviours if they don't suit
    4.48 +you.  If a command normally operates on the whole working directory,
    4.49 +you can invoke it on just the current directory and its subdirectories
    4.50 +by giving it the name ``\dirname{.}''.
    4.51 +\interaction{filenames.wdir-subdir}
    4.52 +
    4.53 +Along the same lines, some commands normally print file names relative
    4.54 +to the root of the repository, even if you're invoking them from a
    4.55 +subdirectory.  Such a command will print file names relative to your
    4.56 +subdirectory if you give it explicit names.  Here, we're going to run
    4.57 +\hgcmd{status} from a subdirectory, and get it to operate on the
    4.58 +entire working directory while printing file names relative to our
    4.59 +subdirectory, by passing it the output of the \hgcmd{root} command.
    4.60 +\interaction{filenames.wdir-relname}
    4.61 +
    4.62 +\section{Telling you what's going on}
    4.63 +
    4.64 +The \hgcmd{add} example in the preceding section illustrates something
    4.65 +else that's helpful about Mercurial commands.  If a command operates
    4.66 +on a file that you didn't name explicitly on the command line, it will
    4.67 +usually print the name of the file, so that you will not be surprised
    4.68 +what's going on.
    4.69 +
    4.70 +The principle here is of \emph{least surprise}.  If you've exactly
    4.71 +named a file on the command line, there's no point in repeating it
    4.72 +back at you.  If Mercurial is acting on a file \emph{implicitly},
    4.73 +because you provided no names, or a directory, or a pattern (see
    4.74 +below), it's safest to tell you what it's doing.
    4.75 +
    4.76 +For commands that behave this way, you can silence them using the
    4.77 +\hggopt{-q} option.  You can also get them to print the name of every
    4.78 +file, even those you've named explicitly, using the \hggopt{-v}
    4.79 +option.
    4.80 +
    4.81 +\section{Using patterns to identify files}
    4.82 +
    4.83 +In addition to working with file and directory names, Mercurial lets
    4.84 +you use \emph{patterns} to identify files.  Mercurial's pattern
    4.85 +handling is expressive.
    4.86 +
    4.87 +On Unix-like systems (Linux, MacOS, etc.), the job of matching file
    4.88 +names to patterns normally falls to the shell.  On these systems, you
    4.89 +must explicitly tell Mercurial that a name is a pattern.  On Windows,
    4.90 +the shell does not expand patterns, so Mercurial will automatically
    4.91 +identify names that are patterns, and expand them for you.
    4.92 +
    4.93 +To provide a pattern in place of a regular name on the command line,
    4.94 +the mechanism is simple:
    4.95 +\begin{codesample2}
    4.96 +  syntax:patternbody
    4.97 +\end{codesample2}
    4.98 +That is, a pattern is identified by a short text string that says what
    4.99 +kind of pattern this is, followed by a colon, followed by the actual
   4.100 +pattern.
   4.101 +
   4.102 +Mercurial supports two kinds of pattern syntax.  The most frequently
   4.103 +used is called \texttt{glob}; this is the same kind of pattern
   4.104 +matching used by the Unix shell, and should be familiar to Windows
   4.105 +command prompt users, too.  
   4.106 +
   4.107 +When Mercurial does automatic pattern matching on Windows, it uses
   4.108 +\texttt{glob} syntax.  You can thus omit the ``\texttt{glob:}'' prefix
   4.109 +on Windows, but it's safe to use it, too.
   4.110 +
   4.111 +The \texttt{re} syntax is more powerful; it lets you specify patterns
   4.112 +using regular expressions, also known as regexps.
   4.113 +
   4.114 +By the way, in the examples that follow, notice that I'm careful to
   4.115 +wrap all of my patterns in quote characters, so that they won't get
   4.116 +expanded by the shell before Mercurial sees them.
   4.117 +
   4.118 +\subsection{Shell-style \texttt{glob} patterns}
   4.119 +
   4.120 +This is an overview of the kinds of patterns you can use when you're
   4.121 +matching on glob patterns.
   4.122 +
   4.123 +The ``\texttt{*}'' character matches any string, within a single
   4.124 +directory.
   4.125 +\interaction{filenames.glob.star}
   4.126 +
   4.127 +The ``\texttt{**}'' pattern matches any string, and crosses directory
   4.128 +boundaries.  It's not a standard Unix glob token, but it's accepted by
   4.129 +several popular Unix shells, and is very useful.
   4.130 +\interaction{filenames.glob.starstar}
   4.131 +
   4.132 +The ``\texttt{?}'' pattern matches any single character.
   4.133 +\interaction{filenames.glob.question}
   4.134 +
   4.135 +The ``\texttt{[}'' character begins a \emph{character class}.  This
   4.136 +matches any single character within the class.  The class ends with a
   4.137 +``\texttt{]}'' character.  A class may contain multiple \emph{range}s
   4.138 +of the form ``\texttt{a-f}'', which is shorthand for
   4.139 +``\texttt{abcdef}''.
   4.140 +\interaction{filenames.glob.range}
   4.141 +If the first character after the ``\texttt{[}'' in a character class
   4.142 +is a ``\texttt{!}'', it \emph{negates} the class, making it match any
   4.143 +single character not in the class.
   4.144 +
   4.145 +A ``\texttt{\{}'' begins a group of subpatterns, where the whole group
   4.146 +matches if any subpattern in the group matches.  The ``\texttt{,}''
   4.147 +character separates subpatterns, and ``\texttt{\}}'' ends the group.
   4.148 +\interaction{filenames.glob.group}
   4.149 +
   4.150 +\subsubsection{Watch out!}
   4.151 +
   4.152 +Don't forget that if you want to match a pattern in any directory, you
   4.153 +should not be using the ``\texttt{*}'' match-any token, as this will
   4.154 +only match within one directory.  Instead, use the ``\texttt{**}''
   4.155 +token.  This small example illustrates the difference between the two.
   4.156 +\interaction{filenames.glob.star-starstar}
   4.157 +
   4.158 +\subsection{Regular expression matching with \texttt{re} patterns}
   4.159 +
   4.160 +Mercurial accepts the same regular expression syntax as the Python
   4.161 +programming language (it uses Python's regexp engine internally).
   4.162 +This is based on the Perl language's regexp syntax, which is the most
   4.163 +popular dialect in use (it's also used in Java, for example).
   4.164 +
   4.165 +I won't discuss Mercurial's regexp dialect in any detail here, as
   4.166 +regexps are not often used.  Perl-style regexps are in any case
   4.167 +already exhaustively documented on a multitude of web sites, and in
   4.168 +many books.  Instead, I will focus here on a few things you should
   4.169 +know if you find yourself needing to use regexps with Mercurial.
   4.170 +
   4.171 +A regexp is matched against an entire file name, relative to the root
   4.172 +of the repository.  In other words, even if you're already in
   4.173 +subbdirectory \dirname{foo}, if you want to match files under this
   4.174 +directory, your pattern must start with ``\texttt{foo/}''.
   4.175 +
   4.176 +One thing to note, if you're familiar with Perl-style regexps, is that
   4.177 +Mercurial's are \emph{rooted}.  That is, a regexp starts matching
   4.178 +against the beginning of a string; it doesn't look for a match
   4.179 +anywhere within the string.  To match anywhere in a string, start
   4.180 +your pattern with ``\texttt{.*}''.
   4.181 +
   4.182 +\section{Filtering files}
   4.183 +
   4.184 +Not only does Mercurial give you a variety of ways to specify files;
   4.185 +it lets you further winnow those files using \emph{filters}.  Commands
   4.186 +that work with file names accept two filtering options.
   4.187 +\begin{itemize}
   4.188 +\item \hggopt{-I}, or \hggopt{--include}, lets you specify a pattern
   4.189 +  that file names must match in order to be processed.
   4.190 +\item \hggopt{-X}, or \hggopt{--exclude}, gives you a way to
   4.191 +  \emph{avoid} processing files, if they match this pattern.
   4.192 +\end{itemize}
   4.193 +You can provide multiple \hggopt{-I} and \hggopt{-X} options on the
   4.194 +command line, and intermix them as you please.  Mercurial interprets
   4.195 +the patterns you provide using glob syntax by default (but you can use
   4.196 +regexps if you need to).
   4.197 +
   4.198 +You can read a \hggopt{-I} filter as ``process only the files that
   4.199 +match this filter''.
   4.200 +\interaction{filenames.filter.include}
   4.201 +The \hggopt{-X} filter is best read as ``process only the files that
   4.202 +don't match this pattern''.
   4.203 +\interaction{filenames.filter.exclude}
   4.204 +
   4.205 +\section{Ignoring unwanted files and directories}
   4.206 +
   4.207 +XXX.
   4.208 +
   4.209 +\section{Case sensitivity}
   4.210 +\label{sec:names:case}
   4.211 +
   4.212 +If you're working in a mixed development environment that contains
   4.213 +both Linux (or other Unix) systems and Macs or Windows systems, you
   4.214 +should keep in the back of your mind the knowledge that they treat the
   4.215 +case (``N'' versus ``n'') of file names in incompatible ways.  This is
   4.216 +not very likely to affect you, and it's easy to deal with if it does,
   4.217 +but it could surprise you if you don't know about it.
   4.218 +
   4.219 +Operating systems and filesystems differ in the way they handle the
   4.220 +\emph{case} of characters in file and directory names.  There are
   4.221 +three common ways to handle case in names.
   4.222 +\begin{itemize}
   4.223 +\item Completely case insensitive.  Uppercase and lowercase versions
   4.224 +  of a letter are treated as identical, both when creating a file and
   4.225 +  during subsequent accesses.  This is common on older DOS-based
   4.226 +  systems.
   4.227 +\item Case preserving, but insensitive.  When a file or directory is
   4.228 +  created, the case of its name is stored, and can be retrieved and
   4.229 +  displayed by the operating system.  When an existing file is being
   4.230 +  looked up, its case is ignored.  This is the standard arrangement on
   4.231 +  Windows and MacOS.  The names \filename{foo} and \filename{FoO}
   4.232 +  identify the same file.  This treatment of uppercase and lowercase
   4.233 +  letters as interchangeable is also referred to as \emph{case
   4.234 +    folding}.
   4.235 +\item Case sensitive.  The case of a name is significant at all times.
   4.236 +  The names \filename{foo} and {FoO} identify different files.  This
   4.237 +  is the way Linux and Unix systems normally work.
   4.238 +\end{itemize}
   4.239 +
   4.240 +On Unix-like systems, it is possible to have any or all of the above
   4.241 +ways of handling case in action at once.  For example, if you use a
   4.242 +USB thumb drive formatted with a FAT32 filesystem on a Linux system,
   4.243 +Linux will handle names on that filesystem in a case preserving, but
   4.244 +insensitive, way.
   4.245 +
   4.246 +\subsection{Safe, portable repository storage}
   4.247 +
   4.248 +Mercurial's repository storage mechanism is \emph{case safe}.  It
   4.249 +translates file names so that they can be safely stored on both case
   4.250 +sensitive and case insensitive filesystems.  This means that you can
   4.251 +use normal file copying tools to transfer a Mercurial repository onto,
   4.252 +for example, a USB thumb drive, and safely move that drive and
   4.253 +repository back and forth between a Mac, a PC running Windows, and a
   4.254 +Linux box.
   4.255 +
   4.256 +\subsection{Detecting case conflicts}
   4.257 +
   4.258 +When operating in the working directory, Mercurial honours the naming
   4.259 +policy of the filesystem where the working directory is located.  If
   4.260 +the filesystem is case preserving, but insensitive, Mercurial will
   4.261 +treat names that differ only in case as the same.
   4.262 +
   4.263 +An important aspect of this approach is that it is possible to commit
   4.264 +a changeset on a case sensitive (typically Linux or Unix) filesystem
   4.265 +that will cause trouble for users on case insensitive (usually Windows
   4.266 +and MacOS) users.  If a Linux user commits changes to two files, one
   4.267 +named \filename{myfile.c} and the other named \filename{MyFile.C},
   4.268 +they will be stored correctly in the repository.  And in the working
   4.269 +directories of other Linux users, they will be correctly represented
   4.270 +as separate files.
   4.271 +
   4.272 +If a Windows or Mac user pulls this change, they will not initially
   4.273 +have a problem, because Mercurial's repository storage mechanism is
   4.274 +case safe.  However, once they try to \hgcmd{update} the working
   4.275 +directory to that changeset, or \hgcmd{merge} with that changeset,
   4.276 +Mercurial will spot the conflict between the two file names that the
   4.277 +filesystem would treat as the same, and forbid the update or merge
   4.278 +from occurring.
   4.279 +
   4.280 +\subsection{Fixing a case conflict}
   4.281 +
   4.282 +If you are using Windows or a Mac in a mixed environment where some of
   4.283 +your collaborators are using Linux or Unix, and Mercurial reports a
   4.284 +case folding conflict when you try to \hgcmd{update} or \hgcmd{merge},
   4.285 +the procedure to fix the problem is simple.
   4.286 +
   4.287 +Just find a nearby Linux or Unix box, clone the problem repository
   4.288 +onto it, and use Mercurial's \hgcmd{rename} command to change the
   4.289 +names of any offending files or directories so that they will no
   4.290 +longer cause case folding conflicts.  Commit this change, \hgcmd{pull}
   4.291 +or \hgcmd{push} it across to your Windows or MacOS system, and
   4.292 +\hgcmd{update} to the revision with the non-conflicting names.
   4.293 +
   4.294 +The changeset with case-conflicting names will remain in your
   4.295 +project's history, and you still won't be able to \hgcmd{update} your
   4.296 +working directory to that changeset on a Windows or MacOS system, but
   4.297 +you can continue development unimpeded.
   4.298 +
   4.299 +\begin{note}
   4.300 +  Prior to version~0.9.3, Mercurial did not use a case safe repository
   4.301 +  storage mechanism, and did not detect case folding conflicts.  If
   4.302 +  you are using an older version of Mercurial on Windows or MacOS, I
   4.303 +  strongly recommend that you upgrade.
   4.304 +\end{note}
   4.305 +
   4.306 +%%% Local Variables: 
   4.307 +%%% mode: latex
   4.308 +%%% TeX-master: "00book"
   4.309 +%%% End: 

     5.1 --- a/es/intro.tex	Fri Nov 07 21:33:22 2008 -0500
     5.2 +++ b/es/intro.tex	Fri Nov 07 21:42:57 2008 -0500
     5.3 @@ -0,0 +1,561 @@
     5.4 +\chapter{Introduction}
     5.5 +\label{chap:intro}
     5.6 +
     5.7 +\section{About revision control}
     5.8 +
     5.9 +Revision control is the process of managing multiple versions of a
    5.10 +piece of information.  In its simplest form, this is something that
    5.11 +many people do by hand: every time you modify a file, save it under a
    5.12 +new name that contains a number, each one higher than the number of
    5.13 +the preceding version.
    5.14 +
    5.15 +Manually managing multiple versions of even a single file is an
    5.16 +error-prone task, though, so software tools to help automate this
    5.17 +process have long been available.  The earliest automated revision
    5.18 +control tools were intended to help a single user to manage revisions
    5.19 +of a single file.  Over the past few decades, the scope of revision
    5.20 +control tools has expanded greatly; they now manage multiple files,
    5.21 +and help multiple people to work together.  The best modern revision
    5.22 +control tools have no problem coping with thousands of people working
    5.23 +together on projects that consist of hundreds of thousands of files.
    5.24 +
    5.25 +\subsection{Why use revision control?}
    5.26 +
    5.27 +There are a number of reasons why you or your team might want to use
    5.28 +an automated revision control tool for a project.
    5.29 +\begin{itemize}
    5.30 +\item It will track the history and evolution of your project, so you
    5.31 +  don't have to.  For every change, you'll have a log of \emph{who}
    5.32 +  made it; \emph{why} they made it; \emph{when} they made it; and
    5.33 +  \emph{what} the change was.
    5.34 +\item When you're working with other people, revision control software
    5.35 +  makes it easier for you to collaborate.  For example, when people
    5.36 +  more or less simultaneously make potentially incompatible changes,
    5.37 +  the software will help you to identify and resolve those conflicts.
    5.38 +\item It can help you to recover from mistakes.  If you make a change
    5.39 +  that later turns out to be in error, you can revert to an earlier
    5.40 +  version of one or more files.  In fact, a \emph{really} good
    5.41 +  revision control tool will even help you to efficiently figure out
    5.42 +  exactly when a problem was introduced (see
    5.43 +  section~\ref{sec:undo:bisect} for details).
    5.44 +\item It will help you to work simultaneously on, and manage the drift
    5.45 +  between, multiple versions of your project.
    5.46 +\end{itemize}
    5.47 +Most of these reasons are equally valid---at least in theory---whether
    5.48 +you're working on a project by yourself, or with a hundred other
    5.49 +people.
    5.50 +
    5.51 +A key question about the practicality of revision control at these two
    5.52 +different scales (``lone hacker'' and ``huge team'') is how its
    5.53 +\emph{benefits} compare to its \emph{costs}.  A revision control tool
    5.54 +that's difficult to understand or use is going to impose a high cost.
    5.55 +
    5.56 +A five-hundred-person project is likely to collapse under its own
    5.57 +weight almost immediately without a revision control tool and process.
    5.58 +In this case, the cost of using revision control might hardly seem
    5.59 +worth considering, since \emph{without} it, failure is almost
    5.60 +guaranteed.
    5.61 +
    5.62 +On the other hand, a one-person ``quick hack'' might seem like a poor
    5.63 +place to use a revision control tool, because surely the cost of using
    5.64 +one must be close to the overall cost of the project.  Right?
    5.65 +
    5.66 +Mercurial uniquely supports \emph{both} of these scales of
    5.67 +development.  You can learn the basics in just a few minutes, and due
    5.68 +to its low overhead, you can apply revision control to the smallest of
    5.69 +projects with ease.  Its simplicity means you won't have a lot of
    5.70 +abstruse concepts or command sequences competing for mental space with
    5.71 +whatever you're \emph{really} trying to do.  At the same time,
    5.72 +Mercurial's high performance and peer-to-peer nature let you scale
    5.73 +painlessly to handle large projects.
    5.74 +
    5.75 +No revision control tool can rescue a poorly run project, but a good
    5.76 +choice of tools can make a huge difference to the fluidity with which
    5.77 +you can work on a project.
    5.78 +
    5.79 +\subsection{The many names of revision control}
    5.80 +
    5.81 +Revision control is a diverse field, so much so that it doesn't
    5.82 +actually have a single name or acronym.  Here are a few of the more
    5.83 +common names and acronyms you'll encounter:
    5.84 +\begin{itemize}
    5.85 +\item Revision control (RCS)
    5.86 +\item Software configuration management (SCM), or configuration management
    5.87 +\item Source code management
    5.88 +\item Source code control, or source control
    5.89 +\item Version control (VCS)
    5.90 +\end{itemize}
    5.91 +Some people claim that these terms actually have different meanings,
    5.92 +but in practice they overlap so much that there's no agreed or even
    5.93 +useful way to tease them apart.
    5.94 +
    5.95 +\section{A short history of revision control}
    5.96 +
    5.97 +The best known of the old-time revision control tools is SCCS (Source
    5.98 +Code Control System), which Marc Rochkind wrote at Bell Labs, in the
    5.99 +early 1970s.  SCCS operated on individual files, and required every
   5.100 +person working on a project to have access to a shared workspace on a
   5.101 +single system.  Only one person could modify a file at any time;
   5.102 +arbitration for access to files was via locks.  It was common for
   5.103 +people to lock files, and later forget to unlock them, preventing
   5.104 +anyone else from modifying those files without the help of an
   5.105 +administrator.  
   5.106 +
   5.107 +Walter Tichy developed a free alternative to SCCS in the early 1980s;
   5.108 +he called his program RCS (Revison Control System).  Like SCCS, RCS
   5.109 +required developers to work in a single shared workspace, and to lock
   5.110 +files to prevent multiple people from modifying them simultaneously.
   5.111 +
   5.112 +Later in the 1980s, Dick Grune used RCS as a building block for a set
   5.113 +of shell scripts he initially called cmt, but then renamed to CVS
   5.114 +(Concurrent Versions System).  The big innovation of CVS was that it
   5.115 +let developers work simultaneously and somewhat independently in their
   5.116 +own personal workspaces.  The personal workspaces prevented developers
   5.117 +from stepping on each other's toes all the time, as was common with
   5.118 +SCCS and RCS.  Each developer had a copy of every project file, and
   5.119 +could modify their copies independently.  They had to merge their
   5.120 +edits prior to committing changes to the central repository.
   5.121 +
   5.122 +Brian Berliner took Grune's original scripts and rewrote them in~C,
   5.123 +releasing in 1989 the code that has since developed into the modern
   5.124 +version of CVS.  CVS subsequently acquired the ability to operate over
   5.125 +a network connection, giving it a client/server architecture.  CVS's
   5.126 +architecture is centralised; only the server has a copy of the history
   5.127 +of the project.  Client workspaces just contain copies of recent
   5.128 +versions of the project's files, and a little metadata to tell them
   5.129 +where the server is.  CVS has been enormously successful; it is
   5.130 +probably the world's most widely used revision control system.
   5.131 +
   5.132 +In the early 1990s, Sun Microsystems developed an early distributed
   5.133 +revision control system, called TeamWare.  A TeamWare workspace
   5.134 +contains a complete copy of the project's history.  TeamWare has no
   5.135 +notion of a central repository.  (CVS relied upon RCS for its history
   5.136 +storage; TeamWare used SCCS.)
   5.137 +
   5.138 +As the 1990s progressed, awareness grew of a number of problems with
   5.139 +CVS.  It records simultaneous changes to multiple files individually,
   5.140 +instead of grouping them together as a single logically atomic
   5.141 +operation.  It does not manage its file hierarchy well; it is easy to
   5.142 +make a mess of a repository by renaming files and directories.  Worse,
   5.143 +its source code is difficult to read and maintain, which made the
   5.144 +``pain level'' of fixing these architectural problems prohibitive.
   5.145 +
   5.146 +In 2001, Jim Blandy and Karl Fogel, two developers who had worked on
   5.147 +CVS, started a project to replace it with a tool that would have a
   5.148 +better architecture and cleaner code.  The result, Subversion, does
   5.149 +not stray from CVS's centralised client/server model, but it adds
   5.150 +multi-file atomic commits, better namespace management, and a number
   5.151 +of other features that make it a generally better tool than CVS.
   5.152 +Since its initial release, it has rapidly grown in popularity.
   5.153 +
   5.154 +More or less simultaneously, Graydon Hoare began working on an
   5.155 +ambitious distributed revision control system that he named Monotone.
   5.156 +While Monotone addresses many of CVS's design flaws and has a
   5.157 +peer-to-peer architecture, it goes beyond earlier (and subsequent)
   5.158 +revision control tools in a number of innovative ways.  It uses
   5.159 +cryptographic hashes as identifiers, and has an integral notion of
   5.160 +``trust'' for code from different sources.
   5.161 +
   5.162 +Mercurial began life in 2005.  While a few aspects of its design are
   5.163 +influenced by Monotone, Mercurial focuses on ease of use, high
   5.164 +performance, and scalability to very large projects.
   5.165 +
   5.166 +\section{Trends in revision control}
   5.167 +
   5.168 +There has been an unmistakable trend in the development and use of
   5.169 +revision control tools over the past four decades, as people have
   5.170 +become familiar with the capabilities of their tools and constrained
   5.171 +by their limitations.
   5.172 +
   5.173 +The first generation began by managing single files on individual
   5.174 +computers.  Although these tools represented a huge advance over
   5.175 +ad-hoc manual revision control, their locking model and reliance on a
   5.176 +single computer limited them to small, tightly-knit teams.
   5.177 +
   5.178 +The second generation loosened these constraints by moving to
   5.179 +network-centered architectures, and managing entire projects at a
   5.180 +time.  As projects grew larger, they ran into new problems.  With
   5.181 +clients needing to talk to servers very frequently, server scaling
   5.182 +became an issue for large projects.  An unreliable network connection
   5.183 +could prevent remote users from being able to talk to the server at
   5.184 +all.  As open source projects started making read-only access
   5.185 +available anonymously to anyone, people without commit privileges
   5.186 +found that they could not use the tools to interact with a project in
   5.187 +a natural way, as they could not record their changes.
   5.188 +
   5.189 +The current generation of revision control tools is peer-to-peer in
   5.190 +nature.  All of these systems have dropped the dependency on a single
   5.191 +central server, and allow people to distribute their revision control
   5.192 +data to where it's actually needed.  Collaboration over the Internet
   5.193 +has moved from constrained by technology to a matter of choice and
   5.194 +consensus.  Modern tools can operate offline indefinitely and
   5.195 +autonomously, with a network connection only needed when syncing
   5.196 +changes with another repository.
   5.197 +
   5.198 +\section{A few of the advantages of distributed revision control}
   5.199 +
   5.200 +Even though distributed revision control tools have for several years
   5.201 +been as robust and usable as their previous-generation counterparts,
   5.202 +people using older tools have not yet necessarily woken up to their
   5.203 +advantages.  There are a number of ways in which distributed tools
   5.204 +shine relative to centralised ones.
   5.205 +
   5.206 +For an individual developer, distributed tools are almost always much
   5.207 +faster than centralised tools.  This is for a simple reason: a
   5.208 +centralised tool needs to talk over the network for many common
   5.209 +operations, because most metadata is stored in a single copy on the
   5.210 +central server.  A distributed tool stores all of its metadata
   5.211 +locally.  All else being equal, talking over the network adds overhead
   5.212 +to a centralised tool.  Don't underestimate the value of a snappy,
   5.213 +responsive tool: you're going to spend a lot of time interacting with
   5.214 +your revision control software.
   5.215 +
   5.216 +Distributed tools are indifferent to the vagaries of your server
   5.217 +infrastructure, again because they replicate metadata to so many
   5.218 +locations.  If you use a centralised system and your server catches
   5.219 +fire, you'd better hope that your backup media are reliable, and that
   5.220 +your last backup was recent and actually worked.  With a distributed
   5.221 +tool, you have many backups available on every contributor's computer.
   5.222 +
   5.223 +The reliability of your network will affect distributed tools far less
   5.224 +than it will centralised tools.  You can't even use a centralised tool
   5.225 +without a network connection, except for a few highly constrained
   5.226 +commands.  With a distributed tool, if your network connection goes
   5.227 +down while you're working, you may not even notice.  The only thing
   5.228 +you won't be able to do is talk to repositories on other computers,
   5.229 +something that is relatively rare compared with local operations.  If
   5.230 +you have a far-flung team of collaborators, this may be significant.
   5.231 +
   5.232 +\subsection{Advantages for open source projects}
   5.233 +
   5.234 +If you take a shine to an open source project and decide that you
   5.235 +would like to start hacking on it, and that project uses a distributed
   5.236 +revision control tool, you are at once a peer with the people who
   5.237 +consider themselves the ``core'' of that project.  If they publish
   5.238 +their repositories, you can immediately copy their project history,
   5.239 +start making changes, and record your work, using the same tools in
   5.240 +the same ways as insiders.  By contrast, with a centralised tool, you
   5.241 +must use the software in a ``read only'' mode unless someone grants
   5.242 +you permission to commit changes to their central server.  Until then,
   5.243 +you won't be able to record changes, and your local modifications will
   5.244 +be at risk of corruption any time you try to update your client's view
   5.245 +of the repository.
   5.246 +
   5.247 +\subsubsection{The forking non-problem}
   5.248 +
   5.249 +It has been suggested that distributed revision control tools pose
   5.250 +some sort of risk to open source projects because they make it easy to
   5.251 +``fork'' the development of a project.  A fork happens when there are
   5.252 +differences in opinion or attitude between groups of developers that
   5.253 +cause them to decide that they can't work together any longer.  Each
   5.254 +side takes a more or less complete copy of the project's source code,
   5.255 +and goes off in its own direction.
   5.256 +
   5.257 +Sometimes the camps in a fork decide to reconcile their differences.
   5.258 +With a centralised revision control system, the \emph{technical}
   5.259 +process of reconciliation is painful, and has to be performed largely
   5.260 +by hand.  You have to decide whose revision history is going to
   5.261 +``win'', and graft the other team's changes into the tree somehow.
   5.262 +This usually loses some or all of one side's revision history.
   5.263 +
   5.264 +What distributed tools do with respect to forking is they make forking
   5.265 +the \emph{only} way to develop a project.  Every single change that
   5.266 +you make is potentially a fork point.  The great strength of this
   5.267 +approach is that a distributed revision control tool has to be really
   5.268 +good at \emph{merging} forks, because forks are absolutely
   5.269 +fundamental: they happen all the time.  
   5.270 +
   5.271 +If every piece of work that everybody does, all the time, is framed in
   5.272 +terms of forking and merging, then what the open source world refers
   5.273 +to as a ``fork'' becomes \emph{purely} a social issue.  If anything,
   5.274 +distributed tools \emph{lower} the likelihood of a fork:
   5.275 +\begin{itemize}
   5.276 +\item They eliminate the social distinction that centralised tools
   5.277 +  impose: that between insiders (people with commit access) and
   5.278 +  outsiders (people without).
   5.279 +\item They make it easier to reconcile after a social fork, because
   5.280 +  all that's involved from the perspective of the revision control
   5.281 +  software is just another merge.
   5.282 +\end{itemize}
   5.283 +
   5.284 +Some people resist distributed tools because they want to retain tight
   5.285 +control over their projects, and they believe that centralised tools
   5.286 +give them this control.  However, if you're of this belief, and you
   5.287 +publish your CVS or Subversion repositories publically, there are
   5.288 +plenty of tools available that can pull out your entire project's
   5.289 +history (albeit slowly) and recreate it somewhere that you don't
   5.290 +control.  So while your control in this case is illusory, you are
   5.291 +forgoing the ability to fluidly collaborate with whatever people feel
   5.292 +compelled to mirror and fork your history.
   5.293 +
   5.294 +\subsection{Advantages for commercial projects}
   5.295 +
   5.296 +Many commercial projects are undertaken by teams that are scattered
   5.297 +across the globe.  Contributors who are far from a central server will
   5.298 +see slower command execution and perhaps less reliability.  Commercial
   5.299 +revision control systems attempt to ameliorate these problems with
   5.300 +remote-site replication add-ons that are typically expensive to buy
   5.301 +and cantankerous to administer.  A distributed system doesn't suffer
   5.302 +from these problems in the first place.  Better yet, you can easily
   5.303 +set up multiple authoritative servers, say one per site, so that
   5.304 +there's no redundant communication between repositories over expensive
   5.305 +long-haul network links.
   5.306 +
   5.307 +Centralised revision control systems tend to have relatively low
   5.308 +scalability.  It's not unusual for an expensive centralised system to
   5.309 +fall over under the combined load of just a few dozen concurrent
   5.310 +users.  Once again, the typical response tends to be an expensive and
   5.311 +clunky replication facility.  Since the load on a central server---if
   5.312 +you have one at all---is many times lower with a distributed
   5.313 +tool (because all of the data is replicated everywhere), a single
   5.314 +cheap server can handle the needs of a much larger team, and
   5.315 +replication to balance load becomes a simple matter of scripting.
   5.316 +
   5.317 +If you have an employee in the field, troubleshooting a problem at a
   5.318 +customer's site, they'll benefit from distributed revision control.
   5.319 +The tool will let them generate custom builds, try different fixes in
   5.320 +isolation from each other, and search efficiently through history for
   5.321 +the sources of bugs and regressions in the customer's environment, all
   5.322 +without needing to connect to your company's network.
   5.323 +
   5.324 +\section{Why choose Mercurial?}
   5.325 +
   5.326 +Mercurial has a unique set of properties that make it a particularly
   5.327 +good choice as a revision control system.
   5.328 +\begin{itemize}
   5.329 +\item It is easy to learn and use.
   5.330 +\item It is lightweight.
   5.331 +\item It scales excellently.
   5.332 +\item It is easy to customise.
   5.333 +\end{itemize}
   5.334 +
   5.335 +If you are at all familiar with revision control systems, you should
   5.336 +be able to get up and running with Mercurial in less than five
   5.337 +minutes.  Even if not, it will take no more than a few minutes
   5.338 +longer.  Mercurial's command and feature sets are generally uniform
   5.339 +and consistent, so you can keep track of a few general rules instead
   5.340 +of a host of exceptions.
   5.341 +
   5.342 +On a small project, you can start working with Mercurial in moments.
   5.343 +Creating new changes and branches; transferring changes around
   5.344 +(whether locally or over a network); and history and status operations
   5.345 +are all fast.  Mercurial attempts to stay nimble and largely out of
   5.346 +your way by combining low cognitive overhead with blazingly fast
   5.347 +operations.
   5.348 +
   5.349 +The usefulness of Mercurial is not limited to small projects: it is
   5.350 +used by projects with hundreds to thousands of contributors, each
   5.351 +containing tens of thousands of files and hundreds of megabytes of
   5.352 +source code.
   5.353 +
   5.354 +If the core functionality of Mercurial is not enough for you, it's
   5.355 +easy to build on.  Mercurial is well suited to scripting tasks, and
   5.356 +its clean internals and implementation in Python make it easy to add
   5.357 +features in the form of extensions.  There are a number of popular and
   5.358 +useful extensions already available, ranging from helping to identify
   5.359 +bugs to improving performance.
   5.360 +
   5.361 +\section{Mercurial compared with other tools}
   5.362 +
   5.363 +Before you read on, please understand that this section necessarily
   5.364 +reflects my own experiences, interests, and (dare I say it) biases.  I
   5.365 +have used every one of the revision control tools listed below, in
   5.366 +most cases for several years at a time.
   5.367 +
   5.368 +
   5.369 +\subsection{Subversion}
   5.370 +
   5.371 +Subversion is a popular revision control tool, developed to replace
   5.372 +CVS.  It has a centralised client/server architecture.
   5.373 +
   5.374 +Subversion and Mercurial have similarly named commands for performing
   5.375 +the same operations, so if you're familiar with one, it is easy to
   5.376 +learn to use the other.  Both tools are portable to all popular
   5.377 +operating systems.
   5.378 +
   5.379 +Prior to version 1.5, Subversion had no useful support for merges.
   5.380 +At the time of writing, its merge tracking capability is new, and known to be
   5.381 +\href{http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword}{complicated
   5.382 +  and buggy}.
   5.383 +
   5.384 +Mercurial has a substantial performance advantage over Subversion on
   5.385 +every revision control operation I have benchmarked.  I have measured
   5.386 +its advantage as ranging from a factor of two to a factor of six when
   5.387 +compared with Subversion~1.4.3's \emph{ra\_local} file store, which is
   5.388 +the fastest access method available.  In more realistic deployments
   5.389 +involving a network-based store, Subversion will be at a substantially
   5.390 +larger disadvantage.  Because many Subversion commands must talk to
   5.391 +the server and Subversion does not have useful replication facilities,
   5.392 +server capacity and network bandwidth become bottlenecks for modestly
   5.393 +large projects.
   5.394 +
   5.395 +Additionally, Subversion incurs substantial storage overhead to avoid
   5.396 +network transactions for a few common operations, such as finding
   5.397 +modified files (\texttt{status}) and displaying modifications against
   5.398 +the current revision (\texttt{diff}).  As a result, a Subversion
   5.399 +working copy is often the same size as, or larger than, a Mercurial
   5.400 +repository and working directory, even though the Mercurial repository
   5.401 +contains a complete history of the project.
   5.402 +
   5.403 +Subversion is widely supported by third party tools.  Mercurial
   5.404 +currently lags considerably in this area.  This gap is closing,
   5.405 +however, and indeed some of Mercurial's GUI tools now outshine their
   5.406 +Subversion equivalents.  Like Mercurial, Subversion has an excellent
   5.407 +user manual.
   5.408 +
   5.409 +Because Subversion doesn't store revision history on the client, it is
   5.410 +well suited to managing projects that deal with lots of large, opaque
   5.411 +binary files.  If you check in fifty revisions to an incompressible
   5.412 +10MB file, Subversion's client-side space usage stays constant The
   5.413 +space used by any distributed SCM will grow rapidly in proportion to
   5.414 +the number of revisions, because the differences between each revision
   5.415 +are large.
   5.416 +
   5.417 +In addition, it's often difficult or, more usually, impossible to
   5.418 +merge different versions of a binary file.  Subversion's ability to
   5.419 +let a user lock a file, so that they temporarily have the exclusive
   5.420 +right to commit changes to it, can be a significant advantage to a
   5.421 +project where binary files are widely used.
   5.422 +
   5.423 +Mercurial can import revision history from a Subversion repository.
   5.424 +It can also export revision history to a Subversion repository.  This
   5.425 +makes it easy to ``test the waters'' and use Mercurial and Subversion
   5.426 +in parallel before deciding to switch.  History conversion is
   5.427 +incremental, so you can perform an initial conversion, then small
   5.428 +additional conversions afterwards to bring in new changes.
   5.429 +
   5.430 +
   5.431 +\subsection{Git}
   5.432 +
   5.433 +Git is a distributed revision control tool that was developed for
   5.434 +managing the Linux kernel source tree.  Like Mercurial, its early
   5.435 +design was somewhat influenced by Monotone.
   5.436 +
   5.437 +Git has a very large command set, with version~1.5.0 providing~139
   5.438 +individual commands.  It has something of a reputation for being
   5.439 +difficult to learn.  Compared to Git, Mercurial has a strong focus on
   5.440 +simplicity.
   5.441 +
   5.442 +In terms of performance, Git is extremely fast.  In several cases, it
   5.443 +is faster than Mercurial, at least on Linux, while Mercurial performs
   5.444 +better on other operations.  However, on Windows, the performance and
   5.445 +general level of support that Git provides is, at the time of writing,
   5.446 +far behind that of Mercurial.
   5.447 +
   5.448 +While a Mercurial repository needs no maintenance, a Git repository
   5.449 +requires frequent manual ``repacks'' of its metadata.  Without these,
   5.450 +performance degrades, while space usage grows rapidly.  A server that
   5.451 +contains many Git repositories that are not rigorously and frequently
   5.452 +repacked will become heavily disk-bound during backups, and there have
   5.453 +been instances of daily backups taking far longer than~24 hours as a
   5.454 +result.  A freshly packed Git repository is slightly smaller than a
   5.455 +Mercurial repository, but an unpacked repository is several orders of
   5.456 +magnitude larger.
   5.457 +
   5.458 +The core of Git is written in C.  Many Git commands are implemented as
   5.459 +shell or Perl scripts, and the quality of these scripts varies widely.
   5.460 +I have encountered several instances where scripts charged along
   5.461 +blindly in the presence of errors that should have been fatal.
   5.462 +
   5.463 +Mercurial can import revision history from a Git repository.
   5.464 +
   5.465 +
   5.466 +\subsection{CVS}
   5.467 +
   5.468 +CVS is probably the most widely used revision control tool in the
   5.469 +world.  Due to its age and internal untidiness, it has been only
   5.470 +lightly maintained for many years.
   5.471 +
   5.472 +It has a centralised client/server architecture.  It does not group
   5.473 +related file changes into atomic commits, making it easy for people to
   5.474 +``break the build'': one person can successfully commit part of a
   5.475 +change and then be blocked by the need for a merge, causing other
   5.476 +people to see only a portion of the work they intended to do.  This
   5.477 +also affects how you work with project history.  If you want to see
   5.478 +all of the modifications someone made as part of a task, you will need
   5.479 +to manually inspect the descriptions and timestamps of the changes
   5.480 +made to each file involved (if you even know what those files were).
   5.481 +
   5.482 +CVS has a muddled notion of tags and branches that I will not attempt
   5.483 +to even describe.  It does not support renaming of files or
   5.484 +directories well, making it easy to corrupt a repository.  It has
   5.485 +almost no internal consistency checking capabilities, so it is usually
   5.486 +not even possible to tell whether or how a repository is corrupt.  I
   5.487 +would not recommend CVS for any project, existing or new.
   5.488 +
   5.489 +Mercurial can import CVS revision history.  However, there are a few
   5.490 +caveats that apply; these are true of every other revision control
   5.491 +tool's CVS importer, too.  Due to CVS's lack of atomic changes and
   5.492 +unversioned filesystem hierarchy, it is not possible to reconstruct
   5.493 +CVS history completely accurately; some guesswork is involved, and
   5.494 +renames will usually not show up.  Because a lot of advanced CVS
   5.495 +administration has to be done by hand and is hence error-prone, it's
   5.496 +common for CVS importers to run into multiple problems with corrupted
   5.497 +repositories (completely bogus revision timestamps and files that have
   5.498 +remained locked for over a decade are just two of the less interesting
   5.499 +problems I can recall from personal experience).
   5.500 +
   5.501 +Mercurial can import revision history from a CVS repository.
   5.502 +
   5.503 +
   5.504 +\subsection{Commercial tools}
   5.505 +
   5.506 +Perforce has a centralised client/server architecture, with no
   5.507 +client-side caching of any data.  Unlike modern revision control
   5.508 +tools, Perforce requires that a user run a command to inform the
   5.509 +server about every file they intend to edit.
   5.510 +
   5.511 +The performance of Perforce is quite good for small teams, but it
   5.512 +falls off rapidly as the number of users grows beyond a few dozen.
   5.513 +Modestly large Perforce installations require the deployment of
   5.514 +proxies to cope with the load their users generate.
   5.515 +
   5.516 +
   5.517 +\subsection{Choosing a revision control tool}
   5.518 +
   5.519 +With the exception of CVS, all of the tools listed above have unique
   5.520 +strengths that suit them to particular styles of work.  There is no
   5.521 +single revision control tool that is best in all situations.
   5.522 +
   5.523 +As an example, Subversion is a good choice for working with frequently
   5.524 +edited binary files, due to its centralised nature and support for
   5.525 +file locking.
   5.526 +
   5.527 +I personally find Mercurial's properties of simplicity, performance,
   5.528 +and good merge support to be a compelling combination that has served
   5.529 +me well for several years.
   5.530 +
   5.531 +
   5.532 +\section{Switching from another tool to Mercurial}
   5.533 +
   5.534 +Mercurial is bundled with an extension named \hgext{convert}, which
   5.535 +can incrementally import revision history from several other revision
   5.536 +control tools.  By ``incremental'', I mean that you can convert all of
   5.537 +a project's history to date in one go, then rerun the conversion later
   5.538 +to obtain new changes that happened after the initial conversion.
   5.539 +
   5.540 +The revision control tools supported by \hgext{convert} are as
   5.541 +follows:
   5.542 +\begin{itemize}
   5.543 +\item Subversion
   5.544 +\item CVS
   5.545 +\item Git
   5.546 +\item Darcs
   5.547 +\end{itemize}
   5.548 +
   5.549 +In addition, \hgext{convert} can export changes from Mercurial to
   5.550 +Subversion.  This makes it possible to try Subversion and Mercurial in
   5.551 +parallel before committing to a switchover, without risking the loss
   5.552 +of any work.
   5.553 +
   5.554 +The \hgxcmd{conver}{convert} command is easy to use.  Simply point it
   5.555 +at the path or URL of the source repository, optionally give it the
   5.556 +name of the destination repository, and it will start working.  After
   5.557 +the initial conversion, just run the same command again to import new
   5.558 +changes.
   5.559 +
   5.560 +
   5.561 +%%% Local Variables: 
   5.562 +%%% mode: latex
   5.563 +%%% TeX-master: "00book"
   5.564 +%%% End: 

     6.1 --- a/es/srcinstall.tex	Fri Nov 07 21:33:22 2008 -0500
     6.2 +++ b/es/srcinstall.tex	Fri Nov 07 21:42:57 2008 -0500
     6.3 @@ -0,0 +1,53 @@
     6.4 +\chapter{Installing Mercurial from source}
     6.5 +\label{chap:srcinstall}
     6.6 +
     6.7 +\section{On a Unix-like system}
     6.8 +\label{sec:srcinstall:unixlike}
     6.9 +
    6.10 +If you are using a Unix-like system that has a sufficiently recent
    6.11 +version of Python (2.3~or newer) available, it is easy to install
    6.12 +Mercurial from source.
    6.13 +\begin{enumerate}
    6.14 +\item Download a recent source tarball from
    6.15 +  \url{http://www.selenic.com/mercurial/download}.
    6.16 +\item Unpack the tarball:
    6.17 +  \begin{codesample4}
    6.18 +    gzip -dc mercurial-\emph{version}.tar.gz | tar xf -
    6.19 +  \end{codesample4}
    6.20 +\item Go into the source directory and run the installer script.  This
    6.21 +  will build Mercurial and install it in your home directory.
    6.22 +  \begin{codesample4}
    6.23 +    cd mercurial-\emph{version}
    6.24 +    python setup.py install --force --home=\$HOME
    6.25 +  \end{codesample4}
    6.26 +\end{enumerate}
    6.27 +Once the install finishes, Mercurial will be in the \texttt{bin}
    6.28 +subdirectory of your home directory.  Don't forget to make sure that
    6.29 +this directory is present in your shell's search path.
    6.30 +
    6.31 +You will probably need to set the \envar{PYTHONPATH} environment
    6.32 +variable so that the Mercurial executable can find the rest of the
    6.33 +Mercurial packages.  For example, on my laptop, I have set it to
    6.34 +\texttt{/home/bos/lib/python}.  The exact path that you will need to
    6.35 +use depends on how Python was built for your system, but should be
    6.36 +easy to figure out.  If you're uncertain, look through the output of
    6.37 +the installer script above, and see where the contents of the
    6.38 +\texttt{mercurial} directory were installed to.
    6.39 +
    6.40 +\section{On Windows}
    6.41 +
    6.42 +Building and installing Mercurial on Windows requires a variety of
    6.43 +tools, a fair amount of technical knowledge, and considerable
    6.44 +patience.  I very much \emph{do not recommend} this route if you are a
    6.45 +``casual user''.  Unless you intend to hack on Mercurial, I strongly
    6.46 +suggest that you use a binary package instead.
    6.47 +
    6.48 +If you are intent on building Mercurial from source on Windows, follow
    6.49 +the ``hard way'' directions on the Mercurial wiki at
    6.50 +\url{http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall},
    6.51 +and expect the process to involve a lot of fiddly work.
    6.52 +
    6.53 +%%% Local Variables: 
    6.54 +%%% mode: latex
    6.55 +%%% TeX-master: "00book"
    6.56 +%%% End: 

     7.1 --- a/es/template.tex	Fri Nov 07 21:33:22 2008 -0500
     7.2 +++ b/es/template.tex	Fri Nov 07 21:42:57 2008 -0500
     7.3 @@ -0,0 +1,475 @@
     7.4 +\chapter{Customising the output of Mercurial}
     7.5 +\label{chap:template}
     7.6 +
     7.7 +Mercurial provides a powerful mechanism to let you control how it
     7.8 +displays information.  The mechanism is based on templates.  You can
     7.9 +use templates to generate specific output for a single command, or to
    7.10 +customise the entire appearance of the built-in web interface.
    7.11 +
    7.12 +\section{Using precanned output styles}
    7.13 +\label{sec:style}
    7.14 +
    7.15 +Packaged with Mercurial are some output styles that you can use
    7.16 +immediately.  A style is simply a precanned template that someone
    7.17 +wrote and installed somewhere that Mercurial can find.
    7.18 +
    7.19 +Before we take a look at Mercurial's bundled styles, let's review its
    7.20 +normal output.
    7.21 +
    7.22 +\interaction{template.simple.normal}
    7.23 +
    7.24 +This is somewhat informative, but it takes up a lot of space---five
    7.25 +lines of output per changeset.  The \texttt{compact} style reduces
    7.26 +this to three lines, presented in a sparse manner.
    7.27 +
    7.28 +\interaction{template.simple.compact}
    7.29 +
    7.30 +The \texttt{changelog} style hints at the expressive power of
    7.31 +Mercurial's templating engine.  This style attempts to follow the GNU
    7.32 +Project's changelog guidelines\cite{web:changelog}.
    7.33 +
    7.34 +\interaction{template.simple.changelog}
    7.35 +
    7.36 +You will not be shocked to learn that Mercurial's default output style
    7.37 +is named \texttt{default}.
    7.38 +
    7.39 +\subsection{Setting a default style}
    7.40 +
    7.41 +You can modify the output style that Mercurial will use for every
    7.42 +command by editing your \hgrc\ file, naming the style you would
    7.43 +prefer to use.
    7.44 +
    7.45 +\begin{codesample2}
    7.46 +  [ui]
    7.47 +  style = compact
    7.48 +\end{codesample2}
    7.49 +
    7.50 +If you write a style of your own, you can use it by either providing
    7.51 +the path to your style file, or copying your style file into a
    7.52 +location where Mercurial can find it (typically the \texttt{templates}
    7.53 +subdirectory of your Mercurial install directory).
    7.54 +
    7.55 +\section{Commands that support styles and templates}
    7.56 +
    7.57 +All of Mercurial's ``\texttt{log}-like'' commands let you use styles
    7.58 +and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and
    7.59 +\hgcmd{tip}.
    7.60 +
    7.61 +As I write this manual, these are so far the only commands that
    7.62 +support styles and templates.  Since these are the most important
    7.63 +commands that need customisable output, there has been little pressure
    7.64 +from the Mercurial user community to add style and template support to
    7.65 +other commands.
    7.66 +
    7.67 +\section{The basics of templating}
    7.68 +
    7.69 +At its simplest, a Mercurial template is a piece of text.  Some of the
    7.70 +text never changes, while other parts are \emph{expanded}, or replaced
    7.71 +with new text, when necessary.
    7.72 +
    7.73 +Before we continue, let's look again at a simple example of
    7.74 +Mercurial's normal output.
    7.75 +
    7.76 +\interaction{template.simple.normal}
    7.77 +
    7.78 +Now, let's run the same command, but using a template to change its
    7.79 +output.
    7.80 +
    7.81 +\interaction{template.simple.simplest}
    7.82 +
    7.83 +The example above illustrates the simplest possible template; it's
    7.84 +just a piece of static text, printed once for each changeset.  The
    7.85 +\hgopt{log}{--template} option to the \hgcmd{log} command tells
    7.86 +Mercurial to use the given text as the template when printing each
    7.87 +changeset.
    7.88 +
    7.89 +Notice that the template string above ends with the text
    7.90 +``\Verb+\n+''.  This is an \emph{escape sequence}, telling Mercurial
    7.91 +to print a newline at the end of each template item.  If you omit this
    7.92 +newline, Mercurial will run each piece of output together.  See
    7.93 +section~\ref{sec:template:escape} for more details of escape sequences.
    7.94 +
    7.95 +A template that prints a fixed string of text all the time isn't very
    7.96 +useful; let's try something a bit more complex.
    7.97 +
    7.98 +\interaction{template.simple.simplesub}
    7.99 +
   7.100 +As you can see, the string ``\Verb+{desc}+'' in the template has been
   7.101 +replaced in the output with the description of each changeset.  Every
   7.102 +time Mercurial finds text enclosed in curly braces (``\texttt{\{}''
   7.103 +and ``\texttt{\}}''), it will try to replace the braces and text with
   7.104 +the expansion of whatever is inside.  To print a literal curly brace,
   7.105 +you must escape it, as described in section~\ref{sec:template:escape}.
   7.106 +
   7.107 +\section{Common template keywords}
   7.108 +\label{sec:template:keyword}
   7.109 +
   7.110 +You can start writing simple templates immediately using the keywords
   7.111 +below.
   7.112 +
   7.113 +\begin{itemize}
   7.114 +\item[\tplkword{author}] String.  The unmodified author of the changeset.
   7.115 +\item[\tplkword{branches}] String.  The name of the branch on which
   7.116 +  the changeset was committed.  Will be empty if the branch name was
   7.117 +  \texttt{default}.
   7.118 +\item[\tplkword{date}] Date information.  The date when the changeset
   7.119 +  was committed.  This is \emph{not} human-readable; you must pass it
   7.120 +  through a filter that will render it appropriately.  See
   7.121 +  section~\ref{sec:template:filter} for more information on filters.
   7.122 +  The date is expressed as a pair of numbers.  The first number is a
   7.123 +  Unix UTC timestamp (seconds since January 1, 1970); the second is
   7.124 +  the offset of the committer's timezone from UTC, in seconds.
   7.125 +\item[\tplkword{desc}] String.  The text of the changeset description.
   7.126 +\item[\tplkword{files}] List of strings.  All files modified, added, or
   7.127 +  removed by this changeset.
   7.128 +\item[\tplkword{file\_adds}] List of strings.  Files added by this
   7.129 +  changeset.
   7.130 +\item[\tplkword{file\_dels}] List of strings.  Files removed by this
   7.131 +  changeset.
   7.132 +\item[\tplkword{node}] String.  The changeset identification hash, as a
   7.133 +  40-character hexadecimal string.
   7.134 +\item[\tplkword{parents}] List of strings.  The parents of the
   7.135 +  changeset.
   7.136 +\item[\tplkword{rev}] Integer.  The repository-local changeset revision
   7.137 +  number.
   7.138 +\item[\tplkword{tags}] List of strings.  Any tags associated with the
   7.139 +  changeset.
   7.140 +\end{itemize}
   7.141 +
   7.142 +A few simple experiments will show us what to expect when we use these
   7.143 +keywords; you can see the results in
   7.144 +figure~\ref{fig:template:keywords}.
   7.145 +
   7.146 +\begin{figure}
   7.147 +  \interaction{template.simple.keywords}
   7.148 +  \caption{Template keywords in use}
   7.149 +  \label{fig:template:keywords}
   7.150 +\end{figure}
   7.151 +
   7.152 +As we noted above, the date keyword does not produce human-readable
   7.153 +output, so we must treat it specially.  This involves using a
   7.154 +\emph{filter}, about which more in section~\ref{sec:template:filter}.
   7.155 +
   7.156 +\interaction{template.simple.datekeyword}
   7.157 +
   7.158 +\section{Escape sequences}
   7.159 +\label{sec:template:escape}
   7.160 +
   7.161 +Mercurial's templating engine recognises the most commonly used escape
   7.162 +sequences in strings.  When it sees a backslash (``\Verb+\+'')
   7.163 +character, it looks at the following character and substitutes the two
   7.164 +characters with a single replacement, as described below.
   7.165 +
   7.166 +\begin{itemize}
   7.167 +\item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
   7.168 +  ASCII~134.
   7.169 +\item[\Verb+\textbackslash n+] Newline, ASCII~12.
   7.170 +\item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
   7.171 +\item[\Verb+\textbackslash t+] Tab, ASCII~11.
   7.172 +\item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
   7.173 +\item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
   7.174 +\item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
   7.175 +\end{itemize}
   7.176 +
   7.177 +As indicated above, if you want the expansion of a template to contain
   7.178 +a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
   7.179 +must escape it.
   7.180 +
   7.181 +\section{Filtering keywords to change their results}
   7.182 +\label{sec:template:filter}
   7.183 +
   7.184 +Some of the results of template expansion are not immediately easy to
   7.185 +use.  Mercurial lets you specify an optional chain of \emph{filters}
   7.186 +to modify the result of expanding a keyword.  You have already seen a
   7.187 +common filter, \tplkwfilt{date}{isodate}, in action above, to make a
   7.188 +date readable.
   7.189 +
   7.190 +Below is a list of the most commonly used filters that Mercurial
   7.191 +supports.  While some filters can be applied to any text, others can
   7.192 +only be used in specific circumstances.  The name of each filter is
   7.193 +followed first by an indication of where it can be used, then a
   7.194 +description of its effect.
   7.195 +
   7.196 +\begin{itemize}
   7.197 +\item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
   7.198 +  tag before the end of every line except the last.  For example,
   7.199 +  ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''.
   7.200 +\item[\tplkwfilt{date}{age}] \tplkword{date} keyword.  Render the
   7.201 +  age of the date, relative to the current time.  Yields a string like
   7.202 +  ``\Verb+10 minutes+''.
   7.203 +\item[\tplfilter{basename}] Any text, but most useful for the
   7.204 +  \tplkword{files} keyword and its relatives.  Treat the text as a
   7.205 +  path, and return the basename. For example, ``\Verb+foo/bar/baz+''
   7.206 +  becomes ``\Verb+baz+''.
   7.207 +\item[\tplkwfilt{date}{date}] \tplkword{date} keyword.  Render a date
   7.208 +  in a similar format to the Unix \tplkword{date} command, but with
   7.209 +  timezone included.  Yields a string like
   7.210 +  ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
   7.211 +\item[\tplkwfilt{author}{domain}] Any text, but most useful for the
   7.212 +  \tplkword{author} keyword.  Finds the first string that looks like
   7.213 +  an email address, and extract just the domain component.  For
   7.214 +  example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
   7.215 +  ``\Verb+serpentine.com+''.
   7.216 +\item[\tplkwfilt{author}{email}] Any text, but most useful for the
   7.217 +  \tplkword{author} keyword.  Extract the first string that looks like
   7.218 +  an email address.  For example,
   7.219 +  ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
   7.220 +  ``\Verb+bos@serpentine.com+''.
   7.221 +\item[\tplfilter{escape}] Any text.  Replace the special XML/XHTML
   7.222 +  characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
   7.223 +  XML entities.
   7.224 +\item[\tplfilter{fill68}] Any text.  Wrap the text to fit in 68
   7.225 +  columns.  This is useful before you pass text through the
   7.226 +  \tplfilter{tabindent} filter, and still want it to fit in an
   7.227 +  80-column fixed-font window.
   7.228 +\item[\tplfilter{fill76}] Any text.  Wrap the text to fit in 76
   7.229 +  columns.
   7.230 +\item[\tplfilter{firstline}] Any text.  Yield the first line of text,
   7.231 +  without any trailing newlines.
   7.232 +\item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword.  Render the
   7.233 +  date as a pair of readable numbers.  Yields a string like
   7.234 +  ``\Verb+1157407993 25200+''.
   7.235 +\item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword.  Render the
   7.236 +  date as a text string in ISO~8601 format.  Yields a string like
   7.237 +  ``\Verb+2006-09-04 15:13:13 -0700+''.
   7.238 +\item[\tplfilter{obfuscate}] Any text, but most useful for the
   7.239 +  \tplkword{author} keyword.  Yield the input text rendered as a
   7.240 +  sequence of XML entities.  This helps to defeat some particularly
   7.241 +  stupid screen-scraping email harvesting spambots.
   7.242 +\item[\tplkwfilt{author}{person}] Any text, but most useful for the
   7.243 +  \tplkword{author} keyword.  Yield the text before an email address.
   7.244 +  For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
   7.245 +  becomes ``\Verb+Bryan O'Sullivan+''.
   7.246 +\item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword.  Render a
   7.247 +  date using the same format used in email headers.  Yields a string
   7.248 +  like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
   7.249 +\item[\tplkwfilt{node}{short}] Changeset hash.  Yield the short form
   7.250 +  of a changeset hash, i.e.~a 12-byte hexadecimal string.
   7.251 +\item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword.  Render
   7.252 +  the year, month, and day of the date.  Yields a string like
   7.253 +  ``\Verb+2006-09-04+''.
   7.254 +\item[\tplfilter{strip}] Any text.  Strip all leading and trailing
   7.255 +  whitespace from the string.
   7.256 +\item[\tplfilter{tabindent}] Any text.  Yield the text, with every line
   7.257 +  except the first starting with a tab character.
   7.258 +\item[\tplfilter{urlescape}] Any text.  Escape all characters that are
   7.259 +  considered ``special'' by URL parsers.  For example, \Verb+foo bar+
   7.260 +  becomes \Verb+foo%20bar+.
   7.261 +\item[\tplkwfilt{author}{user}] Any text, but most useful for the
   7.262 +  \tplkword{author} keyword.  Return the ``user'' portion of an email
   7.263 +  address.  For example,
   7.264 +  ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
   7.265 +  ``\Verb+bos+''.
   7.266 +\end{itemize}
   7.267 +
   7.268 +\begin{figure}
   7.269 +  \interaction{template.simple.manyfilters}
   7.270 +  \caption{Template filters in action}
   7.271 +  \label{fig:template:filters}
   7.272 +\end{figure}
   7.273 +
   7.274 +\begin{note}
   7.275 +  If you try to apply a filter to a piece of data that it cannot
   7.276 +  process, Mercurial will fail and print a Python exception.  For
   7.277 +  example, trying to run the output of the \tplkword{desc} keyword
   7.278 +  into the \tplkwfilt{date}{isodate} filter is not a good idea.
   7.279 +\end{note}
   7.280 +
   7.281 +\subsection{Combining filters}
   7.282 +
   7.283 +It is easy to combine filters to yield output in the form you would
   7.284 +like.  The following chain of filters tidies up a description, then
   7.285 +makes sure that it fits cleanly into 68 columns, then indents it by a
   7.286 +further 8~characters (at least on Unix-like systems, where a tab is
   7.287 +conventionally 8~characters wide).
   7.288 +
   7.289 +\interaction{template.simple.combine}
   7.290 +
   7.291 +Note the use of ``\Verb+\t+'' (a tab character) in the template to
   7.292 +force the first line to be indented; this is necessary since
   7.293 +\tplkword{tabindent} indents all lines \emph{except} the first.
   7.294 +
   7.295 +Keep in mind that the order of filters in a chain is significant.  The
   7.296 +first filter is applied to the result of the keyword; the second to
   7.297 +the result of the first filter; and so on.  For example, using
   7.298 +\Verb+fill68|tabindent+ gives very different results from
   7.299 +\Verb+tabindent|fill68+.
   7.300 +
   7.301 +
   7.302 +\section{From templates to styles}
   7.303 +
   7.304 +A command line template provides a quick and simple way to format some
   7.305 +output.  Templates can become verbose, though, and it's useful to be
   7.306 +able to give a template a name.  A style file is a template with a
   7.307 +name, stored in a file.
   7.308 +
   7.309 +More than that, using a style file unlocks the power of Mercurial's
   7.310 +templating engine in ways that are not possible using the command line
   7.311 +\hgopt{log}{--template} option.
   7.312 +
   7.313 +\subsection{The simplest of style files}
   7.314 +
   7.315 +Our simple style file contains just one line:
   7.316 +
   7.317 +\interaction{template.simple.rev}
   7.318 +
   7.319 +This tells Mercurial, ``if you're printing a changeset, use the text
   7.320 +on the right as the template''.
   7.321 +
   7.322 +\subsection{Style file syntax}
   7.323 +
   7.324 +The syntax rules for a style file are simple.
   7.325 +
   7.326 +\begin{itemize}
   7.327 +\item The file is processed one line at a time.
   7.328 +
   7.329 +\item Leading and trailing white space are ignored.
   7.330 +
   7.331 +\item Empty lines are skipped.
   7.332 +
   7.333 +\item If a line starts with either of the characters ``\texttt{\#}'' or
   7.334 +  ``\texttt{;}'', the entire line is treated as a comment, and skipped
   7.335 +  as if empty.
   7.336 +
   7.337 +\item A line starts with a keyword.  This must start with an
   7.338 +  alphabetic character or underscore, and can subsequently contain any
   7.339 +  alphanumeric character or underscore.  (In regexp notation, a
   7.340 +  keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
   7.341 +
   7.342 +\item The next element must be an ``\texttt{=}'' character, which can
   7.343 +  be preceded or followed by an arbitrary amount of white space.
   7.344 +
   7.345 +\item If the rest of the line starts and ends with matching quote
   7.346 +  characters (either single or double quote), it is treated as a
   7.347 +  template body.
   7.348 +
   7.349 +\item If the rest of the line \emph{does not} start with a quote
   7.350 +  character, it is treated as the name of a file; the contents of this
   7.351 +  file will be read and used as a template body.
   7.352 +\end{itemize}
   7.353 +
   7.354 +\section{Style files by example}
   7.355 +
   7.356 +To illustrate how to write a style file, we will construct a few by
   7.357 +example.  Rather than provide a complete style file and walk through
   7.358 +it, we'll mirror the usual process of developing a style file by
   7.359 +starting with something very simple, and walking through a series of
   7.360 +successively more complete examples.
   7.361 +
   7.362 +\subsection{Identifying mistakes in style files}
   7.363 +
   7.364 +If Mercurial encounters a problem in a style file you are working on,
   7.365 +it prints a terse error message that, once you figure out what it
   7.366 +means, is actually quite useful.
   7.367 +
   7.368 +\interaction{template.svnstyle.syntax.input}
   7.369 +
   7.370 +Notice that \filename{broken.style} attempts to define a
   7.371 +\texttt{changeset} keyword, but forgets to give any content for it.
   7.372 +When instructed to use this style file, Mercurial promptly complains.
   7.373 +
   7.374 +\interaction{template.svnstyle.syntax.error}
   7.375 +
   7.376 +This error message looks intimidating, but it is not too hard to
   7.377 +follow.
   7.378 +
   7.379 +\begin{itemize}
   7.380 +\item The first component is simply Mercurial's way of saying ``I am
   7.381 +  giving up''.
   7.382 +  \begin{codesample4}
   7.383 +    \textbf{abort:} broken.style:1: parse error
   7.384 +  \end{codesample4}
   7.385 +
   7.386 +\item Next comes the name of the style file that contains the error.
   7.387 +  \begin{codesample4}
   7.388 +    abort: \textbf{broken.style}:1: parse error
   7.389 +  \end{codesample4}
   7.390 +
   7.391 +\item Following the file name is the line number where the error was
   7.392 +  encountered.
   7.393 +  \begin{codesample4}
   7.394 +    abort: broken.style:\textbf{1}: parse error
   7.395 +  \end{codesample4}
   7.396 +
   7.397 +\item Finally, a description of what went wrong.
   7.398 +  \begin{codesample4}
   7.399 +    abort: broken.style:1: \textbf{parse error}
   7.400 +  \end{codesample4}
   7.401 +  The description of the problem is not always clear (as in this
   7.402 +  case), but even when it is cryptic, it is almost always trivial to
   7.403 +  visually inspect the offending line in the style file and see what
   7.404 +  is wrong.
   7.405 +\end{itemize}
   7.406 +
   7.407 +\subsection{Uniquely identifying a repository}
   7.408 +
   7.409 +If you would like to be able to identify a Mercurial repository
   7.410 +``fairly uniquely'' using a short string as an identifier, you can
   7.411 +use the first revision in the repository.
   7.412 +\interaction{template.svnstyle.id} 
   7.413 +This is not guaranteed to be unique, but it is nevertheless useful in
   7.414 +many cases.
   7.415 +\begin{itemize}
   7.416 +\item It will not work in a completely empty repository, because such
   7.417 +  a repository does not have a revision~zero.
   7.418 +\item Neither will it work in the (extremely rare) case where a
   7.419 +  repository is a merge of two or more formerly independent
   7.420 +  repositories, and you still have those repositories around.
   7.421 +\end{itemize}
   7.422 +Here are some uses to which you could put this identifier:
   7.423 +\begin{itemize}
   7.424 +\item As a key into a table for a database that manages repositories
   7.425 +  on a server.
   7.426 +\item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
   7.427 +  Save this information away when you run an automated build or other
   7.428 +  activity, so that you can ``replay'' the build later if necessary.
   7.429 +\end{itemize}
   7.430 +
   7.431 +\subsection{Mimicking Subversion's output}
   7.432 +
   7.433 +Let's try to emulate the default output format used by another
   7.434 +revision control tool, Subversion.
   7.435 +\interaction{template.svnstyle.short}
   7.436 +
   7.437 +Since Subversion's output style is fairly simple, it is easy to
   7.438 +copy-and-paste a hunk of its output into a file, and replace the text
   7.439 +produced above by Subversion with the template values we'd like to see
   7.440 +expanded.
   7.441 +\interaction{template.svnstyle.template}
   7.442 +
   7.443 +There are a few small ways in which this template deviates from the
   7.444 +output produced by Subversion.
   7.445 +\begin{itemize}
   7.446 +\item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
   7.447 +    2006}'' in the example output above) in parentheses.  Mercurial's
   7.448 +  templating engine does not provide a way to display a date in this
   7.449 +  format without also printing the time and time zone.
   7.450 +\item We emulate Subversion's printing of ``separator'' lines full of
   7.451 +  ``\texttt{-}'' characters by ending the template with such a line.
   7.452 +  We use the templating engine's \tplkword{header} keyword to print a
   7.453 +  separator line as the first line of output (see below), thus
   7.454 +  achieving similar output to Subversion.
   7.455 +\item Subversion's output includes a count in the header of the number
   7.456 +  of lines in the commit message.  We cannot replicate this in
   7.457 +  Mercurial; the templating engine does not currently provide a filter
   7.458 +  that counts the number of items it is passed.
   7.459 +\end{itemize}
   7.460 +It took me no more than a minute or two of work to replace literal
   7.461 +text from an example of Subversion's output with some keywords and
   7.462 +filters to give the template above.  The style file simply refers to
   7.463 +the template.
   7.464 +\interaction{template.svnstyle.style}
   7.465 +
   7.466 +We could have included the text of the template file directly in the
   7.467 +style file by enclosing it in quotes and replacing the newlines with
   7.468 +``\verb!\n!'' sequences, but it would have made the style file too
   7.469 +difficult to read.  Readability is a good guide when you're trying to
   7.470 +decide whether some text belongs in a style file, or in a template
   7.471 +file that the style file points to.  If the style file will look too
   7.472 +big or cluttered if you insert a literal piece of text, drop it into a
   7.473 +template instead.
   7.474 +
   7.475 +%%% Local Variables: 
   7.476 +%%% mode: latex
   7.477 +%%% TeX-master: "00book"
   7.478 +%%% End: