1.1 --- a/en/99defs.tex	Mon Jul 17 00:00:12 2006 -0700
     1.2 +++ b/en/99defs.tex	Mon Jul 17 00:01:01 2006 -0700
     1.3 @@ -1,34 +1,92 @@
     1.4 +% Bug ID.
     1.5  \newcommand{\bug}[1]{\index{Mercurial issue!no.~#1}\href{http://www.selenic.com/mercurial/bts/issue#1}{Mercurial issue no.~#1}}
     1.6 +
     1.7 +% File name in the user's home directory.
     1.8  \newcommand{\tildefile}[1]{\texttt{\~{}/#1}}
     1.9 +
    1.10 +% File name.
    1.11  \newcommand{\filename}[1]{\texttt{#1}}
    1.12 +
    1.13 +% Directory name.
    1.14  \newcommand{\dirname}[1]{\texttt{#1}}
    1.15 +
    1.16 +% File name, with index entry.
    1.17 +% The ``s'' prefix comes from ``special''.
    1.18  \newcommand{\sfilename}[1]{\index{\texttt{#1} file}\texttt{#1}}
    1.19 +
    1.20 +% Directory name, with index entry.
    1.21  \newcommand{\sdirname}[1]{\index{\texttt{#1} directory}\texttt{#1}}
    1.22 +
    1.23 +% Mercurial extension.
    1.24  \newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
    1.25 +
    1.26 +% Mercurial command.
    1.27  \newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''}
    1.28 +
    1.29 +% Mercurial command, with arguments.
    1.30 +\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
    1.31 +
    1.32 +% Shell/system command.
    1.33  \newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}}
    1.34 +
    1.35 +% Shell/system command, with arguments.
    1.36  \newcommand{\cmdargs}[2]{\index{\texttt{#1} command}``\texttt{#1 #2}''}
    1.37 -\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
    1.38 +
    1.39 +% Mercurial command option.
    1.40  \newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
    1.41 +
    1.42 +% Mercurial global option.
    1.43 +\newcommand{\hggopt}[1]{\index{global options!\texttt{#1} option}\texttt{#1}}
    1.44 +
    1.45 +% Shell/system command option.
    1.46  \newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
    1.47 +
    1.48 +% Command option.
    1.49  \newcommand{\option}[1]{\texttt{#1}}
    1.50 +
    1.51 +% Software package.
    1.52  \newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}}
    1.53 +
    1.54 +% Section name from a hgrc file.
    1.55  \newcommand{\rcsection}[1]{\index{\texttt{hgrc} file!\texttt{#1} section}\texttt{[#1]}}
    1.56 +
    1.57 +% Named item in a hgrc file section.
    1.58  \newcommand{\rcitem}[2]{\index{\texttt{hgrc} file!\texttt{#1}
    1.59      section!\texttt{#2} entry}\texttt{#1.#2}}
    1.60 +
    1.61 +% hgrc file.
    1.62  \newcommand{\hgrc}{\index{\texttt{hgrc} file}\texttt{hgrc}}
    1.63 +
    1.64 +% Hook name.
    1.65  \newcommand{\hook}[1]{\index{\texttt{#1} hook}\index{hooks!\texttt{#1}}\texttt{#1}}
    1.66 +
    1.67 +% Environment variable.
    1.68  \newcommand{\envar}[1]{\index{\texttt{#1} environment
    1.69      variable}\index{environment variables!\texttt{#1}}\texttt{#1}}
    1.70  
    1.71 +% Python module.
    1.72 +\newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}}
    1.73 +
    1.74 +% Python class in a module.
    1.75 +\newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2}
    1.76 +    class}\texttt{#1.#2}}
    1.77 +
    1.78 +% Note: blah blah.
    1.79  \newsavebox{\notebox}
    1.80  \newenvironment{note}%
    1.81    {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}%
    1.82    {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
    1.83  
    1.84 +% Code sample, eating 4 characters of leading space.
    1.85  \DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}}
    1.86 +
    1.87 +% Code sample, eating 2 characters of leading space.
    1.88 +\DefineVerbatimEnvironment{codesample2}{Verbatim}{frame=single,gobble=2,numbers=left,commandchars=\\\{\}}
    1.89 +
    1.90 +% Interaction from the examples directory.
    1.91  \newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.out}}
    1.92  
    1.93 +% Graphics inclusion.
    1.94  \ifpdf
    1.95    \newcommand{\grafix}[1]{\includegraphics{#1}}
    1.96  \else

     2.1 --- a/en/hook.tex	Mon Jul 17 00:00:12 2006 -0700
     2.2 +++ b/en/hook.tex	Mon Jul 17 00:01:01 2006 -0700
     2.3 @@ -95,11 +95,18 @@
     2.4  comment contains a bug ID.  If it does, the commit can complete.  If
     2.5  not, the commit is rolled back.
     2.6  
     2.7 -\section{Choosing how to write a hook}
     2.8 -\label{sec:hook:impl}
     2.9 +\section{Writing your own hooks}
    2.10 +
    2.11 +When you are writing a hook, you might find it useful to run Mercurial
    2.12 +either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config
    2.13 +item set to ``true''.  When you do so, Mercurial will print a message
    2.14 +before it calls each hook.
    2.15 +
    2.16 +\subsection{Choosing how your hook should run}
    2.17 +\label{sec:hook:lang}
    2.18  
    2.19  You can write a hook either as a normal program---typically a shell
    2.20 -script---or as a Python function that is called within the Mercurial
    2.21 +script---or as a Python function that is executed within the Mercurial
    2.22  process.
    2.23  
    2.24  Writing a hook as an external program has the advantage that it
    2.25 @@ -119,7 +126,7 @@
    2.26  performance (probably the majority of hooks), a shell script is
    2.27  perfectly fine.
    2.28  
    2.29 -\section{Hook parameters}
    2.30 +\subsection{Hook parameters}
    2.31  \label{sec:hook:param}
    2.32  
    2.33  Mercurial calls each hook with a set of well-defined parameters.  In
    2.34 @@ -128,9 +135,82 @@
    2.35  environment variable.
    2.36  
    2.37  Whether your hook is written in Python or as a shell script, the
    2.38 -parameter names and values will be the same.  A boolean parameter will
    2.39 -be represented as a boolean value in Python, but as the number 1 (for
    2.40 -``true'') or 0 (for ``false'')
    2.41 +hook-specific parameter names and values will be the same.  A boolean
    2.42 +parameter will be represented as a boolean value in Python, but as the
    2.43 +number 1 (for ``true'') or 0 (for ``false'') as an environment
    2.44 +variable for an external hook.  If a hook parameter is named
    2.45 +\texttt{foo}, the keyword argument for a Python hook will also be
    2.46 +named \texttt{foo} Python, while the environment variable for an
    2.47 +external hook will be named \texttt{HG\_FOO}.
    2.48 +
    2.49 +\subsection{Hook return values and activity control}
    2.50 +
    2.51 +A hook that executes successfully must exit with a status of zero if
    2.52 +external, or return boolean ``false'' if in-process.  Failure is
    2.53 +indicated with a non-zero exit status from an external hook, or an
    2.54 +in-process hook returning boolean ``true''.  If an in-process hook
    2.55 +raises an exception, the hook is considered to have failed.
    2.56 +
    2.57 +For a hook that controls whether an activity can proceed, zero/false
    2.58 +means ``allow'', while non-zero/true/exception means ``deny''.
    2.59 +
    2.60 +\subsection{Writing an external hook}
    2.61 +
    2.62 +When you define an external hook in your \hgrc\ and the hook is run,
    2.63 +its value is passed to your shell, which interprets it.  This means
    2.64 +that you can use normal shell constructs in the body of the hook.
    2.65 +
    2.66 +An executable hook is always run with its current directory set to a
    2.67 +repository's root directory.
    2.68 +
    2.69 +Each hook parameter is passed in as an environment variable; the name
    2.70 +is upper-cased, and prefixed with the string ``\texttt{HG\_}''.
    2.71 +
    2.72 +With the exception of hook parameters, Mercurial does not set or
    2.73 +modify any environment variables when running a hook.  This is useful
    2.74 +to remember if you are writing a site-wide hook that may be run by a
    2.75 +number of different users with differing environment variables set.
    2.76 +In multi-user situations, you should not rely on environment variables
    2.77 +being set to the values you have in your environment when testing the
    2.78 +hook.
    2.79 +
    2.80 +\subsection{Telling Mercurial to use an in-process hook}
    2.81 +
    2.82 +The \hgrc\ syntax for defining an in-process hook is slightly
    2.83 +different than for an executable hook.  The value of the hook must
    2.84 +start with the text ``\texttt{python:}'', and continue with the
    2.85 +fully-qualified name of a callable object to use as the hook's value.
    2.86 +
    2.87 +The module in which a hook lives is automatically imported when a hook
    2.88 +is run.  So long as you have the module name and \envar{PYTHONPATH}
    2.89 +right, it should ``just work''.
    2.90 +
    2.91 +The following \hgrc\ example snippet illustrates the syntax and
    2.92 +meaning of the notions we just described.
    2.93 +\begin{codesample2}
    2.94 +  [hooks]
    2.95 +  commit.example = python:mymodule.submodule.myhook
    2.96 +\end{codesample2}
    2.97 +When Mercurial runs the \texttt{commit.example} hook, it imports
    2.98 +\texttt{mymodule.submodule}, looks for the callable object named
    2.99 +\texttt{myhook}, and calls it.
   2.100 +
   2.101 +\subsection{Writing an in-process hook}
   2.102 +
   2.103 +The simplest in-process hook does nothing, but illustrates the basic
   2.104 +shape of the hook API:
   2.105 +\begin{codesample2}
   2.106 +  def myhook(ui, repo, **kwargs):
   2.107 +      pass
   2.108 +\end{codesample2}
   2.109 +The first argument to a Python hook is always a
   2.110 +\pymodclass{mercurial.ui}{ui} object.  The second is a repository object;
   2.111 +at the moment, it is always an instance of
   2.112 +\pymodclass{mercurial.localrepo}{localrepository}.  Following these two
   2.113 +arguments are other keyword arguments.  Which ones are passed in
   2.114 +depends on the hook being called, but a hook can ignore arguments it
   2.115 +doesn't care about by dropping them into a keyword argument dict, as
   2.116 +with \texttt{**kwargs} above.
   2.117  
   2.118  
   2.119  %%% Local Variables: