1.1 --- a/en/00book.tex	Sun Jul 09 23:18:39 2006 -0700
     1.2 +++ b/en/00book.tex	Tue Jul 11 23:48:25 2006 -0700
     1.3 @@ -1,3 +1,5 @@
     1.4 +% The use of oneside here is a temporary hack; \marginpar entries
     1.5 +% don't show up on odd pages of PDF output without it.  Sigh.
     1.6  \documentclass[oneside]{book}
     1.7  \usepackage{enumerate}
     1.8  \usepackage{fullpage}
     1.9 @@ -32,6 +34,7 @@
    1.10  
    1.11  \pagenumbering{arabic}
    1.12  
    1.13 +\include{preface}
    1.14  \include{intro}
    1.15  \include{mq}
    1.16  

     2.1 --- a/en/99defs.tex	Sun Jul 09 23:18:39 2006 -0700
     2.2 +++ b/en/99defs.tex	Tue Jul 11 23:48:25 2006 -0700
     2.3 @@ -1,3 +1,4 @@
     2.4 +\newcommand{\bug}[1]{\index{Mercurial issue!no.~#1}\href{http://www.selenic.com/mercurial/bts/issue#1}{Mercurial issue no.~#1}}
     2.5  \newcommand{\tildefile}[1]{\texttt{\~{}/#1}}
     2.6  \newcommand{\filename}[1]{\texttt{#1}}
     2.7  \newcommand{\dirname}[1]{\texttt{#1}}
     2.8 @@ -6,7 +7,7 @@
     2.9  \newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
    2.10  \newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''}
    2.11  \newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}}
    2.12 -\newcommand{\cmdargs}[2]{\index{\texttt{#1} command}\texttt{#1 #2}}
    2.13 +\newcommand{\cmdargs}[2]{\index{\texttt{#1} command}``\texttt{#1 #2}''}
    2.14  \newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
    2.15  \newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
    2.16  \newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}

     3.1 --- a/en/Makefile	Sun Jul 09 23:18:39 2006 -0700
     3.2 +++ b/en/Makefile	Tue Jul 11 23:48:25 2006 -0700
     3.3 @@ -6,6 +6,7 @@
     3.4  	00book.tex \
     3.5  	99book.bib \
     3.6  	99defs.tex \
     3.7 +	preface.tex \
     3.8  	intro.tex \
     3.9  	mq.tex \
    3.10  	build_id.tex
    3.11 @@ -38,6 +39,7 @@
    3.12  	cd $(dir $@) && makeindex $(basename $(notdir $@))
    3.13  	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
    3.14  	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
    3.15 +	if grep 'Reference.*undefined' $(@:.pdf=.log); then exit 1; fi
    3.16  endef
    3.17  
    3.18  pdf/hgbook.pdf: $(sources) $(image-sources:%.svg=%_pdf.png) examples

     4.1 --- a/en/mq.tex	Sun Jul 09 23:18:39 2006 -0700
     4.2 +++ b/en/mq.tex	Tue Jul 11 23:48:25 2006 -0700
     4.3 @@ -128,6 +128,7 @@
     4.4  where you cannot use Mercurial and MQ.
     4.5  
     4.6  \section{Understanding patches}
     4.7 +\label{sec:mq:patch}
     4.8  
     4.9  Because MQ doesn't hide its patch-oriented nature, it is helpful to
    4.10  understand what patches are, and a little about the tools that work
    4.11 @@ -179,7 +180,7 @@
    4.12  deletion and one insertion.
    4.13  
    4.14  We will return to ome of the more subtle aspects of patches later (in
    4.15 -section~\ref{ex:mq:adv-patch}), but you should have enough information
    4.16 +section~\ref{sec:mq:adv-patch}), but you should have enough information
    4.17  now to use MQ.
    4.18  
    4.19  \section{Getting started with Mercurial Queues}
    4.20 @@ -380,8 +381,58 @@
    4.21  \label{sec:mq:adv-patch}
    4.22  
    4.23  MQ uses the GNU \command{patch} command to apply patches, so it's
    4.24 -helpful to know about a few more detailed aspects of how
    4.25 -\command{patch} works.
    4.26 +helpful to know a few more detailed aspects of how \command{patch}
    4.27 +works, and about patches themselves.
    4.28 +
    4.29 +\subsection{The strip count}
    4.30 +
    4.31 +If you look at the file headers in a patch, you will notice that the
    4.32 +pathnames usually have an extra component on the front that isn't
    4.33 +present in the actual path name.  This is a holdover from the way that
    4.34 +people used to generate patches (people still do this, but it's
    4.35 +somewhat rare with modern revision control tools).  
    4.36 +
    4.37 +Alice would unpack a tarball, edit her files, then decide that she
    4.38 +wanted to create a patch.  So she'd rename her working directory,
    4.39 +unpack the tarball again (hence the need for the rename), and use the
    4.40 +\cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to
    4.41 +recursively generate a patch between the unmodified directory and the
    4.42 +modified one.  The result would be that the name of the unmodified
    4.43 +directory would be at the front of the left-hand path in every file
    4.44 +header, and the name of the modified directory would be at the front
    4.45 +of the right-hand path.
    4.46 +
    4.47 +Since someone receiving a patch from the Alices of the net would be
    4.48 +unlikely to have unmodified and modified directories with exactly the
    4.49 +same names, the \command{patch} command has a \cmdopt{patch}{-p}
    4.50 +option that indicates the number of leading path name components to
    4.51 +strip when trying to apply a patch.  This number is called the
    4.52 +\emph{strip count}.
    4.53 +
    4.54 +An option of ``\texttt{-p1}'' means ``use a strip count of one''.  If
    4.55 +\command{patch} sees a file name \filename{foo/bar/baz} in a file
    4.56 +header, it will strip \filename{foo} and try to patch a file named
    4.57 +\filename{bar/baz}.  (Strictly speaking, the strip count refers to the
    4.58 +number of \emph{path separators} (and the components that go with them
    4.59 +) to strip.  A strip count of one will turn \filename{foo/bar} into
    4.60 +\filename{bar}, but \filename{/foo/bar} (notice the extra leading
    4.61 +slash) into \filename{foo/bar}.)
    4.62 +
    4.63 +The ``standard'' strip count for patches is one; almost all patches
    4.64 +contain one leading path name component that needs to be stripped.
    4.65 +Mercurial's \hgcmd{diff} command generates path names in this form,
    4.66 +and the \hgcmd{import} command and MQ expect patches to have a strip
    4.67 +count of one.
    4.68 +
    4.69 +If you receive a patch from someone that you want to add to your patch
    4.70 +queue, and the patch needs a strip count other than one, you cannot
    4.71 +just \hgcmd{qimport} the patch, because \hgcmd{qimport} does not yet
    4.72 +have a \texttt{-p} option (see~\bug{311}).  Your best bet is to
    4.73 +\hgcmd{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}}
    4.74 +to apply their patch, followed by \hgcmd{addremove} to pick up any
    4.75 +files added or removed by the patch, followed by \hgcmd{qrefresh}.
    4.76 +This complexity may become unnecessary; see~\bug{311} for details.
    4.77 +\subsection{Strategies for applying a patch}
    4.78  
    4.79  When \command{patch} applies a hunk, it tries a handful of
    4.80  successively less accurate strategies to try to make the hunk apply.
    4.81 @@ -604,6 +655,24 @@
    4.82  or \hgcmd{strip}.  You can delete \sdirname{.hg/patches.\emph{N}} once
    4.83  you are sure that you no longer need it as a backup.
    4.84  
    4.85 +\section{Useful things to know about}
    4.86 +
    4.87 +There are a number of aspects of MQ usage that don't fit tidily into
    4.88 +sections of their own, but that are good to know.  Here they are, in
    4.89 +one place.
    4.90 +
    4.91 +\begin{itemize}
    4.92 +\item Normally, when you \hgcmd{qpop} a patch and \hgcmd{qpush} it
    4.93 +  again, the changeset that represents the patch after the pop/push
    4.94 +  will have a \emph{different identity} than the changeset that
    4.95 +  represented the hash beforehand.  See section~\ref{sec:mq:cmd:qpush}
    4.96 +  for information as to why this is.
    4.97 +\item It's not a good idea to \hgcmd{merge} changes from another
    4.98 +  branch with a patch changeset, at least if you want to maintain the
    4.99 +  ``patchiness'' of that changeset and changesets below it on the
   4.100 +  patch stack.  If you try to do this, it will appear to succeed, but
   4.101 +  MQ will become confused.
   4.102 +\end{itemize}
   4.103  \section{Managing patches in a repository}
   4.104  
   4.105  Because MQ's \sdirname{.hg/patches} directory resides outside a
   4.106 @@ -617,14 +686,14 @@
   4.107  the patch.  This lets you ``roll back'' to that version of the patch
   4.108  later on.
   4.109  
   4.110 -In addition, you can then share different versions of the same patch
   4.111 -stack among multiple underlying repositories.  I use this when I am
   4.112 -developing a Linux kernel feature.  I have a pristine copy of my
   4.113 -kernel sources for each of several CPU architectures, and a cloned
   4.114 -repository under each that contains the patches I am working on.  When
   4.115 -I want to test a change on a different architecture, I push my current
   4.116 -patches to the patch repository associated with that kernel tree, pop
   4.117 -and push all of my patches, and build and test that kernel.
   4.118 +You can then share different versions of the same patch stack among
   4.119 +multiple underlying repositories.  I use this when I am developing a
   4.120 +Linux kernel feature.  I have a pristine copy of my kernel sources for
   4.121 +each of several CPU architectures, and a cloned repository under each
   4.122 +that contains the patches I am working on.  When I want to test a
   4.123 +change on a different architecture, I push my current patches to the
   4.124 +patch repository associated with that kernel tree, pop and push all of
   4.125 +my patches, and build and test that kernel.
   4.126  
   4.127  Managing patches in a repository makes it possible for multiple
   4.128  developers to work on the same patch series without colliding with
   4.129 @@ -669,7 +738,7 @@
   4.130  see those changes show up there.  If you forget to do this, you can
   4.131  confuse MQ's idea of which patches are applied.
   4.132  
   4.133 -\section{Commands for working with patches}
   4.134 +\section{Third party tools for working with patches}
   4.135  \label{sec:mq:tools}
   4.136  
   4.137  Once you've been working with patches for a while, you'll find
   4.138 @@ -801,9 +870,11 @@
   4.139  
   4.140  This command prints three different kinds of number:
   4.141  \begin{itemize}
   4.142 -\item a \emph{file number} to identify each file modified in the patch;
   4.143 -\item the line number within a modified file that a hunk starts at; and
   4.144 -\item a \emph{hunk number} to identify that hunk.
   4.145 +\item (in the first column) a \emph{file number} to identify each file
   4.146 +  modified in the patch;
   4.147 +\item (on the next line, indented) the line number within a modified
   4.148 +  file where a hunk starts; and
   4.149 +\item (on the same line) a \emph{hunk number} to identify that hunk.
   4.150  \end{itemize}
   4.151  
   4.152  You'll have to use some visual inspection, and reading of the patch,
   4.153 @@ -815,6 +886,18 @@
   4.154  Once you have this hunk, you can concatenate it onto the end of your
   4.155  destination patch and continue with the remainder of
   4.156  section~\ref{sec:mq:combine}.
   4.157 +
   4.158 +\section{Differences between quilt and MQ}
   4.159 +
   4.160 +If you are already familiar with quilt, MQ provides a similar command
   4.161 +set.  There are a few differences in the way that it works.
   4.162 +
   4.163 +You will already have noticed that most quilt commands have MQ
   4.164 +counterparts that simply begin with a ``\texttt{q}''.  The exceptions
   4.165 +are quilt's \texttt{add} and \texttt{remove} commands, the
   4.166 +counterparts for which are the normal Mercurial \hgcmd{add} and
   4.167 +\hgcmd{remove} commands.  There is no MQ equivalent of the quilt
   4.168 +\texttt{edit} command.
   4.169  \section{MQ command reference}
   4.170  \label{sec:mq:cmdref}
   4.171  
   4.172 @@ -953,6 +1036,7 @@
   4.173  This will become the topmost applied patch if you run \hgcmd{qpop}.
   4.174  
   4.175  \subsection{\hgcmd{qpush}---push patches onto the stack}
   4.176 +\label{sec:mq:cmd:qpush}
   4.177  
   4.178  The \hgcmd{qpush} command adds patches onto the applied stack.  By
   4.179  default, it adds only one patch.
   4.180 @@ -960,7 +1044,7 @@
   4.181  This command creates a new changeset to represent each applied patch,
   4.182  and updates the working directory to apply the effects of the patches.
   4.183  
   4.184 -The data used when creating a changeset are as follows:
   4.185 +The default data used when creating a changeset are as follows:
   4.186  \begin{itemize}
   4.187  \item The commit date and time zone are the current date and time
   4.188    zone.  Because these data are used to compute the identity of a
   4.189 @@ -973,6 +1057,8 @@
   4.190    before the first diff header.  If there is no such text, a default
   4.191    commit message is used that identifies the name of the patch.
   4.192  \end{itemize}
   4.193 +If a patch contains a Mercurial patch header (XXX add link), the
   4.194 +information in the patch header overrides these defaults.
   4.195  
   4.196  Options:
   4.197  \begin{itemize}
   4.198 @@ -1016,15 +1102,87 @@
   4.199  changeset to differ from the previous changeset that identified the
   4.200  patch.
   4.201  
   4.202 +\subsection{\hgcmd{qrestore}---restore saved queue state}
   4.203 +
   4.204 +XXX No idea what this does.
   4.205 +
   4.206 +\subsection{\hgcmd{qsave}---save current queue state}
   4.207 +
   4.208 +XXX Likewise.
   4.209 +
   4.210 +\subsection{\hgcmd{qseries}---print the entire patch series}
   4.211 +
   4.212 +The \hgcmd{qseries} command prints the entire patch series from the
   4.213 +\sfilename{series} file.  It prints only patch names, not empty lines
   4.214 +or comments.  It prints in order from first to be applied to last.
   4.215 +
   4.216 +\subsection{\hgcmd{qtop}---print the name of the current patch}
   4.217 +
   4.218 +The \hgcmd{qtop} prints the name of the topmost currently applied
   4.219 +patch.
   4.220 +
   4.221 +\subsection{\hgcmd{qunapplied}---print patches not yet applied}
   4.222 +
   4.223 +The \hgcmd{qunapplied} command prints the names of patches from the
   4.224 +\sfilename{series} file that are not yet applied.  It prints them in
   4.225 +order from the next patch that will be pushed to the last.
   4.226 +
   4.227 +\subsection{\hgcmd{qversion}}
   4.228 +
   4.229 +The \hgcmd{qversion} command prints the version of MQ that is in use.
   4.230 +
   4.231 +\subsection{\hgcmd{strip}---remove a revision and descendants}
   4.232 +
   4.233 +The \hgcmd{strip} command removes a revision, and all of its
   4.234 +descendants, from the repository.  It undoes the effects of the
   4.235 +removed revisions from the repository, and updates the working
   4.236 +directory to the first parent of the removed revision.
   4.237 +
   4.238 +The \hgcmd{strip} command saves a backup of the removed changesets in
   4.239 +a bundle, so that they can be reapplied if removed in error.
   4.240 +
   4.241 +Options:
   4.242 +\begin{itemize}
   4.243 +\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed
   4.244 +  with the stripped changesets in the backup bundle.
   4.245 +\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all
   4.246 +  heads. XXX This should be renamed, and use \texttt{-f} to strip revs
   4.247 +  when there are pending changes.
   4.248 +\item[\hgopt{strip}{-n}] Do not save a backup bundle.
   4.249 +\end{itemize}
   4.250  \section{MQ file reference}
   4.251  
   4.252  
   4.253  \subsection{The \sfilename{series} file}
   4.254  
   4.255 -
   4.256 +The \sfilename{series} file contains a list of the names of all
   4.257 +patches that MQ can apply.  It is represented as a list of names, with
   4.258 +one name saved per line.  Leading and trailing white space in each
   4.259 +line are ignored.
   4.260 +
   4.261 +Lines may contain comments.  A comment begins with the ``\texttt{\#}''
   4.262 +character, and extends to the end of the line.  Empty lines, and lines
   4.263 +that contain only comments, are ignored.
   4.264 +
   4.265 +You will often need to edit the \sfilename{series} file by hand, hence
   4.266 +the support for comments and empty lines noted above.  For example,
   4.267 +you can comment out a patch temporarily, and \hgcmd{qpush} will skip
   4.268 +over that patch when applying patches.  You can also change the order
   4.269 +in which patches are applied by reordering their entries in the
   4.270 +\sfilename{series} file.
   4.271 +
   4.272 +Placing the \sfilename{series} file under revision control is also
   4.273 +supported; it is a good idea to place all of the patches that it
   4.274 +refers to under revision control, as well.  If you create a patch
   4.275 +directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this
   4.276 +will be done for you automatically.
   4.277  \subsection{The \sfilename{status} file}
   4.278  
   4.279 -
   4.280 +The \sfilename{status} file contains the names and changeset hashes of
   4.281 +all patches that MQ currently has applied.  Unlike the
   4.282 +\sfilename{series} file, this file is not intended for editing.  You
   4.283 +should not place this file under revision control, or modify it in any
   4.284 +way.  It is used by MQ strictly for internal book-keeping.
   4.285  
   4.286  %%% Local Variables: 
   4.287  %%% mode: latex

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/preface.tex	Tue Jul 11 23:48:25 2006 -0700
     5.3 @@ -0,0 +1,34 @@
     5.4 +\chapter*{Preface}
     5.5 +\addcontentsline{toc}{chapter}{Preface}
     5.6 +\label{chap:preface}
     5.7 +
     5.8 +Distributed revision control is a relatively new territory, and has
     5.9 +thus far grown due to people's willingness to strike out into
    5.10 +ill-charted territory.
    5.11 +
    5.12 +I am writing a book about distributed revision control because I
    5.13 +believe that it is an important subject that deserves a field guide.
    5.14 +I chose to write about Mercurial because it is the easiest tool to
    5.15 +learn the terrain with, and yet it scales to the demands of real,
    5.16 +challenging environments where many other revision control tools fail.
    5.17 +
    5.18 +\section{This book is a work in progress}
    5.19 +
    5.20 +I am releasing this book while I am still writing it, in the hope that
    5.21 +it will prove useful to others.  I also hope that readers will
    5.22 +contribute as they see fit.
    5.23 +
    5.24 +\section{Colophon---this book is Free}
    5.25 +
    5.26 +This book is licensed under the Open Publication License, and is
    5.27 +produced entirely using Free Software tools.  It is typeset with
    5.28 +\LaTeX{}; illustrations are drawn and rendered with
    5.29 +\href{http://www.inkscape.org/}{Inkscape}.
    5.30 +
    5.31 +The complete source code for this book is published as a Mercurial
    5.32 +repository, at \url{http://hg.serpentine.com/mercurial/book}.
    5.33 +
    5.34 +%%% Local Variables: 
    5.35 +%%% mode: latex
    5.36 +%%% TeX-master: "00book"
    5.37 +%%% End: