1.1 --- a/en/99defs.tex	Tue Jul 25 00:02:24 2006 -0400
     1.2 +++ b/en/99defs.tex	Tue Jul 25 09:07:20 2006 -0400
     1.3 @@ -70,6 +70,9 @@
     1.4  % Python module.
     1.5  \newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}}
     1.6  
     1.7 +% Bundled extension.
     1.8 +\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
     1.9 +
    1.10  % Python class in a module.
    1.11  \newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2}
    1.12      class}\texttt{#1.#2}}
    1.13 @@ -94,7 +97,7 @@
    1.14  
    1.15  % Graphics inclusion.
    1.16  \ifpdf
    1.17 -  \newcommand{\grafix}[1]{\includegraphics{#1}}
    1.18 +  \newcommand{\grafix}[1]{\includegraphics{#1.pdf}}
    1.19  \else
    1.20    \newcommand{\grafix}[1]{\includegraphics{#1.png}}
    1.21  \fi

     2.1 --- a/en/Makefile	Tue Jul 25 00:02:24 2006 -0400
     2.2 +++ b/en/Makefile	Tue Jul 25 09:07:20 2006 -0400
     2.3 @@ -19,6 +19,7 @@
     2.4  
     2.5  example-sources := \
     2.6  	examples/daily.files \
     2.7 +	examples/hook.msglen \
     2.8  	examples/hook.simple \
     2.9  	examples/hook.ws \
    2.10  	examples/concepts \

     3.1 --- a/en/examples/data/check_whitespace.py	Tue Jul 25 00:02:24 2006 -0400
     3.2 +++ b/en/examples/data/check_whitespace.py	Tue Jul 25 09:07:20 2006 -0400
     3.3 @@ -1,31 +1,44 @@
     3.4  #!/usr/bin/python
     3.5  
     3.6 -import os, re, sys
     3.7 +import re
     3.8  
     3.9 -count = 0
    3.10 +def trailing_whitespace(difflines):
    3.11 +    added, linenum, header = [], 0, False
    3.12  
    3.13 -for line in os.popen('hg export tip'):
    3.14 -    # remember the name of the file that this diff affects
    3.15 -    m = re.match(r'^--- [^/]/([^\t])', line)
    3.16 -    if m: 
    3.17 -	filename = m.group(1)
    3.18 -	continue
    3.19 -    # remember the line number
    3.20 -    m = re.match(r'^@@ -(\d+),')
    3.21 -    if m:
    3.22 -        linenum = m.group(1)
    3.23 -        continue
    3.24 -    linenum += 1
    3.25 -    # check for an added line with trailing whitespace
    3.26 -    m = re.match(r'^\+.*\s$', line)
    3.27 -    if m:
    3.28 -	print >> sys.stderr, ('%s:%d: trailing whitespace introduced' %
    3.29 -                              (filename, linenum))
    3.30 -        count += 1
    3.31 +    for line in difflines:
    3.32 +        if header:
    3.33 +            if line.startswith('+++ '):
    3.34 +                header = False
    3.35 +            else:
    3.36 +                # remember the name of the file that this diff affects
    3.37 +                m = re.match(r'--- [^/]/([^\t])', line)
    3.38 +                if m: filename = m.group(1)
    3.39 +            continue
    3.40 +        if line.startswith('diff '):
    3.41 +            header = True
    3.42 +            continue
    3.43 +        # hunk header - save the line number
    3.44 +        m = re.match(r'@@ -(\d+),', line)
    3.45 +        if m:
    3.46 +            linenum = int(m.group(1))
    3.47 +            continue
    3.48 +        # hunk body - check for an added line with trailing whitespace
    3.49 +        m = re.match(r'\+.*\s$', line)
    3.50 +        if m:
    3.51 +            added.append((filename, linenum))
    3.52 +        if line and line[0] in ' +':
    3.53 +            linenum += 1
    3.54 +    return added
    3.55  
    3.56 -if count:
    3.57 -    # save the commit message so we don't need to retype it
    3.58 -    os.system('hg tip --template "{desc}" > .hg/commit.save')
    3.59 -    print >> sys.stderr, 'commit message saved to .hg/commit.save'
    3.60 -
    3.61 -sys.exit(count)
    3.62 +if __name__ == '__main__':
    3.63 +    import os, sys
    3.64 +    
    3.65 +    added = trailing_whitespace(os.popen('hg export tip'))
    3.66 +    if added:
    3.67 +        for filename, linenum in added:
    3.68 +            print >> sys.stderr, ('%s, line %d: trailing whitespace added' %
    3.69 +                                  (filename, linenum))
    3.70 +        # save the commit message so we don't need to retype it
    3.71 +        os.system('hg tip --template "{desc}" > .hg/commit.save')
    3.72 +        print >> sys.stderr, 'commit message saved to .hg/commit.save'
    3.73 +        sys.exit(1)

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/examples/hook.msglen	Tue Jul 25 09:07:20 2006 -0400
     4.3 @@ -0,0 +1,14 @@
     4.4 +#!/bin/sh
     4.5 +
     4.6 +hg init a
     4.7 +cd a
     4.8 +echo '[hooks]' > .hg/hgrc
     4.9 +echo 'pretxncommit.msglen = test `hg tip --template {desc} | wc -c` -ge 10' >> .hg/hgrc
    4.10 +
    4.11 +#$ name: run
    4.12 +
    4.13 +cat .hg/hgrc
    4.14 +echo a > a
    4.15 +hg add a
    4.16 +hg commit -A -m 'too short'
    4.17 +hg commit -A -m 'long enough'

     5.1 --- a/en/examples/hook.ws	Tue Jul 25 00:02:24 2006 -0400
     5.2 +++ b/en/examples/hook.ws	Tue Jul 25 09:07:20 2006 -0400
     5.3 @@ -1,7 +1,5 @@
     5.4  #!/bin/bash
     5.5  
     5.6 -cp $EXAMPLE_DIR/data/check_whitespace.py .
     5.7 -
     5.8  hg init a
     5.9  cd a
    5.10  echo '[hooks]' > .hg/hgrc
    5.11 @@ -12,3 +10,19 @@
    5.12  cat .hg/hgrc
    5.13  echo 'a ' > a
    5.14  hg commit -A -m 'test with trailing whitespace'
    5.15 +echo 'a' > a
    5.16 +hg commit -A -m 'drop trailing whitespace and try again'
    5.17 +
    5.18 +#$ name:
    5.19 +
    5.20 +echo '[hooks]' > .hg/hgrc
    5.21 +echo "pretxncommit.whitespace = check_whitespace.py" >> .hg/hgrc
    5.22 +cp $EXAMPLE_DIR/data/check_whitespace.py .
    5.23 +
    5.24 +#$ name: better
    5.25 +
    5.26 +cat .hg/hgrc
    5.27 +echo 'a ' >> a
    5.28 +hg commit -A -m 'add new line with trailing whitespace'
    5.29 +perl -pi -e 's,\s+$,,' a
    5.30 +hg commit -A -m 'trimmed trailing whitespace'

     6.1 --- a/en/hook.tex	Tue Jul 25 00:02:24 2006 -0400
     6.2 +++ b/en/hook.tex	Tue Jul 25 09:07:20 2006 -0400
     6.3 @@ -415,7 +415,20 @@
     6.4  
     6.5  \section{Some hook examples}
     6.6  
     6.7 -\subsection{Enforcing coding guidelines in your own repository}
     6.8 +\subsection{Writing meaningful commit messages}
     6.9 +
    6.10 +It's hard to imagine a useful commit message being very short.  The
    6.11 +simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.run}
    6.12 +will prevent you from committing a changeset with a message that is
    6.13 +less than ten bytes long.
    6.14 +
    6.15 +\begin{figure}[ht]
    6.16 +  \interaction{hook.msglen.run}
    6.17 +  \caption{A hook that forbids overly short commit messages}
    6.18 +  \label{ex:hook:msglen.run}
    6.19 +\end{figure}
    6.20 +
    6.21 +\subsection{Checking for trailing whitespace}
    6.22  
    6.23  An interesting use of a commit-related hook is to help you to write
    6.24  cleaner code.  A simple example of ``cleaner code'' is the dictum that
    6.25 @@ -423,7 +436,7 @@
    6.26  whitespace''.  Trailing whitespace is a series of space and tab
    6.27  characters at the end of a line of text.  In most cases, trailing
    6.28  whitespace is unnecessary, invisible noise, but it is occasionally
    6.29 -problematic, and people tend to prefer to get rid of it.
    6.30 +problematic, and people often prefer to get rid of it.
    6.31  
    6.32  You can use either the \hook{precommit} or \hook{pretxncommit} hook to
    6.33  tell whether you have a trailing whitespace problem.  If you use the
    6.34 @@ -453,7 +466,58 @@
    6.35  hook that checks for trailing whitespace.  This hook is short, but not
    6.36  very helpful.  It exits with an error status if a change adds a line
    6.37  with trailing whitespace to any file, but does not print any
    6.38 -information that might help us to identify the offending file or line.
    6.39 +information that might help us to identify the offending file or
    6.40 +line.  It also has the nice property of not paying attention to
    6.41 +unmodified lines; only lines that introduce new trailing whitespace
    6.42 +cause problems.
    6.43 +
    6.44 +\begin{figure}[ht]
    6.45 +  \interaction{hook.ws.better}
    6.46 +  \caption{A better trailing whitespace hook}
    6.47 +  \label{ex:hook:ws.better}
    6.48 +\end{figure}
    6.49 +
    6.50 +The example of figure~\ref{ex:hook:ws.better} is much more complex,
    6.51 +but also more useful.  It parses a unified diff to see if any lines
    6.52 +add trailing whitespace, and prints the name of the file and the line
    6.53 +number of each such occurrence.  Even better, if the change adds
    6.54 +trailing whitespace, this hook saves the commit comment and prints the
    6.55 +name of the save file before exiting and telling Mercurial to roll the
    6.56 +transaction back, so you can use
    6.57 +\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the
    6.58 +saved commit message once you've corrected the problem.
    6.59 +
    6.60 +As a final aside, note in figure~\ref{ex:hook:ws.better} the use of
    6.61 +\command{perl}'s in-place editing feature to get rid of trailing
    6.62 +whitespace from a file.  This is concise and useful enough that I will
    6.63 +reproduce it here.
    6.64 +\begin{codesample2}
    6.65 +  perl -pi -e 's,\\s+$,,' filename
    6.66 +\end{codesample2}
    6.67 +
    6.68 +\section{Bundled hooks}
    6.69 +
    6.70 +Mercurial ships with several bundled hooks.  You can find them in the
    6.71 +\dirname{hgext} directory of a Mercurial source tree.  If you are
    6.72 +using a Mercurial binary package, the hooks will be located in the
    6.73 +\dirname{hgext} directory of wherever your package installer put
    6.74 +Mercurial.
    6.75 +
    6.76 +\subsection{\hgext{acl}---access control for parts of a repository}
    6.77 +
    6.78 +The \hgext{acl} extension lets you control which remote users are
    6.79 +allowed to push changesets to a networked server.  You can protect any
    6.80 +portion of a repository (including the entire repo), so that a
    6.81 +specific remote user can push changes that do not affect the protected
    6.82 +portion.
    6.83 +
    6.84 +This extension implements access control based on the identity of the
    6.85 +user performing a push, \emph{not} on who committed the changesets
    6.86 +they're pushing.  (If access control based on committer was to work
    6.87 +properly, it would require commits to be cryptographically signed,
    6.88 +which is an onerous and hence unusual policy to enforce.)
    6.89 +
    6.90 +XXX More help.
    6.91  
    6.92  \section{Hook reference}
    6.93  \label{sec:hook:ref}