1.1 --- a/en/00book.tex	Sun Jul 16 00:01:43 2006 -0700
     1.2 +++ b/en/00book.tex	Mon Jul 24 23:57:52 2006 -0400
     1.3 @@ -37,6 +37,7 @@
     1.4  
     1.5  \include{preface}
     1.6  \include{intro}
     1.7 +\include{concepts}
     1.8  \include{hook}
     1.9  \include{mq}
    1.10  

     2.1 --- a/en/99defs.tex	Sun Jul 16 00:01:43 2006 -0700
     2.2 +++ b/en/99defs.tex	Mon Jul 24 23:57:52 2006 -0400
     2.3 @@ -25,6 +25,9 @@
     2.4  \newenvironment{note}%
     2.5    {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}%
     2.6    {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
     2.7 +\newenvironment{caution}%
     2.8 +  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Caution:}\space}%
     2.9 +  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
    2.10  
    2.11  \DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}}
    2.12  \newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.out}}

     3.1 --- a/en/Makefile	Sun Jul 16 00:01:43 2006 -0700
     3.2 +++ b/en/Makefile	Mon Jul 24 23:57:52 2006 -0400
     3.3 @@ -7,6 +7,7 @@
     3.4  	99book.bib \
     3.5  	99defs.tex \
     3.6  	build_id.tex \
     3.7 +	concepts.tex \
     3.8  	hook.tex \
     3.9  	intro.tex \
    3.10  	mq.tex \
    3.11 @@ -18,6 +19,7 @@
    3.12  example-sources := \
    3.13  	examples/run-example \
    3.14  	examples/hook.simple \
    3.15 +	examples/concepts \
    3.16  	examples/mq.qinit-help \
    3.17  	examples/mq.diff \
    3.18  	examples/mq.tarball \

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/concepts.tex	Mon Jul 24 23:57:52 2006 -0400
     4.3 @@ -0,0 +1,131 @@
     4.4 +\chapter{Basic Concepts}
     4.5 +\label{chap:concepts}
     4.6 +
     4.7 +This chapter introduces some of the basic concepts behind distributed
     4.8 +version control systems such as Mercurial.
     4.9 +
    4.10 +\section{Repository}
    4.11 +\label{sec:concepts:repo}
    4.12 +The repository is a directory where Mercurial stores the history for the
    4.13 +files under revision control.
    4.14 +
    4.15 +\subsection{Where?}
    4.16 +% where is this repository you speak of?
    4.17 +XXX
    4.18 +
    4.19 +\subsection{How?}
    4.20 +% How are the changes stored?
    4.21 +XXX
    4.22 +
    4.23 +\subsection{Structure}
    4.24 +\label{sec:concepts:structure}
    4.25 +% What's the structure of the repository?
    4.26 +A typical Mercurial repository is a directory which contains a checked out
    4.27 +working copy (see section~\ref{sec:concepts:workingcopy}) as well as
    4.28 +\sdirname{.hg} directory.  Figure~\ref{ex:concepts:dirlist} shows the
    4.29 +contents of a freshly created repository.  This repository does not contain
    4.30 +any revisions. Let's take a look at a repository that has history for
    4.31 +several files.
    4.32 +Figure~\ref{ex:concepts:dirlist2} shows the contents of a repository keeping
    4.33 +history on two files.  We see the checked out copies of the files
    4.34 +\filename{foo} and \filename{bar}, as well as the files containing their
    4.35 +histories \filename{foo.i} and \filename{bar.i}, respectively. Additionally,
    4.36 +we see the \filename{changelog.i} and \filename{00manifest.i} files. These
    4.37 +contain the repository-wide revision data, such as the commit message, and
    4.38 +the list of files in the repository during the commit.
    4.39 +
    4.40 +\begin{figure}[ht]
    4.41 +  \interaction{concepts.dirlist}
    4.42 +  \caption{Contents of a freshly created repository}
    4.43 +  \label{ex:concepts:dirlist}
    4.44 +\end{figure}
    4.45 +
    4.46 +\begin{figure}[ht]
    4.47 +  \interaction{concepts.dirlist2}
    4.48 +  \caption{Contents of a repository tracking two files}
    4.49 +  \label{ex:concepts:dirlist2}
    4.50 +\end{figure}
    4.51 +
    4.52 +\subsection{hgrc}
    4.53 +% .hg/hgrc
    4.54 +XXX
    4.55 +
    4.56 +\subsection{Creating a Repository}
    4.57 +% hg init
    4.58 +Creating a repository is quick and painless.  One uses the \hgcmd{init}
    4.59 +command as figure~\ref{ex:concepts:hginit} demonstrates.  The one argument
    4.60 +passed to the \hgcmd{init} command is the name of the repository. The name
    4.61 +can be any string usable as a directory name.
    4.62 +
    4.63 +\begin{caution}
    4.64 +If you do not specify a name of the repository, the current working
    4.65 +directory will be used instead.
    4.66 +\end{caution}
    4.67 +
    4.68 +\begin{figure}[ht]
    4.69 +  \interaction{concepts.hginit}
    4.70 +  \caption{Creating a new repository}
    4.71 +  \label{ex:concepts:hginit}
    4.72 +\end{figure}
    4.73 +
    4.74 +\subsection{Remote Repositories}
    4.75 +\label{sec:concepts:remoterepo}
    4.76 +In addition to repositories stored on the local file system, Mercurial
    4.77 +supports so called \emph{remote repositories}.  These remote repositories
    4.78 +can be accessed via several different methods.  See
    4.79 +section~\ref{sec:XXX:remotesetup} for instructions how to set up remote
    4.80 +repositories.
    4.81 +% XXX: reference the proper section!
    4.82 +
    4.83 +\subsubsection{SSH}
    4.84 +\label{sec:concepts:remoterepo:ssh}
    4.85 +Mercurial can use \command{ssh} to send and receive changes. The remote
    4.86 +repository is identified by an URL. The basic format for the URL is:
    4.87 +
    4.88 +\begin{verbatim}
    4.89 +ssh://[user@]host/path
    4.90 +\end{verbatim}
    4.91 +
    4.92 +Where \cmdargs{user} is optional, and the \cmdargs{path} is path to the
    4.93 +repository --- either an absolute or relative to the user's home directory
    4.94 +--- on the remote host with hostname: \cmdargs{host}.
    4.95 +
    4.96 +\begin{note}
    4.97 +If the path for the remote repository is absolute there will be two
    4.98 +consecutive slashes.  E.g., if the remote path is \dirname{/repos/hgbook},
    4.99 +the URL would look something like the following:
   4.100 +
   4.101 +\begin{verbatim}
   4.102 +ssh://someuser@remotebox//repos/hgbook
   4.103 +\end{verbatim}
   4.104 +
   4.105 +Relative paths have only one slash and are relative to the user's home
   4.106 +directory.
   4.107 +\end{note}
   4.108 +
   4.109 +\subsubsection{HTTP \& HTTPS}
   4.110 +\label{sec:concepts:remoterepo:http}
   4.111 +The other protocol supported is HTTP as well as HTTPS.  The repository URL
   4.112 +is very much like that of the \command{ssh}.
   4.113 +
   4.114 +\begin{verbatim}
   4.115 +http://[user@]remotebox/path
   4.116 +\end{verbatim}
   4.117 +
   4.118 +Just as before, the username is optional.
   4.119 +% XXX: is it optional for both push & pull or just for pull?
   4.120 +This time however, the path is relative to the HTTP server root.  
   4.121 +
   4.122 +\section{Working Copy}
   4.123 +\label{sec:concepts:workingcopy}
   4.124 +XXX
   4.125 +
   4.126 +\section{Revisions}
   4.127 +\label{sec:concepts:revs}
   4.128 +XXX
   4.129 +
   4.130 +%%% Local Variables: 
   4.131 +%%% mode: latex
   4.132 +%%% TeX-master: "00book"
   4.133 +%%% End:
   4.134 +

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/concepts	Mon Jul 24 23:57:52 2006 -0400
     5.3 @@ -0,0 +1,19 @@
     5.4 +#$ name: dirlist
     5.5 +hg init newrepo
     5.6 +cd newrepo
     5.7 +
     5.8 +find .
     5.9 +
    5.10 +#$ name:
    5.11 +echo "a line of text" > foo
    5.12 +echo "another life of text" > bar
    5.13 +hg commit -A -m "Some files"
    5.14 +
    5.15 +#$ name: dirlist2
    5.16 +find .
    5.17 +
    5.18 +#$ name:
    5.19 +cd ..
    5.20 +
    5.21 +#$ name: hginit
    5.22 +hg init reponame