1.1 --- a/en/00book.tex	Thu Dec 28 14:10:23 2006 -0800
     1.2 +++ b/en/00book.tex	Thu Dec 28 16:45:56 2006 -0800
     1.3 @@ -46,9 +46,10 @@
     1.4  \include{template}
     1.5  \include{mq}
     1.6  \include{mq-collab}
     1.7 -\include{mq-ref}
     1.8  
     1.9  \appendix
    1.10 +\include{cmdref}
    1.11 +\include{mq-ref}
    1.12  \include{srcinstall}
    1.13  \include{license}
    1.14  \addcontentsline{toc}{chapter}{Bibliography}

     2.1 --- a/en/99defs.tex	Thu Dec 28 14:10:23 2006 -0800
     2.2 +++ b/en/99defs.tex	Thu Dec 28 16:45:56 2006 -0800
     2.3 @@ -116,6 +116,12 @@
     2.4    \newcommand{\grafix}[1]{\includegraphics{#1.png}}
     2.5  \fi
     2.6  
     2.7 +% Reference entry for a command.
     2.8 +\newcommand{\cmdref}[1]{\section{#1}\label{cmdref:#1}\index{\texttt{#1} command}``\texttt{hg #1}''}
     2.9 +
    2.10 +% Reference entry for a command option.
    2.11 +\newcommand{\optref}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
    2.12 +
    2.13  %%% Local Variables: 
    2.14  %%% mode: latex
    2.15  %%% TeX-master: "00book"

     3.1 --- a/en/Makefile	Thu Dec 28 14:10:23 2006 -0800
     3.2 +++ b/en/Makefile	Thu Dec 28 16:45:56 2006 -0800
     3.3 @@ -7,6 +7,7 @@
     3.4  	99book.bib \
     3.5  	99defs.tex \
     3.6  	build_id.tex \
     3.7 +	cmdref.tex \
     3.8  	concepts.tex \
     3.9  	daily.tex \
    3.10  	hook.tex \

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/cmdref.tex	Thu Dec 28 16:45:56 2006 -0800
     4.3 @@ -0,0 +1,106 @@
     4.4 +\chapter{Command reference}
     4.5 +\label{cmdref}
     4.6 +
     4.7 +\cmdref{diff}
     4.8 +
     4.9 +Show differences between revisions for the specified files or
    4.10 +directories, using the unified diff format.  For a description of the
    4.11 +unified diff format, see section~\ref{sec:mq:patch}.
    4.12 +
    4.13 +\optref{diff}{-r}{--rev}
    4.14 +
    4.15 +Specify a revision to compare.
    4.16 +
    4.17 +\optref{diff}{-a}{--text}
    4.18 +
    4.19 +If this option is not specified, \hgcmd{diff} will refuse to print
    4.20 +diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
    4.21 +forces \hgcmd{diff} to treat all files as text, and generate diffs for
    4.22 +all of them.
    4.23 +
    4.24 +This option is useful for files that are ``mostly text'' but have a
    4.25 +few embedded NUL characters.  If you use it on files that are really
    4.26 +binary, its output will be incomprehensible.
    4.27 +
    4.28 +\subsection{Specifying revisions}
    4.29 +
    4.30 +The \hgcmd{diff} command accepts up to two \hgopt{diff}{-r} options to
    4.31 +specify the revisions to compare.
    4.32 +
    4.33 +\begin{enumerate}
    4.34 +\setcounter{enumi}{0}
    4.35 +\item Display the differences between the parent of the working
    4.36 +  directory and the working directory.
    4.37 +\item Display the differences between the specified changeset and the
    4.38 +  working directory.
    4.39 +\item Display the differences between the two specified changesets.
    4.40 +\end{enumerate}
    4.41 +
    4.42 +You can specify two revisions using either two \hgopt{diff}{-r}
    4.43 +options or revision range notation.  For example, the two revision
    4.44 +specifications below are equivalent.
    4.45 +\begin{codesample2}
    4.46 +  hg diff -r 10 -r 20
    4.47 +  hg diff -r10:20
    4.48 +\end{codesample2}
    4.49 +
    4.50 +When you provide two revisions, Mercurial treats the order of those
    4.51 +revisions as significant.  Thus, \hgcmdargs{diff}{-r10:20} will
    4.52 +produce a diff that will transform files from their contents as of
    4.53 +revision~10 to their contents as of revision~20, while
    4.54 +\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will
    4.55 +transform files from their revision~20 contents to their revision~10
    4.56 +contents.  You cannot reverse the ordering in this way if you are
    4.57 +diffing against the working directory.
    4.58 +
    4.59 +\subsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
    4.60 +  differ?}
    4.61 +\label{cmdref:diff-vs-status}
    4.62 +
    4.63 +When you run the \hgcmd{status} command, you'll see a list of files
    4.64 +that Mercurial will record changes for the next time you perform a
    4.65 +commit.  If you run the \hgcmd{diff} command, you may notice that it
    4.66 +prints diffs for only a \emph{subset} of the files that \hgcmd{status}
    4.67 +listed.  There are two possible reasons for this.
    4.68 +
    4.69 +The first is that \hgcmd{status} prints some kinds of modifications
    4.70 +that \hgcmd{diff} doesn't normally display.  The \hgcmd{diff} command
    4.71 +normally outputs unified diffs, which don't have the ability to
    4.72 +represent some changes that Mercurial can track.  Most notably,
    4.73 +traditional diffs can't represent a change in whether or not a file is
    4.74 +executable, but Mercurial records this information.
    4.75 +
    4.76 +If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
    4.77 +display \command{git}-compatible diffs that \emph{can} display this
    4.78 +extra information.
    4.79 +
    4.80 +The second possible reason that \hgcmd{diff} might be printing diffs
    4.81 +for a subset of the files displayed by \hgcmd{status} is that if you
    4.82 +invoke it without any arguments, \hgcmd{diff} prints diffs against the
    4.83 +first parent of the working directory.  If you have run \hgcmd{merge}
    4.84 +to merge two changesets, but you haven't yet committed the results of
    4.85 +the merge, your working directory has two parents (use \hgcmd{parents}
    4.86 +to see them).  While \hgcmd{status} prints modifications relative to
    4.87 +\emph{both} parents after an uncommitted merge, \hgcmd{diff} still
    4.88 +operates relative only to the first parent.  You can get it to print
    4.89 +diffs relative to the second parent by specifying that parent with the
    4.90 +\hgopt{diff}{-r} option.  There is no way to print diffs relative to
    4.91 +both parents.
    4.92 +
    4.93 +\subsection{Generating safe binary diffs}
    4.94 +
    4.95 +If you use the \hgopt{diff}{-a} option to force Mercurial to print
    4.96 +diffs of files that are either ``mostly text'' or contain lots of
    4.97 +binary data, those diffs cannot subsequently be applied by either
    4.98 +Mercurial's \hgcmd{import} command or the system's \command{patch}
    4.99 +command.  
   4.100 +
   4.101 +If you want to generate a diff of a binary file that is safe to use as
   4.102 +input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
   4.103 +generate the patch.  The system \command{patch} command cannot handle
   4.104 +binary patches at all.
   4.105 +
   4.106 +%%% Local Variables: 
   4.107 +%%% mode: latex
   4.108 +%%% TeX-master: "00book"
   4.109 +%%% End: