1.1 --- a/en/99defs.tex	Tue Jul 25 00:18:31 2006 -0700
     1.2 +++ b/en/99defs.tex	Thu Jul 27 10:20:55 2006 -0700
     1.3 @@ -70,9 +70,6 @@
     1.4  % Python module.
     1.5  \newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}}
     1.6  
     1.7 -% Bundled extension.
     1.8 -\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
     1.9 -
    1.10  % Python class in a module.
    1.11  \newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2}
    1.12      class}\texttt{#1.#2}}

     2.1 --- a/en/Makefile	Tue Jul 25 00:18:31 2006 -0700
     2.2 +++ b/en/Makefile	Thu Jul 27 10:20:55 2006 -0700
     2.3 @@ -23,6 +23,7 @@
     2.4  	examples/hook.ws \
     2.5  	examples/mq.qinit-help \
     2.6  	examples/mq.dodiff \
     2.7 +	examples/mq.id \
     2.8  	examples/mq.tarball \
     2.9  	examples/mq.tools \
    2.10  	examples/mq.tutorial

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/examples/mq.id	Thu Jul 27 10:20:55 2006 -0700
     3.3 @@ -0,0 +1,22 @@
     3.4 +#!/bin/sh
     3.5 +
     3.6 +hg init a
     3.7 +cd a
     3.8 +hg qinit
     3.9 +echo 'int x;' > test.c
    3.10 +hg ci -Ama
    3.11 +
    3.12 +hg qnew first.patch
    3.13 +echo 'float c;' >> test.c
    3.14 +hg qrefresh
    3.15 +
    3.16 +hg qnew second.patch
    3.17 +echo 'double u;' > other.c
    3.18 +hg add other.c
    3.19 +hg qrefresh
    3.20 +
    3.21 +#$ name: out
    3.22 +
    3.23 +hg qapplied
    3.24 +hg log -r qbase:qtip
    3.25 +hg export second.patch

     4.1 --- a/en/mq.tex	Tue Jul 25 00:18:31 2006 -0700
     4.2 +++ b/en/mq.tex	Thu Jul 27 10:20:55 2006 -0700
     4.3 @@ -69,7 +69,6 @@
     4.4  \subsection{A patchwork quilt}
     4.5  \label{sec:mq:quilt}
     4.6  
     4.7 -
     4.8  In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
     4.9  approach of Andrew's scripts and published a tool called ``patchwork
    4.10  quilt''~\cite{web:quilt}, or simply ``quilt''
    4.11 @@ -114,19 +113,45 @@
    4.12  Mercurial.  Each patch that you push is represented as a Mercurial
    4.13  changeset.  Pop a patch, and the changeset goes away.
    4.14  
    4.15 -This integration makes understanding patches and debugging their
    4.16 -effects \emph{enormously} easier.  Since every applied patch has an
    4.17 -associated changeset, you can use \hgcmdargs{log}{\emph{filename}} to
    4.18 -see which changesets and patches affected a file.  You can use the
    4.19 -\hgext{bisect} extension to binary-search through all changesets and
    4.20 -applied patches to see where a bug got introduced or fixed.  You can
    4.21 -use the \hgcmd{annotate} command to see which changeset or patch
    4.22 -modified a particular line of a source file.  And so on.
    4.23 -
    4.24  Because quilt does not care about revision control tools, it is still
    4.25  a tremendously useful piece of software to know about for situations
    4.26  where you cannot use Mercurial and MQ.
    4.27  
    4.28 +\section{The huge advantage of MQ}
    4.29 +
    4.30 +I cannot overstate the value that MQ offers through the unification of
    4.31 +patches and revision control.
    4.32 +
    4.33 +A major reaon that patches have persisted in the free software and
    4.34 +open source world---in spite of the availability of increasingly
    4.35 +capable revision control tools over the years---is the \emph{agility}
    4.36 +they offer.  
    4.37 +
    4.38 +Traditional revision control tools make a permanent, irreversible
    4.39 +record of everything that you do.  While this has great value, it's
    4.40 +also somewhat stifling.  If you want to perform a wild-eyed
    4.41 +experiment, you have to be careful in how you go about it, or you risk
    4.42 +leaving unneeded---or worse, misleading or destabilising---traces of
    4.43 +your missteps and errors in the permanent revision record.
    4.44 +
    4.45 +By contrast, MQ's marriage of distributed revision control with
    4.46 +patches makes it much easier to isolate your work.  Your patches live
    4.47 +on top of normal revision history, and you can make them disappear or
    4.48 +reappear at will.  If you don't like a patch, you can drop it.  If a
    4.49 +patch isn't quite as you want it to be, simply fix it---as many times
    4.50 +as you need to, until you have refined it into the form you desire.
    4.51 +
    4.52 +As an example, the integration of patches with revision control makes
    4.53 +understanding patches and debugging their effects---and their
    4.54 +interplay with the code they're based on---\emph{enormously} easier.
    4.55 +Since every applied patch has an associated changeset, you can use
    4.56 +\hgcmdargs{log}{\emph{filename}} to see which changesets and patches
    4.57 +affected a file.  You can use the \hgext{bisect} extension to
    4.58 +binary-search through all changesets and applied patches to see where
    4.59 +a bug got introduced or fixed.  You can use the \hgcmd{annotate}
    4.60 +command to see which changeset or patch modified a particular line of
    4.61 +a source file.  And so on.
    4.62 +
    4.63  \section{Understanding patches}
    4.64  \label{sec:mq:patch}
    4.65  
    4.66 @@ -596,7 +621,8 @@
    4.67  
    4.68  On my old, slow laptop, I was able to
    4.69  \hgcmdargs{qpush}{\hgopt{qpush}{-a}} all 1,738 patches in 3.5 minutes,
    4.70 -and \hgcmdargs{qpop}{\hgopt{qpop}{-a}} them all in 30 seconds.  I
    4.71 +and \hgcmdargs{qpop}{\hgopt{qpop}{-a}} them all in 30 seconds.  (On a
    4.72 +newer laptop, the time to push all patches dropped to two minutes.)  I
    4.73  could \hgcmd{qrefresh} one of the biggest patches (which made 22,779
    4.74  lines of changes to 287 files) in 6.6 seconds.
    4.75  
    4.76 @@ -615,8 +641,7 @@
    4.77  patch'' that you want to end up at.  When you \hgcmd{qpush} with a
    4.78  destination specified, it will push patches until that patch is at the
    4.79  top of the applied stack.  When you \hgcmd{qpop} to a destination, MQ
    4.80 -will pop patches until the destination patch \emph{is no longer}
    4.81 -applied.
    4.82 +will pop patches until the destination patch is at the top.
    4.83  
    4.84  You can identify a destination patch using either the name of the
    4.85  patch, or by number.  If you use numeric addressing, patches are
    4.86 @@ -692,6 +717,60 @@
    4.87  or \hgcmd{strip}.  You can delete \sdirname{.hg/patches.\emph{N}} once
    4.88  you are sure that you no longer need it as a backup.
    4.89  
    4.90 +\section{Identifying patches}
    4.91 +
    4.92 +MQ commands that work with patches let you refer to a patch either by
    4.93 +using its name or by a number.  By name is obvious enough; pass the
    4.94 +name \filename{foo.patch} to \hgcmd{qpush}, for example, and it will
    4.95 +push patches until \filename{foo.patch} is applied.
    4.96 +
    4.97 +Referring to a patch by index isn't much different.  The first patch
    4.98 +printed in the output of \hgcmd{qseries} is patch zero (yes, it's one
    4.99 +of those start-at-zero counting systems); the second is patch one; and
   4.100 +so on
   4.101 +
   4.102 +MQ also makes it easy to work with patches when you are using normal
   4.103 +Mercurial commands.  Every command that accepts a changeset ID will
   4.104 +also accept the name of an applied patch.  MQ augments the tags
   4.105 +normally in the repository with an eponymous one for each applied
   4.106 +patch.  In addition, the special tags \index{tags!special tag
   4.107 +  names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag
   4.108 +  names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and
   4.109 +topmost applied patches, respectively.
   4.110 +
   4.111 +These additions to Mercurial's normal tagging capabilities make
   4.112 +dealing with patches even more of a breeze.
   4.113 +\begin{itemize}
   4.114 +\item Want to patchbomb a mailing list with your latest series of
   4.115 +  changes?
   4.116 +  \begin{codesample4}
   4.117 +    hg email qbase:qtip
   4.118 +  \end{codesample4}
   4.119 +\item Need to see all of the patches since \texttt{foo.patch} that
   4.120 +  have touched files in a subdirectory of your tree?
   4.121 +  \begin{codesample4}
   4.122 +    hg log -r foo.patch:qtip \emph{subdir}
   4.123 +  \end{codesample4}
   4.124 +\end{itemize}
   4.125 +
   4.126 +Because MQ makes the names of patches available to the rest of
   4.127 +Mercurial through its normal internal tag machinery, you don't need to
   4.128 +type in the entire name of a patch when you want to identify it by
   4.129 +name.
   4.130 +
   4.131 +\begin{figure}[ht]
   4.132 +  \interaction{mq.id.out}
   4.133 +  \caption{Using MQ's tag features to work with patches}
   4.134 +  \label{ex:mq:id}
   4.135 +\end{figure}
   4.136 +
   4.137 +Another nice consequence of representing patch names as tags is that
   4.138 +when you run the \hgcmd{log} command, it will display a patch's name
   4.139 +as a tag, simply as part of its normal output.  This makes it easy to
   4.140 +visually distinguish applied patches from underlying ``normal''
   4.141 +revisions.  Figure~\ref{ex:mq:id} shows a few normal Mercurial
   4.142 +commands in use with applied patches.
   4.143 +
   4.144  \section{Useful things to know about}
   4.145  
   4.146  There are a number of aspects of MQ usage that don't fit tidily into
   4.147 @@ -710,6 +789,7 @@
   4.148    patch stack.  If you try to do this, it will appear to succeed, but
   4.149    MQ will become confused.
   4.150  \end{itemize}
   4.151 +
   4.152  \section{Managing patches in a repository}
   4.153  
   4.154  Because MQ's \sdirname{.hg/patches} directory resides outside a
   4.155 @@ -935,6 +1015,7 @@
   4.156  counterparts for which are the normal Mercurial \hgcmd{add} and
   4.157  \hgcmd{remove} commands.  There is no MQ equivalent of the quilt
   4.158  \texttt{edit} command.
   4.159 +
   4.160  \section{MQ command reference}
   4.161  \label{sec:mq:cmdref}
   4.162  
   4.163 @@ -1038,11 +1119,11 @@
   4.164  
   4.165  This command takes an optional argument, which it uses as the name or
   4.166  index of the patch to pop to.  If given a name, it will pop patches
   4.167 -until the named patch is no longer applied.  If given a number,
   4.168 -\hgcmd{qpop} treats the number as an index into the entries in the
   4.169 -series file, counting from zero (empty lines and lines containing only
   4.170 -comments do not count).  It pops patches until the patch identified by
   4.171 -the given index is no longer applied.
   4.172 +until the named patch is the topmost applied patch.  If given a
   4.173 +number, \hgcmd{qpop} treats the number as an index into the entries in
   4.174 +the series file, counting from zero (empty lines and lines containing
   4.175 +only comments do not count).  It pops patches until the patch
   4.176 +identified by the given index is the topmost applied patch.
   4.177  
   4.178  The \hgcmd{qpop} command does not read or write patches or the
   4.179  \sfilename{series} file.  It is thus safe to \hgcmd{qpop} a patch that
   4.180 @@ -1066,6 +1147,7 @@
   4.181  
   4.182  The \hgcmd{qpop} command removes one line from the end of the
   4.183  \sfilename{status} file for each patch that it pops.
   4.184 +
   4.185  \subsection{\hgcmd{qprev}---print the name of the previous patch}
   4.186  
   4.187  The \hgcmd{qprev} command prints the name of the patch in the