hgbook
changeset 16:81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Jul 03 22:43:52 2006 -0700 (2006-07-03) |
parents | b8ac9f312a47 |
children | 2668e15c76e9 |
files | .hgignore en/00book.tex en/99book.bib en/99defs.tex en/Makefile en/intro.tex en/mq.tex |
line diff
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"