Romain Pelisse avatar Romain Pelisse committed 6b680d5

deleting a bunch of files not longer necessary to build the documentation.
Adding missing newly files needed to build the documentation

Comments (0)

Files changed (105)

fr/00book.tex

-% The use of oneside here is a temporary hack; \marginpar entries
-% don't show up on odd pages of PDF output without it.  Sigh.
-\documentclass[oneside]{book}
-\usepackage{enumerate}
-\usepackage{fullpage}
-\usepackage{makeidx}
-\usepackage{ifpdf}
-\usepackage{graphicx}
-\usepackage{pslatex}
-\usepackage{fancyvrb}
-% adding package specific to the french version
-\usepackage[french]{babel}
-\usepackage[utf8]{inputenc}
-% leave hyperref until last
-\usepackage[colorlinks=true,bookmarks=true,pdftitle={Distributed
-  revision control with Mercurial},pdfsubject={Revision
-  control},pdfkeywords={Mercurial, Revision control, Distributed
-  revision control},pdfauthor={Bryan O'Sullivan}]{hyperref}
-
-\include{99defs}
-
-\title{Gestion de source distribué avec Mercurial} \author{Bryan
-  O'Sullivan}
-\date{Copyright \copyright\ 2006, 2007 Bryan O'Sullivan.\\
-  Ce document peut être librement distribué selon les termes et 
-  les conditions décrites dans la version 1.0 de la licence Open Publication.
-  La licence est en annexe~\ref{cha:opl} de ce document.\\
-  
-  Cette traduction a été généré depuis 
-  \href{http://hg.serpentine.com/mercurial/book/}{rev~\input{build_id}}
-  avec \href{http://www.selenic.com/hg/}{rev~\input{hg_id}} of Mercurial.}
-
-\makeindex
-
-\begin{document}
-
-\maketitle
-
-\addcontentsline{toc}{chapter}{Contents}
-\pagenumbering{roman}
-\tableofcontents
-\listoffigures
-%\listoftables
-
-\pagenumbering{arabic}
-
-\include{preface}
-\include{intro}
-\include{tour-basic}
-\include{tour-merge}
-\include{concepts}
-\include{daily}
-\include{collab}
-\include{filenames}
-\include{branch}
-\include{undo}
-\include{hook}
-\include{template}
-\include{mq}
-\include{mq-collab}
-\include{hgext}
-
-\appendix
-\include{cmdref}
-\include{mq-ref}
-\include{srcinstall}
-\include{license}
-\addcontentsline{toc}{chapter}{Bibliography}
-\bibliographystyle{alpha}
-\bibliography{99book}
-
-\addcontentsline{toc}{chapter}{Index}
-\printindex
-
-\end{document}
-
-%%% Local Variables: 
-%%% mode: latex
-%%% TeX-master: t
-%%% End: 
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
+[
+<!-- Below are references to files in this directory. -->
+
+<!-- Chapters. -->
+
+<!ENTITY ch00     SYSTEM "ch00-preface.xml">
+<!ENTITY ch01     SYSTEM "ch01-intro.xml">
+<!ENTITY ch02     SYSTEM "ch02-tour-basic.xml">
+<!ENTITY ch03     SYSTEM "ch03-tour-merge.xml">
+<!ENTITY ch04     SYSTEM "ch04-concepts.xml">
+<!ENTITY ch05     SYSTEM "ch05-daily.xml">
+<!ENTITY ch06     SYSTEM "ch06-collab.xml">
+<!ENTITY ch07     SYSTEM "ch07-filenames.xml">
+<!ENTITY ch08     SYSTEM "ch08-branch.xml">
+<!ENTITY ch09     SYSTEM "ch09-undo.xml">
+<!ENTITY ch10     SYSTEM "ch10-hook.xml">
+<!ENTITY ch11     SYSTEM "ch11-template.xml">
+<!ENTITY ch12     SYSTEM "ch12-mq.xml">
+<!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
+<!ENTITY ch14     SYSTEM "ch14-hgext.xml">
+<!ENTITY appA     SYSTEM "appA-svn.xml">
+<!ENTITY appB     SYSTEM "appB-mq-ref.xml">
+<!ENTITY appC     SYSTEM "appC-srcinstall.xml">
+<!ENTITY appD     SYSTEM "appD-license.xml">
+
+<!-- Include our standard shortcuts. -->
+
+<!ENTITY % SHORTCUTS SYSTEM "book-shortcuts.xml">
+%SHORTCUTS;
+
+<!-- Include automatically and manually generated code snippets. -->
+
+<!ENTITY % AUTOSNIPPETS SYSTEM "examples/auto-snippets.xml">
+%AUTOSNIPPETS;
+]>
+
+<book id="hg">
+  <title>Mercurial: The Definitive Guide</title>
+  
+  <!-- hg parents &#x2d;&#x2d;template '{node|short} ({date|shortdate})' 
+  <subtitle>Compiled from 8a1d3f1aff17 (2009-03-10)</subtitle>
+  -->
+  <subtitle>Compiled from $rev_id$</subtitle>
+  <bookinfo>
+    <edition>1</edition>
+    <isbn>9780596800673</isbn>
+    <authorgroup>
+      <author>
+        <firstname>Bryan</firstname>
+        <surname>O'Sullivan</surname>
+      </author>
+    </authorgroup>
+
+    <editor>
+      <firstname>Mike</firstname>
+      <surname>Loukides</surname>
+    </editor>
+
+    <copyright>
+      <year>2006</year>
+      <year>2007</year>
+      <year>2008</year>
+      <year>2009</year>
+      <holder>Bryan O'Sullivan</holder>
+    </copyright>
+  </bookinfo>
+
+  <!-- BEGIN ch00 -->
+  &ch00;
+  <!-- BEGIN ch01 -->
+  &ch01;
+  <!-- BEGIN ch02 -->
+  &ch02;
+  <!-- BEGIN ch03 -->
+  &ch03;
+  <!-- BEGIN ch04 -->
+  &ch04;
+  <!-- BEGIN ch05 -->
+  &ch05;
+  <!-- BEGIN ch06 -->
+  &ch06;
+  <!-- BEGIN ch07 -->
+  &ch07;
+  <!-- BEGIN ch08 -->
+  &ch08;
+  <!-- BEGIN ch09 -->
+  &ch09;
+  <!-- BEGIN ch10 -->
+  &ch10;
+  <!-- BEGIN ch11 -->
+  &ch11;
+  <!-- BEGIN ch12 -->
+  &ch12;
+  <!-- BEGIN ch13 -->
+  &ch13;
+  <!-- BEGIN ch14 -->
+  &ch14;
+  <!-- BEGIN appA -->
+  &appA;
+  <!-- BEGIN appB -->
+  &appB;
+  <!-- BEGIN appC -->
+  &appC;
+  <!-- BEGIN appD -->
+  &appD;
+</book>

fr/99book.bib

-@Unpublished{gruenbacher:2005,
-  author = 	 {Andreas Gruenbacher},
-  title = 	 {How To Survive With Many Patches (Introduction to \texttt{quilt})},
-  year = 	 {2005},
-  month = 	 {June},
-  note =         {\url{http://www.suse.de/~agruen/quilt.pdf}},
-}
-
-@InProceedings{web:europython,
-  author = 	 {Bryan O'Sullivan},
-  title = 	 {Achieving High Performance in Mercurial},
-  booktitle = 	 {EuroPython Conference},
-  year = 	 {2006},
-  month = 	 {July},
-  note = 	 {\url{XXX}},
-}
-
-@Misc{web:diffstat,
-  author = 	 {Thomas Dickey},
-  title = 	 {\texttt{diffstat}--make a histogram of \texttt{diff} output},
-  note = 	 {\url{http://dickey.his.com/diffstat/diffstat.html}},
-}
-
-@Misc{web:quilt,
-  author = 	 {Andreas Gruenbacher, Martin Quinson, Jean Delvare},
-  title = 	 {Patchwork Quilt},
-  note = 	 {\url{http://savannah.nongnu.org/projects/quilt}},
-}
-
-@Misc{web:patchutils,
-  author = 	 {Tim Waugh},
-  title = 	 {\texttt{patchutils}--programs that operate on patch files},
-  note = 	 {\url{http://cyberelk.net/tim/patchutils/}},
-}
-
-@Misc{web:mpatch,
-  author = 	 {Chris Mason},
-  title = 	 {\texttt{mpatch}--help solve patch rejects},
-  note = 	 {\url{http://oss.oracle.com/~mason/mpatch/}},
-}
-
-@Misc{web:wiggle,
-  author = 	 {Neil Brown},
-  title = 	 {\texttt{wiggle}--apply conflicting patches},
-  note = 	 {\url{http://cgi.cse.unsw.edu.au/~neilb/source/wiggle/}},
-}
-
-@Misc{web:mysql-python,
-  author =	 {Andy Dustman},
-  title =	 {MySQL for Python},
-  note =	 {\url{http://sourceforge.net/projects/mysql-python}},
-}
-
-@Misc{web:changelog,
-  author =	 {Richard Stallman, GNU Project volunteers},
-  title =	 {GNU Coding Standards---Change Logs},
-  note =	 {\url{http://www.gnu.org/prep/standards/html_node/Change-Logs.html}},
-}
-
-@Misc{web:macpython,
-  author =	 {Bob Ippolito, Ronald Oussoren},
-  title =	 {Universal MacPython},
-  note =	 {\url{http://bob.pythonmac.org/archives/2006/04/10/python-and-universal-binaries-on-mac-os-x/}},
-}
-
-@Misc{web:putty,
-  author =	 {Simon Tatham},
-  title =	 {PuTTY---open source ssh client for Windows},
-  note =	 {\url{http://www.chiark.greenend.org.uk/~sgtatham/putty/}},
-}
-
-@Misc{web:configparser,
-  author =       {Python.org},
-  title =	 {\texttt{ConfigParser}---Configuration file parser},
-  note =	 {\url{http://docs.python.org/lib/module-ConfigParser.html}},
-}

fr/99defs.tex

-% Bug ID.
-\newcommand{\bug}[1]{\index{Mercurial bug
-    database!\href{http://www.selenic.com/mercurial/bts/issue#1}{bug
-      ~#1}}\href{http://www.selenic.com/mercurial/bts/issue#1}{Mercurial
-    bug no.~#1}}
-
-% File name in the user's home directory.
-\newcommand{\tildefile}[1]{\texttt{\~{}/#1}}
-
-% File name.
-\newcommand{\filename}[1]{\texttt{#1}}
-
-% Directory name.
-\newcommand{\dirname}[1]{\texttt{#1}}
-
-% File name, with index entry.
-% The ``s'' prefix comes from ``special''.
-\newcommand{\sfilename}[1]{\index{\texttt{#1} file}\texttt{#1}}
-
-% Directory name, with index entry.
-\newcommand{\sdirname}[1]{\index{\texttt{#1} directory}\texttt{#1}}
-
-% Mercurial extension.
-\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
-
-% Command provided by a Mercurial extension.
-\newcommand{\hgxcmd}[2]{\index{\texttt{#2} command (\texttt{#1}
-      extension)}\index{\texttt{#1} extension!\texttt{#2} command}``\texttt{hg #2}''}
-
-% Mercurial command.
-\newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''}
-
-% Mercurial command, with arguments.
-\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
-
-\newcommand{\tplkword}[1]{\index{\texttt{#1} template keyword}\index{template keywords!\texttt{#1}}\texttt{#1}}
-
-\newcommand{\tplkwfilt}[2]{\index{\texttt{#1} template keyword!\texttt{#2}
-    filter}\index{template filters!\texttt{#2}}\index{\texttt{#2}
-    template filter}\texttt{#2}}
-
-\newcommand{\tplfilter}[1]{\index{template
-    filters!\texttt{#1}}\index{\texttt{#1} template
-    filter}\texttt{#1}}
-
-% Shell/system command.
-\newcommand{\command}[1]{\index{\texttt{#1} system command}\texttt{#1}}
-
-% Shell/system command, with arguments.
-\newcommand{\cmdargs}[2]{\index{\texttt{#1} system command}``\texttt{#1 #2}''}
-
-% Mercurial command option.
-\newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
-
-% Mercurial command option, provided by an extension command.
-\newcommand{\hgxopt}[3]{\index{\texttt{#2} command (\texttt{#1} extension)!\texttt{#3} option}\index{\texttt{#1} extension!\texttt{#2} command!\texttt{#3} option}\texttt{#3}}
-
-% Mercurial global option.
-\newcommand{\hggopt}[1]{\index{global options!\texttt{#1} option}\texttt{#1}}
-
-% Shell/system command option.
-\newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
-
-% Command option.
-\newcommand{\option}[1]{\texttt{#1}}
-
-% Software package.
-\newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}}
-
-% Section name from a hgrc file.
-\newcommand{\rcsection}[1]{\index{\texttt{hgrc} file!\texttt{#1} section}\texttt{[#1]}}
-
-% Named item in a hgrc file section.
-\newcommand{\rcitem}[2]{\index{\texttt{hgrc} file!\texttt{#1}
-    section!\texttt{#2} entry}\texttt{#2}}
-
-% hgrc file.
-\newcommand{\hgrc}{\index{configuration file!\texttt{hgrc}
-    (Linux/Unix)}\index{\texttt{hgrc} configuration file}\texttt{hgrc}}
-
-% Mercurial.ini file.
-\newcommand{\hgini}{\index{configuration file!\texttt{Mercurial.ini}
-    (Windows)}\index{\texttt{Mercurial.ini} configuration file}\texttt{Mercurial.ini}}
-
-% Hook name.
-\newcommand{\hook}[1]{\index{\texttt{#1} hook}\index{hooks!\texttt{#1}}\texttt{#1}}
-
-% Environment variable.
-\newcommand{\envar}[1]{\index{\texttt{#1} environment
-    variable}\index{environment variables!\texttt{#1}}\texttt{#1}}
-
-% Python module.
-\newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}}
-
-% Python class in a module.
-\newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2}
-    class}\texttt{#1.#2}}
-
-% Python function in a module.
-\newcommand{\pymodfunc}[2]{\index{\texttt{#1} module!\texttt{#2}
-    function}\texttt{#1.#2}}
-
-% Note: blah blah.
-\newsavebox{\notebox}
-\newenvironment{note}%
-  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}%
-  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
-\newenvironment{caution}%
-  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Caution:}\space}%
-  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
-
-% Code sample, eating 4 characters of leading space.
-\DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}}
-
-% Code sample, eating 2 characters of leading space.
-\DefineVerbatimEnvironment{codesample2}{Verbatim}{frame=single,gobble=2,numbers=left,commandchars=\\\{\}}
-
-% Interaction from the examples directory.
-\newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.lxo}}
-% Example code from the examples directory.
-\newcommand{\excode}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{../examples/#1}}
-
-% Graphics inclusion.
-\ifpdf
-  \newcommand{\grafix}[1]{\includegraphics{#1}}
-\else
-  \newcommand{\grafix}[1]{\includegraphics{#1.png}}
-\fi
-
-% Reference entry for a command.
-\newcommand{\cmdref}[2]{\section{\hgcmd{#1}---#2}\label{cmdref:#1}\index{\texttt{#1} command}}
-
-% Reference entry for a command option with long and short forms.
-\newcommand{\optref}[3]{\subsubsection{\hgopt{#1}{--#3}, also \hgopt{#1}{-#2}}}
-
-% Reference entry for a command option with only long form.
-\newcommand{\loptref}[2]{\subsubsection{\hgopt{#1}{--#2} option}}
-
-% command to generate a footnote to be used as a translator's note
-\newcommand{\ndt}[1]{\footnote{\textbf{N. del T.} #1}}
-
-
-%%% Local Variables: 
-%%% mode: latex
-%%% TeX-master: "00book"
-%%% End: 
+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="svn">
+  <?dbhtml filename="migrating-to-mercurial.html"?>
+<title>Migrating to Mercurial</title>
+
+  <para id="x_6e1">A common way to test the waters with a new revision control
+    tool is to experiment with switching an existing project, rather
+    than starting a new project from scratch.</para>
+
+  <para id="x_6e2">In this appendix, we discuss how to import a project's history
+    into Mercurial, and what to look out for if you are used to a
+    different revision control system.</para>
+
+  <sect1>
+    <title>Importing history from another system</title>
+
+    <para id="x_6e3">Mercurial ships with an extension named
+      <literal>convert</literal>, which can import project history
+      from most popular revision control systems.  At the time this
+      book was written, it could import history from the following
+      systems:</para>
+    <itemizedlist>
+      <listitem>
+	<para id="x_6e4">Subversion</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e5">CVS</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e6">git</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e7">Darcs</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e8">Bazaar</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e9">Monotone</para>
+      </listitem>
+      <listitem>
+	<para id="x_6ea">GNU Arch</para>
+      </listitem>
+      <listitem>
+	<para id="x_6eb">Mercurial</para>
+      </listitem>
+    </itemizedlist>
+
+    <para id="x_6ec">(To see why Mercurial itself is supported as a source, see
+      <xref linkend="svn.filemap"/>.)</para>
+
+    <para id="x_6ed">You can enable the extension in the usual way, by editing
+      your <filename>~/.hgrc</filename> file.</para>
+
+    <programlisting>[extensions]
+convert =</programlisting>
+
+    <para id="x_6ee">This will make a <command>hg convert</command> command
+      available.  The command is easy to use.  For instance, this
+      command will import the Subversion history for the Nose unit
+      testing framework into Mercurial.</para>
+
+    <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
+
+    <para id="x_6ef">The <literal>convert</literal> extension operates
+      incrementally.  In other words, after you have run <command>hg
+	convert</command> once, running it again will import any new
+      revisions committed after the first run began.  Incremental
+      conversion will only work if you run <command>hg
+	convert</command> in the same Mercurial repository that you
+      originally used, because the <literal>convert</literal>
+      extension saves some private metadata in a
+      non-revision-controlled file named
+      <filename>.hg/shamap</filename> inside the target
+      repository.</para>
+
+    <para id="x_707">When you want to start making changes using Mercurial, it's
+      best to clone the tree in which you are doing your conversions,
+      and leave the original tree for future incremental conversions.
+      This is the safest way to let you pull and merge future commits
+      from the source revision control system into your newly active
+      Mercurial project.</para>
+
+    <sect2>
+      <title>Converting multiple branches</title>
+
+      <para id="x_708">The <command>hg convert</command> command given above
+	converts only the history of the <literal>trunk</literal>
+	branch of the Subversion repository.  If we instead use the
+	URL <literal>http://python-nose.googlecode.com/svn</literal>,
+	Mercurial will automatically detect the
+	<literal>trunk</literal>, <literal>tags</literal> and
+	<literal>branches</literal> layout that Subversion projects
+	usually use, and it will import each as a separate Mercurial
+	branch.</para>
+
+      <para id="x_709">By default, each Subversion branch imported into Mercurial
+	is given a branch name.  After the conversion completes, you
+	can get a list of the active branch names in the Mercurial
+	repository using <command>hg branches -a</command>. If you
+	would prefer to import the Subversion branches without names,
+	pass the <option>--config
+	  convert.hg.usebranchnames=false</option> option to
+	<command>hg convert</command>.</para>
+
+      <para id="x_70a">Once you have converted your tree, if you want to follow
+	the usual Mercurial practice of working in a tree that
+	contains a single branch, you can clone that single branch
+	using <command>hg clone -r mybranchname</command>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Mapping user names</title>
+
+      <para id="x_6f0">Some revision control tools save only short usernames with
+	commits, and these can be difficult to interpret.  The norm
+	with Mercurial is to save a committer's name and email
+	address, which is much more useful for talking to them after
+	the fact.</para>
+
+      <para id="x_6f1">If you are converting a tree from a revision control
+	system that uses short names, you can map those names to
+	longer equivalents by passing a <option>--authors</option>
+	option to <command>hg convert</command>.  This option accepts
+	a file name that should contain entries of the following
+	form.</para>
+
+      <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
+soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
+
+      <para id="x_6f2">Whenever <literal>convert</literal> encounters a commit
+	with the username <literal>arist</literal> in the source
+	repository, it will use the name <literal>Aristotle
+	  &lt;aristotle@phil.example.gr&gt;</literal> in the converted
+	Mercurial revision.  If no match is found for a name, it is
+	used verbatim.</para>
+    </sect2>
+
+    <sect2 id="svn.filemap">
+      <title>Tidying up the tree</title>
+
+      <para id="x_6f3">Not all projects have pristine history.  There may be a
+	directory that should never have been checked in, a file that
+	is too big, or a whole hierarchy that needs to be
+	refactored.</para>
+
+      <para id="x_6f4">The <literal>convert</literal> extension supports the idea
+	of a <quote>file map</quote> that can reorganize the files and
+	directories in a project as it imports the project's history.
+	This is useful not only when importing history from other
+	revision control systems, but also to prune or refactor a
+	Mercurial tree.</para>
+
+      <para id="x_6f5">To specify a file map, use the <option>--filemap</option>
+	option and supply a file name.  A file map contains lines of the
+	following forms.</para>
+
+      <programlisting># This is a comment.
+# Empty lines are ignored.	
+
+include path/to/file
+
+exclude path/to/file
+
+rename from/some/path to/some/other/place
+</programlisting>
+
+      <para id="x_6f6">The <literal>include</literal> directive causes a file, or
+	all files under a directory, to be included in the destination
+	repository.  This also excludes all other files and dirs not
+	explicitely included.  The <literal>exclude</literal>
+	directive causes files or directories to be omitted, and
+	others not explicitly mentioned to be included.</para>
+
+      <para id="x_6f7">To move a file or directory from one location to another,
+	use the <literal>rename</literal> directive.  If you need to
+	move a file or directory from a subdirectory into the root of
+	the repository, use <literal>.</literal> as the second
+	argument to the <literal>rename</literal> directive.</para>
+    </sect2>
+
+    <sect2>
+      <title>Improving Subversion conversion performance</title>
+
+      <para id="x_70b">You will often need several attempts before you hit the
+	perfect combination of user map, file map, and other
+	conversion parameters.  Converting a Subversion repository
+	over an access protocol like <literal>ssh</literal> or
+	<literal>http</literal> can proceed thousands of times more
+	slowly than Mercurial is capable of actually operating, due to
+	network delays.  This can make tuning that perfect conversion
+	recipe very painful.</para>
+
+      <para id="x_70c">The <ulink
+	  url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command>svnsync</command></ulink> 
+	command can greatly speed up the conversion of a Subversion
+	repository.  It is a read-only mirroring program for
+	Subversion repositories.  The idea is that you create a local
+	mirror of your Subversion tree, then convert the mirror into a
+	Mercurial repository.</para>
+
+      <para id="x_70d">Suppose we want to convert the Subversion repository for
+	the popular Memcached project into a Mercurial tree.  First,
+	we create a local Subversion repository.</para>
+
+      <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen>
+
+      <para id="x_70e">Next, we set up a Subversion hook that
+	<command>svnsync</command> needs.</para>
+
+      <screen><prompt>$</prompt> <userinput>echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
+<prompt>$</prompt> <userinput>chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
+
+      <para id="x_70f">We then initialize <command>svnsync</command> in this
+	repository.</para>
+
+      <screen><prompt>$</prompt> <userinput>svnsync --init file://`pwd`/memcached-mirror \
+  http://code.sixapart.com/svn/memcached</userinput></screen>
+
+      <para id="x_710">Our next step is to begin the <command>svnsync</command>
+	mirroring process.</para>
+
+      <screen><prompt>$</prompt> <userinput>svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
+
+      <para id="x_711">Finally, we import the history of our local Subversion
+	mirror into Mercurial.</para>
+
+      <screen><prompt>$</prompt> <userinput>hg convert memcached-mirror</userinput></screen>
+      
+      <para id="x_712">We can use this process incrementally if the Subversion
+	repository is still in use.  We run <command>svnsync</command>
+	to pull new changes into our mirror, then <command>hg
+	  convert</command> to import them into our Mercurial
+	tree.</para>
+
+      <para id="x_713">There are two advantages to doing a two-stage import with
+	<command>svnsync</command>.  The first is that it uses more
+	efficient Subversion network syncing code than <command>hg
+	  convert</command>, so it transfers less data over the
+	network.  The second is that the import from a local
+	Subversion tree is so fast that you can tweak your conversion
+	setup repeatedly without having to sit through a painfully
+	slow network-based conversion process each time.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Migrating from Subversion</title>
+
+    <para id="x_6f8">Subversion is currently the most popular open source
+      revision control system. Although there are many differences
+      between Mercurial and Subversion, making the transition from
+      Subversion to Mercurial is not particularly difficult.  The two
+      have similar command sets and generally uniform
+      interfaces.</para>
+
+    <sect2>
+      <title>Philosophical differences</title>
+
+      <para id="x_6f9">The fundamental difference between Subversion and
+	Mercurial is of course that Subversion is centralized, while
+	Mercurial is distributed.  Since Mercurial stores all of a
+	project's history on your local drive, it only needs to
+	perform a network access when you want to explicitly
+	communicate with another repository. In contrast, Subversion
+	stores very little information locally, and the client must
+	thus contact its server for many common operations.</para>
+
+      <para id="x_6fa">Subversion more or less gets away without a well-defined
+	notion of a branch: which portion of a server's namespace
+	qualifies as a branch is a matter of convention, with the
+	software providing no enforcement.  Mercurial treats a
+	repository as the unit of branch management.</para>
+
+      <sect3>
+	<title>Scope of commands</title>
+
+	<para id="x_6fb">Since Subversion doesn't know what parts of its
+	  namespace are really branches, it treats most commands as
+	  requests to operate at and below whatever directory you are
+	  currently visiting.  For instance, if you run <command>svn
+	    log</command>, you'll get the history of whatever part of
+	  the tree you're looking at, not the tree as a whole.</para>
+
+	<para id="x_6fc">Mercurial's commands behave differently, by defaulting
+	  to operating over an entire repository.  Run <command>hg
+	    log</command> and it will tell you the history of the
+	  entire tree, no matter what part of the working directory
+	  you're visiting at the time.  If you want the history of
+	  just a particular file or directory, simply supply it by
+	  name, e.g. <command>hg log src</command>.</para>
+
+	<para id="x_6fd">From my own experience, this difference in default
+	  behaviors is probably the most likely to trip you up if you
+	  have to switch back and forth frequently between the two
+	  tools.</para>
+      </sect3>
+
+      <sect3>
+	<title>Multi-user operation and safety</title>
+
+	<para id="x_6fe">With Subversion, it is normal (though slightly frowned
+	  upon) for multiple people to collaborate in a single branch.
+	  If Alice and Bob are working together, and Alice commits
+	  some changes to their shared branch, Bob must update his
+	  client's view of the branch before he can commit.  Since at
+	  this time he has no permanent record of the changes he has
+	  made, he can corrupt or lose his modifications during and
+	  after his update.</para>
+
+	<para id="x_6ff">Mercurial encourages a commit-then-merge model instead.
+	  Bob commits his changes locally before pulling changes from,
+	  or pushing them to, the server that he shares with Alice.
+	  If Alice pushed her changes before Bob tries to push his, he
+	  will not be able to push his changes until he pulls hers,
+	  merges with them, and commits the result of the merge.  If
+	  he makes a mistake during the merge, he still has the option
+	  of reverting to the commit that recorded his changes.</para>
+
+	<para id="x_700">It is worth emphasizing that these are the common ways
+	  of working with these tools. Subversion supports a safer
+	  work-in-your-own-branch model, but it is cumbersome enough
+	  in practice to not be widely used.  Mercurial can support
+	  the less safe mode of allowing changes to be pulled in and
+	  merged on top of uncommitted edits, but this is considered
+	  highly unusual.</para>
+      </sect3>
+
+      <sect3>
+	<title>Published vs local changes</title>
+
+	<para id="x_701">A Subversion <command>svn commit</command> command
+	  immediately publishes changes to a server, where they can be
+	  seen by everyone who has read access.</para>
+
+	<para id="x_702">With Mercurial, commits are always local, and must be
+	  published via a <command>hg push</command> command
+	  afterwards.</para>
+
+	<para id="x_703">Each approach has its advantages and disadvantages.  The
+	  Subversion model means that changes are published, and hence
+	  reviewable and usable, immediately.  On the other hand, this
+	  means that a user must have commit access to a repository in
+	  order to use the software in a normal way, and commit access
+	  is not lightly given out by most open source
+	  projects.</para>
+
+	<para id="x_704">The Mercurial approach allows anyone who can clone a
+	  repository to commit changes without the need for someone
+	  else's permission, and they can then publish their changes
+	  and continue to participate however they see fit.  The
+	  distinction between committing and pushing does open up the
+	  possibility of someone committing changes to their laptop
+	  and walking away for a few days having forgotten to push
+	  them, which in rare cases might leave collaborators
+	  temporarily stuck.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Quick reference</title>
+
+      <table>
+	<title>Subversion commands and Mercurial equivalents</title>
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Subversion</entry>
+	      <entry>Mercurial</entry>
+	      <entry>Notes</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry><command>svn add</command></entry>
+	      <entry><command>hg add</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn blame</command></entry>
+	      <entry><command>hg annotate</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn cat</command></entry>
+	      <entry><command>hg cat</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn checkout</command></entry>
+	      <entry><command>hg clone</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn cleanup</command></entry>
+	      <entry>n/a</entry>
+	      <entry>No cleanup needed</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn commit</command></entry>
+	      <entry><command>hg commit</command>; <command>hg
+		  push</command></entry>
+	      <entry><command>hg push</command> publishes after
+		commit</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn copy</command></entry>
+	      <entry><command>hg clone</command></entry>
+	      <entry>To create a new branch</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn copy</command></entry>
+	      <entry><command>hg copy</command></entry>
+	      <entry>To copy files or directories</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn delete</command> (<command>svn
+		  remove</command>)</entry>
+	      <entry><command>hg remove</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn diff</command></entry>
+	      <entry><command>hg diff</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn export</command></entry>
+	      <entry><command>hg archive</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn help</command></entry>
+	      <entry><command>hg help</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn import</command></entry>
+	      <entry><command>hg addremove</command>; <command>hg
+		  commit</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn info</command></entry>
+	      <entry><command>hg parents</command></entry>
+	      <entry>Shows what revision is checked out</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn info</command></entry>
+	      <entry><command>hg showconfig
+		  paths.parent</command></entry>
+	      <entry>Shows what URL is checked out</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn list</command></entry>
+	      <entry><command>hg manifest</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn log</command></entry>
+	      <entry><command>hg log</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn merge</command></entry>
+	      <entry><command>hg merge</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn mkdir</command></entry>
+	      <entry>n/a</entry>
+	      <entry>Mercurial does not track directories</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn move</command> (<command>svn
+		  rename</command>)</entry>
+	      <entry><command>hg rename</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn resolved</command></entry>
+	      <entry><command>hg resolve -m</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn revert</command></entry>
+	      <entry><command>hg revert</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn status</command></entry>
+	      <entry><command>hg status</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn update</command></entry>
+	      <entry><command>hg pull -u</command></entry>
+	      <entry></entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Useful tips for newcomers</title>
+
+    <para id="x_705">Under some revision control systems, printing a diff for a
+      single committed revision can be painful. For instance, with
+      Subversion, to see what changed in revision 104654, you must
+      type <command>svn diff -r104653:104654</command>. Mercurial
+      eliminates the need to type the revision ID twice in this common
+      case. For a plain diff, <command>hg export 104654</command>. For
+      a log message followed by a diff, <command>hg log -r104654
+	-p</command>.</para>
+
+    <para id="x_706">When you run <command>hg status</command> without any
+      arguments, it prints the status of the entire tree, with paths
+      relative to the root of the repository.  This makes it tricky to
+      copy a file name from the output of <command>hg status</command>
+      into the command line.  If you supply a file or directory name
+      to <command>hg status</command>, it will print paths relative to
+      your current location instead.  So to get tree-wide status from
+      <command>hg status</command>, with paths that are relative to
+      your current directory and not the root of the repository, feed
+      the output of <command>hg root</command> into <command>hg
+	status</command>.  You can easily do this as follows on a
+      Unix-like system:</para>
+
+    <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->

fr/appB-mq-ref.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="chap:mqref">
+  <?dbhtml filename="mercurial-queues-reference.html"?>
+  <title>Mercurial Queues reference</title>
+
+  <sect1 id="sec:mqref:cmdref">
+    <title>MQ command reference</title>
+
+    <para id="x_5e8">For an overview of the commands provided by MQ, use the
+      command <command role="hg-cmd">hg help mq</command>.</para>
+
+    <sect2>
+      <title><command role="hg-ext-mq">qapplied</command>&emdash;print
+	applied patches</title>
+
+      <para id="x_5e9">The <command role="hg-ext-mq">qapplied</command> command
+	prints the current stack of applied patches.  Patches are
+	printed in oldest-to-newest order, so the last patch in the
+	list is the <quote>top</quote> patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qcommit</command>&emdash;commit
+	changes in the queue repository</title>
+
+      <para id="x_5ea">The <command role="hg-ext-mq">qcommit</command> command
+	commits any outstanding changes in the <filename
+	  role="special" class="directory">.hg/patches</filename>
+	repository.  This command only works if the <filename
+	  role="special" class="directory">.hg/patches</filename>
+	directory is a repository, i.e. you created the directory
+	using <command role="hg-cmd">hg qinit <option
+	    role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
+	ran <command role="hg-cmd">hg init</command> in the directory
+	after running <command
+	  role="hg-ext-mq">qinit</command>.</para>
+
+      <para id="x_5eb">This command is shorthand for <command role="hg-cmd">hg
+	  commit --cwd .hg/patches</command>.</para>
+    </sect2>
+    <sect2>
+	<title><command
+	  role="hg-ext-mq">qdelete</command>&emdash;delete a patch
+	from the <filename role="special">series</filename>
+	file</title>
+
+      <para id="x_5ec">The <command role="hg-ext-mq">qdelete</command> command
+	removes the entry for a patch from the <filename
+	  role="special">series</filename> file in the <filename
+	  role="special" class="directory">.hg/patches</filename>
+	directory.  It does not pop the patch if the patch is already
+	applied.  By default, it does not delete the patch file; use
+	the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
+	to do that.</para>
+
+      <para id="x_5ed">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_5ee"><option
+	      role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
+	    patch file.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qdiff</command>&emdash;print a
+	diff of the topmost applied patch</title>
+
+      <para id="x_5ef">The <command role="hg-ext-mq">qdiff</command> command
+	prints a diff of the topmost applied patch. It is equivalent
+	to <command role="hg-cmd">hg diff -r-2:-1</command>.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qfold</command>&emdash;move
+	applied patches into repository history</title>
+
+      <para id="x_72d">The <command>hg qfinish</command> command converts the
+	specified applied patches into permanent changes by moving
+	them out of MQ's control so that they will be treated as
+	normal repository history.</para>
+    </sect2>
+
+    <sect2>
+      <title><command role="hg-ext-mq">qfold</command>&emdash;merge
+	(<quote>fold</quote>) several patches into one</title>
+
+      <para id="x_5f0">The <command role="hg-ext-mq">qfold</command> command
+	merges multiple patches into the topmost applied patch, so
+	that the topmost applied patch makes the union of all of the
+	changes in the patches in question.</para>
+
+      <para id="x_5f1">The patches to fold must not be applied; <command
+	  role="hg-ext-mq">qfold</command> will exit with an error if
+	any is.  The order in which patches are folded is significant;
+	<command role="hg-cmd">hg qfold a b</command> means
+	<quote>apply the current topmost patch, followed by
+	  <literal>a</literal>, followed by
+	  <literal>b</literal></quote>.</para>
+
+      <para id="x_5f2">The comments from the folded patches are appended to the
+	comments of the destination patch, with each block of comments
+	separated by three asterisk
+	(<quote><literal>*</literal></quote>) characters.  Use the
+	<option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
+	edit the commit message for the combined patch/changeset after
+	the folding has completed.</para>
+
+      <para id="x_5f3">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_5f4"><option
+	      role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
+	    commit message and patch description for the newly folded
+	    patch.</para>
+	</listitem>
+	<listitem><para id="x_5f5"><option
+	      role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
+	    contents of the given file as the new commit message and
+	    patch description for the folded patch.</para>
+	</listitem>
+	<listitem><para id="x_5f6"><option
+	      role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
+	    given text as the new commit message and patch description
+	    for the folded patch.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command
+	  role="hg-ext-mq">qheader</command>&emdash;display the
+	header/description of a patch</title>
+
+      <para id="x_5f7">The <command role="hg-ext-mq">qheader</command> command
+	prints the header, or description, of a patch.  By default, it
+	prints the header of the topmost applied patch. Given an
+	argument, it prints the header of the named patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qimport</command>&emdash;import
+	a third-party patch into the queue</title>
+
+      <para id="x_5f8">The <command role="hg-ext-mq">qimport</command> command
+	adds an entry for an external patch to the <filename
+	  role="special">series</filename> file, and copies the patch
+	into the <filename role="special"
+	  class="directory">.hg/patches</filename> directory.  It adds
+	the entry immediately after the topmost applied patch, but
+	does not push the patch.</para>
+
+      <para id="x_5f9">If the <filename role="special"
+	  class="directory">.hg/patches</filename> directory is a
+	repository, <command role="hg-ext-mq">qimport</command>
+	automatically does an <command role="hg-cmd">hg add</command>
+	of the imported patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qinit</command>&emdash;prepare
+	a repository to work with MQ</title>
+
+      <para id="x_5fa">The <command role="hg-ext-mq">qinit</command> command
+	prepares a repository to work with MQ.  It creates a directory
+	called <filename role="special"
+	  class="directory">.hg/patches</filename>.</para>
+
+      <para id="x_5fb">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_5fc"><option
+	      role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
+	    <filename role="special"
+	      class="directory">.hg/patches</filename> as a repository
+	    in its own right.  Also creates a <filename
+	      role="special">.hgignore</filename> file that will
+	    ignore the <filename role="special">status</filename>
+	    file.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_5fd">When the <filename role="special"
+	  class="directory">.hg/patches</filename> directory is a
+	repository, the <command role="hg-ext-mq">qimport</command>
+	and <command role="hg-ext-mq">qnew</command> commands
+	automatically <command role="hg-cmd">hg add</command> new
+	patches.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qnew</command>&emdash;create a
+	new patch</title>
+
+      <para id="x_5fe">The <command role="hg-ext-mq">qnew</command> command
+	creates a new patch.  It takes one mandatory argument, the
+	name to use for the patch file.  The newly created patch is
+	created empty by default.  It is added to the <filename
+	  role="special">series</filename> file after the current
+	topmost applied patch, and is immediately pushed on top of
+	that patch.</para>
+
+      <para id="x_5ff">If <command role="hg-ext-mq">qnew</command> finds modified
+	files in the working directory, it will refuse to create a new
+	patch unless the <option
+	  role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
+	(see below).  This behavior allows you to <command
+	  role="hg-ext-mq">qrefresh</command> your topmost applied
+	patch before you apply a new patch on top of it.</para>
+
+      <para id="x_600">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_601"><option
+	      role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
+	    patch if the contents of the working directory are
+	    modified.  Any outstanding modifications are added to the
+	    newly created patch, so after this command completes, the
+	    working directory will no longer be modified.</para>
+	</listitem>
+	<listitem><para id="x_602"><option
+	      role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
+	    text as the commit message. This text will be stored at
+	    the beginning of the patch file, before the patch
+	    data.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qnext</command>&emdash;print
+	the name of the next patch</title>
+
+      <para id="x_603">The <command role="hg-ext-mq">qnext</command> command
+	prints the name name of the next patch in the <filename
+	  role="special">series</filename> file after the topmost
+	applied patch.  This patch will become the topmost applied
+	patch if you run <command
+	  role="hg-ext-mq">qpush</command>.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qpop</command>&emdash;pop
+	patches off the stack</title>
+
+      <para id="x_604">The <command role="hg-ext-mq">qpop</command> command
+	removes applied patches from the top of the stack of applied
+	patches.  By default, it removes only one patch.</para>
+
+      <para id="x_605">This command removes the changesets that represent the
+	popped patches from the repository, and updates the working
+	directory to undo the effects of the patches.</para>
+
+      <para id="x_606">This command takes an optional argument, which it uses as
+	the name or index of the patch to pop to.  If given a name, it
+	will pop patches until the named patch is the topmost applied
+	patch.  If given a number, <command
+	  role="hg-ext-mq">qpop</command> treats the number as an
+	index into the entries in the series file, counting from zero
+	(empty lines and lines containing only comments do not count).
+	It pops patches until the patch identified by the given index
+	is the topmost applied patch.</para>
+
+      <para id="x_607">The <command role="hg-ext-mq">qpop</command> command does
+	not read or write patches or the <filename
+	  role="special">series</filename> file.  It is thus safe to
+	<command role="hg-ext-mq">qpop</command> a patch that you have
+	removed from the <filename role="special">series</filename>
+	file, or a patch that you have renamed or deleted entirely.
+	In the latter two cases, use the name of the patch as it was
+	when you applied it.</para>
+
+      <para id="x_608">By default, the <command role="hg-ext-mq">qpop</command>
+	command will not pop any patches if the working directory has
+	been modified.  You can override this behavior using the
+	<option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
+	which reverts all modifications in the working
+	directory.</para>
+
+      <para id="x_609">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_60a"><option
+	      role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
+	    applied patches.  This returns the repository to its state
+	    before you applied any patches.</para>
+	</listitem>
+	<listitem><para id="x_60b"><option
+	      role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
+	    revert any modifications to the working directory when
+	    popping.</para>
+	</listitem>
+	<listitem><para id="x_60c"><option
+	      role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
+	    from the named queue.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_60d">The <command role="hg-ext-mq">qpop</command> command
+	removes one line from the end of the <filename
+	  role="special">status</filename> file for each patch that it
+	pops.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qprev</command>&emdash;print
+	the name of the previous patch</title>
+
+      <para id="x_60e">The <command role="hg-ext-mq">qprev</command> command
+	prints the name of the patch in the <filename
+	  role="special">series</filename> file that comes before the
+	topmost applied patch. This will become the topmost applied
+	patch if you run <command
+	  role="hg-ext-mq">qpop</command>.</para>
+
+    </sect2>
+    <sect2 id="sec:mqref:cmd:qpush">
+      <title><command role="hg-ext-mq">qpush</command>&emdash;push
+	patches onto the stack</title>
+
+      <para id="x_60f">The <command role="hg-ext-mq">qpush</command> command adds
+	patches onto the applied stack.  By default, it adds only one
+	patch.</para>
+
+      <para id="x_610">This command creates a new changeset to represent each
+	applied patch, and updates the working directory to apply the
+	effects of the patches.</para>
+
+      <para id="x_611">The default data used when creating a changeset are as
+	follows:</para>
+      <itemizedlist>
+	<listitem><para id="x_612">The commit date and time zone are the current
+	    date and time zone.  Because these data are used to
+	    compute the identity of a changeset, this means that if
+	    you <command role="hg-ext-mq">qpop</command> a patch and
+	    <command role="hg-ext-mq">qpush</command> it again, the
+	    changeset that you push will have a different identity
+	    than the changeset you popped.</para>
+	</listitem>
+	<listitem><para id="x_613">The author is the same as the default used by
+	    the <command role="hg-cmd">hg commit</command>
+	    command.</para>
+	</listitem>
+	<listitem><para id="x_614">The commit message is any text from the patch
+	    file that comes before the first diff header.  If there is
+	    no such text, a default commit message is used that
+	    identifies the name of the patch.</para>
+	</listitem></itemizedlist>
+      <para id="x_615">If a patch contains a Mercurial patch header,
+	the information in the patch header overrides these
+	defaults.</para>
+
+      <para id="x_616">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_617"><option
+	      role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
+	    unapplied patches from the <filename
+	      role="special">series</filename> file until there are
+	    none left to push.</para>
+	</listitem>
+	<listitem><para id="x_618"><option
+	      role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
+	    of the patch to the end of the commit message.</para>
+	</listitem>
+	<listitem><para id="x_619"><option
+	      role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
+	    fails to apply cleanly, use the entry for the patch in
+	    another saved queue to compute the parameters for a
+	    three-way merge, and perform a three-way merge using the
+	    normal Mercurial merge machinery.  Use the resolution of
+	    the merge as the new patch content.</para>
+	</listitem>
+	<listitem><para id="x_61a"><option
+	      role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
+	    named queue if merging while pushing.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_61b">The <command role="hg-ext-mq">qpush</command> command
+	reads, but does not modify, the <filename
+	  role="special">series</filename> file.  It appends one line
+	to the <command role="hg-cmd">hg status</command> file for
+	each patch that it pushes.</para>
+
+    </sect2>
+    <sect2>
+      <title><command
+	  role="hg-ext-mq">qrefresh</command>&emdash;update the
+	topmost applied patch</title>
+
+      <para id="x_61c">The <command role="hg-ext-mq">qrefresh</command> command
+	updates the topmost applied patch.  It modifies the patch,
+	removes the old changeset that represented the patch, and
+	creates a new changeset to represent the modified
+	patch.</para>
+
+      <para id="x_61d">The <command role="hg-ext-mq">qrefresh</command> command
+	looks for the following modifications:</para>
+      <itemizedlist>
+	<listitem><para id="x_61e">Changes to the commit message, i.e. the text
+	    before the first diff header in the patch file, are
+	    reflected in the new changeset that represents the
+	    patch.</para>
+	</listitem>
+	<listitem><para id="x_61f">Modifications to tracked files in the working
+	    directory are added to the patch.</para>
+	</listitem>
+	<listitem><para id="x_620">Changes to the files tracked using <command
+	      role="hg-cmd">hg add</command>, <command
+	      role="hg-cmd">hg copy</command>, <command
+	      role="hg-cmd">hg remove</command>, or <command
+	      role="hg-cmd">hg rename</command>.  Added files and copy
+	    and rename destinations are added to the patch, while
+	    removed files and rename sources are removed.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_621">Even if <command role="hg-ext-mq">qrefresh</command>
+	detects no changes, it still recreates the changeset that
+	represents the patch.  This causes the identity of the
+	changeset to differ from the previous changeset that
+	identified the patch.</para>
+
+      <para id="x_622">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_623"><option
+	      role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
+	    the commit and patch description, using the preferred text
+	    editor.</para>
+	</listitem>
+	<listitem><para id="x_624"><option
+	      role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
+	    the commit message and patch description, using the given
+	    text.</para>
+	</listitem>
+	<listitem><para id="x_625"><option
+	      role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
+	    the commit message and patch description, using text from
+	    the given file.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qrename</command>&emdash;rename
+	a patch</title>
+
+      <para id="x_626">The <command role="hg-ext-mq">qrename</command> command
+	renames a patch, and changes the entry for the patch in the
+	<filename role="special">series</filename> file.</para>
+
+      <para id="x_627">With a single argument, <command
+	  role="hg-ext-mq">qrename</command> renames the topmost
+	applied patch.  With two arguments, it renames its first
+	argument to its second.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qseries</command>&emdash;print
+	the entire patch series</title>
+
+      <para id="x_62a">The <command role="hg-ext-mq">qseries</command> command
+	prints the entire patch series from the <filename
+	  role="special">series</filename> file.  It prints only patch
+	names, not empty lines or comments.  It prints in order from
+	first to be applied to last.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq">qtop</command>&emdash;print the
+	name of the current patch</title>
+
+      <para id="x_62b">The <command role="hg-ext-mq">qtop</command> prints the
+	name of the topmost currently applied patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command
+	  role="hg-ext-mq">qunapplied</command>&emdash;print patches
+	not yet applied</title>
+
+      <para id="x_62c">The <command role="hg-ext-mq">qunapplied</command> command
+	prints the names of patches from the <filename
+	  role="special">series</filename> file that are not yet
+	applied.  It prints them in order from the next patch that
+	will be pushed to the last.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-cmd">hg strip</command>&emdash;remove a
+	revision and descendants</title>
+
+      <para id="x_62d">The <command role="hg-cmd">hg strip</command> command
+	removes a revision, and all of its descendants, from the
+	repository.  It undoes the effects of the removed revisions
+	from the repository, and updates the working directory to the
+	first parent of the removed revision.</para>
+
+      <para id="x_62e">The <command role="hg-cmd">hg strip</command> command
+	saves a backup of the removed changesets in a bundle, so that
+	they can be reapplied if removed in error.</para>
+
+      <para id="x_62f">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save
+	    unrelated changesets that are intermixed with the stripped
+	    changesets in the backup bundle.</para>
+	</listitem>
+	<listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
+	    branch has multiple heads, remove all heads.</para>
+	</listitem>
+	<listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
+	    not save a backup bundle.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>MQ file reference</title>
+
+    <sect2>
+      <title>The <filename role="special">series</filename>
+	file</title>
+
+      <para id="x_633">The <filename role="special">series</filename> file
+	contains a list of the names of all patches that MQ can apply.
+	It is represented as a list of names, with one name saved per
+	line.  Leading and trailing white space in each line are
+	ignored.</para>
+
+      <para id="x_634">Lines may contain comments.  A comment begins with the
+	<quote><literal>#</literal></quote> character, and extends to
+	the end of the line.  Empty lines, and lines that contain only
+	comments, are ignored.</para>
+
+      <para id="x_635">You will often need to edit the <filename
+	  role="special">series</filename> file by hand, hence the
+	support for comments and empty lines noted above.  For
+	example, you can comment out a patch temporarily, and <command
+	  role="hg-ext-mq">qpush</command> will skip over that patch
+	when applying patches.  You can also change the order in which
+	patches are applied by reordering their entries in the
+	<filename role="special">series</filename> file.</para>
+
+      <para id="x_636">Placing the <filename role="special">series</filename>
+	file under revision control is also supported; it is a good
+	idea to place all of the patches that it refers to under
+	revision control, as well.  If you create a patch directory
+	using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
+	option to <command role="hg-ext-mq">qinit</command>, this will
+	be done for you automatically.</para>
+
+    </sect2>
+    <sect2>
+      <title>The <filename role="special">status</filename>
+	file</title>
+
+      <para id="x_637">The <filename role="special">status</filename> file
+	contains the names and changeset hashes of all patches that MQ
+	currently has applied.  Unlike the <filename
+	  role="special">series</filename> file, this file is not
+	intended for editing.  You should not place this file under
+	revision control, or modify it in any way.  It is used by MQ
+	strictly for internal book-keeping.</para>
+
+    </sect2>
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->

fr/appC-srcinstall.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="chap:srcinstall">
+  <?dbhtml filename="installing-mercurial-from-source.html"?>
+  <title>Installing Mercurial from source</title>
+
+  <sect1 id="sec:srcinstall:unixlike">
+    <title>On a Unix-like system</title>
+
+    <para id="x_5e0">If you are using a Unix-like system that has a sufficiently
+      recent version of Python (2.3 or newer) available, it is easy to
+      install Mercurial from source.</para>
+    <orderedlist>
+      <listitem><para id="x_5e1">Download a recent source tarball from <ulink
+	    url="http://www.selenic.com/mercurial/download">http://www.selenic.com/mercurial/download</ulink>.</para>
+      </listitem>
+      <listitem><para id="x_5e2">Unpack the tarball:</para>
+	<programlisting>gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting>
+      </listitem>
+      <listitem><para id="x_5e3">Go into the source directory and run the
+	  installer script.  This will build Mercurial and install it
+	  in your home directory.</para>
+	<programlisting>cd mercurial-MYVERSION
+python setup.py install --force --home=$HOME</programlisting>
+      </listitem>
+    </orderedlist>
+    <para id="x_5e4">Once the install finishes, Mercurial will be in the
+      <literal>bin</literal> subdirectory of your home directory.
+      Don't forget to make sure that this directory is present in your
+      shell's search path.</para>
+
+    <para id="x_5e5">You will probably need to set the <envar>PYTHONPATH</envar>
+      environment variable so that the Mercurial executable can find
+      the rest of the Mercurial packages.  For example, on my laptop,
+      I have set it to <literal>/home/bos/lib/python</literal>.  The
+      exact path that you will need to use depends on how Python was
+      built for your system, but should be easy to figure out.  If
+      you're uncertain, look through the output of the installer
+      script above, and see where the contents of the
+      <literal>mercurial</literal> directory were installed to.</para>
+
+  </sect1>
+  <sect1>
+    <title>On Windows</title>
+
+    <para id="x_5e6">Building and installing Mercurial on Windows requires a
+      variety of tools, a fair amount of technical knowledge, and
+      considerable patience.  I very much <emphasis>do not
+	recommend</emphasis> this route if you are a <quote>casual
+	user</quote>.  Unless you intend to hack on Mercurial, I
+      strongly suggest that you use a binary package instead.</para>
+
+    <para id="x_5e7">If you are intent on building Mercurial from source on
+      Windows, follow the <quote>hard way</quote> directions on the
+      Mercurial wiki at <ulink
+	url="http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall">http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>, 
+      and expect the process to involve a lot of fiddly work.</para>
+
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->

fr/appD-license.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter>
+<title>Open Publication License</title>
+<para>\label{cha:opl}</para>
+
+<para>Version 1.0, 8 June 1999</para>
+
+<sect1>
+<title>Requirements on both unmodified and modified versions</title>
+
+<para>The Open Publication works may be reproduced and distributed in whole
+or in part, in any medium physical or electronic, provided that the
+terms of this license are adhered to, and that this license or an
+incorporation of it by reference (with any options elected by the
+author(s) and/or publisher) is displayed in the reproduction.</para>
+
+<para>Proper form for an incorporation by reference is as follows:</para>
+
+<blockquote>
+<para>  Copyright (c) <emphasis>year</emphasis> by <emphasis>author's name or designee</emphasis>. This
+  material may be distributed only subject to the terms and conditions
+  set forth in the Open Publication License, v<emphasis>x.y</emphasis> or later (the
+  latest version is presently available at
+  <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
+</blockquote>
+
+<para>The reference must be immediately followed with any options elected by
+the author(s) and/or publisher of the document (see
+section <xref linkend="sec:opl:options"/>).</para>
+
+<para>Commercial redistribution of Open Publication-licensed material is
+permitted.</para>
+
+<para>Any publication in standard (paper) book form shall require the
+citation of the original publisher and author. The publisher and
+author's names shall appear on all outer surfaces of the book. On all
+outer surfaces of the book the original publisher's name shall be as
+large as the title of the work and cited as possessive with respect to
+the title.</para>
+
+</sect1>
+<sect1>
+<title>Copyright</title>
+
+<para>The copyright to each Open Publication is owned by its author(s) or
+designee.
+</para>
+
+</sect1>
+<sect1>
+<title>Scope of license</title>
+
+<para>The following license terms apply to all Open Publication works,
+unless otherwise explicitly stated in the document.
+</para>
+
+<para>Mere aggregation of Open Publication works or a portion of an Open
+Publication work with other works or programs on the same media shall
+not cause this license to apply to those other works. The aggregate
+work shall contain a notice specifying the inclusion of the Open
+Publication material and appropriate copyright notice.
+</para>
+
+<para><emphasis role="bold">Severability</emphasis>. If any part of this license is found to be
+unenforceable in any jurisdiction, the remaining portions of the
+license remain in force.
+</para>
+
+<para><emphasis role="bold">No warranty</emphasis>. Open Publication works are licensed and provided
+<quote>as is</quote> without warranty of any kind, express or implied, including,
+but not limited to, the implied warranties of merchantability and
+fitness for a particular purpose or a warranty of non-infringement.
+</para>
+
+</sect1>
+<sect1>
+<title>Requirements on modified works</title>
+
+<para>All modified versions of documents covered by this license, including
+translations, anthologies, compilations and partial documents, must
+meet the following requirements:
+</para>
+
+<orderedlist>
+<listitem><para>The modified version must be labeled as such.
+</para>
+</listitem>
+<listitem><para>The person making the modifications must be identified and the
+  modifications dated.
+</para>
+</listitem>
+<listitem><para>Acknowledgement of the original author and publisher if
+  applicable must be retained according to normal academic citation
+  practices.
+</para>
+</listitem>
+<listitem><para>The location of the original unmodified document must be
+  identified.
+</para>
+</listitem>
+<listitem><para>The original author's (or authors') name(s) may not be used to
+  assert or imply endorsement of the resulting document without the
+  original author's (or authors') permission.
+</para>
+</listitem></orderedlist>
+
+</sect1>
+<sect1>
+<title>Good-practice recommendations</title>
+
+<para>In addition to the requirements of this license, it is requested from
+and strongly recommended of redistributors that:
+</para>
+
+<orderedlist>
+<listitem><para>If you are distributing Open Publication works on hardcopy or
+  CD-ROM, you provide email notification to the authors of your intent
+  to redistribute at least thirty days before your manuscript or media
+  freeze, to give the authors time to provide updated documents. This
+  notification should describe modifications, if any, made to the
+  document.
+</para>
+</listitem>
+<listitem><para>All substantive modifications (including deletions) be either
+  clearly marked up in the document or else described in an attachment
+  to the document.
+</para>
+</listitem>
+<listitem><para>Finally, while it is not mandatory under this license, it is
+  considered good form to offer a free copy of any hardcopy and CD-ROM
+  expression of an Open Publication-licensed work to its author(s).
+</para>
+</listitem></orderedlist>
+
+</sect1>
+<sect1>
+<title>License options</title>
+<para>\label{sec:opl:options}
+</para>
+
+<para>The author(s) and/or publisher of an Open Publication-licensed
+document may elect certain options by appending language to the
+reference to or copy of the license. These options are considered part
+of the license instance and must be included with the license (or its
+incorporation by reference) in derived works.
+</para>
+
+<orderedlist>
+<listitem><para>To prohibit distribution of substantively modified versions
+  without the explicit permission of the author(s). <quote>Substantive
+  modification</quote> is defined as a change to the semantic content of the
+  document, and excludes mere changes in format or typographical
+  corrections.
+</para>
+</listitem>
+<listitem><para>  To accomplish this, add the phrase <quote>Distribution of substantively
+  modified versions of this document is prohibited without the
+  explicit permission of the copyright holder.</quote> to the license
+  reference or copy.
+</para>
+</listitem>
+</para>
+</listitem>
+<listitem><para>To prohibit any publication of this work or derivative works in
+  whole or in part in standard (paper) book form for commercial
+  purposes is prohibited unless prior permission is obtained from the
+  copyright holder.
+</para>
+</listitem>
+<listitem><para>  To accomplish this, add the phrase <quote>Distribution of the work or
+  derivative of the work in any standard (paper) book form is
+  prohibited unless prior permission is obtained from the copyright
+  holder.</quote> to the license reference or copy.
+</para>
+</listitem></orderedlist>
+
+</sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+#!/usr/bin/env python
+#
+# Add unique ID attributes to para tags.  This script should only be
+# run by one person, since otherwise it introduces the possibility of
+# chaotic conflicts among tags.
+
+import glob, os, re, sys
+
+tagged = re.compile('<para[^>]* id="x_([0-9a-f]+)"[^>]*>', re.M)
+untagged = re.compile('<para>')
+
+names = glob.glob('ch*.xml') + glob.glob('app*.xml')
+
+# First pass: find the highest-numbered paragraph ID.
+
+biggest_id = 0
+seen = set()
+errs = 0
+
+for name in names:
+    for m in tagged.finditer(open(name).read()):
+        i = int(m.group(1),16)
+        if i in seen:
+            print >> sys.stderr, '%s: duplication of ID %s' % (name, i)
+            errs += 1
+        seen.add(i)
+        if i > biggest_id:
+            biggest_id = i
+
+def retag(s):
+    global biggest_id
+    biggest_id += 1
+    return '<para id="x_%x">' % biggest_id
+
+# Second pass: add IDs to paragraphs that currently lack them.
+
+for name in names:
+    f = open(name).read()
+    f1 = untagged.sub(retag, f)
+    if f1 != f:
+        tmpname = name + '.tmp'
+        fp = open(tmpname, 'w')
+        fp.write(f1)
+        fp.close()
+        os.rename(tmpname, name)
+
+sys.exit(errs)

fr/book-shortcuts.xml

+<!-- Please keep the contents of this file sorted. -->
+
+<!ENTITY emdash "&#8212;">

fr/bookhtml.cfg

-% -*- latex -*-
-
-\Preamble{xhtml}
-
-% Tex4ht's default definition of lists is complete crap.
-% Unfortunately, it can't distinguish between "ul" and "dl" lists.
-
-\ConfigureList{itemize}%
-   {\EndP\HCode{<ul>}\let\endItem=\empty}
-   {\ifvmode \IgnorePar\fi
-    \EndP\HCode{</li></ul>}\ShowPar}
-   {\endItem \def\endItem{\EndP\Tg</span>}\HCode{<li><span class="dt">}}
-   {\HCode{</span><span class="dd">}}
-\def\textbullet{}
-
-\begin{document}
-
-\EndPreamble

fr/branch.tex

-\chapter{Managing releases and branchy development}
-\label{chap:branch}
-
-Mercurial provides several mechanisms for you to manage a project that
-is making progress on multiple fronts at once.  To understand these
-mechanisms, let's first take a brief look at a fairly normal software
-project structure.
-
-Many software projects issue periodic ``major'' releases that contain
-substantial new features.  In parallel, they may issue ``minor''
-releases.  These are usually identical to the major releases off which
-they're based, but with a few bugs fixed.
-
-In this chapter, we'll start by talking about how to keep records of
-project milestones such as releases.  We'll then continue on to talk
-about the flow of work between different phases of a project, and how
-Mercurial can help you to isolate and manage this work.
-
-\section{Giving a persistent name to a revision}
-
-Once you decide that you'd like to call a particular revision a
-``release'', it's a good idea to record the identity of that revision.
-This will let you reproduce that release at a later date, for whatever
-purpose you might need at the time (reproducing a bug, porting to a
-new platform, etc).
-\interaction{tag.init}
-
-Mercurial lets you give a permanent name to any revision using the
-\hgcmd{tag} command.  Not surprisingly, these names are called
-``tags''.
-\interaction{tag.tag}
-
-A tag is nothing more than a ``symbolic name'' for a revision.  Tags
-exist purely for your convenience, so that you have a handy permanent
-way to refer to a revision; Mercurial doesn't interpret the tag names
-you use in any way.  Neither does Mercurial place any restrictions on
-the name of a tag, beyond a few that are necessary to ensure that a
-tag can be parsed unambiguously.  A tag name cannot contain any of the
-following characters:
-\begin{itemize}
-\item Colon (ASCII 58, ``\texttt{:}'')
-\item Carriage return (ASCII 13, ``\Verb+\r+'')
-\item Newline (ASCII 10, ``\Verb+\n+'')
-\end{itemize}
-
-You can use the \hgcmd{tags} command to display the tags present in
-your repository.  In the output, each tagged revision is identified
-first by its name, then by revision number, and finally by the unique
-hash of the revision.  
-\interaction{tag.tags}
-Notice that \texttt{tip} is listed in the output of \hgcmd{tags}.  The
-\texttt{tip} tag is a special ``floating'' tag, which always
-identifies the newest revision in the repository.
-
-In the output of the \hgcmd{tags} command, tags are listed in reverse
-order, by revision number.  This usually means that recent tags are
-listed before older tags.  It also means that \texttt{tip} is always
-going to be the first tag listed in the output of \hgcmd{tags}.
-
-When you run \hgcmd{log}, if it displays a revision that has tags
-associated with it, it will print those tags.
-\interaction{tag.log}
-
-Any time you need to provide a revision~ID to a Mercurial command, the
-command will accept a tag name in its place.  Internally, Mercurial
-will translate your tag name into the corresponding revision~ID, then
-use that.
-\interaction{tag.log.v1.0}
-
-There's no limit on the number of tags you can have in a repository,
-or on the number of tags that a single revision can have.  As a
-practical matter, it's not a great idea to have ``too many'' (a number
-which will vary from project to project), simply because tags are
-supposed to help you to find revisions.  If you have lots of tags, the
-ease of using them to identify revisions diminishes rapidly.
-
-For example, if your project has milestones as frequent as every few
-days, it's perfectly reasonable to tag each one of those.  But if you
-have a continuous build system that makes sure every revision can be
-built cleanly, you'd be introducing a lot of noise if you were to tag
-every clean build.  Instead, you could tag failed builds (on the
-assumption that they're rare!), or simply not use tags to track
-buildability.
-
-If you want to remove a tag that you no longer want, use
-\hgcmdargs{tag}{--remove}.  
-\interaction{tag.remove}
-You can also modify a tag at any time, so that it identifies a
-different revision, by simply issuing a new \hgcmd{tag} command.
-You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that
-you \emph{really} want to update the tag.
-\interaction{tag.replace}
-There will still be a permanent record of the previous identity of the
-tag, but Mercurial will no longer use it.  There's thus no penalty to
-tagging the wrong revision; all you have to do is turn around and tag
-the correct revision once you discover your error.
-
-Mercurial stores tags in a normal revision-controlled file in your
-repository.  If you've created any tags, you'll find them in a file
-named \sfilename{.hgtags}.  When you run the \hgcmd{tag} command,
-Mercurial modifies this file, then automatically commits the change to
-it.  This means that every time you run \hgcmd{tag}, you'll see a
-corresponding changeset in the output of \hgcmd{log}.
-\interaction{tag.tip}
-
-\subsection{Handling tag conflicts during a merge}
-
-You won't often need to care about the \sfilename{.hgtags} file, but
-it sometimes makes its presence known during a merge.  The format of
-the file is simple: it consists of a series of lines.  Each line
-starts with a changeset hash, followed by a space, followed by the
-name of a tag.
-
-If you're resolving a conflict in the \sfilename{.hgtags} file during
-a merge, there's one twist to modifying the \sfilename{.hgtags} file:
-when Mercurial is parsing the tags in a repository, it \emph{never}
-reads the working copy of the \sfilename{.hgtags} file.  Instead, it
-reads the \emph{most recently committed} revision of the file.
-
-An unfortunate consequence of this design is that you can't actually
-verify that your merged \sfilename{.hgtags} file is correct until
-\emph{after} you've committed a change.  So if you find yourself
-resolving a conflict on \sfilename{.hgtags} during a merge, be sure to
-run \hgcmd{tags} after you commit.  If it finds an error in the
-\sfilename{.hgtags} file, it will report the location of the error,
-which you can then fix and commit.  You should then run \hgcmd{tags}
-again, just to be sure that your fix is correct.
-
-\subsection{Tags and cloning}
-
-You may have noticed that the \hgcmd{clone} command has a
-\hgopt{clone}{-r} option that lets you clone an exact copy of the
-repository as of a particular changeset.  The new clone will not
-contain any project history that comes after the revision you
-specified.  This has an interaction with tags that can surprise the
-unwary.
-
-Recall that a tag is stored as a revision to the \sfilename{.hgtags}
-file, so that when you create a tag, the changeset in which it's
-recorded necessarily refers to an older changeset.  When you run
-\hgcmdargs{clone}{-r foo} to clone a repository as of tag
-\texttt{foo}, the new clone \emph{will not contain the history that
-  created the tag} that you used to clone the repository.  The result
-is that you'll get exactly the right subset of the project's history
-in the new repository, but \emph{not} the tag you might have expected.
-
-\subsection{When permanent tags are too much}
-
-Since Mercurial's tags are revision controlled and carried around with
-a project's history, everyone you work with will see the tags you
-create.  But giving names to revisions has uses beyond simply noting
-that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}.  If
-you're trying to track down a subtle bug, you might want a tag to
-remind you of something like ``Anne saw the symptoms with this
-revision''.
-
-For cases like this, what you might want to use are \emph{local} tags.
-You can create a local tag with the \hgopt{tag}{-l} option to the
-\hgcmd{tag} command.  This will store the tag in a file called
-\sfilename{.hg/localtags}.  Unlike \sfilename{.hgtags},
-\sfilename{.hg/localtags} is not revision controlled.  Any tags you
-create using \hgopt{tag}{-l} remain strictly local to the repository
-you're currently working in.
-
-\section{The flow of changes---big picture vs. little}
-
-To return to the outline I sketched at the beginning of a chapter,
-let's think about a project that has multiple concurrent pieces of
-work under development at once.
-
-There might be a push for a new ``main'' release; a new minor bugfix
-release to the last main release; and an unexpected ``hot fix'' to an
-old release that is now in maintenance mode.
-
-The usual way people refer to these different concurrent directions of
-development is as ``branches''.  However, we've already seen numerous
-times that Mercurial treats \emph{all of history} as a series of
-branches and merges.  Really, what we have here is two ideas that are
-peripherally related, but which happen to share a name.
-\begin{itemize}
-\item ``Big picture'' branches represent the sweep of a project's
-  evolution; people give them names, and talk about them in
-  conversation.
-\item ``Little picture'' branches are artefacts of the day-to-day
-  activity of developing and merging changes.  They expose the
-  narrative of how the code was developed.
-\end{itemize}
-
-\section{Managing big-picture branches in repositories}
-
-The easiest way to isolate a ``big picture'' branch in Mercurial is in
-a dedicated repository.  If you have an existing shared
-repository---let's call it \texttt{myproject}---that reaches a ``1.0''
-milestone, you can start to prepare for future maintenance releases on
-top of version~1.0 by tagging the revision from which you prepared
-the~1.0 release.
-\interaction{branch-repo.tag}
-You can then clone a new shared \texttt{myproject-1.0.1} repository as
-of that tag.
-\interaction{branch-repo.clone}
-
-Afterwards, if someone needs to work on a bug fix that ought to go
-into an upcoming~1.0.1 minor release, they clone the
-\texttt{myproject-1.0.1} repository, make their changes, and push them
-back.
-\interaction{branch-repo.bugfix}
-Meanwhile, development for the next major release can continue,
-isolated and unabated, in the \texttt{myproject} repository.
-\interaction{branch-repo.new}
-
-\section{Don't repeat yourself: merging across branches}
-
-In many cases, if you have a bug to fix on a maintenance branch, the
-chances are good that the bug exists on your project's main branch
-(and possibly other maintenance branches, too).  It's a rare developer
-who wants to fix the same bug multiple times, so let's look at a few
-ways that Mercurial can help you to manage these bugfixes without
-duplicating your work.
-
-In the simplest instance, all you need to do is pull changes from your
-maintenance branch into your local clone of the target branch.
-\interaction{branch-repo.pull}
-You'll then need to merge the heads of the two branches, and push back
-to the main branch.
-\interaction{branch-repo.merge}
-
-\section{Naming branches within one repository}
-
-In most instances, isolating branches in repositories is the right
-approach.  Its simplicity makes it easy to understand; and so it's
-hard to make mistakes.  There's a one-to-one relationship between
-branches you're working in and directories on your system.  This lets
-you use normal (non-Mercurial-aware) tools to work on files within a
-branch/repository.
-
-If you're more in the ``power user'' category (\emph{and} your
-collaborators are too), there is an alternative way of handling
-branches that you can consider.  I've already mentioned the
-human-level distinction between ``small picture'' and ``big picture''
-branches.  While Mercurial works with multiple ``small picture''
-branches in a repository all the time (for example after you pull
-changes in, but before you merge them), it can \emph{also} work with
-multiple ``big picture'' branches.
-
-The key to working this way is that Mercurial lets you assign a
-persistent \emph{name} to a branch.  There always exists a branch
-named \texttt{default}.  Even before you start naming branches
-yourself, you can find traces of the \texttt{default} branch if you
-look for them.
-
-As an example, when you run the \hgcmd{commit} command, and it pops up
-your editor so that you can enter a commit message, look for a line
-that contains the text ``\texttt{HG: branch default}'' at the bottom.
-This is telling you that your commit will occur on the branch named
-\texttt{default}.
-
-To start working with named branches, use the \hgcmd{branches}
-command.  This command lists the named branches already present in
-your repository, telling you which changeset is the tip of each.
-\interaction{branch-named.branches}
-Since you haven't created any named branches yet, the only one that
-exists is \texttt{default}.
-
-To find out what the ``current'' branch is, run the \hgcmd{branch}
-command, giving it no arguments.  This tells you what branch the
-parent of the current changeset is on.
-\interaction{branch-named.branch}
-
-To create a new branch, run the \hgcmd{branch} command again.  This
-time, give it one argument: the name of the branch you want to create.
-\interaction{branch-named.create}
-
-After you've created a branch, you might wonder what effect the
-\hgcmd{branch} command has had.  What do the \hgcmd{status} and
-\hgcmd{tip} commands report?
-\interaction{branch-named.status}
-Nothing has changed in the working directory, and there's been no new
-history created.  As this suggests, running the \hgcmd{branch} command
-has no permanent effect; it only tells Mercurial what branch name to
-use the \emph{next} time you commit a changeset.
-
-When you commit a change, Mercurial records the name of the branch on
-which you committed.  Once you've switched from the \texttt{default}
-branch to another and committed, you'll see the name of the new branch
-show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands
-that display the same kind of output.
-\interaction{branch-named.commit}
-The \hgcmd{log}-like commands will print the branch name of every
-changeset that's not on the \texttt{default} branch.  As a result, if
-you never use named branches, you'll never see this information.
-