1.1 --- a/en/Makefile	Sun Jul 23 12:21:36 2006 -0700
     1.2 +++ b/en/Makefile	Sun Jul 23 23:25:52 2006 -0700
     1.3 @@ -20,6 +20,7 @@
     1.4  	examples/run-example \
     1.5  	examples/daily.files \
     1.6  	examples/hook.simple \
     1.7 +	examples/hook.ws \
     1.8  	examples/mq.qinit-help \
     1.9  	examples/mq.diff \
    1.10  	examples/mq.tarball \

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/en/examples/data/check_whitespace.py	Sun Jul 23 23:25:52 2006 -0700
     2.3 @@ -0,0 +1,31 @@
     2.4 +#!/usr/bin/python
     2.5 +
     2.6 +import os, re, sys
     2.7 +
     2.8 +count = 0
     2.9 +
    2.10 +for line in os.popen('hg export tip'):
    2.11 +    # remember the name of the file that this diff affects
    2.12 +    m = re.match(r'^--- [^/]/([^\t])', line)
    2.13 +    if m: 
    2.14 +	filename = m.group(1)
    2.15 +	continue
    2.16 +    # remember the line number
    2.17 +    m = re.match(r'^@@ -(\d+),')
    2.18 +    if m:
    2.19 +        linenum = m.group(1)
    2.20 +        continue
    2.21 +    linenum += 1
    2.22 +    # check for an added line with trailing whitespace
    2.23 +    m = re.match(r'^\+.*\s$', line)
    2.24 +    if m:
    2.25 +	print >> sys.stderr, ('%s:%d: trailing whitespace introduced' %
    2.26 +                              (filename, linenum))
    2.27 +        count += 1
    2.28 +
    2.29 +if count:
    2.30 +    # save the commit message so we don't need to retype it
    2.31 +    os.system('hg tip --template "{desc}" > .hg/commit.save')
    2.32 +    print >> sys.stderr, 'commit message saved to .hg/commit.save'
    2.33 +
    2.34 +sys.exit(count)

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/examples/hook.ws	Sun Jul 23 23:25:52 2006 -0700
     3.3 @@ -0,0 +1,12 @@
     3.4 +cp $EXAMPLE_DIR/data/check_whitespace.py .
     3.5 +
     3.6 +hg init a
     3.7 +cd a
     3.8 +echo '[hooks]' > .hg/hgrc
     3.9 +echo "pretxncommit.whitespace = hg export tip | (! grep -qP '^\\+.*[ \\t]$')" >> .hg/hgrc
    3.10 +
    3.11 +#$ name: simple
    3.12 +
    3.13 +cat .hg/hgrc
    3.14 +echo 'a ' > a
    3.15 +hg commit -A -m 'test with trailing whitespace'

     4.1 --- a/en/hook.tex	Sun Jul 23 12:21:36 2006 -0700
     4.2 +++ b/en/hook.tex	Sun Jul 23 23:25:52 2006 -0700
     4.3 @@ -413,6 +413,48 @@
     4.4  doesn't care about by dropping them into a keyword argument dict, as
     4.5  with \texttt{**kwargs} above.
     4.6  
     4.7 +\section{Some hook examples}
     4.8 +
     4.9 +\subsection{Enforcing coding guidelines in your own repository}
    4.10 +
    4.11 +An interesting use of a commit-related hook is to help you to write
    4.12 +cleaner code.  A simple example of ``cleaner code'' is the dictum that
    4.13 +a change should not add any new lines of text that contain ``trailing
    4.14 +whitespace''.  Trailing whitespace is a series of space and tab
    4.15 +characters at the end of a line of text.  In most cases, trailing
    4.16 +whitespace is unnecessary, invisible noise, but it is occasionally
    4.17 +problematic, and people tend to prefer to get rid of it.
    4.18 +
    4.19 +You can use either the \hook{precommit} or \hook{pretxncommit} hook to
    4.20 +tell whether you have a trailing whitespace problem.  If you use the
    4.21 +\hook{precommit} hook, the hook will not know which files you are
    4.22 +committing, so it will have to check every modified file in the
    4.23 +repository for trailing white space.  If you want to commit a change
    4.24 +to just the file \filename{foo}, but the file \filename{bar} contains
    4.25 +trailing whitespace, doing a check in the \hook{precommit} hook will
    4.26 +prevent you from committing \filename{foo} due to the problem with
    4.27 +\filename{bar}.  This doesn't seem right.
    4.28 +
    4.29 +Should you choose the \hook{pretxncommit} hook, the check won't occur
    4.30 +until just before the transaction for the commit completes.  This will
    4.31 +allow you to check for problems only the exact files that are being
    4.32 +committed.  However, if you entered the commit message interactively
    4.33 +and the hook fails, the transaction will roll back; you'll have to
    4.34 +re-enter the commit message after you fix the trailing whitespace and
    4.35 +run \hgcmd{commit} again.
    4.36 +
    4.37 +\begin{figure}[ht]
    4.38 +  \interaction{hook.ws.simple}
    4.39 +  \caption{A simple hook that checks for trailing whitespace}
    4.40 +  \label{ex:hook:ws.simple}
    4.41 +\end{figure}
    4.42 +
    4.43 +Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
    4.44 +hook that checks for trailing whitespace.  This hook is short, but not
    4.45 +very helpful.  It exits with an error status if a change adds a line
    4.46 +with trailing whitespace to any file, but does not print any
    4.47 +information that might help us to identify the offending file or line.
    4.48 +
    4.49  \section{Hook reference}
    4.50  \label{sec:hook:ref}
    4.51