1.1 --- a/en/hook.tex	Sun Jul 23 23:25:52 2006 -0700
     1.2 +++ b/en/hook.tex	Tue Jul 25 00:18:31 2006 -0700
     1.3 @@ -415,7 +415,20 @@
     1.4  
     1.5  \section{Some hook examples}
     1.6  
     1.7 -\subsection{Enforcing coding guidelines in your own repository}
     1.8 +\subsection{Writing meaningful commit messages}
     1.9 +
    1.10 +It's hard to imagine a useful commit message being very short.  The
    1.11 +simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.run}
    1.12 +will prevent you from committing a changeset with a message that is
    1.13 +less than ten bytes long.
    1.14 +
    1.15 +\begin{figure}[ht]
    1.16 +  \interaction{hook.msglen.run}
    1.17 +  \caption{A hook that forbids overly short commit messages}
    1.18 +  \label{ex:hook:msglen.run}
    1.19 +\end{figure}
    1.20 +
    1.21 +\subsection{Checking for trailing whitespace}
    1.22  
    1.23  An interesting use of a commit-related hook is to help you to write
    1.24  cleaner code.  A simple example of ``cleaner code'' is the dictum that
    1.25 @@ -423,7 +436,7 @@
    1.26  whitespace''.  Trailing whitespace is a series of space and tab
    1.27  characters at the end of a line of text.  In most cases, trailing
    1.28  whitespace is unnecessary, invisible noise, but it is occasionally
    1.29 -problematic, and people tend to prefer to get rid of it.
    1.30 +problematic, and people often prefer to get rid of it.
    1.31  
    1.32  You can use either the \hook{precommit} or \hook{pretxncommit} hook to
    1.33  tell whether you have a trailing whitespace problem.  If you use the
    1.34 @@ -453,7 +466,58 @@
    1.35  hook that checks for trailing whitespace.  This hook is short, but not
    1.36  very helpful.  It exits with an error status if a change adds a line
    1.37  with trailing whitespace to any file, but does not print any
    1.38 -information that might help us to identify the offending file or line.
    1.39 +information that might help us to identify the offending file or
    1.40 +line.  It also has the nice property of not paying attention to
    1.41 +unmodified lines; only lines that introduce new trailing whitespace
    1.42 +cause problems.
    1.43 +
    1.44 +\begin{figure}[ht]
    1.45 +  \interaction{hook.ws.better}
    1.46 +  \caption{A better trailing whitespace hook}
    1.47 +  \label{ex:hook:ws.better}
    1.48 +\end{figure}
    1.49 +
    1.50 +The example of figure~\ref{ex:hook:ws.better} is much more complex,
    1.51 +but also more useful.  It parses a unified diff to see if any lines
    1.52 +add trailing whitespace, and prints the name of the file and the line
    1.53 +number of each such occurrence.  Even better, if the change adds
    1.54 +trailing whitespace, this hook saves the commit comment and prints the
    1.55 +name of the save file before exiting and telling Mercurial to roll the
    1.56 +transaction back, so you can use
    1.57 +\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the
    1.58 +saved commit message once you've corrected the problem.
    1.59 +
    1.60 +As a final aside, note in figure~\ref{ex:hook:ws.better} the use of
    1.61 +\command{perl}'s in-place editing feature to get rid of trailing
    1.62 +whitespace from a file.  This is concise and useful enough that I will
    1.63 +reproduce it here.
    1.64 +\begin{codesample2}
    1.65 +  perl -pi -e 's,\\s+$,,' filename
    1.66 +\end{codesample2}
    1.67 +
    1.68 +\section{Bundled hooks}
    1.69 +
    1.70 +Mercurial ships with several bundled hooks.  You can find them in the
    1.71 +\dirname{hgext} directory of a Mercurial source tree.  If you are
    1.72 +using a Mercurial binary package, the hooks will be located in the
    1.73 +\dirname{hgext} directory of wherever your package installer put
    1.74 +Mercurial.
    1.75 +
    1.76 +\subsection{\hgext{acl}---access control for parts of a repository}
    1.77 +
    1.78 +The \hgext{acl} extension lets you control which remote users are
    1.79 +allowed to push changesets to a networked server.  You can protect any
    1.80 +portion of a repository (including the entire repo), so that a
    1.81 +specific remote user can push changes that do not affect the protected
    1.82 +portion.
    1.83 +
    1.84 +This extension implements access control based on the identity of the
    1.85 +user performing a push, \emph{not} on who committed the changesets
    1.86 +they're pushing.  (If access control based on committer was to work
    1.87 +properly, it would require commits to be cryptographically signed,
    1.88 +which is an onerous and hence unusual policy to enforce.)
    1.89 +
    1.90 +XXX More help.
    1.91  
    1.92  \section{Hook reference}
    1.93  \label{sec:hook:ref}