Commits

Bryan O'Sullivan committed 8145442

Progress on a few fronts, mainly indexing and MQ chapter content

  • Participants
  • Parent commits b8ac9f3

Comments (0)

Files changed (7)

 
 syntax: glob
 
+build_id.tex
 *.aux
 *.bbl
 *.bib
 *.blg
 *.dvi
+*.idx
+*.ilg
+*.ind
 *.lg
 *.lo[fgt]
 *.out
 \documentclass{book}
 \usepackage{enumerate}
 \usepackage{fullpage}
+\usepackage{makeidx}
 \usepackage{ifpdf}
 \usepackage{graphicx}
 \usepackage{newcent}
   version 1.0 of the Open Publication License. Please refer to
   Appendix~\ref{cha:opl} for the license text.}
 
+\makeindex
+
 \begin{document}
 
 \maketitle
 
 \pagenumbering{arabic}
 
+\include{intro}
 \include{mq}
 
 \appendix
+\include{license}
 \addcontentsline{toc}{chapter}{Bibliography}
 \bibliographystyle{alpha}
 \bibliography{99book}
-\include{license}
+
+\printindex
 
 \end{document}
 
   note =         {\url{http://www.suse.de/~agruen/quilt.pdf}},
 }
 
+@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:rej,
   author = 	 {Chris Mason},
   title = 	 {\texttt{rej}--help solve patch rejects},
 \newcommand{\tildefile}[1]{\texttt{\~{}/#1}}
 \newcommand{\filename}[1]{\texttt{#1}}
-\newcommand{\hgext}[1]{\texttt{#1}}
-\newcommand{\hgcmd}[1]{``\texttt{hg #1}''}
-\newcommand{\command}[1]{\texttt{#1}}
-\newcommand{\hgcmdargs}[2]{``\texttt{hg #1 #2}''}
+\newcommand{\dirname}[1]{\texttt{#1}}
+\newcommand{\sfilename}[1]{\index{\texttt{#1} file}\texttt{#1}}
+\newcommand{\sdirname}[1]{\index{\texttt{#1} directory}\texttt{#1}}
+\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
+\newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''}
+\newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}}
+\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
+\newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}``\texttt{#2}''}
+\newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}}
 
 \newsavebox{\notebox}
 \newenvironment{note}%
 	00book.tex \
 	99book.bib \
 	99defs.tex \
-	mq.tex
+	intro.tex \
+	mq.tex \
+	build_id.tex
 
 image-sources := \
 	mq-stack.svg
 	pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
 	cp 99book.bib $(dir $@)
 	cd $(dir $@) && bibtex $(basename $(notdir $@))
+	cd $(dir $@) && makeindex $(basename $(notdir $@))
 	pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
 	pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
 
 	head -2 $(shell which htlatex) > $(dir $(1))/htlatex.book
 	cp 99book.bib $(dir $@)
 	echo '(cd $(dir $@) && bibtex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book
+	echo '(cd $(dir $@) && makeindex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book
 	head -3 $(shell which htlatex) >> $(dir $(1))/htlatex.book
 	echo 'echo status $$$$' >>  $(dir $(1))/htlatex.book
 	chmod 755 $(dir $(1))/htlatex.book
 examples/.run: $(example-sources)
 	cd examples && ./run-example
 
+build_id.tex:
+	echo 'in-place build' > $@
+
+build_id:
+	hg id | sed -e 's/ tip\>//' > build_id.tex
+
 clean:
-	rm -rf html pdf *.eps *.png *.aux *.dvi *.log *.out examples/*.out examples/.run
+	rm -rf html pdf *.eps *.png *.aux *.dvi *.log *.out examples/*.out examples/.run buildrev.tex
+\chapter{Introduction}
+\label{chap:intro}
+
+XXX.
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "00book"
+%%% End: 
 only operate within that repository.  To get started, simply prepare
 the repository using the \hgcmd{qinit} command (see
 figure~\ref{ex:mq:qinit}).  This command creates an empty directory
-called \filename{.hg/patches}, where MQ will keep its metadata.  As
+called \sdirname{.hg/patches}, where MQ will keep its metadata.  As
 with many Mercurial commands, the \hgcmd{qinit} command prints nothing
 if it succeeds.
 
 
 To begin work on a new patch, use the \hgcmd{qnew} command.  This
 command takes one argument, the name of the patch to create.  MQ will
-use this as the name of an actual file in the \filename{.hg/patches}
+use this as the name of an actual file in the \sdirname{.hg/patches}
 directory, as you can see in figure~\ref{ex:mq:qnew}.
 
-Also newly present in the \filename{.hg/patches} directory are two
-other files, \filename{series} and \filename{status}.  The
-\filename{series} file lists all of the patches that MQ knows about
+Also newly present in the \sdirname{.hg/patches} directory are two
+other files, \sfilename{series} and \sfilename{status}.  The
+\sfilename{series} file lists all of the patches that MQ knows about
 for this repository, with one patch per line.  Mercurial uses the
-\filename{status} file for internal book-keeping; it tracks all of the
+\sfilename{status} file for internal book-keeping; it tracks all of the
 patches that MQ has \emph{applied} in this repository.
 
 \begin{note}
-  You may sometimes want to edit the \filename{series} file by hand;
+  You may sometimes want to edit the \sfilename{series} file by hand;
   for example, to change the sequence in which some patches are
-  applied.  However, manually editing the \filename{status} file is
+  applied.  However, manually editing the \sfilename{status} file is
   almost always a bad idea, as it's easy to corrupt MQ's idea of what
   is happening.
 \end{note}
 \section{Mercurial Queues and GNU patch}
 \label{sec:mq:patch}
 
-MQ uses the GNU \command{patch} command to apply patches.  It will
-help you to understand the data that MQ and \command{patch} work with,
-and a few aspects of how \command{patch} operates.
+MQ uses the GNU \command{patch} command to apply patches.  Because MQ
+doesn't hide its patch-oriented nature, it is helpful to understand
+the data that MQ and \command{patch} work with, and a few aspects of
+how \command{patch} operates.
 
 The \command{diff} command generates a list of modifications by
 comparing two files.  The \command{patch} command applies a list of
 When neither of these techniques works, \command{patch} prints a
 message saying that the hunk in question was rejected.  It saves
 rejected hunks to a file with the same name, and an added
-\filename{.rej} extension.  It also saves an unmodified copy of the
-file with a \filename{.orig} extension; the copy of the file without
+\sfilename{.rej} extension.  It also saves an unmodified copy of the
+file with a \sfilename{.orig} extension; the copy of the file without
 any extensions will contain any changes made by hunks that \emph{did}
 apply cleanly.  If you have a patch that modifies \filename{foo} with
 six hunks, and one of them fails to apply, you will have: an
 \subsection{Handling rejection}
 
 If \hgcmd{qpush} fails to apply a patch, it will print an error
-message and exit.  If it has left \filename{.rej} files behind, it is
+message and exit.  If it has left \sfilename{.rej} files behind, it is
 usually best to fix up the rejected hunks before you push more patches
 or do any further work.
 
 Mercurial Queues can help; see section~\ref{seq:mq:merge} for details.
 
 Unfortunately, there aren't any great techniques for dealing with
-rejected hunks.  Most often, you'll need to view the \filename{.rej}
+rejected hunks.  Most often, you'll need to view the \sfilename{.rej}
 file and edit the target file, applying the rejected hunks by hand.
 
-If you're feeling adventurous, Neil Brown, an Australian Linux kernel
-hacker, has written a tool called \command{wiggle}~\cite{web:wiggle},
-which is more vigorous than \command{patch} in its attempts to make a
-patch apply.
+If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
+wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
+vigorous than \command{patch} in its attempts to make a patch apply.
 
 Another Linux kernel hacker, Chris Mason (the author of Mercurial
 Queues), wrote a similar tool called \command{rej}~\cite{web:rej},
 
 XXX.
 
+\section{Managing patches in a repository}
+
+Because MQ's \sdirname{.hg/patches} directory resides outside a
+Mercurial repository's working directory, the ``underlying'' Mercurial
+repository knows nothing about the management or presence of patches.
+
+This presents the interesting possibility of managing the contents of
+the patch directory as a Mercurial repository in its own right.  This
+can be a useful way to work.  For example, you can work on a patch for
+a while, \hgcmd{qrefresh} it, then \hgcmd{commit} the current state of
+the patch.  This lets you ``roll back'' to that version of the patch
+later on.
+
+In addition, you can then share different versions of the same patch
+stack among multiple underlying repositories.  I use this when I am
+developing a Linux kernel feature.  I have a pristine copy of my
+kernel sources for each of several CPU architectures, and a cloned
+repository under each that contains the patches I am working on.  When
+I want to test a change on a different architecture, I push my current
+patches to the patch repository associated with that kernel tree, pop
+and push all of my patches, and build and test that kernel.
+
+Managing patches in a repository makes it possible for multiple
+developers to work on the same patch series without colliding with
+each other, all on top of an underlying source base that they may or
+may not control.
+
+\subsection{MQ support for managing a patch repository}
+
+MQ helps you to work with the \sdirname{.hg/patches} directory as a
+repository; when you prepare a repository for working with patches
+using \hgcmdargs{qinit}, you can pass the \hgopt{qinit}{-c} option to
+create the \sdirname{.hg/patches} directory as a Mercurial repository.
+
+\begin{note}
+  If you forget to use the \hgopt{qinit}{-c} option, you can simply go
+  into the \sdirname{.hg/patches} directory at any time and run
+  \hgcmd{init}.  Don't forget to add an entry for the
+  \filename{status} file to the \filename{.hgignore} file, though
+  (\hgopt{qinit}{-c} does this for you automatically); you
+  \emph{really} don't want to manage the \filename{status} file.
+\end{note}
+
+As a convenience, if MQ notices that the \dirname{.hg/patches}
+directory is a repository, it will automatically \hgcmd{add} every
+patch that you create and import.
+
+Finally, MQ provides a shortcut command, \hgcmd{qcommit}, that runs
+\hgcmd{commit} in the \sdirname{.hg/patches} directory.  This saves
+some cumbersome typing.
+
+\subsection{A few things to watch out for}
+
+MQ's support for working with a repository full of patches is limited
+in a few small respects.
+
+MQ cannot automatically detect changes that you make to the patch
+directory.  If you \hgcmd{pull}, manually edit, or \hgcmd{update}
+changes to patches or the \sfilename{series} file, you will have to
+\hgcmdargs{qpop}{-a} and then \hgcmdargs{qpush}{-a} in the underlying
+repository to see those changes show up there.  If you forget to do
+this, you can confuse MQ's idea of which patches are applied.
+
+\section{Commands for working with patches}
+
+Once you've been working with patches for a while, you'll find
+yourself hungry for tools that will help you to understand and
+manipulate the patches you're dealing with.
+
+The \command{diffstat} command~\cite{web:diffstat} generates a
+histogram of the modifications made to each file in a patch.  It
+provides a good way to ``get a sense of'' a patch--which files it
+affects, and how much change it introduces to each file and as a
+whole.  (I find that it's a good idea to use \command{diffstat}'s
+\texttt{-p} option as a matter of course, as otherwise it will try to
+do clever things with prefixes of file names that inevitably confuse
+at least me.)
+
+The \package{patchutils} package~\cite{web:patchutils} is invaluable.
+It provides a set of small utilities that follow the ``Unix
+philosophy;'' each does one useful thing with a patch.  The
+\package{patchutils} command I use most is \command{filterdiff}, which
+extracts subsets from a patch file.  For example, given a patch that
+modifies hundreds of files across dozens of directories, a single
+invocation of \command{filterdiff} can generate a smaller patch that
+only touches files whose names match a particular glob pattern.
+
 %%% Local Variables: 
 %%% mode: latex
 %%% TeX-master: "00book"