changeset 59:0aae9d676e0f

Merge with jeffpc.

--- a/en/00book.tex	Wed Aug 02 19:43:53 2006 -0700
+++ b/en/00book.tex	Wed Aug 02 19:53:34 2006 -0700
@@ -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	Wed Aug 02 19:43:53 2006 -0700
+++ b/en/99defs.tex	Wed Aug 02 19:53:34 2006 -0700
@@ -79,6 +79,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	Wed Aug 02 19:43:53 2006 -0700
+++ b/en/Makefile	Wed Aug 02 19:53:34 2006 -0700
@@ -7,6 +7,7 @@
 	99book.bib \
 	99defs.tex \
 	build_id.tex \
+	concepts.tex \
 	daily.tex \
 	hook.tex \
 	intro.tex \
@@ -21,6 +22,7 @@
 	examples/hook.msglen \
 	examples/hook.simple \
 	examples/hook.ws \
+	examples/concepts \
 	examples/mq.qinit-help \
 	examples/mq.dodiff \
 	examples/mq.id \

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/concepts.tex	Wed Aug 02 19:53:34 2006 -0700
@@ -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	Wed Aug 02 19:53:34 2006 -0700
@@ -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