1.1 --- a/en/hook.tex	Thu Jul 20 19:42:50 2006 -0700
     1.2 +++ b/en/hook.tex	Sun Jul 23 23:25:52 2006 -0700
     1.3 @@ -413,6 +413,48 @@
     1.4  doesn't care about by dropping them into a keyword argument dict, as
     1.5  with \texttt{**kwargs} above.
     1.6  
     1.7 +\section{Some hook examples}
     1.8 +
     1.9 +\subsection{Enforcing coding guidelines in your own repository}
    1.10 +
    1.11 +An interesting use of a commit-related hook is to help you to write
    1.12 +cleaner code.  A simple example of ``cleaner code'' is the dictum that
    1.13 +a change should not add any new lines of text that contain ``trailing
    1.14 +whitespace''.  Trailing whitespace is a series of space and tab
    1.15 +characters at the end of a line of text.  In most cases, trailing
    1.16 +whitespace is unnecessary, invisible noise, but it is occasionally
    1.17 +problematic, and people tend to prefer to get rid of it.
    1.18 +
    1.19 +You can use either the \hook{precommit} or \hook{pretxncommit} hook to
    1.20 +tell whether you have a trailing whitespace problem.  If you use the
    1.21 +\hook{precommit} hook, the hook will not know which files you are
    1.22 +committing, so it will have to check every modified file in the
    1.23 +repository for trailing white space.  If you want to commit a change
    1.24 +to just the file \filename{foo}, but the file \filename{bar} contains
    1.25 +trailing whitespace, doing a check in the \hook{precommit} hook will
    1.26 +prevent you from committing \filename{foo} due to the problem with
    1.27 +\filename{bar}.  This doesn't seem right.
    1.28 +
    1.29 +Should you choose the \hook{pretxncommit} hook, the check won't occur
    1.30 +until just before the transaction for the commit completes.  This will
    1.31 +allow you to check for problems only the exact files that are being
    1.32 +committed.  However, if you entered the commit message interactively
    1.33 +and the hook fails, the transaction will roll back; you'll have to
    1.34 +re-enter the commit message after you fix the trailing whitespace and
    1.35 +run \hgcmd{commit} again.
    1.36 +
    1.37 +\begin{figure}[ht]
    1.38 +  \interaction{hook.ws.simple}
    1.39 +  \caption{A simple hook that checks for trailing whitespace}
    1.40 +  \label{ex:hook:ws.simple}
    1.41 +\end{figure}
    1.42 +
    1.43 +Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
    1.44 +hook that checks for trailing whitespace.  This hook is short, but not
    1.45 +very helpful.  It exits with an error status if a change adds a line
    1.46 +with trailing whitespace to any file, but does not print any
    1.47 +information that might help us to identify the offending file or line.
    1.48 +
    1.49  \section{Hook reference}
    1.50  \label{sec:hook:ref}
    1.51