Mercurial > hgbook

changeset 58:3649ee841264

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge with bos
author Josef "Jeff" Sipek <jeffpc@josefsipek.net>
date Tue, 25 Jul 2006 09:07:20 -0400
parents fa8bafe467cb (diff) 18210d46491f (current diff)
children 0aae9d676e0f
files en/99defs.tex en/Makefile
diffstat 5 files changed, 338 insertions(+), 182 deletions(-) [+]
line wrap: on
line diff
--- a/en/00book.tex	Tue Jul 25 00:18:31 2006 -0700
+++ b/en/00book.tex	Tue Jul 25 09:07:20 2006 -0400
@@ -1,57 +1,58 @@
-% The use of oneside here is a temporary hack; \marginpar entries
-% don't show up on odd pages of PDF output without it.  Sigh.
-\documentclass[oneside]{book}
-\usepackage{enumerate}
-\usepackage{fullpage}
-\usepackage{makeidx}
-\usepackage{ifpdf}
-\usepackage{graphicx}
-\usepackage{pslatex}
-\usepackage{fancyvrb}
-% leave hyperref until last
-\usepackage[colorlinks=true,bookmarks=true]{hyperref}
-
-\include{99defs}
-
-\title{Distributed revision control with Mercurial}
-\author{Bryan O'Sullivan}
-\date{Copyright \copyright\ 2006 Bryan O'Sullivan.\\
-  This material may be distributed only subject to the terms and
-  conditions set forth in version 1.0 of the Open Publication License.
-  Please refer to Appendix~\ref{cha:opl} for the license text.\\
-  This book was prepared from revision \input{build_id}.}
-
-\makeindex
-
-\begin{document}
-
-\maketitle
-
-\addcontentsline{toc}{chapter}{Contents}
-\pagenumbering{roman}
-\tableofcontents
-\listoffigures
-%\listoftables
-
-\pagenumbering{arabic}
-
-\include{preface}
-\include{intro}
-\include{daily}
-\include{hook}
-\include{mq}
-
-\appendix
-\include{license}
-\addcontentsline{toc}{chapter}{Bibliography}
-\bibliographystyle{alpha}
-\bibliography{99book}
-
-\printindex
-
-\end{document}
-
-%%% Local Variables: 
-%%% mode: latex
-%%% TeX-master: t
-%%% End: 
+% The use of oneside here is a temporary hack; \marginpar entries
+% don't show up on odd pages of PDF output without it.  Sigh.
+\documentclass[oneside]{book}
+\usepackage{enumerate}
+\usepackage{fullpage}
+\usepackage{makeidx}
+\usepackage{ifpdf}
+\usepackage{graphicx}
+\usepackage{pslatex}
+\usepackage{fancyvrb}
+% leave hyperref until last
+\usepackage[colorlinks=true,bookmarks=true]{hyperref}
+
+\include{99defs}
+
+\title{Distributed revision control with Mercurial}
+\author{Bryan O'Sullivan}
+\date{Copyright \copyright\ 2006 Bryan O'Sullivan.\\
+  This material may be distributed only subject to the terms and
+  conditions set forth in version 1.0 of the Open Publication License.
+  Please refer to Appendix~\ref{cha:opl} for the license text.\\
+  This book was prepared from revision \input{build_id}.}
+
+\makeindex
+
+\begin{document}
+
+\maketitle
+
+\addcontentsline{toc}{chapter}{Contents}
+\pagenumbering{roman}
+\tableofcontents
+\listoffigures
+%\listoftables
+
+\pagenumbering{arabic}
+
+\include{preface}
+\include{intro}
+\include{concepts}
+\include{daily}
+\include{hook}
+\include{mq}
+
+\appendix
+\include{license}
+\addcontentsline{toc}{chapter}{Bibliography}
+\bibliographystyle{alpha}
+\bibliography{99book}
+
+\printindex
+
+\end{document}
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: t
+%%% End: 
--- a/en/99defs.tex	Tue Jul 25 00:18:31 2006 -0700
+++ b/en/99defs.tex	Tue Jul 25 09:07:20 2006 -0400
@@ -82,6 +82,9 @@
 \newenvironment{note}%
   {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}%
   {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
+\newenvironment{caution}%
+  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Caution:}\space}%
+  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
 
 % Code sample, eating 4 characters of leading space.
 \DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}}
--- a/en/Makefile	Tue Jul 25 00:18:31 2006 -0700
+++ b/en/Makefile	Tue Jul 25 09:07:20 2006 -0400
@@ -1,125 +1,127 @@
-# This makefile requires GNU make.
-
-hg_id := $(shell hg parents --template '{node|short}\n' | head -1)
-
-sources := \
-	00book.tex \
-	99book.bib \
-	99defs.tex \
-	build_id.tex \
-	daily.tex \
-	hook.tex \
-	intro.tex \
-	mq.tex \
-	preface.tex
-
-image-sources := \
-	mq-stack.svg
-
-example-sources := \
-	examples/daily.files \
-	examples/hook.msglen \
-	examples/hook.simple \
-	examples/hook.ws \
-	examples/mq.qinit-help \
-	examples/mq.dodiff \
-	examples/mq.tarball \
-	examples/mq.tools \
-	examples/mq.tutorial
-
-latex-options = \
-	-interaction batchmode \
-	-output-directory $(dir $(1)) \
-	-jobname $(basename $(notdir $(1)))
-
-all: pdf html
-
-pdf: pdf/hgbook.pdf
-
-define pdf
-	mkdir -p $(dir $@)
-	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
-	cp 99book.bib $(dir $@)
-	cd $(dir $@) && bibtex $(basename $(notdir $@))
-	cd $(dir $@) && makeindex $(basename $(notdir $@))
-	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
-	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
-	if grep 'Reference.*undefined' $(@:.pdf=.log); then exit 1; fi
-endef
-
-pdf/hgbook.pdf: $(sources) $(image-sources:%.svg=%.pdf) examples
-	$(call pdf)
-
-html: html/onepage/hgbook.html html/split/hgbook.html
-
-# This is a horrible hack to work around the fact that the htlatex
-# command in tex4ht is itself a horrible hack.  I really don't want to
-# include verbatim the big wad of TeX that is repeated in that script,
-# so instead I mangle the script itself.
-
-define htlatex
-	mkdir -p $(dir $(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
-	TEXINPUTS=$(dir $(2)): $(dir $(1))/htlatex.book $(2) "xhtml,html4-uni,$(3)" " -cunihtf -utf8" "" "$(call latex-options,$(1))" || (rm -f $(1); exit 1)
-	cd $(dir $(1)) && tex4ht -f/$(basename $(notdir $(1))) -cvalidate -cunihtf
-	cd $(dir $(1)) && t4ht -f/$(basename $(notdir $(1)))
-	perl -pi -e 's/&#x00([0-7][0-9a-f]);/chr(hex($$1))/egi' $(dir $(1))/*.html
-endef
-
-html/onepage/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
-	$(call htlatex,$@,$<)
-	cp $(image-sources:%.svg=%.png) $(dir $@)
-
-html/split/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
-	$(call htlatex,$@,$<,2)
-	cp $(image-sources:%.svg=%.png) $(dir $@)
-
-beta: beta/pdf/hgbook.pdf beta/html/onepage/hgbook.html beta/html/split/hgbook.html
-
-beta/%.tex: %.tex
-	./fblinks $(hg_id) $(dir $@) $<
-
-beta/pdf/hgbook.pdf: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.pdf) examples fblinks
-	$(call pdf)
-
-beta/html/onepage/hgbook.html: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.png) examples
-	$(call htlatex,$@,$<)
-	cp $(image-sources:%.svg=%.png) $(dir $@)
-
-beta/html/split/hgbook.html: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.png) examples
-	$(call htlatex,$@,$<,2)
-	cp $(image-sources:%.svg=%.png) $(dir $@)
-
-# Produce 90dpi PNGs for the web.
-
-%.png: %.svg
-	inkscape -D -e $@ $<
-
-# Produce eps & pdf for the pdf
-
-%.pdf: %.eps
-	epstopdf $<
-
-%.eps: %.svg
-	inkscape -E $@ $<
-
-examples: examples/.run
-
-examples/.run: $(example-sources:%=%.run)
-	touch examples/.run
-
-examples/%.run: examples/% examples/run-example
-	cd examples && ./run-example $(notdir $<)
-
-build_id.tex: $(wildcard ../.hg/00changelog.[id])
-	echo -n $(hg_id) > build_id.tex
-
-clean:
-	rm -rf beta html pdf *.eps *.pdf *.png *.aux *.dvi *.log *.out \
-		examples/*.{out,run} examples/.run build_id.tex
+# This makefile requires GNU make.
+
+hg_id := $(shell hg parents --template '{node|short}\n' | head -1)
+
+sources := \
+	00book.tex \
+	99book.bib \
+	99defs.tex \
+	build_id.tex \
+	concepts.tex \
+	daily.tex \
+	hook.tex \
+	intro.tex \
+	mq.tex \
+	preface.tex
+
+image-sources := \
+	mq-stack.svg
+
+example-sources := \
+	examples/daily.files \
+	examples/hook.msglen \
+	examples/hook.simple \
+	examples/hook.ws \
+	examples/concepts \
+	examples/mq.qinit-help \
+	examples/mq.dodiff \
+	examples/mq.tarball \
+	examples/mq.tools \
+	examples/mq.tutorial
+
+latex-options = \
+	-interaction batchmode \
+	-output-directory $(dir $(1)) \
+	-jobname $(basename $(notdir $(1)))
+
+all: pdf html
+
+pdf: pdf/hgbook.pdf
+
+define pdf
+	mkdir -p $(dir $@)
+	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
+	cp 99book.bib $(dir $@)
+	cd $(dir $@) && bibtex $(basename $(notdir $@))
+	cd $(dir $@) && makeindex $(basename $(notdir $@))
+	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
+	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
+	if grep 'Reference.*undefined' $(@:.pdf=.log); then exit 1; fi
+endef
+
+pdf/hgbook.pdf: $(sources) $(image-sources:%.svg=%.pdf) examples
+	$(call pdf)
+
+html: html/onepage/hgbook.html html/split/hgbook.html
+
+# This is a horrible hack to work around the fact that the htlatex
+# command in tex4ht is itself a horrible hack.  I really don't want to
+# include verbatim the big wad of TeX that is repeated in that script,
+# so instead I mangle the script itself.
+
+define htlatex
+	mkdir -p $(dir $(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
+	TEXINPUTS=$(dir $(2)): $(dir $(1))/htlatex.book $(2) "xhtml,html4-uni,$(3)" " -cunihtf -utf8" "" "$(call latex-options,$(1))" || (rm -f $(1); exit 1)
+	cd $(dir $(1)) && tex4ht -f/$(basename $(notdir $(1))) -cvalidate -cunihtf
+	cd $(dir $(1)) && t4ht -f/$(basename $(notdir $(1)))
+	perl -pi -e 's/&#x00([0-7][0-9a-f]);/chr(hex($$1))/egi' $(dir $(1))/*.html
+endef
+
+html/onepage/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
+	$(call htlatex,$@,$<)
+	cp $(image-sources:%.svg=%.png) $(dir $@)
+
+html/split/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
+	$(call htlatex,$@,$<,2)
+	cp $(image-sources:%.svg=%.png) $(dir $@)
+
+beta: beta/pdf/hgbook.pdf beta/html/onepage/hgbook.html beta/html/split/hgbook.html
+
+beta/%.tex: %.tex
+	./fblinks $(hg_id) $(dir $@) $<
+
+beta/pdf/hgbook.pdf: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.pdf) examples fblinks
+	$(call pdf)
+
+beta/html/onepage/hgbook.html: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.png) examples
+	$(call htlatex,$@,$<)
+	cp $(image-sources:%.svg=%.png) $(dir $@)
+
+beta/html/split/hgbook.html: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.png) examples
+	$(call htlatex,$@,$<,2)
+	cp $(image-sources:%.svg=%.png) $(dir $@)
+
+# Produce 90dpi PNGs for the web.
+
+%.png: %.svg
+	inkscape -D -e $@ $<
+
+# Produce eps & pdf for the pdf
+
+%.pdf: %.eps
+	epstopdf $<
+
+%.eps: %.svg
+	inkscape -E $@ $<
+
+examples: examples/.run
+
+examples/.run: $(example-sources:%=%.run)
+	touch examples/.run
+
+examples/%.run: examples/% examples/run-example
+	cd examples && ./run-example $(notdir $<)
+
+build_id.tex: $(wildcard ../.hg/00changelog.[id])
+	echo -n $(hg_id) > build_id.tex
+
+clean:
+	rm -rf beta html pdf *.eps *.pdf *.png *.aux *.dvi *.log *.out \
+		examples/*.{out,run} examples/.run build_id.tex
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/concepts.tex	Tue Jul 25 09:07:20 2006 -0400
@@ -0,0 +1,131 @@
+\chapter{Basic Concepts}
+\label{chap:concepts}
+
+This chapter introduces some of the basic concepts behind distributed
+version control systems such as Mercurial.
+
+\section{Repository}
+\label{sec:concepts:repo}
+The repository is a directory where Mercurial stores the history for the
+files under revision control.
+
+\subsection{Where?}
+% where is this repository you speak of?
+XXX
+
+\subsection{How?}
+% How are the changes stored?
+XXX
+
+\subsection{Structure}
+\label{sec:concepts:structure}
+% What's the structure of the repository?
+A typical Mercurial repository is a directory which contains a checked out
+working copy (see section~\ref{sec:concepts:workingcopy}) as well as
+\sdirname{.hg} directory.  Figure~\ref{ex:concepts:dirlist} shows the
+contents of a freshly created repository.  This repository does not contain
+any revisions. Let's take a look at a repository that has history for
+several files.
+Figure~\ref{ex:concepts:dirlist2} shows the contents of a repository keeping
+history on two files.  We see the checked out copies of the files
+\filename{foo} and \filename{bar}, as well as the files containing their
+histories \filename{foo.i} and \filename{bar.i}, respectively. Additionally,
+we see the \filename{changelog.i} and \filename{00manifest.i} files. These
+contain the repository-wide revision data, such as the commit message, and
+the list of files in the repository during the commit.
+
+\begin{figure}[ht]
+  \interaction{concepts.dirlist}
+  \caption{Contents of a freshly created repository}
+  \label{ex:concepts:dirlist}
+\end{figure}
+
+\begin{figure}[ht]
+  \interaction{concepts.dirlist2}
+  \caption{Contents of a repository tracking two files}
+  \label{ex:concepts:dirlist2}
+\end{figure}
+
+\subsection{hgrc}
+% .hg/hgrc
+XXX
+
+\subsection{Creating a Repository}
+% hg init
+Creating a repository is quick and painless.  One uses the \hgcmd{init}
+command as figure~\ref{ex:concepts:hginit} demonstrates.  The one argument
+passed to the \hgcmd{init} command is the name of the repository. The name
+can be any string usable as a directory name.
+
+\begin{caution}
+If you do not specify a name of the repository, the current working
+directory will be used instead.
+\end{caution}
+
+\begin{figure}[ht]
+  \interaction{concepts.hginit}
+  \caption{Creating a new repository}
+  \label{ex:concepts:hginit}
+\end{figure}
+
+\subsection{Remote Repositories}
+\label{sec:concepts:remoterepo}
+In addition to repositories stored on the local file system, Mercurial
+supports so called \emph{remote repositories}.  These remote repositories
+can be accessed via several different methods.  See
+section~\ref{sec:XXX:remotesetup} for instructions how to set up remote
+repositories.
+% XXX: reference the proper section!
+
+\subsubsection{SSH}
+\label{sec:concepts:remoterepo:ssh}
+Mercurial can use \command{ssh} to send and receive changes. The remote
+repository is identified by an URL. The basic format for the URL is:
+
+\begin{verbatim}
+ssh://[user@]host/path
+\end{verbatim}
+
+Where \cmdargs{user} is optional, and the \cmdargs{path} is path to the
+repository --- either an absolute or relative to the user's home directory
+--- on the remote host with hostname: \cmdargs{host}.
+
+\begin{note}
+If the path for the remote repository is absolute there will be two
+consecutive slashes.  E.g., if the remote path is \dirname{/repos/hgbook},
+the URL would look something like the following:
+
+\begin{verbatim}
+ssh://someuser@remotebox//repos/hgbook
+\end{verbatim}
+
+Relative paths have only one slash and are relative to the user's home
+directory.
+\end{note}
+
+\subsubsection{HTTP \& HTTPS}
+\label{sec:concepts:remoterepo:http}
+The other protocol supported is HTTP as well as HTTPS.  The repository URL
+is very much like that of the \command{ssh}.
+
+\begin{verbatim}
+http://[user@]remotebox/path
+\end{verbatim}
+
+Just as before, the username is optional.
+% XXX: is it optional for both push & pull or just for pull?
+This time however, the path is relative to the HTTP server root.  
+
+\section{Working Copy}
+\label{sec:concepts:workingcopy}
+XXX
+
+\section{Revisions}
+\label{sec:concepts:revs}
+XXX
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "00book"
+%%% End:
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/concepts	Tue Jul 25 09:07:20 2006 -0400
@@ -0,0 +1,19 @@
+#$ name: dirlist
+hg init newrepo
+cd newrepo
+
+find .
+
+#$ name:
+echo "a line of text" > foo
+echo "another life of text" > bar
+hg commit -A -m "Some files"
+
+#$ name: dirlist2
+find .
+
+#$ name:
+cd ..
+
+#$ name: hginit
+hg init reponame