1.1 --- a/.hgignore	Mon Jul 03 17:58:29 2006 -0700
     1.2 +++ b/.hgignore	Mon Jul 03 22:43:52 2006 -0700
     1.3 @@ -3,11 +3,15 @@
     1.4  
     1.5  syntax: glob
     1.6  
     1.7 +build_id.tex
     1.8  *.aux
     1.9  *.bbl
    1.10  *.bib
    1.11  *.blg
    1.12  *.dvi
    1.13 +*.idx
    1.14 +*.ilg
    1.15 +*.ind
    1.16  *.lg
    1.17  *.lo[fgt]
    1.18  *.out

     2.1 --- a/en/00book.tex	Mon Jul 03 17:58:29 2006 -0700
     2.2 +++ b/en/00book.tex	Mon Jul 03 22:43:52 2006 -0700
     2.3 @@ -1,6 +1,7 @@
     2.4  \documentclass{book}
     2.5  \usepackage{enumerate}
     2.6  \usepackage{fullpage}
     2.7 +\usepackage{makeidx}
     2.8  \usepackage{ifpdf}
     2.9  \usepackage{graphicx}
    2.10  \usepackage{newcent}
    2.11 @@ -17,6 +18,8 @@
    2.12    version 1.0 of the Open Publication License. Please refer to
    2.13    Appendix~\ref{cha:opl} for the license text.}
    2.14  
    2.15 +\makeindex
    2.16 +
    2.17  \begin{document}
    2.18  
    2.19  \maketitle
    2.20 @@ -29,13 +32,16 @@
    2.21  
    2.22  \pagenumbering{arabic}
    2.23  
    2.24 +\include{intro}
    2.25  \include{mq}
    2.26  
    2.27  \appendix
    2.28 +\include{license}
    2.29  \addcontentsline{toc}{chapter}{Bibliography}
    2.30  \bibliographystyle{alpha}
    2.31  \bibliography{99book}
    2.32 -\include{license}
    2.33 +
    2.34 +\printindex
    2.35  
    2.36  \end{document}
    2.37  

     3.1 --- a/en/99book.bib	Mon Jul 03 17:58:29 2006 -0700
     3.2 +++ b/en/99book.bib	Mon Jul 03 22:43:52 2006 -0700
     3.3 @@ -6,12 +6,24 @@
     3.4    note =         {\url{http://www.suse.de/~agruen/quilt.pdf}},
     3.5  }
     3.6  
     3.7 +@Misc{web:diffstat,
     3.8 +  author = 	 {Thomas Dickey},
     3.9 +  title = 	 {\texttt{diffstat}--make a histogram of \texttt{diff} output},
    3.10 +  note = 	 {\url{http://dickey.his.com/diffstat/diffstat.html}},
    3.11 +}
    3.12 +
    3.13  @Misc{web:quilt,
    3.14    author = 	 {Andreas Gruenbacher, Martin Quinson, Jean Delvare},
    3.15    title = 	 {Patchwork Quilt},
    3.16    note = 	 {\url{http://savannah.nongnu.org/projects/quilt}},
    3.17  }
    3.18  
    3.19 +@Misc{web:patchutils,
    3.20 +  author = 	 {Tim Waugh},
    3.21 +  title = 	 {\texttt{patchutils}--programs that operate on patch files},
    3.22 +  note = 	 {\url{http://cyberelk.net/tim/patchutils/}},
    3.23 +}
    3.24 +
    3.25  @Misc{web:rej,
    3.26    author = 	 {Chris Mason},
    3.27    title = 	 {\texttt{rej}--help solve patch rejects},

     4.1 --- a/en/99defs.tex	Mon Jul 03 17:58:29 2006 -0700
     4.2 +++ b/en/99defs.tex	Mon Jul 03 22:43:52 2006 -0700
     4.3 @@ -1,9 +1,14 @@
     4.4  \newcommand{\tildefile}[1]{\texttt{\~{}/#1}}
     4.5  \newcommand{\filename}[1]{\texttt{#1}}
     4.6 -\newcommand{\hgext}[1]{\texttt{#1}}
     4.7 -\newcommand{\hgcmd}[1]{``\texttt{hg #1}''}
     4.8 -\newcommand{\command}[1]{\texttt{#1}}
     4.9 -\newcommand{\hgcmdargs}[2]{``\texttt{hg #1 #2}''}
    4.10 +\newcommand{\dirname}[1]{\texttt{#1}}
    4.11 +\newcommand{\sfilename}[1]{\index{\texttt{#1} file}\texttt{#1}}
    4.12 +\newcommand{\sdirname}[1]{\index{\texttt{#1} directory}\texttt{#1}}
    4.13 +\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
    4.14 +\newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''}
    4.15 +\newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}}
    4.16 +\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
    4.17 +\newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}``\texttt{#2}''}
    4.18 +\newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}}
    4.19  
    4.20  \newsavebox{\notebox}
    4.21  \newenvironment{note}%

     5.1 --- a/en/Makefile	Mon Jul 03 17:58:29 2006 -0700
     5.2 +++ b/en/Makefile	Mon Jul 03 22:43:52 2006 -0700
     5.3 @@ -2,7 +2,9 @@
     5.4  	00book.tex \
     5.5  	99book.bib \
     5.6  	99defs.tex \
     5.7 -	mq.tex
     5.8 +	intro.tex \
     5.9 +	mq.tex \
    5.10 +	build_id.tex
    5.11  
    5.12  image-sources := \
    5.13  	mq-stack.svg
    5.14 @@ -26,6 +28,7 @@
    5.15  	pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
    5.16  	cp 99book.bib $(dir $@)
    5.17  	cd $(dir $@) && bibtex $(basename $(notdir $@))
    5.18 +	cd $(dir $@) && makeindex $(basename $(notdir $@))
    5.19  	pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
    5.20  	pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
    5.21  
    5.22 @@ -36,6 +39,7 @@
    5.23  	head -2 $(shell which htlatex) > $(dir $(1))/htlatex.book
    5.24  	cp 99book.bib $(dir $@)
    5.25  	echo '(cd $(dir $@) && bibtex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book
    5.26 +	echo '(cd $(dir $@) && makeindex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book
    5.27  	head -3 $(shell which htlatex) >> $(dir $(1))/htlatex.book
    5.28  	echo 'echo status $$$$' >>  $(dir $(1))/htlatex.book
    5.29  	chmod 755 $(dir $(1))/htlatex.book
    5.30 @@ -67,5 +71,11 @@
    5.31  examples/.run: $(example-sources)
    5.32  	cd examples && ./run-example
    5.33  
    5.34 +build_id.tex:
    5.35 +	echo 'in-place build' > $@
    5.36 +
    5.37 +build_id:
    5.38 +	hg id | sed -e 's/ tip\>//' > build_id.tex
    5.39 +
    5.40  clean:
    5.41 -	rm -rf html pdf *.eps *.png *.aux *.dvi *.log *.out examples/*.out examples/.run
    5.42 +	rm -rf html pdf *.eps *.png *.aux *.dvi *.log *.out examples/*.out examples/.run buildrev.tex

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/intro.tex	Mon Jul 03 22:43:52 2006 -0700
     6.3 @@ -0,0 +1,9 @@
     6.4 +\chapter{Introduction}
     6.5 +\label{chap:intro}
     6.6 +
     6.7 +XXX.
     6.8 +
     6.9 +%%% Local Variables: 
    6.10 +%%% mode: latex
    6.11 +%%% TeX-master: "00book"
    6.12 +%%% End: 

     7.1 --- a/en/mq.tex	Mon Jul 03 17:58:29 2006 -0700
     7.2 +++ b/en/mq.tex	Mon Jul 03 22:43:52 2006 -0700
     7.3 @@ -158,7 +158,7 @@
     7.4  only operate within that repository.  To get started, simply prepare
     7.5  the repository using the \hgcmd{qinit} command (see
     7.6  figure~\ref{ex:mq:qinit}).  This command creates an empty directory
     7.7 -called \filename{.hg/patches}, where MQ will keep its metadata.  As
     7.8 +called \sdirname{.hg/patches}, where MQ will keep its metadata.  As
     7.9  with many Mercurial commands, the \hgcmd{qinit} command prints nothing
    7.10  if it succeeds.
    7.11  
    7.12 @@ -178,20 +178,20 @@
    7.13  
    7.14  To begin work on a new patch, use the \hgcmd{qnew} command.  This
    7.15  command takes one argument, the name of the patch to create.  MQ will
    7.16 -use this as the name of an actual file in the \filename{.hg/patches}
    7.17 +use this as the name of an actual file in the \sdirname{.hg/patches}
    7.18  directory, as you can see in figure~\ref{ex:mq:qnew}.
    7.19  
    7.20 -Also newly present in the \filename{.hg/patches} directory are two
    7.21 -other files, \filename{series} and \filename{status}.  The
    7.22 -\filename{series} file lists all of the patches that MQ knows about
    7.23 +Also newly present in the \sdirname{.hg/patches} directory are two
    7.24 +other files, \sfilename{series} and \sfilename{status}.  The
    7.25 +\sfilename{series} file lists all of the patches that MQ knows about
    7.26  for this repository, with one patch per line.  Mercurial uses the
    7.27 -\filename{status} file for internal book-keeping; it tracks all of the
    7.28 +\sfilename{status} file for internal book-keeping; it tracks all of the
    7.29  patches that MQ has \emph{applied} in this repository.
    7.30  
    7.31  \begin{note}
    7.32 -  You may sometimes want to edit the \filename{series} file by hand;
    7.33 +  You may sometimes want to edit the \sfilename{series} file by hand;
    7.34    for example, to change the sequence in which some patches are
    7.35 -  applied.  However, manually editing the \filename{status} file is
    7.36 +  applied.  However, manually editing the \sfilename{status} file is
    7.37    almost always a bad idea, as it's easy to corrupt MQ's idea of what
    7.38    is happening.
    7.39  \end{note}
    7.40 @@ -322,9 +322,10 @@
    7.41  \section{Mercurial Queues and GNU patch}
    7.42  \label{sec:mq:patch}
    7.43  
    7.44 -MQ uses the GNU \command{patch} command to apply patches.  It will
    7.45 -help you to understand the data that MQ and \command{patch} work with,
    7.46 -and a few aspects of how \command{patch} operates.
    7.47 +MQ uses the GNU \command{patch} command to apply patches.  Because MQ
    7.48 +doesn't hide its patch-oriented nature, it is helpful to understand
    7.49 +the data that MQ and \command{patch} work with, and a few aspects of
    7.50 +how \command{patch} operates.
    7.51  
    7.52  The \command{diff} command generates a list of modifications by
    7.53  comparing two files.  The \command{patch} command applies a list of
    7.54 @@ -381,8 +382,8 @@
    7.55  When neither of these techniques works, \command{patch} prints a
    7.56  message saying that the hunk in question was rejected.  It saves
    7.57  rejected hunks to a file with the same name, and an added
    7.58 -\filename{.rej} extension.  It also saves an unmodified copy of the
    7.59 -file with a \filename{.orig} extension; the copy of the file without
    7.60 +\sfilename{.rej} extension.  It also saves an unmodified copy of the
    7.61 +file with a \sfilename{.orig} extension; the copy of the file without
    7.62  any extensions will contain any changes made by hunks that \emph{did}
    7.63  apply cleanly.  If you have a patch that modifies \filename{foo} with
    7.64  six hunks, and one of them fails to apply, you will have: an
    7.65 @@ -413,7 +414,7 @@
    7.66  \subsection{Handling rejection}
    7.67  
    7.68  If \hgcmd{qpush} fails to apply a patch, it will print an error
    7.69 -message and exit.  If it has left \filename{.rej} files behind, it is
    7.70 +message and exit.  If it has left \sfilename{.rej} files behind, it is
    7.71  usually best to fix up the rejected hunks before you push more patches
    7.72  or do any further work.
    7.73  
    7.74 @@ -422,13 +423,12 @@
    7.75  Mercurial Queues can help; see section~\ref{seq:mq:merge} for details.
    7.76  
    7.77  Unfortunately, there aren't any great techniques for dealing with
    7.78 -rejected hunks.  Most often, you'll need to view the \filename{.rej}
    7.79 +rejected hunks.  Most often, you'll need to view the \sfilename{.rej}
    7.80  file and edit the target file, applying the rejected hunks by hand.
    7.81  
    7.82 -If you're feeling adventurous, Neil Brown, an Australian Linux kernel
    7.83 -hacker, has written a tool called \command{wiggle}~\cite{web:wiggle},
    7.84 -which is more vigorous than \command{patch} in its attempts to make a
    7.85 -patch apply.
    7.86 +If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
    7.87 +wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
    7.88 +vigorous than \command{patch} in its attempts to make a patch apply.
    7.89  
    7.90  Another Linux kernel hacker, Chris Mason (the author of Mercurial
    7.91  Queues), wrote a similar tool called \command{rej}~\cite{web:rej},
    7.92 @@ -453,6 +453,93 @@
    7.93  
    7.94  XXX.
    7.95  
    7.96 +\section{Managing patches in a repository}
    7.97 +
    7.98 +Because MQ's \sdirname{.hg/patches} directory resides outside a
    7.99 +Mercurial repository's working directory, the ``underlying'' Mercurial
   7.100 +repository knows nothing about the management or presence of patches.
   7.101 +
   7.102 +This presents the interesting possibility of managing the contents of
   7.103 +the patch directory as a Mercurial repository in its own right.  This
   7.104 +can be a useful way to work.  For example, you can work on a patch for
   7.105 +a while, \hgcmd{qrefresh} it, then \hgcmd{commit} the current state of
   7.106 +the patch.  This lets you ``roll back'' to that version of the patch
   7.107 +later on.
   7.108 +
   7.109 +In addition, you can then share different versions of the same patch
   7.110 +stack among multiple underlying repositories.  I use this when I am
   7.111 +developing a Linux kernel feature.  I have a pristine copy of my
   7.112 +kernel sources for each of several CPU architectures, and a cloned
   7.113 +repository under each that contains the patches I am working on.  When
   7.114 +I want to test a change on a different architecture, I push my current
   7.115 +patches to the patch repository associated with that kernel tree, pop
   7.116 +and push all of my patches, and build and test that kernel.
   7.117 +
   7.118 +Managing patches in a repository makes it possible for multiple
   7.119 +developers to work on the same patch series without colliding with
   7.120 +each other, all on top of an underlying source base that they may or
   7.121 +may not control.
   7.122 +
   7.123 +\subsection{MQ support for managing a patch repository}
   7.124 +
   7.125 +MQ helps you to work with the \sdirname{.hg/patches} directory as a
   7.126 +repository; when you prepare a repository for working with patches
   7.127 +using \hgcmdargs{qinit}, you can pass the \hgopt{qinit}{-c} option to
   7.128 +create the \sdirname{.hg/patches} directory as a Mercurial repository.
   7.129 +
   7.130 +\begin{note}
   7.131 +  If you forget to use the \hgopt{qinit}{-c} option, you can simply go
   7.132 +  into the \sdirname{.hg/patches} directory at any time and run
   7.133 +  \hgcmd{init}.  Don't forget to add an entry for the
   7.134 +  \filename{status} file to the \filename{.hgignore} file, though
   7.135 +  (\hgopt{qinit}{-c} does this for you automatically); you
   7.136 +  \emph{really} don't want to manage the \filename{status} file.
   7.137 +\end{note}
   7.138 +
   7.139 +As a convenience, if MQ notices that the \dirname{.hg/patches}
   7.140 +directory is a repository, it will automatically \hgcmd{add} every
   7.141 +patch that you create and import.
   7.142 +
   7.143 +Finally, MQ provides a shortcut command, \hgcmd{qcommit}, that runs
   7.144 +\hgcmd{commit} in the \sdirname{.hg/patches} directory.  This saves
   7.145 +some cumbersome typing.
   7.146 +
   7.147 +\subsection{A few things to watch out for}
   7.148 +
   7.149 +MQ's support for working with a repository full of patches is limited
   7.150 +in a few small respects.
   7.151 +
   7.152 +MQ cannot automatically detect changes that you make to the patch
   7.153 +directory.  If you \hgcmd{pull}, manually edit, or \hgcmd{update}
   7.154 +changes to patches or the \sfilename{series} file, you will have to
   7.155 +\hgcmdargs{qpop}{-a} and then \hgcmdargs{qpush}{-a} in the underlying
   7.156 +repository to see those changes show up there.  If you forget to do
   7.157 +this, you can confuse MQ's idea of which patches are applied.
   7.158 +
   7.159 +\section{Commands for working with patches}
   7.160 +
   7.161 +Once you've been working with patches for a while, you'll find
   7.162 +yourself hungry for tools that will help you to understand and
   7.163 +manipulate the patches you're dealing with.
   7.164 +
   7.165 +The \command{diffstat} command~\cite{web:diffstat} generates a
   7.166 +histogram of the modifications made to each file in a patch.  It
   7.167 +provides a good way to ``get a sense of'' a patch--which files it
   7.168 +affects, and how much change it introduces to each file and as a
   7.169 +whole.  (I find that it's a good idea to use \command{diffstat}'s
   7.170 +\texttt{-p} option as a matter of course, as otherwise it will try to
   7.171 +do clever things with prefixes of file names that inevitably confuse
   7.172 +at least me.)
   7.173 +
   7.174 +The \package{patchutils} package~\cite{web:patchutils} is invaluable.
   7.175 +It provides a set of small utilities that follow the ``Unix
   7.176 +philosophy;'' each does one useful thing with a patch.  The
   7.177 +\package{patchutils} command I use most is \command{filterdiff}, which
   7.178 +extracts subsets from a patch file.  For example, given a patch that
   7.179 +modifies hundreds of files across dozens of directories, a single
   7.180 +invocation of \command{filterdiff} can generate a smaller patch that
   7.181 +only touches files whose names match a particular glob pattern.
   7.182 +
   7.183  %%% Local Variables: 
   7.184  %%% mode: latex
   7.185  %%% TeX-master: "00book"