Commits

Romain Pelisse committed 108c5ec

fix merge with Bryan on this particular file

Comments (0)

Files changed (1)

en/ch02-tour-basic.xml

-\chapter{A tour of Mercurial: the basics}
-\label{chap:tour-basic}
+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-\section{Installing Mercurial on your system}
-\label{sec:tour:install}
+<chapter id="chap:tour-basic">
+  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
+  <title>A tour of Mercurial: the basics</title>
 
-Prebuilt binary packages of Mercurial are available for every popular
-operating system.  These make it easy to start using Mercurial on your
-computer immediately.
+  <sect1 id="sec:tour:install">
+    <title>Installing Mercurial on your system</title>
 
-\subsection{Linux}
+    <para id="x_1">Prebuilt binary packages of Mercurial are available for
+      every popular operating system.  These make it easy to start
+      using Mercurial on your computer immediately.</para>
 
-Because each Linux distribution has its own packaging tools, policies,
-and rate of development, it's difficult to give a comprehensive set of
-instructions on how to install Mercurial binaries.  The version of
-Mercurial that you will end up with can vary depending on how active
-the person is who maintains the package for your distribution.
+    <sect2>
+      <title>Windows</title>
 
-To keep things simple, I will focus on installing Mercurial from the
-command line under the most popular Linux distributions.  Most of
-these distributions provide graphical package managers that will let
-you install Mercurial with a single click; the package name to look
-for is \texttt{mercurial}.
+      <para id="x_c">The best version of Mercurial for Windows is
+	TortoiseHg, which can be found at <ulink
+	  url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 
+	This package has no external dependencies; it <quote>just
+	  works</quote>.  It provides both command line and graphical
+	user interfaces.</para>
 
-\begin{itemize}
-\item[Debian]
-  \begin{codesample4}
-    apt-get install mercurial
-  \end{codesample4}
+    </sect2>
 
-\item[Fedora Core]
-  \begin{codesample4}
-    yum install mercurial
-  \end{codesample4}
+    <sect2>
+      <title>Mac OS X</title>
 
-\item[Gentoo]
-  \begin{codesample4}
-    emerge mercurial
-  \end{codesample4}
+      <para id="x_a">Lee Cantey publishes an installer of Mercurial
+	for Mac OS X at <ulink
+	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
+    </sect2>
 
-\item[OpenSUSE]
-  \begin{codesample4}
-    yum install mercurial
-  \end{codesample4}
+    <sect2>
+      <title>Linux</title>
 
-\item[Ubuntu] Ubuntu's Mercurial package is based on Debian's.  To
-  install it, run the following command.
-  \begin{codesample4}
-    apt-get install mercurial
-  \end{codesample4}
-  The Ubuntu package for Mercurial tends to lag behind the Debian
-  version by a considerable time margin (at the time of writing, seven
-  months), which in some cases will mean that on Ubuntu, you may run
-  into problems that have since been fixed in the Debian package.
-\end{itemize}
+      <para id="x_2">Because each Linux distribution has its own packaging
+	tools, policies, and rate of development, it's difficult to
+	give a comprehensive set of instructions on how to install
+	Mercurial binaries.  The version of Mercurial that you will
+	end up with can vary depending on how active the person is who
+	maintains the package for your distribution.</para>
 
-\subsection{Solaris}
+      <para id="x_3">To keep things simple, I will focus on installing
+	Mercurial from the command line under the most popular Linux
+	distributions.  Most of these distributions provide graphical
+	package managers that will let you install Mercurial with a
+	single click; the package name to look for is
+	<literal>mercurial</literal>.</para>
 
