diff en/cmdref.tex @ 133:1e013fbe35f7

Lots of filename related content. A little more command reference work. Added a script to make sure commands are exhaustively documented.

--- a/en/cmdref.tex	Thu Dec 28 16:45:56 2006 -0800
+++ b/en/cmdref.tex	Fri Dec 29 17:54:14 2006 -0800
@@ -1,17 +1,41 @@
 \chapter{Command reference}
 \label{cmdref}
 
-\cmdref{diff}
+\cmdref{add}{add files at the next commit}
+\optref{add}{I}{include}
+\optref{add}{X}{exclude}
+\optref{add}{n}{dry-run}
+
+\cmdref{diff}{print changes in history or working directory}
 
 Show differences between revisions for the specified files or
 directories, using the unified diff format.  For a description of the
 unified diff format, see section~\ref{sec:mq:patch}.
 
-\optref{diff}{-r}{--rev}
+By default, this command does not print diffs for files that Mercurial
+considers to contain binary data.  To control this behaviour, see the
+\hgopt{diff}{-a} and \hgopt{diff}{--git} options.
+
+\subsection{Options}
+
+\loptref{diff}{nodates}
+
+Omit date and time information when printing diff headers.
+
+\optref{diff}{B}{ignore-blank-lines}
 
-Specify a revision to compare.
+Do not print changes that only insert or delete blank lines.  A line
+that contains only whitespace is not considered blank.
+
+\optref{diff}{I}{include}
 
-\optref{diff}{-a}{--text}
+Exclude files and directories whose names match the given patterns.
+
+\optref{diff}{X}{exclude}
+
+Include files and directories whose names match the given patterns.
+
+\optref{diff}{a}{text}
 
 If this option is not specified, \hgcmd{diff} will refuse to print
 diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
@@ -19,18 +43,37 @@
 all of them.
 
 This option is useful for files that are ``mostly text'' but have a
-few embedded NUL characters.  If you use it on files that are really
-binary, its output will be incomprehensible.
+few embedded NUL characters.  If you use it on files that contain a
+lot of binary data, its output will be incomprehensible.
+
+\optref{diff}{b}{ignore-space-change}
+
+Do not print a line if the only change to that line is in the amount
+of white space it contains.
+
+\optref{diff}{g}{git}
+
+Print \command{git}-compatible diffs.  XXX reference a format
+description.
 
-\subsection{Specifying revisions}
+\optref{diff}{p}{show-function}
 
-The \hgcmd{diff} command accepts up to two \hgopt{diff}{-r} options to
-specify the revisions to compare.
+Display the name of the enclosing function in a hunk header, using a
+simple heuristic.  This functionality is enabled by default, so the
+\hgopt{diff}{-p} option has no effect unless you change the value of
+the \rcitem{diff}{showfunc} config item, as in the following example.
+\interaction{cmdref.diff-p}
+
+\optref{diff}{r}{rev}
+
+Specify one or more revisions to compare.  The \hgcmd{diff} command
+accepts up to two \hgopt{diff}{-r} options to specify the revisions to
+compare.
 
 \begin{enumerate}
 \setcounter{enumi}{0}
-\item Display the differences between the parent of the working
-  directory and the working directory.
+\item Display the differences between the parent revision of the
+  working directory and the working directory.
 \item Display the differences between the specified changeset and the
   working directory.
 \item Display the differences between the two specified changesets.
@@ -53,7 +96,34 @@
 contents.  You cannot reverse the ordering in this way if you are
 diffing against the working directory.
 
-\subsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
+\optref{diff}{w}{ignore-all-space}
+
+\cmdref{version}{print version and copyright information}
+
+This command displays the version of Mercurial you are running, and
+its copyright license.  There are four kinds of version string that
+you may see.
+\begin{itemize}
+\item The string ``\texttt{unknown}''. This version of Mercurial was
+  not built in a Mercurial repository, and cannot determine its own
+  version.
+\item A short numeric string, such as ``\texttt{1.1}''. This is a
+  build of a revision of Mercurial that was identified by a specific
+  tag in the repository where it was built.  (This doesn't necessarily
+  mean that you're running an official release; someone else could
+  have added that tag to any revision in the repository where they
+  built Mercurial.)
+\item A hexadecimal string, such as ``\texttt{875489e31abe}''.  This
+  is a build of the given revision of Mercurial.
+\item A hexadecimal string followed by a date, such as
+  ``\texttt{875489e31abe+20070205}''.  This is a build of the given
+  revision of Mercurial, where the build repository contained some
+  local changes that had not been committed.
+\end{itemize}
+
+\subsection{Tips and tricks}
+
+\subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
   differ?}
 \label{cmdref:diff-vs-status}
 
@@ -87,7 +157,7 @@
 \hgopt{diff}{-r} option.  There is no way to print diffs relative to
 both parents.
 
-\subsection{Generating safe binary diffs}
+\subsubsection{Generating safe binary diffs}
 
 If you use the \hgopt{diff}{-a} option to force Mercurial to print
 diffs of files that are either ``mostly text'' or contain lots of