1.1 --- a/en/ch10-hook.xml	Thu Mar 12 15:51:39 2009 +0800
     1.2 +++ b/en/ch10-hook.xml	Wed Mar 18 20:32:37 2009 +0800
     1.3 @@ -115,7 +115,7 @@
     1.4        <para>In some cases, you may be exposed to hooks that you did
     1.5  	not install yourself.  If you work with Mercurial on an
     1.6  	unfamiliar system, Mercurial will run hooks defined in that
     1.7 -	system's global <filename role="special"> /.hgrc</filename>\
     1.8 +	system's global <filename role="special">~/.hgrc</filename>
     1.9  	file.
    1.10        </para>
    1.11  
    1.12 @@ -175,8 +175,7 @@
    1.13        <para>In a corporate intranet, this is somewhat easier to
    1.14  	control, as you can for example provide a
    1.15  	<quote>standard</quote> installation of Mercurial on an NFS
    1.16 -	filesystem, and use a site-wide <filename role="special">
    1.17 -	  /.hgrc</filename>\ file to define hooks that all users will
    1.18 +	filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will
    1.19  	see.  However, this too has its limits; see below.
    1.20        </para>
    1.21  
    1.22 @@ -190,7 +189,7 @@
    1.23        </para>
    1.24  
    1.25        <para>If you deploy a system- or site-wide <filename
    1.26 -	  role="special"> /.hgrc</filename>\ file that defines some
    1.27 +	  role="special">~/.hgrc</filename> file that defines some
    1.28  	hooks, you should thus understand that your users can disable
    1.29  	or override those hooks.
    1.30        </para>
    1.31 @@ -203,7 +202,7 @@
    1.32  	want others to be able to work around.  For example, you may
    1.33  	have a requirement that every changeset must pass a rigorous
    1.34  	set of tests.  Defining this requirement via a hook in a
    1.35 -	site-wide <filename role="special"> /.hgrc</filename>\ won't
    1.36 +	site-wide <filename role="special">~/.hgrc</filename> won't
    1.37  	work for remote users on laptops, and of course local users
    1.38  	can subvert it at will by overriding the hook.
    1.39        </para>
    1.40 @@ -359,7 +358,7 @@
    1.41  
    1.42      <para>You add an entry to the <literal
    1.43  	role="rc-hooks">hooks</literal> section of your <filename
    1.44 -	role="special"> /.hgrc</filename>.  On the left is the name of
    1.45 +	role="special">~/.hgrc</filename>.  On the left is the name of
    1.46        the event to trigger on; on the right is the action to take.  As
    1.47        you can see, you can run an arbitrary shell command in a hook.
    1.48        Mercurial passes extra information to the hook using environment
    1.49 @@ -533,7 +532,7 @@
    1.50        <title>Writing an external hook</title>
    1.51  
    1.52        <para>When you define an external hook in your <filename
    1.53 -	  role="special"> /.hgrc</filename>\ and the hook is run, its
    1.54 +	  role="special">~/.hgrc</filename> and the hook is run, its
    1.55  	value is passed to your shell, which interprets it.  This
    1.56  	means that you can use normal shell constructs in the body of
    1.57  	the hook.
    1.58 @@ -561,7 +560,7 @@
    1.59      <sect2>
    1.60        <title>Telling Mercurial to use an in-process hook</title>
    1.61  
    1.62 -      <para>The <filename role="special"> /.hgrc</filename>\ syntax
    1.63 +      <para>The <filename role="special">~/.hgrc</filename> syntax
    1.64  	for defining an in-process hook is slightly different than for
    1.65  	an executable hook.  The value of the hook must start with the
    1.66  	text <quote><literal>python:</literal></quote>, and continue
    1.67 @@ -575,12 +574,12 @@
    1.68  	  work</quote>.
    1.69        </para>
    1.70  
    1.71 -      <para>The following <filename role="special"> /.hgrc</filename>\
    1.72 +      <para>The following <filename role="special">~/.hgrc</filename>
    1.73  	example snippet illustrates the syntax and meaning of the
    1.74  	notions we just described.
    1.75        </para>
    1.76 -      <programlisting>[hooks] commit.example =
    1.77 -	python:mymodule.submodule.myhook</programlisting>
    1.78 +      <programlisting>[hooks]
    1.79 +commit.example = python:mymodule.submodule.myhook</programlisting>
    1.80        <para>When Mercurial runs the <literal>commit.example</literal>
    1.81  	hook, it imports <literal>mymodule.submodule</literal>, looks
    1.82  	for the callable object named <literal>myhook</literal>, and
    1.83 @@ -595,7 +594,7 @@
    1.84  	the basic shape of the hook API:
    1.85        </para>
    1.86        <programlisting>def myhook(ui, repo, **kwargs):
    1.87 -	pass</programlisting>
    1.88 +    pass</programlisting>
    1.89        <para>The first argument to a Python hook is always a <literal
    1.90  	  role="py-mod-mercurial.ui">ui</literal> object.  The second
    1.91  	is a repository object; at the moment, it is always an
    1.92 @@ -745,8 +744,8 @@
    1.93  	  changeset, and roll back a group of changesets if they
    1.94  	  modify <quote>forbidden</quote> files.  Example:
    1.95  	</para>
    1.96 -	<programlisting>[hooks] pretxnchangegroup.acl =
    1.97 -	  python:hgext.acl.hook</programlisting>
    1.98 +	<programlisting>[hooks]
    1.99 +pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
   1.100  
   1.101  	<para>The <literal role="hg-ext">acl</literal> extension is
   1.102  	  configured using three sections.
   1.103 @@ -813,8 +812,10 @@
   1.104  	  to any file or directory except <filename
   1.105  	    class="directory">source/sensitive</filename>.
   1.106  	</para>
   1.107 -	<programlisting>[acl.allow] docs/** = docwriter [acl.deny]
   1.108 -	  source/sensitive/** = intern</programlisting>
   1.109 +	<programlisting>[acl.allow]
   1.110 +docs/** = docwriter
   1.111 +[acl.deny]
   1.112 +source/sensitive/** = intern</programlisting>
   1.113  
   1.114        </sect3>
   1.115        <sect3>
   1.116 @@ -827,9 +828,10 @@
   1.117  	  possible) to pass in the <option
   1.118  	    role="hg-opt-global">--debug</option> option, don't forget
   1.119  	  that you can enable debugging output in your <filename
   1.120 -	    role="special"> /.hgrc</filename>:
   1.121 -	</para>
   1.122 -	<programlisting>[ui] debug = true</programlisting>
   1.123 +	    role="special">~/.hgrc</filename>:
   1.124 +	</para>
   1.125 +	<programlisting>[ui]
   1.126 +debug = true</programlisting>
   1.127  	<para>With this enabled, the <literal
   1.128  	    role="hg-ext">acl</literal> hook will print enough
   1.129  	  information to let you figure out why it is allowing or
   1.130 @@ -893,12 +895,12 @@
   1.131  	  hook</title>
   1.132  
   1.133  	<para>You should configure this hook in your server's
   1.134 -	  <filename role="special"> /.hgrc</filename>\ as an <literal
   1.135 +	  <filename role="special">~/.hgrc</filename> as an <literal
   1.136  	    role="hook">incoming</literal> hook, for example as
   1.137  	  follows:
   1.138  	</para>
   1.139 -	<programlisting>[hooks] incoming.bugzilla =
   1.140 -	  python:hgext.bugzilla.hook</programlisting>
   1.141 +	<programlisting>[hooks]
   1.142 +incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
   1.143  
   1.144  	<para>Because of the specialised nature of this hook, and
   1.145  	  because Bugzilla was not written with this kind of
   1.146 @@ -915,7 +917,7 @@
   1.147  
   1.148  	<para>Configuration information for this hook lives in the
   1.149  	  <literal role="rc-bugzilla">bugzilla</literal> section of
   1.150 -	  your <filename role="special"> /.hgrc</filename>.
   1.151 +	  your <filename role="special">~/.hgrc</filename>.
   1.152  	</para>
   1.153  	<itemizedlist>
   1.154  	  <listitem><para><envar
   1.155 @@ -950,7 +952,7 @@
   1.156  	      password for the user you configured above.  This is
   1.157  	      stored as plain text, so you should make sure that
   1.158  	      unauthorised users cannot read the <filename
   1.159 -		role="special"> /.hgrc</filename>\ file where you
   1.160 +		role="special">~/.hgrc</filename> file where you
   1.161  	      store this information.
   1.162  	    </para>
   1.163  	  </listitem>
   1.164 @@ -1005,8 +1007,8 @@
   1.165  	  email address on the left, and a Bugzilla user name on the
   1.166  	  right.
   1.167  	</para>
   1.168 -	<programlisting>[usermap] jane.user@example.com =
   1.169 -	  jane</programlisting>
   1.170 +	<programlisting>[usermap]
   1.171 +jane.user@example.com = jane</programlisting>
   1.172  	<para>You can either keep the <literal
   1.173  	    role="rc-usermap">usermap</literal> data in a normal
   1.174  	  <filename role="special">~/.hgrc</filename>, or tell the
   1.175 @@ -1017,18 +1019,17 @@
   1.176  	  a user-modifiable repository.  This makes it possible to let
   1.177  	  your users maintain their own <envar
   1.178  	    role="rc-item-bugzilla">usermap</envar> entries.  The main
   1.179 -	  <filename role="special"> /.hgrc</filename>\ file might look
   1.180 +	  <filename role="special">~/.hgrc</filename> file might look
   1.181  	  like this:
   1.182  	</para>
   1.183 -	<programlisting># regular hgrc file refers to external usermap
   1.184 -	  file [bugzilla] usermap =
   1.185 -	  /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
   1.186 +	<programlisting># regular hgrc file refers to external usermap file
   1.187 +[bugzilla]
   1.188 +usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
   1.189  	<para>While the <filename>usermap</filename> file that it
   1.190  	  refers to might look like this:
   1.191  	</para>
   1.192 -	<programlisting># bugzilla-usermap.conf - inside a hg
   1.193 -	  repository [usermap] stephanie@example.com =
   1.194 -	  steph</programlisting>
   1.195 +	<programlisting># bugzilla-usermap.conf - inside a hg repository
   1.196 +[usermap] stephanie@example.com = steph</programlisting>
   1.197  
   1.198        </sect3>
   1.199        <sect3>
   1.200 @@ -1036,7 +1037,7 @@
   1.201  
   1.202  	<para>You can configure the text that this hook adds as a
   1.203  	  comment; you specify it in the form of a Mercurial template.
   1.204 -	  Several <filename role="special"> /.hgrc</filename>\ entries
   1.205 +	  Several <filename role="special">~/.hgrc</filename> entries
   1.206  	  (still in the <literal role="rc-bugzilla">bugzilla</literal>
   1.207  	  section) control this behaviour.
   1.208  	</para>
   1.209 @@ -1068,27 +1069,20 @@
   1.210  	<para>In addition, you can add a <envar
   1.211  	    role="rc-item-web">baseurl</envar> item to the <literal
   1.212  	    role="rc-web">web</literal> section of your <filename
   1.213 -	    role="special"> /.hgrc</filename>.  The <literal
   1.214 +	    role="special">~/.hgrc</filename>.  The <literal
   1.215  	    role="hg-ext">bugzilla</literal> hook will make this
   1.216  	  available when expanding a template, as the base string to
   1.217  	  use when constructing a URL that will let users browse from
   1.218  	  a Bugzilla comment to view a changeset.  Example:
   1.219  	</para>
   1.220 -	<programlisting>[web] baseurl =
   1.221 -	  http://hg.domain.com/</programlisting>
   1.222 +	<programlisting>[web]
   1.223 +baseurl = http://hg.domain.com/</programlisting>
   1.224  
   1.225  	<para>Here is an example set of <literal
   1.226  	    role="hg-ext">bugzilla</literal> hook config information.
   1.227  	</para>
   1.228 -	<programlisting>[bugzilla] host = bugzilla.example.com
   1.229 -	  password = mypassword version = 2.16 # server-side repos
   1.230 -	  live in /home/hg/repos, so strip 4 leading # separators
   1.231 -	  strip = 4 hgweb = http://hg.example.com/ usermap =
   1.232 -	  /home/hg/repos/notify/bugzilla.conf template = Changeset
   1.233 -	  {node|short}, made by {author} in the {webroot} repo, refers
   1.234 -	  to this bug.\\nFor complete details, see
   1.235 -	  {hgweb}{webroot}?cmd=changeset;node={node|short}\\nChangeset
   1.236 -	  description:\\n\\t{desc|tabindent}</programlisting>
   1.237 +
   1.238 +	&ch10-bugzilla-config.lst;
   1.239  
   1.240        </sect3>
   1.241        <sect3>
   1.242 @@ -1116,9 +1110,8 @@
   1.243  	  <command>sudo</command> command.  Here is an example entry
   1.244  	  for a <filename>sudoers</filename> file.
   1.245  	</para>
   1.246 -	<programlisting>hg_user = (httpd_user) NOPASSWD:
   1.247 -	  /var/www/html/bugzilla/processmail-wrapper
   1.248 -	  %s</programlisting>
   1.249 +	<programlisting>hg_user = (httpd_user)
   1.250 +NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
   1.251  	<para>This allows the <literal>hg_user</literal> user to run a
   1.252  	  <filename>processmail-wrapper</filename> program under the
   1.253  	  identity of <literal>httpd_user</literal>.
   1.254 @@ -1131,8 +1124,8 @@
   1.255  	  <filename>sudoers</filename> file.  The contents of the
   1.256  	  wrapper script are simple:
   1.257  	</para>
   1.258 -	<programlisting>#!/bin/sh cd `dirname $0` &amp;&amp;
   1.259 -	  ./processmail "$1" nobody@example.com</programlisting>
   1.260 +	<programlisting>#!/bin/sh
   1.261 +cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com</programlisting>
   1.262  	<para>It doesn't seem to matter what email address you pass to
   1.263  	  <filename>processmail</filename>.
   1.264  	</para>
   1.265 @@ -1143,8 +1136,7 @@
   1.266  	  push changes to the server.  The error message will look
   1.267  	  like this:
   1.268  	</para>
   1.269 -	<programlisting>cannot find bugzilla user id for
   1.270 -	  john.q.public@example.com</programlisting>
   1.271 +	<programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting>
   1.272  	<para>What this means is that the committer's address,
   1.273  	  <literal>john.q.public@example.com</literal>, is not a valid
   1.274  	  Bugzilla user name, nor does it have an entry in your
   1.275 @@ -1189,14 +1181,15 @@
   1.276  	  changesets (all those that arrived in a single pull or
   1.277  	  push).
   1.278  	</para>
   1.279 -	<programlisting>[hooks] # send one email per group of changes
   1.280 -	  changegroup.notify = python:hgext.notify.hook # send one
   1.281 -	  email per change incoming.notify =
   1.282 -	  python:hgext.notify.hook</programlisting>
   1.283 +	<programlisting>[hooks]
   1.284 +# send one email per group of changes
   1.285 +changegroup.notify = python:hgext.notify.hook
   1.286 +# send one email per change
   1.287 +incoming.notify = python:hgext.notify.hook</programlisting>
   1.288  
   1.289  	<para>Configuration information for this hook lives in the
   1.290  	  <literal role="rc-notify">notify</literal> section of a
   1.291 -	  <filename role="special"> /.hgrc</filename>\ file.
   1.292 +	  <filename role="special">~/.hgrc</filename> file.
   1.293  	</para>
   1.294  	<itemizedlist>
   1.295  	  <listitem><para><envar role="rc-item-notify">test</envar>:
   1.296 @@ -1214,7 +1207,7 @@
   1.297  	  <listitem><para><envar role="rc-item-notify">config</envar>:
   1.298  	      The path to a configuration file that contains
   1.299  	      subscription information.  This is kept separate from
   1.300 -	      the main <filename role="special"> /.hgrc</filename>\ so
   1.301 +	      the main <filename role="special">~/.hgrc</filename> so
   1.302  	      that you can maintain it in a repository of its own.
   1.303  	      People can then clone that repository, update their
   1.304  	      subscriptions, and push the changes back to your server.
   1.305 @@ -1273,35 +1266,14 @@
   1.306  	<para>Here is an example set of <literal
   1.307  	    role="hg-ext">notify</literal> configuration information.
   1.308  	</para>
   1.309 -	<programlisting>
   1.310 -	  [notify] # really send email test = false # subscriber data
   1.311 -	  lives in the notify repo config =
   1.312 -	  /home/hg/repos/notify/notify.conf # repos live in
   1.313 -	  /home/hg/repos on server, so strip 4 "/" chars strip = 4
   1.314 -	  template = X-Hg-Repo: {webroot} Subject: {webroot}:
   1.315 -	  {desc|firstline|strip} From: {author} changeset {node|short}
   1.316 -	  in {root} details:
   1.317 -	  {baseurl}{webroot}?cmd=changeset;node={node|short}
   1.318 -	  description: {desc|tabindent|strip} [web] baseurl =
   1.319 -	  http://hg.example.com/
   1.320 -	</programlisting>
   1.321 +
   1.322 +	&ch10-notify-config.lst;
   1.323  
   1.324  	<para>This will produce a message that looks like the
   1.325  	  following:
   1.326  	</para>
   1.327 -	<programlisting>
   1.328 -	  X-Hg-Repo: tests/slave Subject: tests/slave: Handle error
   1.329 -	  case when slave has no buffers Date: Wed,  2 Aug 2006
   1.330 -	  15:25:46 -0700 (PDT) changeset 3cba9bfe74b5 in
   1.331 -	  /home/hg/repos/tests/slave details:
   1.332 -	  http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 
   1.333 -	  description: Handle error case when slave has no buffers
   1.334 -	  diffs (54 lines): diff -r 9d95df7cf2ad -r 3cba9bfe74b5
   1.335 -	  include/tests.h --- a/include/tests.h      Wed Aug 02
   1.336 -	  15:19:52 2006 -0700 +++ b/include/tests.h      Wed Aug 02
   1.337 -	  15:25:26 2006 -0700 @@ -212,6 +212,15 @@ static __inline__
   1.338 -	  void test_headers(void *h) [...snip...]
   1.339 -	</programlisting>
   1.340 +
   1.341 +	&ch10-notify-config-mail.lst;
   1.342  
   1.343        </sect3>
   1.344        <sect3>
   1.345 @@ -1327,9 +1299,7 @@
   1.346        <para>An in-process hook is called with arguments of the
   1.347  	following form:
   1.348        </para>
   1.349 -      <programlisting>
   1.350 -	def myhook(ui, repo, **kwargs): pass
   1.351 -      </programlisting>
   1.352 +      <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting>
   1.353        <para>The <literal>ui</literal> parameter is a <literal
   1.354  	  role="py-mod-mercurial.ui">ui</literal> object. The
   1.355  	<literal>repo</literal> parameter is a <literal
   1.356 @@ -1373,7 +1343,7 @@
   1.357        <para>Note that changeset IDs are passed into Python hooks as
   1.358  	hexadecimal strings, not the binary hashes that Mercurial's
   1.359  	APIs normally use.  To convert a hash from hex to binary, use
   1.360 -	the \pymodfunc{mercurial.node}{bin} function.
   1.361 +	the <literal>bin</literal> function.
   1.362        </para>
   1.363  
   1.364      </sect2>
   1.365 @@ -1526,9 +1496,8 @@
   1.366  	<listitem><para><literal>node</literal>: A changeset ID.  The
   1.367  	    changeset ID of the first changeset in the group that was
   1.368  	    added.  All changesets between this and
   1.369 -	    \index{tags!<literal>tip</literal>}<literal>tip</literal>,
   1.370 -	    inclusive, were added by a single <command
   1.371 -	      role="hg-cmd">hg pull</command>, <command
   1.372 +	    <literal role="tag">tip</literal>, inclusive, were added by a single
   1.373 +	    <command role="hg-cmd">hg pull</command>, <command
   1.374  	      role="hg-cmd">hg push</command> or <command
   1.375  	      role="hg-cmd">hg unbundle</command>.
   1.376  	  </para>
   1.377 @@ -1880,7 +1849,7 @@
   1.378  	<listitem><para><literal>node</literal>: A changeset ID.  The
   1.379  	    changeset ID of the first changeset in the group that was
   1.380  	    added.  All changesets between this and
   1.381 -	    \index{tags!<literal>tip</literal>}<literal>tip</literal>,
   1.382 +	    <literal role="tag">tip</literal>,
   1.383  	    inclusive, were added by a single <command
   1.384  	      role="hg-cmd">hg pull</command>, <command
   1.385  	      role="hg-cmd">hg push</command> or <command