-SunFreeWare, at \url{http://www.sunfreeware.com}, is a good source for a
-large number of pre-built Solaris packages for 32 and 64 bit Intel and
-Sparc architectures, including current versions of Mercurial.
+      <itemizedlist>
+	<listitem><para id="x_4">Ubuntu and Debian:</para>
+	  <programlisting>apt-get install mercurial</programlisting></listitem>
+	<listitem><para id="x_5">Fedora:</para>
+	  <programlisting>yum install mercurial</programlisting></listitem>
+	<listitem><para id="x_715">OpenSUSE:</para>
+	  <programlisting>zypper install mercurial</programlisting></listitem>
+	<listitem><para id="x_6">Gentoo:</para>
+	  <programlisting>emerge mercurial</programlisting></listitem>
+      </itemizedlist>
 
-\subsection{Mac OS X}
+    </sect2>
+    <sect2>
+      <title>Solaris</title>
 
-Lee Cantey publishes an installer of Mercurial for Mac OS~X at
-\url{http://mercurial.berkwood.com}.  This package works on both
-Intel-~and Power-based Macs.  Before you can use it, you must install
-a compatible version of Universal MacPython~\cite{web:macpython}.  This
-is easy to do; simply follow the instructions on Lee's site.
+      <para id="x_9">SunFreeWare, at <ulink
+	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
+	provides prebuilt packages of Mercurial.</para>
 
-It's also possible to install Mercurial using Fink or MacPorts,
-two popular free package managers for Mac OS X.  If you have Fink,
-use \command{sudo fink install mercurial-py25}.  If MacPorts,
-\command{sudo port install mercurial}.
+    </sect2>
 
-\subsection{Windows}
+  </sect1>
 
-Lee Cantey publishes an installer of Mercurial for Windows at
-\url{http://mercurial.berkwood.com}.  This package has no external
-dependencies; it ``just works''.
+  <sect1>
+    <title>Getting started</title>
 
-\begin{note}
-  The Windows version of Mercurial does not automatically convert line
-  endings between Windows and Unix styles.  If you want to share work
-  with Unix users, you must do a little additional configuration
-  work. XXX Flesh this out.
-\end{note}
+    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
+	version</command> command to find out whether Mercurial is
+      installed properly.  The actual version information that it
+      prints isn't so important; we simply care whether the command
+      runs and prints anything at all.</para>
 
-\section{Getting started}
+    &interaction.tour.version;
 
-To begin, we'll use the \hgcmd{version} command to find out whether
-Mercurial is actually installed properly.  The actual version
-information that it prints isn't so important; it's whether it prints
-anything at all that we care about.
-\interaction{tour.version}
+    <sect2>
+      <title>Built-in help</title>
 
-\subsection{Built-in help}
+      <para id="x_f">Mercurial provides a built-in help system.  This is
+	  invaluable for those times when you find yourself stuck
+	  trying to remember how to run a command.  If you are
+	  completely stuck, simply run <command role="hg-cmd">hg
+	    help</command>; it will print a brief list of commands,
+	  along with a description of what each does.  If you ask for
+	  help on a specific command (as below), it prints more
+	  detailed information.</para>
 
-Mercurial provides a built-in help system.  This is invaluable for those
-times when you find yourself stuck trying to remember how to run a
-command.  If you are completely stuck, simply run \hgcmd{help}; it
-will print a brief list of commands, along with a description of what
-each does.  If you ask for help on a specific command (as below), it
-prints more detailed information.
-\interaction{tour.help}
-For a more impressive level of detail (which you won't usually need)
-run \hgcmdargs{help}{\hggopt{-v}}.  The \hggopt{-v} option is short
-for \hggopt{--verbose}, and tells Mercurial to print more information
-than it usually would.
+	&interaction.tour.help;
 
-\section{Working with a repository}
+	<para id="x_10">For a more impressive level of detail (which you won't
+	  usually need) run <command role="hg-cmd">hg help <option
+	      role="hg-opt-global">-v</option></command>.  The <option
+	    role="hg-opt-global">-v</option> option is short for
+	  <option role="hg-opt-global">--verbose</option>, and tells
+	  Mercurial to print more information than it usually
+	  would.</para>
 
-In Mercurial, everything happens inside a \emph{repository}.  The
-repository for a project contains all of the files that ``belong to''
-that project, along with a historical record of the project's files.
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Working with a repository</title>
 
-There's nothing particularly magical about a repository; it is simply
-a directory tree in your filesystem that Mercurial treats as special.
-You can rename or delete a repository any time you like, using either the
-command line or your file browser.
+    <para id="x_11">In Mercurial, everything happens inside a
+      <emphasis>repository</emphasis>.  The repository for a project
+      contains all of the files that <quote>belong to</quote> that
+      project, along with a historical record of the project's
+      files.</para>
 
-\subsection{Making a local copy of a repository}
+    <para id="x_12">There's nothing particularly magical about a repository; it
+      is simply a directory tree in your filesystem that Mercurial
+      treats as special. You can rename or delete a repository any
+      time you like, using either the command line or your file
+      browser.</para>
 
-\emph{Copying} a repository is just a little bit special.  While you
-could use a normal file copying command to make a copy of a
-repository, it's best to use a built-in command that Mercurial
-provides.  This command is called \hgcmd{clone}, because it creates an
-identical copy of an existing repository.
-\interaction{tour.clone}
-If our clone succeeded, we should now have a local directory called
-\dirname{hello}.  This directory will contain some files.
-\interaction{tour.ls}
-These files have the same contents and history in our repository as
-they do in the repository we cloned.
+    <sect2>
+      <title>Making a local copy of a repository</title>
 
-Every Mercurial repository is complete, self-contained, and
-independent.  It contains its own private copy of a project's files
-and history.  A cloned repository remembers the location of the
-repository it was cloned from, but it does not communicate with that
-repository, or any other, unless you tell it to.
+      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
+	bit special.  While you could use a normal file copying
+	command to make a copy of a repository, it's best to use a
+	built-in command that Mercurial provides.  This command is
+	called <command role="hg-cmd">hg clone</command>, because it
+	makes an identical copy of an existing repository.</para>
 
-What this means for now is that we're free to experiment with our
-repository, safe in the knowledge that it's a private ``sandbox'' that
-won't affect anyone else.
+      &interaction.tour.clone;
 
-\subsection{What's in a repository?}
+      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
+	  clone</command> is that, as we can see above, it lets us clone
+	repositories over the network.  Another is that it remembers
+	where we cloned from, which we'll find useful soon when we
+	want to fetch new changes from another repository.</para>
 
-When we take a more detailed look inside a repository, we can see that
-it contains a directory named \dirname{.hg}.  This is where Mercurial
-keeps all of its metadata for the repository.
-\interaction{tour.ls-a}
+      <para id="x_14">If our clone succeeded, we should now have a local
+	directory called <filename class="directory">hello</filename>.
+	This directory will contain some files.</para>
 
-The contents of the \dirname{.hg} directory and its subdirectories are
-private to Mercurial.  Every other file and directory in the
-repository is yours to do with as you please.
+      &interaction.tour.ls;
 
-To introduce a little terminology, the \dirname{.hg} directory is the
-``real'' repository, and all of the files and directories that coexist
-with it are said to live in the \emph{working directory}.  An easy way
-to remember the distinction is that the \emph{repository} contains the
-\emph{history} of your project, while the \emph{working directory}
-contains a \emph{snapshot} of your project at a particular point in
-history.
+      <para id="x_15">These files have the same contents and history in our
+	repository as they do in the repository we cloned.</para>
 
-\section{A tour through history}
+      <para id="x_16">Every Mercurial repository is complete,
+	self-contained, and independent.  It contains its own private
+	copy of a project's files and history.  As we just mentioned,
+	a cloned repository remembers the location of the repository
+	it was cloned from, but Mercurial will not communicate with
+	that repository, or any other, unless you tell it to.</para>
 
-One of the first things we might want to do with a new, unfamiliar
-repository is understand its history.  The \hgcmd{log} command gives
-us a view of history.
-\interaction{tour.log}
-By default, this command prints a brief paragraph of output for each
-change to the project that was recorded.  In Mercurial terminology, we
-call each of these recorded events a \emph{changeset}, because it can
-contain a record of changes to several files.
+      <para id="x_17">What this means for now is that we're free to experiment
+	with our repository, safe in the knowledge that it's a private
+	<quote>sandbox</quote> that won't affect anyone else.</para>
 
-The fields in a record of output from \hgcmd{log} are as follows.
-\begin{itemize}
-\item[\texttt{changeset}] This field has the format of a number,
-  followed by a colon, followed by a hexadecimal string.  These are
-  \emph{identifiers} for the changeset.  There are two identifiers
-  because the number is shorter and easier to type than the hex
-  string.
-\item[\texttt{user}] The identity of the person who created the
-  changeset.  This is a free-form field, but it most often contains a
-  person's name and email address.
-\item[\texttt{date}] The date and time on which the changeset was
-  created, and the timezone in which it was created.  (The date and
-  time are local to that timezone; they display what time and date it
-  was for the person who created the changeset.)
-\item[\texttt{summary}] The first line of the text message that the
-  creator of the changeset entered to describe the changeset.
-\end{itemize}
-The default output printed by \hgcmd{log} is purely a summary; it is
-missing a lot of detail.
+    </sect2>
+    <sect2>
+      <title>What's in a repository?</title>
 
-Figure~\ref{fig:tour-basic:history} provides a graphical representation of
-the history of the \dirname{hello} repository, to make it a little
-easier to see which direction history is ``flowing'' in.  We'll be
-returning to this figure several times in this chapter and the chapter
-that follows.
+      <para id="x_18">When we take a more detailed look inside a repository, we
+	can see that it contains a directory named <filename
+	  class="directory">.hg</filename>.  This is where Mercurial
+	keeps all of its metadata for the repository.</para>
 
-\begin{figure}[ht]
-  \centering
-  \grafix{tour-history}
-  \caption{Graphical history of the \dirname{hello} repository}
-  \label{fig:tour-basic:history}
-\end{figure}
+      &interaction.tour.ls-a;
 
-\subsection{Changesets, revisions, and talking to other 
-  people}
+      <para id="x_19">The contents of the <filename
+	  class="directory">.hg</filename> directory and its
+	subdirectories are private to Mercurial.  Every other file and
+	directory in the repository is yours to do with as you
+	please.</para>
 
-As English is a notoriously sloppy language, and computer science has
-a hallowed history of terminological confusion (why use one term when
-four will do?), revision control has a variety of words and phrases
-that mean the same thing.  If you are talking about Mercurial history
-with other people, you will find that the word ``changeset'' is often
-compressed to ``change'' or (when written) ``cset'', and sometimes a
-changeset is referred to as a ``revision'' or a ``rev''.
+      <para id="x_1a">To introduce a little terminology, the <filename
+	  class="directory">.hg</filename> directory is the
+	<quote>real</quote> repository, and all of the files and
+	directories that coexist with it are said to live in the
+	<emphasis>working directory</emphasis>.  An easy way to
+	remember the distinction is that the
+	<emphasis>repository</emphasis> contains the
+	<emphasis>history</emphasis> of your project, while the
+	<emphasis>working directory</emphasis> contains a
+	<emphasis>snapshot</emphasis> of your project at a particular
+	point in history.</para>
 
-While it doesn't matter what \emph{word} you use to refer to the
-concept of ``a~changeset'', the \emph{identifier} that you use to
-refer to ``a~\emph{specific} changeset'' is of great importance.
-Recall that the \texttt{changeset} field in the output from
-\hgcmd{log} identifies a changeset using both a number and a
-hexadecimal string.
-\begin{itemize}
-\item The revision number is \emph{only valid in that repository},
-\item while the hex string is the \emph{permanent, unchanging
-    identifier} that will always identify that exact changeset in
-  \emph{every} copy of the repository.
-\end{itemize}
-This distinction is important.  If you send someone an email talking
-about ``revision~33'', there's a high likelihood that their
-revision~33 will \emph{not be the same} as yours.  The reason for this
-is that a revision number depends on the order in which changes
-arrived in a repository, and there is no guarantee that the same
-changes will happen in the same order in different repositories.
-Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
-while in another as $1,0,2$.
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>A tour through history</title>
 
-Mercurial uses revision numbers purely as a convenient shorthand.  If
-you need to discuss a changeset with someone, or make a record of a
-changeset for some other reason (for example, in a bug report), use
-the hexadecimal identifier.
+    <para id="x_1b">One of the first things we might want to do with a new,
+      unfamiliar repository is understand its history.  The <command
+	role="hg-cmd">hg log</command> command gives us a view of
+      the history of changes in the repository.</para>
 
-\subsection{Viewing specific revisions}
+    &interaction.tour.log;
 
-To narrow the output of \hgcmd{log} down to a single revision, use the
-\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
-revision number or a long-form changeset identifier, and you can
-provide as many revisions as you want.  \interaction{tour.log-r}
+    <para id="x_1c">By default, this command prints a brief paragraph of output
+      for each change to the project that was recorded.  In Mercurial
+      terminology, we call each of these recorded events a
+      <emphasis>changeset</emphasis>, because it can contain a record
+      of changes to several files.</para>
 
-If you want to see the history of several revisions without having to
-list each one, you can use \emph{range notation}; this lets you
-express the idea ``I want all revisions between $a$ and $b$,
-inclusive''.
-\interaction{tour.log.range}
-Mercurial also honours the order in which you specify revisions, so
-\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
-prints $4,3,2$.
+    <para id="x_1d">The fields in a record of output from <command
+	role="hg-cmd">hg log</command> are as follows.</para>
 
-\subsection{More detailed information}
+    <itemizedlist>
+      <listitem><para id="x_1e"><literal>changeset</literal>: This
+	  field has the format of a number, followed by a colon,
+	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
+	  string.  These are <emphasis>identifiers</emphasis> for the
+	  changeset.  The hex string is a unique identifier: the same
+	  hex string will always refer to the same changeset in every
+	  copy of this repository. The
+	  number is shorter and easier to type than the hex string,
+	  but it isn't unique: the same number in two different clones
+	  of a repository may identify different changesets.</para>
+      </listitem>
+      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
+	  person who created the changeset.  This is a free-form
+	  field, but it most often contains a person's name and email
+	  address.</para></listitem>
+      <listitem><para id="x_20"><literal>date</literal>: The date and time on
+	  which the changeset was created, and the timezone in which
+	  it was created.  (The date and time are local to that
+	  timezone; they display what time and date it was for the
+	  person who created the changeset.)</para></listitem>
+      <listitem><para id="x_21"><literal>summary</literal>: The first line of
+	  the text message that the creator of the changeset entered
+	  to describe the changeset.</para></listitem>
+      <listitem>
+	<para id="x_67d">Some changesets, such as the first in the list above,
+	  have a <literal>tag</literal> field.  A tag is another way
+	  to identify a changeset, by giving it an easy-to-remember
+	  name. (The tag named <literal>tip</literal> is special: it
+	  always refers to the newest change in a repository.)</para>
+      </listitem>
+    </itemizedlist>
 
-While the summary information printed by \hgcmd{log} is useful if you
-already know what you're looking for, you may need to see a complete
-description of the change, or a list of the files changed, if you're
-trying to decide whether a changeset is the one you're looking for.
-The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
-option gives you this extra detail.
-\interaction{tour.log-v}
+    <para id="x_22">The default output printed by <command
+	role="hg-cmd">hg log</command> is purely a summary; it is
+      missing a lot of detail.</para>
 
-If you want to see both the description and content of a change, add
-the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
-the content of a change as a \emph{unified diff} (if you've never seen
-a unified diff before, see section~\ref{sec:mq:patch} for an overview).
-\interaction{tour.log-vp}
+    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
+      a graphical representation of the history of the <filename
+	class="directory">hello</filename> repository, to make it a
+      little easier to see which direction history is
+      <quote>flowing</quote> in.  We'll be returning to this figure
+      several times in this chapter and the chapter that
+      follows.</para>
 
-\section{All about command options}
+    <figure id="fig:tour-basic:history">
+      <title>Graphical history of the <filename
+	  class="directory">hello</filename> repository</title>
+      <mediaobject>
+	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
+	<textobject><phrase>XXX add text</phrase></textobject>
+      </mediaobject>
+    </figure>
 
-Let's take a brief break from exploring Mercurial commands to discuss
-a pattern in the way that they work; you may find this useful to keep
-in mind as we continue our tour.
+    <sect2>
+      <title>Changesets, revisions, and talking to other
+	people</title>
 
-Mercurial has a consistent and straightforward approach to dealing
-with the options that you can pass to commands.  It follows the
-conventions for options that are common to modern Linux and Unix
-systems.
-\begin{itemize}
-\item Every option has a long name.  For example, as we've already
-  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
-\item Most options have short names, too.  Instead of
-  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
-  some options don't have short names is that the options in question
-  are rarely used.)
-\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
-  while short options start with one (e.g.~\hgopt{log}{-r}).
-\item Option naming and usage is consistent across commands.  For
-  example, every command that lets you specify a changeset~ID or
-  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
-  arguments.
-\end{itemize}
-In the examples throughout this book, I use short options instead of
-long.  This just reflects my own preference, so don't read anything
-significant into it.
+      <para id="x_25">As English is a notoriously sloppy language, and computer
+	science has a hallowed history of terminological confusion
+	(why use one term when four will do?), revision control has a
+	variety of words and phrases that mean the same thing.  If you
+	are talking about Mercurial history with other people, you
+	will find that the word <quote>changeset</quote> is often
+	compressed to <quote>change</quote> or (when written)
+	<quote>cset</quote>, and sometimes a changeset is referred to
+	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
 
-Most commands that print output of some kind will print more output
-when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
-when passed \hggopt{-q} (or \hggopt{--quiet}).
+      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
+	use to refer to the concept of <quote>a changeset</quote>, the
+	<emphasis>identifier</emphasis> that you use to refer to
+	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
+	great importance. Recall that the <literal>changeset</literal>
+	field in the output from <command role="hg-cmd">hg
+	  log</command> identifies a changeset using both a number and
+	a hexadecimal string.</para>
+      <itemizedlist>
+	<listitem><para id="x_27">The revision number is a handy
+	    notation that is <emphasis>only valid in that
+	      repository</emphasis>.</para></listitem>
+	<listitem><para id="x_28">The hexadecimal string is the
+	    <emphasis>permanent, unchanging identifier</emphasis> that
+	    will always identify that exact changeset in
+	    <emphasis>every</emphasis> copy of the
+	    repository.</para></listitem></itemizedlist>
 
-\section{Making and reviewing changes}
+      <para id="x_29">This distinction is important.  If you send
+	someone an email talking about <quote>revision 33</quote>,
+	there's a high likelihood that their revision 33 will
+	<emphasis>not be the same</emphasis> as yours.  The reason for
+	this is that a revision number depends on the order in which
+	changes arrived in a repository, and there is no guarantee
+	that the same changes will happen in the same order in
+	different repositories. Three changes <literal>a,b,c</literal>
+	can easily appear in one repository as
+	<literal>0,1,2</literal>, while in another as
+	<literal>0,2,1</literal>.</para>
 
-Now that we have a grasp of viewing history in Mercurial, let's take a
-look at making some changes and examining them.
+      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
+	shorthand.  If you need to discuss a changeset with someone,
+	or make a record of a changeset for some other reason (for
+	example, in a bug report), use the hexadecimal
+	identifier.</para>
 
-The first thing we'll do is isolate our experiment in a repository of
-its own.  We use the \hgcmd{clone} command, but we don't need to
-clone a copy of the remote repository.  Since we already have a copy
-of it locally, we can just clone that instead.  This is much faster
-than cloning over the network, and cloning a local repository uses
-less disk space in most cases, too.
-\interaction{tour.reclone}
-As an aside, it's often good practice to keep a ``pristine'' copy of a
-remote repository around, which you can then make temporary clones of
-to create sandboxes for each task you want to work on.  This lets you
-work on multiple tasks in parallel, each isolated from the others
-until it's complete and you're ready to integrate it back.  Because
-local clones are so cheap, there's almost no overhead to cloning and
-destroying repositories whenever you want.
+    </sect2>
+    <sect2>
+      <title>Viewing specific revisions</title>
 
-In our \dirname{my-hello} repository, we have a file
-\filename{hello.c} that contains the classic ``hello, world'' program.
-Let's use the ancient and venerable \command{sed} command to edit this
-file so that it prints a second line of output.  (I'm only using
-\command{sed} to do this because it's easy to write a scripted example
-this way.  Since you're not under the same constraint, you probably
-won't want to use \command{sed}; simply use your preferred text editor to
-do the same thing.)
-\interaction{tour.sed}
+      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
+	  log</command> down to a single revision, use the <option
+	  role="hg-opt-log">-r</option> (or <option
+	  role="hg-opt-log">--rev</option>) option.  You can use
+	either a revision number or a hexadecimal identifier,
+	and you can provide as many revisions as you want.</para>
 
-Mercurial's \hgcmd{status} command will tell us what Mercurial knows
-about the files in the repository.
-\interaction{tour.status}
-The \hgcmd{status} command prints no output for some files, but a line
-starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
-it to, \hgcmd{status} will not print any output for files that have
-not been modified.  
+      &interaction.tour.log-r;
 
-The ``\texttt{M}'' indicates that Mercurial has noticed that we
-modified \filename{hello.c}.  We didn't need to \emph{inform}
-Mercurial that we were going to modify the file before we started, or
-that we had modified the file after we were done; it was able to
-figure this out itself.
+      <para id="x_2c">If you want to see the history of several revisions
+	without having to list each one, you can use <emphasis>range
+	  notation</emphasis>; this lets you express the idea <quote>I
+	  want all revisions between <literal>abc</literal> and
+	  <literal>def</literal>, inclusive</quote>.</para>
+      
+	&interaction.tour.log.range;
 
-It's a little bit helpful to know that we've modified
-\filename{hello.c}, but we might prefer to know exactly \emph{what}
-changes we've made to it.  To do this, we use the \hgcmd{diff}
-command.
-\interaction{tour.diff}
+      <para id="x_2d">Mercurial also honours the order in which you specify
+	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
+	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
+	  4:2</command> prints 4, 3, and 2.</para>
 
-\section{Recording changes in a new changeset}
+    </sect2>
+    <sect2>
+      <title>More detailed information</title>
 
-We can modify files, build and test our changes, and use
-\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
-satisfied with what we've done and arrive at a natural stopping point
-where we want to record our work in a new changeset.
+      <para id="x_2e">While the summary information printed by <command
+	  role="hg-cmd">hg log</command> is useful if you already know
+	what you're looking for, you may need to see a complete
+	description of the change, or a list of the files changed, if
+	you're trying to decide whether a changeset is the one you're
+	looking for. The <command role="hg-cmd">hg log</command>
+	command's <option role="hg-opt-global">-v</option> (or <option
+	  role="hg-opt-global">--verbose</option>) option gives you
+	this extra detail.</para>
 
-The \hgcmd{commit} command lets us create a new changeset; we'll
-usually refer to this as ``making a commit'' or ``committing''.  
+      &interaction.tour.log-v;
 
-\subsection{Setting up a username}
+      <para id="x_2f">If you want to see both the description and
+	content of a change, add the <option
+	  role="hg-opt-log">-p</option> (or <option
+	  role="hg-opt-log">--patch</option>) option.  This displays
+	the content of a change as a <emphasis>unified diff</emphasis>
+	(if you've never seen a unified diff before, see <xref
+	  linkend="sec:mq:patch"/> for an overview).</para>
 
-When you try to run \hgcmd{commit} for the first time, it is not
-guaranteed to succeed.  Mercurial records your name and address with
-each change that you commit, so that you and others will later be able
-to tell who made each change.  Mercurial tries to automatically figure
-out a sensible username to commit the change with.  It will attempt
-each of the following methods, in order:
-\begin{enumerate}
-\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
-  command on the command line, followed by a username, this is always
-  given the highest precedence.
-\item If you have set the \envar{HGUSER} environment variable, this is
-  checked next.
-\item If you create a file in your home directory called
-  \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
-  used next.  To see what the contents of this file should look like,
-  refer to section~\ref{sec:tour-basic:username} below.
-\item If you have set the \envar{EMAIL} environment variable, this
-  will be used next.
-\item Mercurial will query your system to find out your local user
-  name and host name, and construct a username from these components.
-  Since this often results in a username that is not very useful, it
-  will print a warning if it has to do this.
-\end{enumerate}
-If all of these mechanisms fail, Mercurial will fail, printing an
-error message.  In this case, it will not let you commit until you set
-up a username.
+      &interaction.tour.log-vp;
 
-You should think of the \envar{HGUSER} environment variable and the
-\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
-\emph{override} Mercurial's default selection of username.  For normal
-use, the simplest and most robust way to set a username for yourself
-is by creating a \sfilename{.hgrc} file; see below for details.
+      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
+	tremendously useful, so it's well worth remembering.</para>
 
-\subsubsection{Creating a Mercurial configuration file}
-\label{sec:tour-basic:username}
+    </sect2>
+  </sect1>
 
-To set a user name, use your favourite editor to create a file called
-\sfilename{.hgrc} in your home directory.  Mercurial will use this
-file to look up your personalised configuration settings.  The initial
-contents of your \sfilename{.hgrc} should look like this.
-\begin{codesample2}
-  # This is a Mercurial configuration file.
-  [ui]
-  username = Firstname Lastname <email.address@domain.net>
-\end{codesample2}
-The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
-so you can read the ``\texttt{username = ...}'' line as meaning ``set
-the value of the \texttt{username} item in the \texttt{ui} section''.
-A section continues until a new section begins, or the end of the
-file.  Mercurial ignores empty lines and treats any text from
-``\texttt{\#}'' to the end of a line as a comment.
+  <sect1>
+    <title>All about command options</title>
 
-\subsubsection{Choosing a user name}
+    <para id="x_30">Let's take a brief break from exploring Mercurial commands
+      to discuss a pattern in the way that they work; you may find
+      this useful to keep in mind as we continue our tour.</para>
 
-You can use any text you like as the value of the \texttt{username}
-config item, since this information is for reading by other people,
-but for interpreting by Mercurial.  The convention that most people
-follow is to use their name and email address, as in the example
-above.
+    <para id="x_31">Mercurial has a consistent and straightforward approach to
+      dealing with the options that you can pass to commands.  It
+      follows the conventions for options that are common to modern
+      Linux and Unix systems.</para>
 
-\begin{note}
-  Mercurial's built-in web server obfuscates email addresses, to make
-  it more difficult for the email harvesting tools that spammers use.
-  This reduces the likelihood that you'll start receiving more junk
-  email if you publish a Mercurial repository on the web.
-\end{note}
+    <itemizedlist>
+      <listitem>
+	<para id="x_32">Every option has a long name.  For example, as
+	  we've already seen, the <command role="hg-cmd">hg
+	    log</command> command accepts a <option
+	    role="hg-opt-log">--rev</option> option.</para>
+      </listitem>
+      <listitem>
+	<para id="x_33">Most options have short names, too.  Instead
+	  of <option role="hg-opt-log">--rev</option>, we can use
+	  <option role="hg-opt-log">-r</option>.  (The reason that
+	  some options don't have short names is that the options in
+	  question are rarely used.)</para>
+      </listitem>
+      <listitem>
+	<para id="x_34">Long options start with two dashes (e.g.
+	  <option role="hg-opt-log">--rev</option>), while short
+	  options start with one (e.g. <option
+	    role="hg-opt-log">-r</option>).</para>
+      </listitem>
+      <listitem>
+	<para id="x_35">Option naming and usage is consistent across
+	  commands.  For example, every command that lets you specify
+	  a changeset ID or revision number accepts both <option
+	    role="hg-opt-log">-r</option> and <option
+	    role="hg-opt-log">--rev</option> arguments.</para>
+      </listitem>
+      <listitem>
+	<para id="x_67f">If you are using short options, you can save typing by
+	  running them together. For example, the command <command
+	    role="hg-cmd">hg log -v -p -r 2</command> can be written
+	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
+      </listitem>
+    </itemizedlist>
 
-\subsection{Writing a commit message}
+    <para id="x_36">In the examples throughout this book, I usually
+      use short options instead of long.  This simply reflects my own
+      preference, so don't read anything significant into it.</para>
 
-When we commit a change, Mercurial drops us into a text editor, to
-enter a message that will describe the modifications we've made in
-this changeset.  This is called the \emph{commit message}.  It will be
-a record for readers of what we did and why, and it will be printed by
-\hgcmd{log} after we've finished committing.
-\interaction{tour.commit}
+    <para id="x_37">Most commands that print output of some kind will print more
+      output when passed a <option role="hg-opt-global">-v</option>
+      (or <option role="hg-opt-global">--verbose</option>) option, and
+      less when passed <option role="hg-opt-global">-q</option> (or
+      <option role="hg-opt-global">--quiet</option>).</para>
 
-The editor that the \hgcmd{commit} command drops us into will contain
-an empty line, followed by a number of lines starting with
-``\texttt{HG:}''.
-\begin{codesample2}
-  \emph{empty line}
-  HG: changed hello.c
-\end{codesample2}
-Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
-them only to tell us which files it's recording changes to.  Modifying
-or deleting these lines has no effect.
+    <note>
+      <title>Option naming consistency</title>
 
-\subsection{Writing a good commit message}
+      <para id="x_680">Almost always, Mercurial commands use consistent option
+	names to refer to the same concepts.  For instance, if a
+	command deals with changesets, you'll always identify them
+	with <option role="hg-opt-log">--rev</option> or <option
+	  role="hg-opt-log">-r</option>.  This consistent use of
+	option names makes it easier to remember what options a
+	particular command takes.</para>
+    </note>
 
-Since \hgcmd{log} only prints the first line of a commit message by
-default, it's best to write a commit message whose first line stands
-alone.  Here's a real example of a commit message that \emph{doesn't}
-follow this guideline, and hence has a summary that is not readable.
-\begin{codesample2}
-  changeset:   73:584af0e231be
-  user:        Censored Person <censored.person@example.org>
-  date:        Tue Sep 26 21:37:07 2006 -0700
-  summary:     include buildmeister/commondefs.   Add an exports and install
-\end{codesample2}
+  </sect1>
+  <sect1>
+    <title>Making and reviewing changes</title>
 
-As far as the remainder of the contents of the commit message are
-concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
-interpret or care about the contents of the commit message, though
-your project may have policies that dictate a certain kind of
-formatting.
+    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
+      let's take a look at making some changes and examining
+      them.</para>
 
-My personal preference is for short, but informative, commit messages
-that tell me something that I can't figure out with a quick glance at
-the output of \hgcmdargs{log}{--patch}.
+    <para id="x_39">The first thing we'll do is isolate our experiment in a
+      repository of its own.  We use the <command role="hg-cmd">hg
+	clone</command> command, but we don't need to clone a copy of
+      the remote repository.  Since we already have a copy of it
+      locally, we can just clone that instead.  This is much faster
+      than cloning over the network, and cloning a local repository
+      uses less disk space in most cases, too<footnote>
+	<para id="x_681">The saving of space arises when source and destination
+	  repositories are on the same filesystem, in which case
+	  Mercurial will use hardlinks to do copy-on-write sharing of
+	  its internal metadata.  If that explanation meant nothing to
+	  you, don't worry: everything happens transparently and
+	  automatically, and you don't need to understand it.</para>
+	</footnote>.</para>
 
-\subsection{Aborting a commit}
+    &interaction.tour.reclone;
 
-If you decide that you don't want to commit while in the middle of
-editing a commit message, simply exit from your editor without saving
-the file that it's editing.  This will cause nothing to happen to
-either the repository or the working directory.
+    <para id="x_3a">As an aside, it's often good practice to keep a
+      <quote>pristine</quote> copy of a remote repository around,
+      which you can then make temporary clones of to create sandboxes
+      for each task you want to work on.  This lets you work on
+      multiple tasks in parallel, each isolated from the others until
+      it's complete and you're ready to integrate it back.  Because
+      local clones are so cheap, there's almost no overhead to cloning
+      and destroying repositories whenever you want.</para>
 
-If we run the \hgcmd{commit} command without any arguments, it records
-all of the changes we've made, as reported by \hgcmd{status} and
-\hgcmd{diff}.
+    <para id="x_3b">In our <filename class="directory">my-hello</filename>
+      repository, we have a file <filename>hello.c</filename> that
+      contains the classic <quote>hello, world</quote> program.</para>
 
-\subsection{Admiring our new handiwork}
+    &interaction.tour.cat1;
 
-Once we've finished the commit, we can use the \hgcmd{tip} command to
-display the changeset we just created.  This command produces output
-that is identical to \hgcmd{log}, but it only displays the newest
-revision in the repository.
-\interaction{tour.tip}
-We refer to the newest revision in the repository as the tip revision,
-or simply the tip.
+    <para id="x_682">Let's edit this file so that it prints a second line of
+      output.</para>
 
-\section{Sharing changes}
+    &interaction.tour.cat2;
 
-We mentioned earlier that repositories in Mercurial are
-self-contained.  This means that the changeset we just created exists
-only in our \dirname{my-hello} repository.  Let's look at a few ways
-that we can propagate this change into other repositories.
+    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
+      command will tell us what Mercurial knows about the files in the
+      repository.</para>
 
-\subsection{Pulling changes from another repository}
-\label{sec:tour:pull}
+    &interaction.tour.status;
 
-To get started, let's clone our original \dirname{hello} repository,
-which does not contain the change we just committed.  We'll call our
-temporary repository \dirname{hello-pull}.
-\interaction{tour.clone-pull}
+    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
+      prints no output for some files, but a line starting with
+      <quote><literal>M</literal></quote> for
+      <filename>hello.c</filename>.  Unless you tell it to, <command
+	role="hg-cmd">hg status</command> will not print any output
+      for files that have not been modified.</para>
 
-We'll use the \hgcmd{pull} command to bring changes from
-\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
-pulling unknown changes into a repository is a somewhat scary
-prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
-what changes the \hgcmd{pull} command \emph{would} pull into the
-repository, without actually pulling the changes in.
-\interaction{tour.incoming}
-(Of course, someone could cause more changesets to appear in the
-repository that we ran \hgcmd{incoming} in, before we get a chance to
-\hgcmd{pull} the changes, so that we could end up pulling changes that we
-didn't expect.)
+    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
+      Mercurial has noticed that we modified
+      <filename>hello.c</filename>.  We didn't need to
+      <emphasis>inform</emphasis> Mercurial that we were going to
+      modify the file before we started, or that we had modified the
+      file after we were done; it was able to figure this out
+      itself.</para>
 
-Bringing changes into a repository is a simple matter of running the
-\hgcmd{pull} command, and telling it which repository to pull from.
-\interaction{tour.pull}
-As you can see from the before-and-after output of \hgcmd{tip}, we
-have successfully pulled changes into our repository.  There remains
-one step before we can see these changes in the working directory.
+    <para id="x_3f">It's somewhat helpful to know that we've modified
+      <filename>hello.c</filename>, but we might prefer to know
+      exactly <emphasis>what</emphasis> changes we've made to it.  To
+      do this, we use the <command role="hg-cmd">hg diff</command>
+      command.</para>
 
-\subsection{Updating the working directory}
+    &interaction.tour.diff;
 
-We have so far glossed over the relationship between a repository and
-its working directory.  The \hgcmd{pull} command that we ran in
-section~\ref{sec:tour:pull} brought changes into the repository, but
-if we check, there's no sign of those changes in the working
-directory.  This is because \hgcmd{pull} does not (by default) touch
-the working directory.  Instead, we use the \hgcmd{update} command to
-do this.
-\interaction{tour.update}
+    <tip>
+      <title>Understanding patches</title>
 
-It might seem a bit strange that \hgcmd{pull} doesn't update the
-working directory automatically.  There's actually a good reason for
-this: you can use \hgcmd{update} to update the working directory to
-the state it was in at \emph{any revision} in the history of the
-repository.  If you had the working directory updated to an old
-revision---to hunt down the origin of a bug, say---and ran a
-\hgcmd{pull} which automatically updated the working directory to a
-new revision, you might not be terribly happy.
+      <para id="x_683">Remember to take a look at <xref
+	  linkend="sec:mq:patch"/> if you don't know how to read
+	output above.</para>
+    </tip>
+  </sect1>
+  <sect1>
+    <title>Recording changes in a new changeset</title>
 
-However, since pull-then-update is such a common thing to do,
-Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
-option to \hgcmd{pull}.
-\begin{codesample2}
-  hg pull -u
-\end{codesample2}
-If you look back at the output of \hgcmd{pull} in
-section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
-you can see that it printed a helpful reminder that we'd have to take
-an explicit step to update the working directory:
-\begin{codesample2}
-  (run 'hg update' to get a working copy)
-\end{codesample2}
+    <para id="x_40">We can modify files, build and test our changes, and use
+      <command role="hg-cmd">hg status</command> and <command
+	role="hg-cmd">hg diff</command> to review our changes, until
+      we're satisfied with what we've done and arrive at a natural
+      stopping point where we want to record our work in a new
+      changeset.</para>
 
-To find out what revision the working directory is at, use the
-\hgcmd{parents} command.
-\interaction{tour.parents}
-If you look back at figure~\ref{fig:tour-basic:history}, you'll see
-arrows connecting each changeset.  The node that the arrow leads
-\emph{from} in each case is a parent, and the node that the arrow
-leads \emph{to} is its child.  The working directory has a parent in
-just the same way; this is the changeset that the working directory
-currently contains.
+    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
+      us create a new changeset; we'll usually refer to this as
+      <quote>making a commit</quote> or
+      <quote>committing</quote>.</para>
 
-To update the working directory to a particular revision, give a
-revision number or changeset~ID to the \hgcmd{update} command.
-\interaction{tour.older}
-If you omit an explicit revision, \hgcmd{update} will update to the
-tip revision, as shown by the second call to \hgcmd{update} in the
-example above.
+    <sect2>
+      <title>Setting up a username</title>
 
-\subsection{Pushing changes to another repository}
+      <para id="x_42">When you try to run <command role="hg-cmd">hg
+	  commit</command> for the first time, it is not guaranteed to
+	succeed.  Mercurial records your name and address with each
+	change that you commit, so that you and others will later be
+	able to tell who made each change.  Mercurial tries to
+	automatically figure out a sensible username to commit the
+	change with.  It will attempt each of the following methods,
+	in order:</para>
+      <orderedlist>
+	<listitem><para id="x_43">If you specify a <option
+	      role="hg-opt-commit">-u</option> option to the <command
+	      role="hg-cmd">hg commit</command> command on the command
+	    line, followed by a username, this is always given the
+	    highest precedence.</para></listitem>
+	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
+	    environment variable, this is checked
+	    next.</para></listitem>
+	<listitem><para id="x_45">If you create a file in your home
+	    directory called <filename
+	      role="special">.hgrc</filename>, with a <envar
+	      role="rc-item-ui">username</envar> entry, that will be
+	    used next.  To see what the contents of this file should
+	    look like, refer to <xref
+	      linkend="sec:tour-basic:username"/>
+	    below.</para></listitem>
+	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
+	    environment variable, this will be used
+	    next.</para></listitem>
+	<listitem><para id="x_47">Mercurial will query your system to find out
+	    your local user name and host name, and construct a
+	    username from these components. Since this often results
+	    in a username that is not very useful, it will print a
+	    warning if it has to do
+	    this.</para></listitem>
+      </orderedlist>
+      <para id="x_48">If all of these mechanisms fail, Mercurial will
+	  fail, printing an error message.  In this case, it will not
+	  let you commit until you set up a
+	  username.</para>
+      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
+	variable and the <option role="hg-opt-commit">-u</option>
+	option to the <command role="hg-cmd">hg commit</command>
+	command as ways to <emphasis>override</emphasis> Mercurial's
+	default selection of username.  For normal use, the simplest
+	and most robust way to set a username for yourself is by
+	creating a <filename role="special">.hgrc</filename> file; see
+	below for details.</para>
+      <sect3 id="sec:tour-basic:username">
+	<title>Creating a Mercurial configuration file</title>
 
-Mercurial lets us push changes to another repository, from the
-repository we're currently visiting.  As with the example of
-\hgcmd{pull} above, we'll create a temporary repository to push our
-changes into.
-\interaction{tour.clone-push}
-The \hgcmd{outgoing} command tells us what changes would be pushed
-into another repository.
-\interaction{tour.outgoing}
-And the \hgcmd{push} command does the actual push.
-\interaction{tour.push}
-As with \hgcmd{pull}, the \hgcmd{push} command does not update the
-working directory in the repository that it's pushing changes into.
-(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
-option that updates the other repository's working directory.)
+	<para id="x_4a">To set a user name, use your favorite editor
+	  to create a file called <filename
+	    role="special">.hgrc</filename> in your home directory.
+	  Mercurial will use this file to look up your personalised
+	  configuration settings.  The initial contents of your
+	  <filename role="special">.hgrc</filename> should look like
+	  this.</para>
 
-What happens if we try to pull or push changes and the receiving
-repository already has those changes?  Nothing too exciting.
-\interaction{tour.push.nothing}
+	<tip>
+	  <title><quote>Home directory</quote> on Windows</title>
 
-\subsection{Sharing changes over a network}
+	  <para id="x_716">When we refer to your home directory, on an English
+	    language installation of Windows this will usually be a
+	    folder named after your user name in
+	    <filename>C:\Documents and Settings</filename>.  You can
+	    find out the exact name of your home directory by opening
+	    a command prompt window and running the following
+	    command.</para>
 
-The commands we have covered in the previous few sections are not
-limited to working with local repositories.  Each works in exactly the
-same fashion over a network connection; simply pass in a URL instead
-of a local path.
-\interaction{tour.outgoing.net}
-In this example, we can see what changes we could push to the remote
-repository, but the repository is understandably not set up to let
-anonymous users push to it.
-\interaction{tour.push.net}
+	  <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
+	</tip>
 
-%%% Local Variables: 
-%%% mode: latex
-%%% TeX-master: "00book"
-%%% End: 
+	<programlisting># This is a Mercurial configuration file.
+[ui]
+username = Firstname Lastname &lt;email.address@example.net&gt;</programlisting>
+
+	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
+	  <emphasis>section</emphasis> of the config file, so you can
+	  read the <quote><literal>username = ...</literal></quote>
+	  line as meaning <quote>set the value of the
+	    <literal>username</literal> item in the
+	    <literal>ui</literal> section</quote>. A section continues
+	  until a new section begins, or the end of the file.
+	  Mercurial ignores empty lines and treats any text from
+	  <quote><literal>#</literal></quote> to the end of a line as
+	  a comment.</para>
+      </sect3>
+
+      <sect3>
+	<title>Choosing a user name</title>
+
+	<para id="x_4c">You can use any text you like as the value of
+	  the <literal>username</literal> config item, since this
+	  information is for reading by other people, but will not be
+	  interpreted by Mercurial.  The convention that most people
+	  follow is to use their name and email address, as in the
+	  example above.</para>
+	<note>
+	  <para id="x_4d">Mercurial's built-in web server obfuscates
+	    email addresses, to make it more difficult for the email
+	    harvesting tools that spammers use. This reduces the
+	    likelihood that you'll start receiving more junk email if
+	    you publish a Mercurial repository on the
+	    web.</para></note>
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Writing a commit message</title>
+
+      <para id="x_4e">When we commit a change, Mercurial drops us into
+	a text editor, to enter a message that will describe the
+	modifications we've made in this changeset.  This is called
+	the <emphasis>commit message</emphasis>.  It will be a record
+	for readers of what we did and why, and it will be printed by
+	<command role="hg-cmd">hg log</command> after we've finished
+	committing.</para>
+
+       &interaction.tour.commit;
+
+      <para id="x_4f">The editor that the <command role="hg-cmd">hg
+	  commit</command> command drops us into will contain an empty
+	line or two, followed by a number of lines starting with
+	<quote><literal>HG:</literal></quote>.</para>
+
+    <programlisting>
+This is where I type my commit comment.
+
+HG: Enter commit message.  Lines beginning with 'HG:' are removed.
+HG: --
+HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+HG: branch 'default'
+HG: changed hello.c</programlisting>
+
+      <para id="x_50">Mercurial ignores the lines that start with
+	<quote><literal>HG:</literal></quote>; it uses them only to
+	tell us which files it's recording changes to.  Modifying or
+	deleting these lines has no effect.</para>
+    </sect2>
+    <sect2>
+      <title>Writing a good commit message</title>
+
+      <para id="x_51">Since <command role="hg-cmd">hg log</command>
+	only prints the first line of a commit message by default,
+	it's best to write a commit message whose first line stands
+	alone.  Here's a real example of a commit message that
+	<emphasis>doesn't</emphasis> follow this guideline, and hence
+	has a summary that is not readable.</para>
+
+      <programlisting>
+changeset:   73:584af0e231be
+user:        Censored Person &lt;censored.person@example.org&gt;
+date:        Tue Sep 26 21:37:07 2006 -0700
+summary:     include buildmeister/commondefs. Add exports.</programlisting>
+
+      <para id="x_52">As far as the remainder of the contents of the
+	commit message are concerned, there are no hard-and-fast
+	rules.  Mercurial itself doesn't interpret or care about the
+	contents of the commit message, though your project may have
+	policies that dictate a certain kind of formatting.</para>
+      <para id="x_53">My personal preference is for short, but
+	informative, commit messages that tell me something that I
+	can't figure out with a quick glance at the output of <command
+	  role="hg-cmd">hg log --patch</command>.</para>
+      <para id="x_55">If we run the <command role="hg-cmd">hg
+	  commit</command> command without any arguments, it records
+	all of the changes we've made, as reported by <command
+	  role="hg-cmd">hg status</command> and <command
+	  role="hg-cmd">hg diff</command>.</para>
+
+      <note>
+	<title>A surprise for Subversion users</title>
+
+	<para id="x_717">Like other Mercurial commands, if we don't supply
+	  explicit names to commit to the <command role="hg-cmd">hg
+	    commit</command>, it will operate across a repository's
+	  entire working directory.  Be wary of this if you're coming
+	  from the Subversion or CVS world, since you might expect it
+	  to operate only on the current directory that you happen to
+	  be visiting and its subdirectories.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Aborting a commit</title>
+
+      <para id="x_54">If you decide that you don't want to commit
+	while in the middle of editing a commit message, simply exit
+	from your editor without saving the file that it's editing.
+	This will cause nothing to happen to either the repository or
+	the working directory.</para>
+    </sect2>
+
+    <sect2>
+      <title>Admiring our new handiwork</title>
+
+      <para id="x_56">Once we've finished the commit, we can use the
+	<command role="hg-cmd">hg tip</command> command to display the
+	changeset we just created.  This command produces output that
+	is identical to <command role="hg-cmd">hg log</command>, but
+	it only displays the newest revision in the repository.</para>
+
+      &interaction.tour.tip;
+
+      <para id="x_57">We refer to the newest revision in the
+	repository as the <emphasis>tip revision</emphasis>, or simply
+	the <emphasis>tip</emphasis>.</para>
+
+      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
+	command accepts many of the same options as <command
+	  role="hg-cmd">hg log</command>, so <option
+	  role="hg-opt-global">-v</option> above indicates <quote>be
+	  verbose</quote>, <option role="hg-opt-tip">-p</option>
+	specifies <quote>print a patch</quote>.  The use of <option
+	  role="hg-opt-tip">-p</option> to print patches is another
+	example of the consistent naming we mentioned earlier.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Sharing changes</title>
+
+    <para id="x_58">We mentioned earlier that repositories in
+      Mercurial are self-contained.  This means that the changeset we
+      just created exists only in our <filename
+	class="directory">my-hello</filename> repository.  Let's look
+      at a few ways that we can propagate this change into other
+      repositories.</para>
+
+    <sect2 id="sec:tour:pull">
+      <title>Pulling changes from another repository</title>
+
+      <para id="x_59">To get started, let's clone our original
+	<filename class="directory">hello</filename> repository, which
+	does not contain the change we just committed.  We'll call our
+	temporary repository <filename
+	  class="directory">hello-pull</filename>.</para>
+
+      &interaction.tour.clone-pull;
+
+      <para id="x_5a">We'll use the <command role="hg-cmd">hg
+	  pull</command> command to bring changes from <filename
+	  class="directory">my-hello</filename> into <filename
+	  class="directory">hello-pull</filename>.  However, blindly
+	pulling unknown changes into a repository is a somewhat scary
+	prospect.  Mercurial provides the <command role="hg-cmd">hg
+	  incoming</command> command to tell us what changes the
+	<command role="hg-cmd">hg pull</command> command
+	<emphasis>would</emphasis> pull into the repository, without
+	actually pulling the changes in.</para>
+
+      &interaction.tour.incoming;
+
+      <para id="x_5c">Bringing changes into a repository is a simple
+	matter of running the <command role="hg-cmd">hg pull</command>
+	command, and optionally telling it which repository to pull from.</para>
+
+      &interaction.tour.pull;
+
+      <para id="x_5d">As you can see from the before-and-after output
+	of <command role="hg-cmd">hg tip</command>, we have
+	successfully pulled changes into our repository.  However,
+	Mercurial separates pulling changes in from updating the
+	working directory. There remains one step before we will see
+	the changes that we just pulled appear in the working
+	directory.</para>
+
+      <tip>
+	<title>Pulling specific changes</title>
+
+	<para id="x_5b">It is possible that due to the delay between
+	  running <command role="hg-cmd">hg incoming</command> and
+	  <command role="hg-cmd">hg pull</command>, you may not see
+	  all changesets that will be brought from the other
+	  repository. Suppose you're pulling changes from a repository
+	  on the network somewhere. While you are looking at the
+	  <command role="hg-cmd">hg incoming</command> output, and
+	  before you pull those changes, someone might have committed
+	  something in the remote repository. This means that it's
+	  possible to pull more changes than you saw when using
+	  <command role="hg-cmd">hg incoming</command>.</para>
+
+	<para id="x_718">If you only want to pull precisely the changes that were
+	  listed by <command role="hg-cmd">hg incoming</command>, or
+	  you have some other reason to pull a subset of changes,
+	  simply identify the change that you want to pull by its
+	  changeset ID, e.g. <command>hg pull
+	    -r7e95bb</command>.</para>
+      </tip>
+    </sect2>
+
+    <sect2>
+      <title>Updating the working directory</title>
+
+      <para id="x_5e">We have so far glossed over the relationship
+	between a repository and its working directory.  The <command
+	  role="hg-cmd">hg pull</command> command that we ran in
+	<xref linkend="sec:tour:pull"/> brought changes into the
+	repository, but if we check, there's no sign of those changes
+	in the working directory.  This is because <command
+	  role="hg-cmd">hg pull</command> does not (by default) touch
+	the working directory.  Instead, we use the <command
+	  role="hg-cmd">hg update</command> command to do this.</para>
+
+      &interaction.tour.update;
+
+      <para id="x_5f">It might seem a bit strange that <command
+	  role="hg-cmd">hg pull</command> doesn't update the working
+	directory automatically.  There's actually a good reason for
+	this: you can use <command role="hg-cmd">hg update</command>
+	to update the working directory to the state it was in at
+	<emphasis>any revision</emphasis> in the history of the
+	repository.  If you had the working directory updated to an
+	old revision&emdash;to hunt down the origin of a bug,
+	say&emdash;and ran a <command role="hg-cmd">hg pull</command>
+	which automatically updated the working directory to a new
+	revision, you might not be terribly happy.</para>
+
+      <para id="x_60">Since pull-then-update is such a common sequence
+	of operations, Mercurial lets you combine the two by passing
+	the <option role="hg-opt-pull">-u</option> option to <command
+	  role="hg-cmd">hg pull</command>.</para>
+
+      <para id="x_61">If you look back at the output of <command
+	  role="hg-cmd">hg pull</command> in <xref
+	    linkend="sec:tour:pull"/> when we ran it without <option
+	  role="hg-opt-pull">-u</option>, you can see that it printed
+	a helpful reminder that we'd have to take an explicit step to
+	update the working directory.</para>
+
+      <para id="x_62">To find out what revision the working directory
+	is at, use the <command role="hg-cmd">hg parents</command>
+	command.</para>
+
+      &interaction.tour.parents;
+
+      <para id="x_63">If you look back at <xref
+	  linkend="fig:tour-basic:history"/>, you'll see arrows
+	connecting each changeset.  The node that the arrow leads
+	<emphasis>from</emphasis> in each case is a parent, and the
+	node that the arrow leads <emphasis>to</emphasis> is its
+	child.  The working directory has a parent in just the same
+	way; this is the changeset that the working directory
+	currently contains.</para>
+
+      <para id="x_64">To update the working directory to a particular
+	revision, give a revision number or changeset ID to the
+	<command role="hg-cmd">hg update</command> command.</para>
+
+      &interaction.tour.older;
+
+      <para id="x_65">If you omit an explicit revision, <command
+	  role="hg-cmd">hg update</command> will update to the tip
+	revision, as shown by the second call to <command
+	  role="hg-cmd">hg update</command> in the example
+	above.</para>
+    </sect2>
+
+    <sect2>
+      <title>Pushing changes to another repository</title>
+
+      <para id="x_66">Mercurial lets us push changes to another
+	repository, from the repository we're currently visiting. As
+	with the example of <command role="hg-cmd">hg pull</command>
+	above, we'll create a temporary repository to push our changes
+	into.</para>
+
+      &interaction.tour.clone-push;
+
+      <para id="x_67">The <command role="hg-cmd">hg outgoing</command>
+	command tells us what changes would be pushed into another
+	repository.</para>
+
+      &interaction.tour.outgoing;
+
+      <para id="x_68">And the <command role="hg-cmd">hg push</command>
+	command does the actual push.</para>
+
+      &interaction.tour.push;
+
+      <para id="x_69">As with <command role="hg-cmd">hg
+	  pull</command>, the <command role="hg-cmd">hg push</command>
+	command does not update the working directory in the
+	repository that it's pushing changes into. Unlike <command
+	  role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
+	  push</command> does not provide a <literal>-u</literal>
+	option that updates the other repository's working directory.
+	This asymmetry is deliberate: the repository we're pushing to
+	might be on a remote server and shared between several people.
+	If we were to update its working directory while someone was
+	working in it, their work would be disrupted.</para>
+
+      <para id="x_6a">What happens if we try to pull or push changes
+	  and the receiving repository already has those changes?
+	  Nothing too exciting.</para>
+
+      &interaction.tour.push.nothing;
+    </sect2>
+
+    <sect2>
+      <title>Default locations</title>
+
+      <para id="x_719">When we clone a repository, Mercurial records the location
+	of the repository we cloned in the
+	<filename>.hg/hgrc</filename> file of the new repository.  If
+	we don't supply a location to <command>hg pull</command> from
+	or <command>hg push</command> to, those commands will use this
+	location as a default.  The <command>hg incoming</command>
+	and <command>hg outgoing</command> commands do so too.</para>
+
+      <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename>
+	file in a text editor, you will see contents like the
+	following.</para>
+
+      <programlisting>[paths]
+default = http://www.selenic.com/repo/hg</programlisting>
+
+      <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the
+	default location for <command>hg push</command> and
+	<command>hg outgoing</command> be different from those for
+	<command>hg pull</command> and <command>hg incoming</command>.
+	We can do this by adding a <literal>default-push</literal>
+	entry to the <literal>[paths]</literal> section of the
+	<filename>.hg/hgrc</filename> file, as follows.</para>
+
+      <programlisting>[paths]
+default = http://www.selenic.com/repo/hg
+default-push = http://hg.example.com/hg</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Sharing changes over a network</title>
+
+      <para id="x_6b">The commands we have covered in the previous few
+	  sections are not limited to working with local repositories.
+	  Each works in exactly the same fashion over a network
+	  connection; simply pass in a URL instead of a local
+	  path.</para>
+	
+      &interaction.tour.outgoing.net;
+
+      <para id="x_6c">In this example, we can see what changes we
+	could push to the remote repository, but the repository is
+	understandably not set up to let anonymous users push to
+	it.</para>
+
+      &interaction.tour.push.net;
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Starting a new project</title>
+
+    <para id="x_71c">It is just as easy to begin a new project as to work on one
+      that already exists.  The <command>hg init</command> command
+      creates a new, empty Mercurial repository.</para>
+
+    &interaction.ch01-new.init;
+
+    <para id="x_71d">This simply creates a repository named
+      <filename>myproject</filename> in the current directory.</para>
+
+    &interaction.ch01-new.ls;
+
+    <para id="x_71e">We can tell that <filename>myproject</filename> is a
+      Mercurial repository, because it contains a
+      <filename>.hg</filename> directory.</para>
+
+    &interaction.ch01-new.ls2;
+
+    <para id="x_71f">If we want to add some pre-existing files to the repository,
+      we copy them into place, and tell Mercurial to start tracking
+      them using the <command>hg add</command> command.</para>
+
+    &interaction.ch01-new.add;
+
+    <para id="x_720">Once we are satisfied that our project looks right, we
+      commit our changes.</para>
+
+    &interaction.ch01-new.commit;
+
+    <para id="x_721">It takes just a few moments to start using Mercurial on a
+      new project, which is part of its appeal. Revision control is
+      now so easy to work with, we can use it on the smallest of
+      projects that we might not have considered with a more
+      complicated tool.</para>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->