1.1 --- a/en/99book.bib	Mon Jul 03 17:12:11 2006 -0700
     1.2 +++ b/en/99book.bib	Mon Jul 03 17:58:29 2006 -0700
     1.3 @@ -1,6 +1,6 @@
     1.4  @Unpublished{gruenbacher:2005,
     1.5    author = 	 {Andreas Gruenbacher},
     1.6 -  title = 	 {How To Survive With Many Patches (Introduction to Quilt)},
     1.7 +  title = 	 {How To Survive With Many Patches (Introduction to \texttt{quilt})},
     1.8    year = 	 {2005},
     1.9    month = 	 {June},
    1.10    note =         {\url{http://www.suse.de/~agruen/quilt.pdf}},
    1.11 @@ -12,3 +12,15 @@
    1.12    note = 	 {\url{http://savannah.nongnu.org/projects/quilt}},
    1.13  }
    1.14  
    1.15 +@Misc{web:rej,
    1.16 +  author = 	 {Chris Mason},
    1.17 +  title = 	 {\texttt{rej}--help solve patch rejects},
    1.18 +  note = 	 {\url{ftp://ftp.suse.com/pub/people/mason/rej/}},
    1.19 +}
    1.20 +
    1.21 +@Misc{web:wiggle,
    1.22 +  author = 	 {Neil Brown},
    1.23 +  title = 	 {\texttt{wiggle}--apply conflicting patches},
    1.24 +  note = 	 {\url{http://cgi.cse.unsw.edu.au/~neilb/source/wiggle/}},
    1.25 +}
    1.26 +

     2.1 --- a/en/mq.tex	Mon Jul 03 17:12:11 2006 -0700
     2.2 +++ b/en/mq.tex	Mon Jul 03 17:58:29 2006 -0700
     2.3 @@ -29,7 +29,8 @@
     2.4  they will build properly in their environments.
     2.5  
     2.6  When you have few changes to maintain, it is easy to manage a single
     2.7 -patch using the standard \texttt{diff} and \texttt{patch} programs.
     2.8 +patch using the standard \texttt{diff} and \texttt{patch} programs
     2.9 +(see section~\ref{sec:mq:patch} for a discussion of these tools).
    2.10  Once the number of changes grows, it starts to makes sense to maintain
    2.11  patches as discrete ``chunks of work,'' so that for example a single
    2.12  patch will contain only one bug fix (the patch might modify several
    2.13 @@ -319,32 +320,43 @@
    2.14  patch to continue where you left off.
    2.15  
    2.16  \section{Mercurial Queues and GNU patch}
    2.17 +\label{sec:mq:patch}
    2.18  
    2.19  MQ uses the GNU \command{patch} command to apply patches.  It will
    2.20  help you to understand the data that MQ and \command{patch} work with,
    2.21  and a few aspects of how \command{patch} operates.
    2.22  
    2.23 +The \command{diff} command generates a list of modifications by
    2.24 +comparing two files.  The \command{patch} command applies a list of
    2.25 +modifications to a file.  The kinds of files that \command{diff} and
    2.26 +\command{patch} work with are referred to as both ``diffs'' and
    2.27 +``patches;'' there is no difference between a diff and a patch.
    2.28 +
    2.29  A patch file can start with arbitrary text; MQ uses this text as the
    2.30  commit message when creating changesets.  It treats the first line
    2.31  that starts with the string ``\texttt{diff~-}'' as the separator
    2.32  between header and content.
    2.33  
    2.34 -MQ works with \emph{unified diffs} (\command{patch} can accept several
    2.35 -other kinds of diff, but MQ doesn't).  A unified diff contains two
    2.36 +MQ works with \emph{unified} diffs (\command{patch} can accept several
    2.37 +other diff formats, but MQ doesn't).  A unified diff contains two
    2.38  kinds of header.  The \emph{file header} describes the file being
    2.39  modified; it contains the name of the file to modify.  When
    2.40 -\command{patch} sees a new file header, it looks for a file of that
    2.41 +\command{patch} sees a new file header, it looks for a file with that
    2.42  name to start modifying.
    2.43  
    2.44 -After the file header come a series of \emph{hunks}.  Each hunk starts
    2.45 -with a header; this identifies the range of line numbers within the
    2.46 -file that the hunk should modify.  Following the header, a hunk starts
    2.47 -and ends with a few lines of text from the unmodified file; these are
    2.48 -called the \emph{context} for the hunk.  Each unmodified line begins
    2.49 -with a space characters.  Within the hunk, a line that begins with
    2.50 -``\texttt{-}'' means ``remove this line,'' while a line that begins
    2.51 -with ``\texttt{+}'' means ``insert this line.''  For example, a line
    2.52 -that is modified is represented by one deletion and one insertion.
    2.53 +After the file header comes a series of \emph{hunks}.  Each hunk
    2.54 +starts with a header; this identifies the range of line numbers within
    2.55 +the file that the hunk should modify.  Following the header, a hunk
    2.56 +starts and ends with a few (usually three) lines of text from the
    2.57 +unmodified file; these are called the \emph{context} for the hunk.
    2.58 +Each unmodified line begins with a space characters.  Within the hunk,
    2.59 +a line that begins with ``\texttt{-}'' means ``remove this line,''
    2.60 +while a line that begins with ``\texttt{+}'' means ``insert this
    2.61 +line.''  For example, a line that is modified is represented by one
    2.62 +deletion and one insertion.
    2.63 +
    2.64 +The \command{diff} command runs hunks together when there's not enough
    2.65 +context between modifications to justify
    2.66  
    2.67  When \command{patch} applies a hunk, it tries a handful of
    2.68  successively less accurate strategies to try to make the hunk apply.
    2.69 @@ -369,8 +381,14 @@
    2.70  When neither of these techniques works, \command{patch} prints a
    2.71  message saying that the hunk in question was rejected.  It saves
    2.72  rejected hunks to a file with the same name, and an added
    2.73 -\filename{.rej} extension.  If \hgcmd{qpush} fails to apply a patch,
    2.74 -it will print an error message and exit.
    2.75 +\filename{.rej} extension.  It also saves an unmodified copy of the
    2.76 +file with a \filename{.orig} extension; the copy of the file without
    2.77 +any extensions will contain any changes made by hunks that \emph{did}
    2.78 +apply cleanly.  If you have a patch that modifies \filename{foo} with
    2.79 +six hunks, and one of them fails to apply, you will have: an
    2.80 +unmodified \filename{foo.orig}, a \filename{foo.rej} containing one
    2.81 +hunk, and \filename{foo}, containing the changes made by the five
    2.82 +successful five hunks.
    2.83  
    2.84  \subsection{Beware the fuzz}
    2.85  
    2.86 @@ -392,6 +410,48 @@
    2.87  apply with some fuzz, provided you've verified the results of the
    2.88  patching process in such cases.
    2.89  
    2.90 +\subsection{Handling rejection}
    2.91 +
    2.92 +If \hgcmd{qpush} fails to apply a patch, it will print an error
    2.93 +message and exit.  If it has left \filename{.rej} files behind, it is
    2.94 +usually best to fix up the rejected hunks before you push more patches
    2.95 +or do any further work.
    2.96 +
    2.97 +If your patch \emph{used to} apply cleanly, and no longer does because
    2.98 +you've changed the underlying code that your patches are based on,
    2.99 +Mercurial Queues can help; see section~\ref{seq:mq:merge} for details.
   2.100 +
   2.101 +Unfortunately, there aren't any great techniques for dealing with
   2.102 +rejected hunks.  Most often, you'll need to view the \filename{.rej}
   2.103 +file and edit the target file, applying the rejected hunks by hand.
   2.104 +
   2.105 +If you're feeling adventurous, Neil Brown, an Australian Linux kernel
   2.106 +hacker, has written a tool called \command{wiggle}~\cite{web:wiggle},
   2.107 +which is more vigorous than \command{patch} in its attempts to make a
   2.108 +patch apply.
   2.109 +
   2.110 +Another Linux kernel hacker, Chris Mason (the author of Mercurial
   2.111 +Queues), wrote a similar tool called \command{rej}~\cite{web:rej},
   2.112 +which takes a simple approach to automating the application of hunks
   2.113 +rejected by \command{patch}.  \command{rej} can help with four common
   2.114 +reasons that a hunk may be rejected:
   2.115 +
   2.116 +\begin{itemize}
   2.117 +\item The context in the middle of a hunk has changed.
   2.118 +\item A hunk is missing some context at the beginning or end.
   2.119 +\item A large hunk might apply better--either entirely or in part--if
   2.120 +  it was broken up into smaller hunks.
   2.121 +\item A hunk removes lines with slightly different content than those
   2.122 +  currently present in the file.
   2.123 +\end{itemize}
   2.124 +
   2.125 +If you use \command{wiggle} or \command{rej}, you should be doubly
   2.126 +careful to check your results when you're done.
   2.127 +
   2.128 +\section{Updating your patches when the underlying code changes}
   2.129 +\label{sec:mq:merge}
   2.130 +
   2.131 +XXX.
   2.132  
   2.133  %%% Local Variables: 
   2.134  %%% mode: latex