Mercurial > hgbook

changeset 746:d0160b0b1a9e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge with http://hg.serpentine.com/mercurial/book
author Dongsheng Song <dongsheng.song@gmail.com>
date Wed, 18 Mar 2009 20:32:37 +0800
parents c2cefd9f9893 (current diff) 5bfa0df6aaed (diff)
children e0ac2341a861
files en/Makefile en/appB-mq-ref.xml en/ch00-preface.xml en/ch02-tour-basic.xml en/ch03-tour-merge.xml en/ch06-collab.xml en/ch08-branch.xml en/ch10-hook.xml en/ch11-template.xml en/ch12-mq.xml en/ch13-mq-collab.xml en/ch14-hgext.xml
diffstat 18 files changed, 369 insertions(+), 310 deletions(-) [+]
line wrap: on
line diff
--- a/en/Makefile	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/Makefile	Wed Mar 18 20:32:37 2009 +0800
@@ -35,7 +35,7 @@
 
 image-html := $(image-dot:%.dot=%.png) $(image-svg:%.svg=%.png) $(image-png)
 
-example-sources := \
+example-sources-by-name := \
 	backout \
 	bisect \
 	branching \
@@ -67,6 +67,10 @@
 	tour \
 	tour-merge-conflict
 
+example-sources := \
+	$(example-sources-by-name:%=examples/%) \
+	$(wildcard examples/ch*/*)
+
 obj-web := html
 obj-websup := html/support
 
@@ -162,11 +166,10 @@
 
 examples: $(example-prereqs) examples/.run
 
-examples/.run: $(example-sources:%=examples/%.run)
-	touch examples/.run
+examples/.run: $(example-sources)
+	cd examples && ./run-example
 
 examples/%.run: examples/% examples/run-example
-	cd examples && ./run-example $(notdir $<)
 
 clean:
 	-rm -rf dist html $(image-dot:%.dot=%.pdf) $(image-dot:%.dot=%.png) \
--- a/en/appB-mq-ref.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/appB-mq-ref.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -38,11 +38,12 @@
 
       <para>This command is shorthand for <command role="hg-cmd">hg
 	  commit --cwd .hg/patches</command>.</para>
-
-      <para>\subsection{<command
+    </sect2>
+    <sect2>
+	<title><command
 	  role="hg-ext-mq">qdelete</command>&emdash;delete a patch
 	from the <filename role="special">series</filename>
-	file}</para>
+	file}</title>
 
       <para>The <command role="hg-ext-mq">qdelete</command> command
 	removes the entry for a patch from the <filename
--- a/en/ch00-preface.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch00-preface.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -64,7 +64,7 @@
 
     <para>This book is licensed under the Open Publication License,
       and is produced entirely using Free Software tools.  It is
-      typeset with \LaTeX{}; illustrations are drawn and rendered with
+      typeset with DocBook XML.  Illustrations are drawn and rendered with
       <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
 
     <para>The complete source code for this book is published as a
--- a/en/ch02-tour-basic.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch02-tour-basic.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -551,7 +551,8 @@
 	    <filename role="special">.hgrc</filename> should look like
 	    this.</para>
 	<programlisting># This is a Mercurial configuration file.
-[ui] username = Firstname Lastname
+[ui]
+username = Firstname Lastname
 &lt;email.address@domain.net&gt;</programlisting>
 
 	<para>The <quote><literal>[ui]</literal></quote> line begins a
@@ -623,8 +624,8 @@
 
       <programlisting>
 changeset:   73:584af0e231be
-user: Censored Person &lt;censored.person@example.org&gt;
-date: Tue Sep 26 21:37:07 2006 -0700
+user:        Censored Person &lt;censored.person@example.org&gt;
+date:        Tue Sep 26 21:37:07 2006 -0700
 summary:     include buildmeister/commondefs. Add exports.</programlisting>
 
       <para>As far as the remainder of the contents of the
--- a/en/ch03-tour-merge.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch03-tour-merge.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -344,9 +344,9 @@
     <para>The process of merging changes as outlined above is
       straightforward, but requires running three commands in
       sequence.</para>
-    <programlisting>
-      hg pull hg merge hg commit -m 'Merged remote changes'
-    </programlisting>
+    <programlisting>hg pull
+hg merge
+hg commit -m 'Merged remote changes'</programlisting>
     <para>In the case of the final commit, you also need to enter a
       commit message, which is almost always going to be a piece of
       uninteresting <quote>boilerplate</quote> text.</para>
@@ -383,9 +383,8 @@
       <literal role="rc-extensions">extensions</literal> section. Then
       add a line that simply reads <quote><literal>fetch
 	</literal></quote>.</para>
-    <programlisting>
-      [extensions] fetch =
-    </programlisting>
+    <programlisting>[extensions]
+fetch =</programlisting>
     <para>(Normally, on the right-hand side of the
       <quote><literal>=</literal></quote> would appear the location of
       the extension, but since the <literal
--- a/en/ch06-collab.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch06-collab.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -539,8 +539,8 @@
 	</listitem>
 	<listitem><para>The <quote>:22</quote> identifies the port
 	    number to connect to the server on.  The default port is
-	    22, so you only need to specify this part if you're
-	    <emphasis>not</emphasis> using port 22.</para>
+	    22, so you only need to specify a colon and port number if
+	    you're <emphasis>not</emphasis> using port 22.</para>
 	</listitem>
 	<listitem><para>The remainder of the URL is the local path to
 	    the repository on the server.</para>
@@ -595,19 +595,20 @@
 	<listitem><para>If you have a high tolerance for pain, you can
 	    use the Cygwin port of OpenSSH.</para>
 	</listitem></itemizedlist>
-      <para>In either case, you'll need to edit your \hgini\ file to
+      <para>In either case, you'll need to edit your <filename
+      role="special">hg.ini</filename> file to
 	tell Mercurial where to find the actual client command.  For
 	example, if you're using PuTTY, you'll need to use the
 	<command>plink</command> command as a command-line ssh
 	client.</para>
-      <programlisting>[ui] ssh = C:/path/to/plink.exe -ssh -i
-	"C:/path/to/my/private/key"</programlisting>
+      <programlisting>[ui]
+ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"</programlisting>
 
       <note>
 	<para>  The path to <command>plink</command> shouldn't contain
 	  any whitespace characters, or Mercurial may not be able to
 	  run it correctly (so putting it in <filename
-	    class="directory">C:\\Program Files</filename> is probably
+	    class="directory">C:\Program Files</filename> is probably
 	  not a good idea).</para>
       </note>
 
@@ -784,7 +785,9 @@
 	your server, the next step is to ensure that Mercurial runs on
 	the server.  The following command should run
 	successfully:</para>
+
       <programlisting>ssh myserver hg version</programlisting>
+
       <para>If you see an error message instead of normal <command
 	  role="hg-cmd">hg version</command> output, this is usually
 	because you haven't installed Mercurial to <filename
@@ -841,17 +844,19 @@
       <para>Both <command>ssh</command> and <command>plink</command>
 	accept a <option role="cmd-opt-ssh">-C</option> option which
 	turns on compression.  You can easily edit your <filename
-	  role="special"> /.hgrc</filename>\ to enable compression for
+	  role="special">~/.hgrc</filename> to enable compression for
 	all of Mercurial's uses of the ssh protocol.</para>
-      <programlisting>[ui] ssh = ssh -C</programlisting>
+      <programlisting>[ui]
+ssh = ssh -C</programlisting>
 
       <para>If you use <command>ssh</command>, you can configure it to
 	always use compression when talking to your server.  To do
 	this, edit your <filename
 	  role="special">.ssh/config</filename> file (which may not
 	yet exist), as follows.</para>
-      <programlisting>Host hg Compression yes HostName
-	hg.example.com</programlisting>
+      <programlisting>Host hg
+  Compression yes
+  HostName hg.example.com</programlisting>
       <para>This defines an alias, <literal>hg</literal>.  When you
 	use it on the <command>ssh</command> command line or in a
 	Mercurial <literal>ssh</literal>-protocol URL, it will cause
@@ -926,8 +931,7 @@
 	directory, from which they can serve up web pages.  A file
 	named <filename>foo</filename> in this directory will be
 	accessible at a URL of the form
-	<literal>http://www.example.com/\
-	  {</literal>username/foo}.</para>
+	<literal>http://www.example.com/username/foo</literal>.</para>
 
       <para>To get started, find the <filename
 	  role="special">hgweb.cgi</filename> script that should be
@@ -939,8 +943,8 @@
       <para>You'll need to copy this script into your <filename
 	  class="directory">public_html</filename> directory, and
 	ensure that it's executable.</para>
-      <programlisting>cp .../hgweb.cgi ~/public_html chmod 755
-	~/public_html/hgweb.cgi</programlisting>
+      <programlisting>cp .../hgweb.cgi ~/public_html
+chmod 755 ~/public_html/hgweb.cgi</programlisting>
       <para>The <literal>755</literal> argument to
 	<command>chmod</command> is a little more general than just
 	making the script executable: it ensures that the script is
@@ -989,9 +993,9 @@
 	    class="directory">public_html</filename> directory, and
 	  read files under the latter too.  Here's a quick recipe to
 	  help you to make your permissions more appropriate.</para>
-	<programlisting>chmod 755 ~ find ~/public_html -type d -print0
-	  | xargs -0r chmod 755 find ~/public_html -type f -print0 |
-	  xargs -0r chmod 644</programlisting>
+	<programlisting>chmod 755 ~
+find ~/public_html -type d -print0 | xargs -0r chmod 755
+find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
 
 	<para>The other possibility with permissions is that you might
 	  get a completely empty window when you try to load the
@@ -1004,13 +1008,9 @@
 	  of CGI programs in your per-user web directory.  Here's
 	  Apache's default per-user configuration from my Fedora
 	  system.</para>
-	<programlisting>&lt;Directory /home/*/public_html&gt;
-	  AllowOverride FileInfo AuthConfig Limit Options MultiViews
-	  Indexes SymLinksIfOwnerMatch IncludesNoExec &lt;Limit GET
-	  POST OPTIONS&gt; Order allow,deny Allow from all
-	  &lt;/Limit&gt; &lt;LimitExcept GET POST OPTIONS&gt; Order
-	  deny,allow Deny from all &lt;/LimitExcept&gt;
-	  &lt;/Directory&gt;</programlisting>
+
+	&ch06-apache-config.lst;
+
 	<para>If you find a similar-looking
 	  <literal>Directory</literal> group in your Apache
 	  configuration, the directive to look at inside it is
@@ -1076,8 +1076,8 @@
 	  <literal>mod_userdir</literal>, both of which were disabled
 	  by default on my system.  I then added a few lines to the
 	  end of the config file, to configure these modules.</para>
-	<programlisting>userdir.path = "public_html" cgi.assign = (
-	  ".cgi" =&gt; "" )</programlisting>
+	<programlisting>userdir.path = "public_html"
+cgi.assign = (".cgi" =&gt; "" )</programlisting>
 	<para>With this done, <literal>lighttpd</literal> ran
 	  immediately for me.  If I had configured
 	  <literal>lighttpd</literal> before Apache, I'd almost
@@ -1112,8 +1112,8 @@
       <para>You'll need to copy this script into your <filename
 	  class="directory">public_html</filename> directory, and
 	ensure that it's executable.</para>
-      <programlisting>cp .../hgwebdir.cgi ~/public_html chmod 755
-	~/public_html ~/public_html/hgwebdir.cgi</programlisting>
+      <programlisting>cp .../hgwebdir.cgi ~/public_html
+chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
       <para>With basic configuration out of the way, try to visit
 	<ulink url="http://myhostname/
 	  myuser/hgwebdir.cgi">http://myhostname/
@@ -1139,8 +1139,8 @@
 	publish <emphasis>every</emphasis> repository under the
 	directories you name.  The section should look like
 	this:</para>
-      <programlisting>[collections] /my/root =
-	/my/root</programlisting>
+      <programlisting>[collections]
+/my/root = /my/root</programlisting>
       <para>Mercurial interprets this by looking at the directory name
 	on the <emphasis>right</emphasis> hand side of the
 	<quote><literal>=</literal></quote> sign; finding repositories
@@ -1199,8 +1199,9 @@
 	  to publish a specific list of repositories.  To do so,
 	  create a <literal>paths</literal> section, with contents of
 	  the following form.</para>
-	<programlisting>[paths] repo1 = /my/path/to/some/repo repo2 =
-	  /some/path/to/another</programlisting>
+	<programlisting>[paths]
+repo1 = /my/path/to/some/repo
+repo2 = /some/path/to/another</programlisting>
 	<para>In this case, the virtual path (the component that will
 	  appear in a URL) is on the left hand side of each
 	  definition, while the path to the repository is on the
@@ -1234,7 +1235,7 @@
 	you'll need to add an <envar
 	  role="rc-item-web">allow_archive</envar> item to the
 	<literal role="rc-web">web</literal> section of your <filename
-	  role="special"> /.hgrc</filename>.</para>
+	  role="special">~/.hgrc</filename>.</para>
 
     </sect2>
     <sect2>
@@ -1277,8 +1278,8 @@
 	    <envar role="rc-item-web">allow_archive</envar> entry at
 	    all, this feature will be disabled.  Here is an example of
 	    how to enable all three supported formats.</para>
-	  <programlisting>[web] allow_archive = bz2 gz
-	    zip</programlisting>
+	  <programlisting>[web]
+allow_archive = bz2 gz zip</programlisting>
 	</listitem>
 	<listitem><para><envar role="rc-item-web">allowpull</envar>:
 	    Boolean.  Determines whether the web interface allows
@@ -1296,9 +1297,9 @@
 	    address of a person or mailing list.  It often makes sense
 	    to place this entry in a repository's own <filename
 	      role="special">.hg/hgrc</filename> file, but it can make
-	    sense to use in a global <filename role="special">
-	      /.hgrc</filename>\ if every repository has a single
-	    maintainer.</para>
+	    sense to use in a global <filename
+	      role="special">~/.hgrc</filename> if every repository
+	    has a single maintainer.</para>
 	</listitem>
 	<listitem><para><envar role="rc-item-web">maxchanges</envar>:
 	    Integer.  The default maximum number of changesets to
@@ -1323,7 +1324,8 @@
 	    <xref linkend="chap.template"/> for details.
 	    Here, you can see how to enable the
 	    <literal>gitweb</literal> style.</para>
-	  <programlisting>[web] style = gitweb</programlisting>
+	  <programlisting>[web]
+style = gitweb</programlisting>
 	</listitem>
 	<listitem><para><envar role="rc-item-web">templates</envar>:
 	    Path.  The directory in which to search for template
@@ -1335,7 +1337,7 @@
 	configuration items in a <literal role="rc-web">web</literal>
 	section of the <filename
 	  role="special">hgweb.config</filename> file instead of a
-	<filename role="special"> /.hgrc</filename>\ file, for
+	<filename role="special">~/.hgrc</filename> file, for
 	convenience.  These items are <envar
 	  role="rc-item-web">motd</envar> and <envar
 	  role="rc-item-web">style</envar>.</para>
@@ -1346,8 +1348,7 @@
 	<para>A few <literal role="rc-web">web</literal> configuration
 	  items ought to be placed in a repository's local <filename
 	    role="special">.hg/hgrc</filename>, rather than a user's
-	  or global <filename role="special">
-	    /.hgrc</filename>.</para>
+	  or global <filename role="special">~/.hgrc</filename>.</para>
 	<itemizedlist>
 	  <listitem><para><envar
 		role="rc-item-web">description</envar>: String.  A
@@ -1367,7 +1368,7 @@
 
 	<para>Some of the items in the <literal
 	    role="rc-web">web</literal> section of a <filename
-	    role="special"> /.hgrc</filename>\ file are only for use
+	    role="special">~/.hgrc</filename> file are only for use
 	  with the <command role="hg-cmd">hg serve</command>
 	  command.</para>
 	<itemizedlist>
@@ -1401,8 +1402,8 @@
 
       </sect3>
       <sect3>
-	<title>Choosing the right <filename role="special">
-	    /.hgrc</filename>\ file to add <literal
+	<title>Choosing the right <filename
+	    role="special">~/.hgrc</filename> file to add <literal
 	    role="rc-web">web</literal> items to</title>
 
 	<para>It is important to remember that a web server like
@@ -1413,16 +1414,15 @@
 	  under that user ID.</para>
 
 	<para>If you add <literal role="rc-web">web</literal> items to
-	  your own personal <filename role="special">
-	    /.hgrc</filename>\ file, CGI scripts won't read that
-	  <filename role="special"> /.hgrc</filename>\ file.  Those
+	  your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
+	  <filename role="special">~/.hgrc</filename> file.  Those
 	  settings will thus only affect the behaviour of the <command
 	    role="hg-cmd">hg serve</command> command when you run it.
 	  To cause CGI scripts to see your settings, either create a
-	  <filename role="special"> /.hgrc</filename>\ file in the
+	  <filename role="special">~/.hgrc</filename> file in the
 	  home directory of the user ID that runs your web server, or
 	  add those settings to a system-wide <filename
-	    role="special"> /.hgrc</filename>\ file.</para>
+	    role="special">~/.hgrc</filename> file.</para>
 
 
       </sect3>
--- a/en/ch08-branch.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch08-branch.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -520,8 +520,8 @@
       <quote>stable</quote> branch.  Such a hook might look like this
       inside the shared repo's <filename role="special">
 	/.hgrc</filename>.</para>
-    <programlisting>[hooks] pretxnchangegroup.branch = hg heads
-      --template '{branches} ' | grep mybranch</programlisting>
+    <programlisting>[hooks]
+pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
 
   </sect1>
 </chapter>
--- a/en/ch10-hook.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch10-hook.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -115,7 +115,7 @@
       <para>In some cases, you may be exposed to hooks that you did
 	not install yourself.  If you work with Mercurial on an
 	unfamiliar system, Mercurial will run hooks defined in that
-	system's global <filename role="special"> /.hgrc</filename>\
+	system's global <filename role="special">~/.hgrc</filename>
 	file.
       </para>
 
@@ -175,8 +175,7 @@
       <para>In a corporate intranet, this is somewhat easier to
 	control, as you can for example provide a
 	<quote>standard</quote> installation of Mercurial on an NFS
-	filesystem, and use a site-wide <filename role="special">
-	  /.hgrc</filename>\ file to define hooks that all users will
+	filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will
 	see.  However, this too has its limits; see below.
       </para>
 
@@ -190,7 +189,7 @@
       </para>
 
       <para>If you deploy a system- or site-wide <filename
-	  role="special"> /.hgrc</filename>\ file that defines some
+	  role="special">~/.hgrc</filename> file that defines some
 	hooks, you should thus understand that your users can disable
 	or override those hooks.
       </para>
@@ -203,7 +202,7 @@
 	want others to be able to work around.  For example, you may
 	have a requirement that every changeset must pass a rigorous
 	set of tests.  Defining this requirement via a hook in a
-	site-wide <filename role="special"> /.hgrc</filename>\ won't
+	site-wide <filename role="special">~/.hgrc</filename> won't
 	work for remote users on laptops, and of course local users
 	can subvert it at will by overriding the hook.
       </para>
@@ -359,7 +358,7 @@
 
     <para>You add an entry to the <literal
 	role="rc-hooks">hooks</literal> section of your <filename
-	role="special"> /.hgrc</filename>.  On the left is the name of
+	role="special">~/.hgrc</filename>.  On the left is the name of
       the event to trigger on; on the right is the action to take.  As
       you can see, you can run an arbitrary shell command in a hook.
       Mercurial passes extra information to the hook using environment
@@ -533,7 +532,7 @@
       <title>Writing an external hook</title>
 
       <para>When you define an external hook in your <filename
-	  role="special"> /.hgrc</filename>\ and the hook is run, its
+	  role="special">~/.hgrc</filename> and the hook is run, its
 	value is passed to your shell, which interprets it.  This
 	means that you can use normal shell constructs in the body of
 	the hook.
@@ -561,7 +560,7 @@
     <sect2>
       <title>Telling Mercurial to use an in-process hook</title>
 
-      <para>The <filename role="special"> /.hgrc</filename>\ syntax
+      <para>The <filename role="special">~/.hgrc</filename> syntax
 	for defining an in-process hook is slightly different than for
 	an executable hook.  The value of the hook must start with the
 	text <quote><literal>python:</literal></quote>, and continue
@@ -575,12 +574,12 @@
 	  work</quote>.
       </para>
 
-      <para>The following <filename role="special"> /.hgrc</filename>\
+      <para>The following <filename role="special">~/.hgrc</filename>
 	example snippet illustrates the syntax and meaning of the
 	notions we just described.
       </para>
-      <programlisting>[hooks] commit.example =
-	python:mymodule.submodule.myhook</programlisting>
+      <programlisting>[hooks]
+commit.example = python:mymodule.submodule.myhook</programlisting>
       <para>When Mercurial runs the <literal>commit.example</literal>
 	hook, it imports <literal>mymodule.submodule</literal>, looks
 	for the callable object named <literal>myhook</literal>, and
@@ -595,7 +594,7 @@
 	the basic shape of the hook API:
       </para>
       <programlisting>def myhook(ui, repo, **kwargs):
-	pass</programlisting>
+    pass</programlisting>
       <para>The first argument to a Python hook is always a <literal
 	  role="py-mod-mercurial.ui">ui</literal> object.  The second
 	is a repository object; at the moment, it is always an
@@ -745,8 +744,8 @@
 	  changeset, and roll back a group of changesets if they
 	  modify <quote>forbidden</quote> files.  Example:
 	</para>
-	<programlisting>[hooks] pretxnchangegroup.acl =
-	  python:hgext.acl.hook</programlisting>
+	<programlisting>[hooks]
+pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
 
 	<para>The <literal role="hg-ext">acl</literal> extension is
 	  configured using three sections.
@@ -813,8 +812,10 @@
 	  to any file or directory except <filename
 	    class="directory">source/sensitive</filename>.
 	</para>
-	<programlisting>[acl.allow] docs/** = docwriter [acl.deny]
-	  source/sensitive/** = intern</programlisting>
+	<programlisting>[acl.allow]
+docs/** = docwriter
+[acl.deny]
+source/sensitive/** = intern</programlisting>
 
       </sect3>
       <sect3>
@@ -827,9 +828,10 @@
 	  possible) to pass in the <option
 	    role="hg-opt-global">--debug</option> option, don't forget
 	  that you can enable debugging output in your <filename
-	    role="special"> /.hgrc</filename>:
+	    role="special">~/.hgrc</filename>:
 	</para>
-	<programlisting>[ui] debug = true</programlisting>
+	<programlisting>[ui]
+debug = true</programlisting>
 	<para>With this enabled, the <literal
 	    role="hg-ext">acl</literal> hook will print enough
 	  information to let you figure out why it is allowing or
@@ -893,12 +895,12 @@
 	  hook</title>
 
 	<para>You should configure this hook in your server's
-	  <filename role="special"> /.hgrc</filename>\ as an <literal
+	  <filename role="special">~/.hgrc</filename> as an <literal
 	    role="hook">incoming</literal> hook, for example as
 	  follows:
 	</para>
-	<programlisting>[hooks] incoming.bugzilla =
-	  python:hgext.bugzilla.hook</programlisting>
+	<programlisting>[hooks]
+incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
 
 	<para>Because of the specialised nature of this hook, and
 	  because Bugzilla was not written with this kind of
@@ -915,7 +917,7 @@
 
 	<para>Configuration information for this hook lives in the
 	  <literal role="rc-bugzilla">bugzilla</literal> section of
-	  your <filename role="special"> /.hgrc</filename>.
+	  your <filename role="special">~/.hgrc</filename>.
 	</para>
 	<itemizedlist>
 	  <listitem><para><envar
@@ -950,7 +952,7 @@
 	      password for the user you configured above.  This is
 	      stored as plain text, so you should make sure that
 	      unauthorised users cannot read the <filename
-		role="special"> /.hgrc</filename>\ file where you
+		role="special">~/.hgrc</filename> file where you
 	      store this information.
 	    </para>
 	  </listitem>
@@ -1005,8 +1007,8 @@
 	  email address on the left, and a Bugzilla user name on the
 	  right.
 	</para>
-	<programlisting>[usermap] jane.user@example.com =
-	  jane</programlisting>
+	<programlisting>[usermap]
+jane.user@example.com = jane</programlisting>
 	<para>You can either keep the <literal
 	    role="rc-usermap">usermap</literal> data in a normal
 	  <filename role="special">~/.hgrc</filename>, or tell the
@@ -1017,18 +1019,17 @@
 	  a user-modifiable repository.  This makes it possible to let
 	  your users maintain their own <envar
 	    role="rc-item-bugzilla">usermap</envar> entries.  The main
-	  <filename role="special"> /.hgrc</filename>\ file might look
+	  <filename role="special">~/.hgrc</filename> file might look
 	  like this:
 	</para>
-	<programlisting># regular hgrc file refers to external usermap
-	  file [bugzilla] usermap =
-	  /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
+	<programlisting># regular hgrc file refers to external usermap file
+[bugzilla]
+usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
 	<para>While the <filename>usermap</filename> file that it
 	  refers to might look like this:
 	</para>
-	<programlisting># bugzilla-usermap.conf - inside a hg
-	  repository [usermap] stephanie@example.com =
-	  steph</programlisting>
+	<programlisting># bugzilla-usermap.conf - inside a hg repository
+[usermap] stephanie@example.com = steph</programlisting>
 
       </sect3>
       <sect3>
@@ -1036,7 +1037,7 @@
 
 	<para>You can configure the text that this hook adds as a
 	  comment; you specify it in the form of a Mercurial template.
-	  Several <filename role="special"> /.hgrc</filename>\ entries
+	  Several <filename role="special">~/.hgrc</filename> entries
 	  (still in the <literal role="rc-bugzilla">bugzilla</literal>
 	  section) control this behaviour.
 	</para>
@@ -1068,27 +1069,20 @@
 	<para>In addition, you can add a <envar
 	    role="rc-item-web">baseurl</envar> item to the <literal
 	    role="rc-web">web</literal> section of your <filename
-	    role="special"> /.hgrc</filename>.  The <literal
+	    role="special">~/.hgrc</filename>.  The <literal
 	    role="hg-ext">bugzilla</literal> hook will make this
 	  available when expanding a template, as the base string to
 	  use when constructing a URL that will let users browse from
 	  a Bugzilla comment to view a changeset.  Example:
 	</para>
-	<programlisting>[web] baseurl =
-	  http://hg.domain.com/</programlisting>
+	<programlisting>[web]
+baseurl = http://hg.domain.com/</programlisting>
 
 	<para>Here is an example set of <literal
 	    role="hg-ext">bugzilla</literal> hook config information.
 	</para>
-	<programlisting>[bugzilla] host = bugzilla.example.com
-	  password = mypassword version = 2.16 # server-side repos
-	  live in /home/hg/repos, so strip 4 leading # separators
-	  strip = 4 hgweb = http://hg.example.com/ usermap =
-	  /home/hg/repos/notify/bugzilla.conf template = Changeset
-	  {node|short}, made by {author} in the {webroot} repo, refers
-	  to this bug.\\nFor complete details, see
-	  {hgweb}{webroot}?cmd=changeset;node={node|short}\\nChangeset
-	  description:\\n\\t{desc|tabindent}</programlisting>
+
+	&ch10-bugzilla-config.lst;
 
       </sect3>
       <sect3>
@@ -1116,9 +1110,8 @@
 	  <command>sudo</command> command.  Here is an example entry
 	  for a <filename>sudoers</filename> file.
 	</para>
-	<programlisting>hg_user = (httpd_user) NOPASSWD:
-	  /var/www/html/bugzilla/processmail-wrapper
-	  %s</programlisting>
+	<programlisting>hg_user = (httpd_user)
+NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
 	<para>This allows the <literal>hg_user</literal> user to run a
 	  <filename>processmail-wrapper</filename> program under the
 	  identity of <literal>httpd_user</literal>.
@@ -1131,8 +1124,8 @@
 	  <filename>sudoers</filename> file.  The contents of the
 	  wrapper script are simple:
 	</para>
-	<programlisting>#!/bin/sh cd `dirname $0` &amp;&amp;
-	  ./processmail "$1" nobody@example.com</programlisting>
+	<programlisting>#!/bin/sh
+cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com</programlisting>
 	<para>It doesn't seem to matter what email address you pass to
 	  <filename>processmail</filename>.
 	</para>
@@ -1143,8 +1136,7 @@
 	  push changes to the server.  The error message will look
 	  like this:
 	</para>
-	<programlisting>cannot find bugzilla user id for
-	  john.q.public@example.com</programlisting>
+	<programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting>
 	<para>What this means is that the committer's address,
 	  <literal>john.q.public@example.com</literal>, is not a valid
 	  Bugzilla user name, nor does it have an entry in your
@@ -1189,14 +1181,15 @@
 	  changesets (all those that arrived in a single pull or
 	  push).
 	</para>
-	<programlisting>[hooks] # send one email per group of changes
-	  changegroup.notify = python:hgext.notify.hook # send one
-	  email per change incoming.notify =
-	  python:hgext.notify.hook</programlisting>
+	<programlisting>[hooks]
+# send one email per group of changes
+changegroup.notify = python:hgext.notify.hook
+# send one email per change
+incoming.notify = python:hgext.notify.hook</programlisting>
 
 	<para>Configuration information for this hook lives in the
 	  <literal role="rc-notify">notify</literal> section of a
-	  <filename role="special"> /.hgrc</filename>\ file.
+	  <filename role="special">~/.hgrc</filename> file.
 	</para>
 	<itemizedlist>
 	  <listitem><para><envar role="rc-item-notify">test</envar>:
@@ -1214,7 +1207,7 @@
 	  <listitem><para><envar role="rc-item-notify">config</envar>:
 	      The path to a configuration file that contains
 	      subscription information.  This is kept separate from
-	      the main <filename role="special"> /.hgrc</filename>\ so
+	      the main <filename role="special">~/.hgrc</filename> so
 	      that you can maintain it in a repository of its own.
 	      People can then clone that repository, update their
 	      subscriptions, and push the changes back to your server.
@@ -1273,35 +1266,14 @@
 	<para>Here is an example set of <literal
 	    role="hg-ext">notify</literal> configuration information.
 	</para>
-	<programlisting>
-	  [notify] # really send email test = false # subscriber data
-	  lives in the notify repo config =
-	  /home/hg/repos/notify/notify.conf # repos live in
-	  /home/hg/repos on server, so strip 4 "/" chars strip = 4
-	  template = X-Hg-Repo: {webroot} Subject: {webroot}:
-	  {desc|firstline|strip} From: {author} changeset {node|short}
-	  in {root} details:
-	  {baseurl}{webroot}?cmd=changeset;node={node|short}
-	  description: {desc|tabindent|strip} [web] baseurl =
-	  http://hg.example.com/
-	</programlisting>
+
+	&ch10-notify-config.lst;
 
 	<para>This will produce a message that looks like the
 	  following:
 	</para>
-	<programlisting>
-	  X-Hg-Repo: tests/slave Subject: tests/slave: Handle error
-	  case when slave has no buffers Date: Wed,  2 Aug 2006
-	  15:25:46 -0700 (PDT) changeset 3cba9bfe74b5 in
-	  /home/hg/repos/tests/slave details:
-	  http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 
-	  description: Handle error case when slave has no buffers
-	  diffs (54 lines): diff -r 9d95df7cf2ad -r 3cba9bfe74b5
-	  include/tests.h --- a/include/tests.h      Wed Aug 02
-	  15:19:52 2006 -0700 +++ b/include/tests.h      Wed Aug 02
-	  15:25:26 2006 -0700 @@ -212,6 +212,15 @@ static __inline__
-	  void test_headers(void *h) [...snip...]
-	</programlisting>
+
+	&ch10-notify-config-mail.lst;
 
       </sect3>
       <sect3>
@@ -1327,9 +1299,7 @@
       <para>An in-process hook is called with arguments of the
 	following form:
       </para>
-      <programlisting>
-	def myhook(ui, repo, **kwargs): pass
-      </programlisting>
+      <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting>
       <para>The <literal>ui</literal> parameter is a <literal
 	  role="py-mod-mercurial.ui">ui</literal> object. The
 	<literal>repo</literal> parameter is a <literal
@@ -1373,7 +1343,7 @@
       <para>Note that changeset IDs are passed into Python hooks as
 	hexadecimal strings, not the binary hashes that Mercurial's
 	APIs normally use.  To convert a hash from hex to binary, use
-	the \pymodfunc{mercurial.node}{bin} function.
+	the <literal>bin</literal> function.
       </para>
 
     </sect2>
@@ -1526,9 +1496,8 @@
 	<listitem><para><literal>node</literal>: A changeset ID.  The
 	    changeset ID of the first changeset in the group that was
 	    added.  All changesets between this and
-	    \index{tags!<literal>tip</literal>}<literal>tip</literal>,
-	    inclusive, were added by a single <command
-	      role="hg-cmd">hg pull</command>, <command
+	    <literal role="tag">tip</literal>, inclusive, were added by a single
+	    <command role="hg-cmd">hg pull</command>, <command
 	      role="hg-cmd">hg push</command> or <command
 	      role="hg-cmd">hg unbundle</command>.
 	  </para>
@@ -1880,7 +1849,7 @@
 	<listitem><para><literal>node</literal>: A changeset ID.  The
 	    changeset ID of the first changeset in the group that was
 	    added.  All changesets between this and
-	    \index{tags!<literal>tip</literal>}<literal>tip</literal>,
+	    <literal role="tag">tip</literal>,
 	    inclusive, were added by a single <command
 	      role="hg-cmd">hg pull</command>, <command
 	      role="hg-cmd">hg push</command> or <command
--- a/en/ch11-template.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch11-template.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -44,11 +44,12 @@
       <title>Setting a default style</title>
 
       <para>You can modify the output style that Mercurial will use
-	for every command by editing your <filename role="special">
-	  /.hgrc</filename>\ file, naming the style you would prefer
-	to use.</para>
+	for every command by editing your <filename
+	  role="special">~/.hgrc</filename> file, naming the style
+	you would prefer to use.</para>
 
-      <programlisting>[ui] style = compact</programlisting>
+      <programlisting>[ui]
+style = compact</programlisting>
 
       <para>If you write a style of your own, you can use it by either
 	providing the path to your style file, or copying your style
@@ -212,27 +213,27 @@
       single replacement, as described below.</para>
 
     <itemizedlist>
-      <listitem><para><literal>\textbackslash\textbackslash</literal>:
+      <listitem><para><literal>\</literal>:
 	  Backslash, <quote><literal>\</literal></quote>, ASCII
 	  134.</para>
       </listitem>
-      <listitem><para><literal>\textbackslash n</literal>: Newline,
+      <listitem><para><literal>\n</literal>: Newline,
 	  ASCII 12.</para>
       </listitem>
-      <listitem><para><literal>\textbackslash r</literal>: Carriage
+      <listitem><para><literal>\r</literal>: Carriage
 	  return, ASCII 15.</para>
       </listitem>
-      <listitem><para><literal>\textbackslash t</literal>: Tab, ASCII
+      <listitem><para><literal>\t</literal>: Tab, ASCII
 	  11.</para>
       </listitem>
-      <listitem><para><literal>\textbackslash v</literal>: Vertical
+      <listitem><para><literal>\v</literal>: Vertical
 	  tab, ASCII 13.</para>
       </listitem>
-      <listitem><para><literal>\textbackslash {</literal>: Open curly
+      <listitem><para><literal>{</literal>: Open curly
 	  brace, <quote><literal>{</literal></quote>, ASCII
 	  173.</para>
       </listitem>
-      <listitem><para><literal>\textbackslash }</literal>: Close curly
+      <listitem><para><literal>}</literal>: Close curly
 	  brace, <quote><literal>}</literal></quote>, ASCII
 	  175.</para>
       </listitem></itemizedlist>
@@ -548,24 +549,19 @@
       <itemizedlist>
 	<listitem><para>The first component is simply Mercurial's way
 	    of saying <quote>I am giving up</quote>.</para>
-	  <programlisting>___abort___: broken.style:1: parse
-	    error</programlisting>
+	  <programlisting>___abort___: broken.style:1: parse error</programlisting>
 	</listitem>
 	<listitem><para>Next comes the name of the style file that
 	    contains the error.</para>
-	  <programlisting>
-	    abort: ___broken.style___:1: parse error
-	  </programlisting>
+	  <programlisting>abort: ___broken.style___:1: parse error</programlisting>
 	</listitem>
 	<listitem><para>Following the file name is the line number
 	    where the error was encountered.</para>
-	  <programlisting>abort: broken.style:___1___: parse
-	    error</programlisting>
+	  <programlisting>abort: broken.style:___1___: parse error</programlisting>
 	</listitem>
 	<listitem><para>Finally, a description of what went
 	    wrong.</para>
-	  <programlisting>abort: broken.style:1: ___parse
-	    error___</programlisting>
+	  <programlisting>abort: broken.style:1: ___parse error___</programlisting>
 	</listitem>
 	<listitem><para>The description of the problem is not always
 	    clear (as in this case), but even when it is cryptic, it
--- a/en/ch12-mq.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch12-mq.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -256,7 +256,8 @@
 	role="home">~/.hgrc</filename> file, and add the lines
       below.</para>
 
-    <programlisting>[extensions] hgext.mq =</programlisting>
+    <programlisting>[extensions]
+hgext.mq =</programlisting>
 
     <para>Once the extension is enabled, it will make a number of new
       commands available.  To verify that the extension is working,
@@ -870,11 +871,9 @@
 	      role="hg-opt-update">-C</option></command> to override
 	  the patches you have pushed.</para>
       </listitem>
-      <listitem><para>Merge all patches using
-	  \hgcmdargs{qpush}{<option role="hg-ext-mq-cmd-qpush-opt">hg
-	    -m</option> <option role="hg-ext-mq-cmd-qpush-opt">hg
-	    -a</option>}.  The <option
-	    role="hg-ext-mq-cmd-qpush-opt">hg -m</option> option to
+      <listitem><para>Merge all patches using <command>hg qpush -m
+	    -a</command>.  The <option
+	    role="hg-ext-mq-cmd-qpush-opt">-m</option> option to
 	  <command role="hg-ext-mq">qpush</command> tells MQ to
 	  perform a three-way merge if the patch fails to
 	  apply.</para>
@@ -931,10 +930,8 @@
       changeset ID will also accept the name of an applied patch.  MQ
       augments the tags normally in the repository with an eponymous
       one for each applied patch.  In addition, the special tags
-      \index{tags!special tag
-      names!<literal>qbase</literal>}<literal>qbase</literal> and
-      \index{tags!special tag
-      names!<literal>qtip</literal>}<literal>qtip</literal> identify
+      <literal role="tag">qbase</literal> and
+      <literal role="tag">qtip</literal> identify
       the <quote>bottom-most</quote> and topmost applied patches,
       respectively.</para>
 
@@ -943,17 +940,14 @@
     <itemizedlist>
       <listitem><para>Want to patchbomb a mailing list with your
 	  latest series of changes?</para>
-	<programlisting>hg email qbase:qtip
-	</programlisting>
+	<programlisting>hg email qbase:qtip</programlisting>
 	<para>  (Don't know what <quote>patchbombing</quote> is?  See
 	  section <xref linkend="sec.hgext.patchbomb"/>.)</para>
       </listitem>
       <listitem><para>Need to see all of the patches since
 	  <literal>foo.patch</literal> that have touched files in a
 	  subdirectory of your tree?</para>
-	<programlisting>
-	  hg log -r foo.patch:qtip <emphasis>subdir</emphasis>
-	</programlisting>
+	<programlisting>hg log -r foo.patch:qtip subdir</programlisting>
       </listitem>
     </itemizedlist>
 
@@ -1081,8 +1075,7 @@
 	snippet in your <filename
 	  role="home">~/.bashrc</filename>.</para>
 
-      <programlisting>alias mq=`hg -R $(hg
-	root)/.hg/patches'</programlisting>
+      <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>
 
       <para>You can then issue commands of the form <command>mq
 	  pull</command> from the main repository.</para>
--- a/en/ch13-mq-collab.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch13-mq-collab.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -460,8 +460,9 @@
 	  role="hg-ext">extdiff</literal> extension in the usual way,
 	by adding a line to the <literal
 	  role="rc-extensions">extensions</literal> section of your
-	<filename role="special"> /.hgrc</filename>.</para>
-      <programlisting>[extensions] extdiff =</programlisting>
+	<filename role="special">~/.hgrc</filename>.</para>
+      <programlisting>[extensions]
+extdiff =</programlisting>
       <para>The <command>interdiff</command> command expects to be
 	passed the names of two files, but the <literal
 	  role="hg-ext">extdiff</literal> extension passes the program
@@ -477,22 +478,20 @@
       <para>With the <filename role="special">hg-interdiff</filename>
 	program in your shell's search path, you can run it as
 	follows, from inside an MQ patch directory:</para>
-      <programlisting>hg extdiff -p hg-interdiff -r A:B
-	my-change.patch</programlisting>
+      <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting>
       <para>Since you'll probably want to use this long-winded command
 	a lot, you can get <literal role="hg-ext">hgext</literal> to
 	make it available as a normal Mercurial command, again by
-	editing your <filename role="special">
-	  /.hgrc</filename>.</para>
-      <programlisting>[extdiff] cmd.interdiff =
-	hg-interdiff</programlisting>
+	editing your <filename
+	  role="special">~/.hgrc</filename>.</para>
+      <programlisting>[extdiff]
+cmd.interdiff = hg-interdiff</programlisting>
       <para>This directs <literal role="hg-ext">hgext</literal> to
 	make an <literal>interdiff</literal> command available, so you
 	can now shorten the previous invocation of <command
 	  role="hg-ext-extdiff">extdiff</command> to something a
 	little more wieldy.</para>
-      <programlisting>hg interdiff -r A:B
-	my-change.patch</programlisting>
+      <programlisting>hg interdiff -r A:B my-change.patch</programlisting>
 
       <note>
 	<para>  The <command>interdiff</command> command works well
--- a/en/ch14-hgext.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/ch14-hgext.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -166,11 +166,10 @@
     <orderedlist>
       <listitem><para>Clone the Python <literal>inotify</literal>
 	  binding repository.  Build and install it.</para>
-	<programlisting>
-	  hg clone http://hg.kublai.com/python/inotify cd inotify
-	  python setup.py build --force sudo python setup.py install
-	  --skip-build
-	</programlisting>
+	<programlisting>hg clone http://hg.kublai.com/python/inotify
+cd inotify
+python setup.py build --force
+sudo python setup.py install --skip-build</programlisting>
       </listitem>
       <listitem><para>Clone the <filename
 	    class="directory">crew</filename> Mercurial repository.
@@ -178,12 +177,9 @@
 	  repository so that Mercurial Queues will be able to apply
 	  patches to your cope of the <filename
 	    class="directory">crew</filename> repository.</para>
-	<programlisting>
-	  hg clone http://hg.intevation.org/mercurial/crew hg clone
-	  crew inotify hg clone
-	  http://hg.kublai.com/mercurial/patches/inotify
-	  inotify/.hg/patches
-	</programlisting>
+	<programlisting>hg clone http://hg.intevation.org/mercurial/crew
+hg clone crew inotify
+hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting>
       </listitem>
       <listitem><para>Make sure that you have the Mercurial Queues
 	  extension, <literal role="hg-ext">mq</literal>, enabled.  If
@@ -197,9 +193,8 @@
 	  using the <option role="hg-ext-mq-cmd-qpush-opt">hg
 	    -a</option> option to the <command
 	    role="hg-ext-mq">qpush</command> command.</para>
-	<programlisting>
-	  cd inotify hg qpush -a
-	</programlisting>
+	<programlisting>cd inotify
+hg qpush -a</programlisting>
       </listitem>
       <listitem><para>  If you get an error message from <command
 	    role="hg-ext-mq">qpush</command>, you should not continue.
@@ -207,16 +202,14 @@
       </listitem>
       <listitem><para>Build and install the patched version of
 	  Mercurial.</para>
-	<programlisting>
-	  python setup.py build --force sudo python setup.py install
-	  --skip-build
-	</programlisting>
+	<programlisting>python setup.py build --force
+sudo python setup.py install --skip-build</programlisting>
       </listitem>
     </orderedlist>
     <para>Once you've build a suitably patched version of Mercurial,
       all you need to do to enable the <literal
 	role="hg-ext">inotify</literal> extension is add an entry to
-      your <filename role="special"> /.hgrc</filename>.</para>
+      your <filename role="special">~/.hgrc</filename>.</para>
     <programlisting>[extensions] inotify =</programlisting>
     <para>When the <literal role="hg-ext">inotify</literal> extension
       is enabled, Mercurial will automatically and transparently start
@@ -280,9 +273,10 @@
     <para>The <literal role="hg-ext">extdiff</literal> extension is
       bundled with Mercurial, so it's easy to set up.  In the <literal
 	role="rc-extensions">extensions</literal> section of your
-      <filename role="special"> /.hgrc</filename>, simply add a
+      <filename role="special">~/.hgrc</filename>, simply add a
       one-line entry to enable the extension.</para>
-    <programlisting>[extensions] extdiff =</programlisting>
+    <programlisting>[extensions]
+extdiff =</programlisting>
     <para>This introduces a command named <command
 	role="hg-ext-extdiff">extdiff</command>, which by default uses
       your system's <command>diff</command> command to generate a
@@ -372,15 +366,16 @@
 	<emphasis>new</emphasis> commands that will invoke your diff
 	viewer with exactly the right options.</para>
 
-      <para>All you need to do is edit your <filename role="special">
-	  /.hgrc</filename>, and add a section named <literal
-	  role="rc-extdiff">extdiff</literal>.  Inside this section,
-	you can define multiple commands.  Here's how to add a
-	<literal>kdiff3</literal> command.  Once you've defined this,
-	you can type <quote><literal>hg kdiff3</literal></quote> and
-	the <literal role="hg-ext">extdiff</literal> extension will
-	run <command>kdiff3</command> for you.</para>
-      <programlisting>[extdiff] cmd.kdiff3 =</programlisting>
+      <para>All you need to do is edit your <filename
+	  role="special">~/.hgrc</filename>, and add a section named
+	<literal role="rc-extdiff">extdiff</literal>.  Inside this
+	section, you can define multiple commands.  Here's how to add
+	a <literal>kdiff3</literal> command.  Once you've defined
+	this, you can type <quote><literal>hg kdiff3</literal></quote>
+	and the <literal role="hg-ext">extdiff</literal> extension
+	will run <command>kdiff3</command> for you.</para>
+      <programlisting>[extdiff]
+cmd.kdiff3 =</programlisting>
       <para>If you leave the right hand side of the definition empty,
 	as above, the <literal role="hg-ext">extdiff</literal>
 	extension uses the name of the command you defined as the name
@@ -388,7 +383,8 @@
 	be the same.  Here, we define a command named
 	<quote><literal>hg wibble</literal></quote>, which runs
 	<command>kdiff3</command>.</para>
-      <programlisting>[extdiff] cmd.wibble = kdiff3</programlisting>
+      <programlisting>[extdiff]
+ cmd.wibble = kdiff3</programlisting>
 
       <para>You can also specify the default options that you want to
 	invoke your diff viewing program with.  The prefix to use is
@@ -397,8 +393,9 @@
 	defines a <quote><literal>hg vimdiff</literal></quote> command
 	that runs the <command>vim</command> editor's
 	<literal>DirDiff</literal> extension.</para>
-      <programlisting>[extdiff] cmd.vimdiff = vim opts.vimdiff = -f
-	'+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting>
+      <programlisting>[extdiff]
+ cmd.vimdiff = vim
+opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting>
 
     </sect2>
   </sect1>
@@ -433,7 +430,8 @@
 	role="hg-ext">patchbomb</literal> extension takes just one or
       two lines in your <filename role="special">
 	/.hgrc</filename>.</para>
-    <programlisting>[extensions] patchbomb =</programlisting>
+    <programlisting>[extensions]
+patchbomb =</programlisting>
     <para>Once you've enabled the extension, you will have a new
       command available, named <command
 	role="hg-ext-patchbomb">email</command>.</para>
--- a/en/examples/auto-snippets.xml	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/examples/auto-snippets.xml	Wed Mar 18 20:32:37 2009 +0800
@@ -1,3 +1,7 @@
+<!ENTITY ch06-apache-config.lst SYSTEM "results/ch06-apache-config.lst.out">
+<!ENTITY ch10-bugzilla-config.lst SYSTEM "results/ch10-bugzilla-config.lst.out">
+<!ENTITY ch10-notify-config-mail.lst SYSTEM "results/ch10-notify-config-mail.lst.out">
+<!ENTITY ch10-notify-config.lst SYSTEM "results/ch10-notify-config.lst.out">
 <!ENTITY interaction.backout.init SYSTEM "results/backout.init.out">
 <!ENTITY interaction.backout.manual.backout SYSTEM "results/backout.manual.backout.out">
 <!ENTITY interaction.backout.manual.cat SYSTEM "results/backout.manual.cat.out">
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/ch06/apache-config.lst	Wed Mar 18 20:32:37 2009 +0800
@@ -0,0 +1,11 @@
+<Directory /home/*/public_html>
+  AllowOverride FileInfo AuthConfig Limit
+  Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
+  <Limit GET POST OPTIONS>
+    Order allow,deny
+    Allow from all
+  </Limit>
+  <LimitExcept GET POST OPTIONS>
+    Order deny,allow Deny from all
+  </LimitExcept>
+</Directory>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/ch10/bugzilla-config.lst	Wed Mar 18 20:32:37 2009 +0800
@@ -0,0 +1,14 @@
+[bugzilla]
+host = bugzilla.example.com
+password = mypassword version = 2.16
+# server-side repos live in /home/hg/repos, so strip 4 leading
+# separators
+strip = 4
+hgweb = http://hg.example.com/
+usermap = /home/hg/repos/notify/bugzilla.conf
+template = Changeset {node|short}, made by {author} in the {webroot}
+  repo, refers to this bug.\n
+  For complete details, see
+  {hgweb}{webroot}?cmd=changeset;node={node|short}\n
+  Changeset description:\n
+  \t{desc|tabindent}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/ch10/notify-config-mail.lst	Wed Mar 18 20:32:37 2009 +0800
@@ -0,0 +1,18 @@
+X-Hg-Repo: tests/slave
+Subject: tests/slave: Handle error case when slave has no buffers
+Date: Wed,  2 Aug 2006 15:25:46 -0700 (PDT)
+
+changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
+
+details:
+http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 
+
+description: Handle error case when slave has no buffers
+
+diffs (54 lines):
+diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
+--- a/include/tests.h      Wed Aug 02 15:19:52 2006 -0700
++++ b/include/tests.h      Wed Aug 02 15:25:26 2006 -0700
+@@ -212,6 +212,15 @@ static __inline__
+void test_headers(void *h)
+[...snip...]
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/ch10/notify-config.lst	Wed Mar 18 20:32:37 2009 +0800
@@ -0,0 +1,19 @@
+[notify]
+# really send email
+test = false
+# subscriber data lives in the notify repo
+config = /home/hg/repos/notify/notify.conf
+# repos live in /home/hg/repos on server, so strip 4 "/" chars
+strip = 4
+template = X-Hg-Repo: {webroot}\n
+  Subject: {webroot}: {desc|firstline|strip}\n
+  From: {author}
+  \n\n
+  changeset {node|short} in {root}
+  \n\ndetails:
+  {baseurl}{webroot}?cmd=changeset;node={node|short}
+  description: {desc|tabindent|strip}
+
+[web]
+baseurl =
+http://hg.example.com/
--- a/en/examples/run-example	Wed Mar 18 19:50:36 2009 +0800
+++ b/en/examples/run-example	Wed Mar 18 20:32:37 2009 +0800
@@ -7,6 +7,7 @@
 import cStringIO
 import errno
 import getopt
+import glob
 import os
 import pty
 import re
@@ -54,10 +55,89 @@
     return None
         
 def result_name(name):
-    dirname, basename = os.path.split(name)
-    return os.path.join(dirname, 'results', basename)
+    return os.path.normpath(os.path.join('results', name.replace(os.sep, '-')))
+
+def wopen(name):
+    path = os.path.dirname(name)
+    if path:
+        try:
+            os.makedirs(path)
+        except OSError, err:
+            if err.errno != errno.EEXIST:
+                raise
+    return open(name, 'w')
 
 class example:
+    entities = dict.fromkeys(l.rstrip() for l in open('auto-snippets.xml'))
+
+    def __init__(self, name, verbose, keep_change):
+        self.name = os.path.normpath(name)
+        self.verbose = verbose
+        self.keep_change = keep_change
+        
+    def status(self, s):
+        sys.stdout.write(s)
+        if not s.endswith('\n'):
+            sys.stdout.flush()
+
+    def rename_output(self, base, ignore=[]):
+        mangle_re = re.compile('(?:' + '|'.join(ignore) + ')')
+        def mangle(s):
+            return mangle_re.sub('', s)
+        def matchfp(fp1, fp2):
+            while True:
+                s1 = mangle(fp1.readline())
+                s2 = mangle(fp2.readline())
+                if cmp(s1, s2):
+                    break
+                if not s1:
+                    return True
+            return False
+
+        oldname = result_name(base + '.out')
+        tmpname = result_name(base + '.tmp')
+        errname = result_name(base + '.err')
+        errfp = open(errname, 'w+')
+        for line in open(tmpname):
+            errfp.write(mangle_re.sub('', line))
+        os.rename(tmpname, result_name(base + '.lxo'))
+        errfp.seek(0)
+        try:
+            oldfp = open(oldname)
+        except IOError, err:
+            if err.errno != errno.ENOENT:
+                raise
+            os.rename(errname, oldname)
+            return False
+        if matchfp(oldfp, errfp):
+            os.unlink(errname)
+            return False
+        else:
+            print >> sys.stderr, '\nOutput of %s has changed!' % base
+            if self.keep_change:
+                os.rename(errname, oldname)
+                return False
+            else:
+                os.system('diff -u %s %s 1>&2' % (oldname, errname))
+            return True
+
+class static_example(example):
+    def run(self):
+        self.status('running %s\n' % self.name)
+        s = open(self.name).read().rstrip()
+        s = s.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
+        ofp = wopen(result_name(self.name + '.tmp'))
+        ofp.write('<programlisting>')
+        ofp.write(s)
+        ofp.write('</programlisting>\n')
+        ofp.close()
+        self.rename_output(self.name)
+        norm = self.name.replace(os.sep, '-')
+        example.entities[
+            '<!ENTITY %s SYSTEM "results/%s.out">' % (norm, norm)] = 1
+
+
+class shell_example(example):
     shell = '/usr/bin/env bash'
     ps1 = '__run_example_ps1__ '
     ps2 = '__run_example_ps2__ '
@@ -65,12 +145,8 @@
     
     timeout = 10
 
-    entities = dict.fromkeys(l.rstrip() for l in open('auto-snippets.xml'))
-
     def __init__(self, name, verbose, keep_change):
-        self.name = name
-        self.verbose = verbose
-        self.keep_change = keep_change
+        example.__init__(self, name, verbose, keep_change)
         self.poll = select.poll()
 
     def parse(self):
@@ -83,11 +159,6 @@
                 yield cfp.getvalue()
                 cfp.seek(0)
                 cfp.truncate()
-        
-    def status(self, s):
-        sys.stdout.write(s)
-        if not s.endswith('\n'):
-            sys.stdout.flush()
 
     def send(self, s):
         if self.verbose:
@@ -153,12 +224,12 @@
         maybe_unlink(self.name + '.run')
 
         rcfile = os.path.join(tmpdir, '.hgrc')
-        rcfp = open(rcfile, 'w')
+        rcfp = wopen(rcfile)
         print >> rcfp, '[ui]'
         print >> rcfp, "username = Bryan O'Sullivan <bos@serpentine.com>"
         
         rcfile = os.path.join(tmpdir, '.bashrc')
-        rcfp = open(rcfile, 'w')
+        rcfp = wopen(rcfile)
         print >> rcfp, 'PS1="%s"' % self.ps1
         print >> rcfp, 'PS2="%s"' % self.ps2
         print >> rcfp, 'unset HISTFILE'
@@ -248,8 +319,7 @@
                                     'SYSTEM "results/%s.out">'
                                     % (norm, norm)] = 1
                                 read_hint = ofp_basename + ' '
-                                ofp = open(result_name(ofp_basename + '.tmp'),
-                                           'w')
+                                ofp = wopen(result_name(ofp_basename + '.tmp'))
                                 ofp.write('<screen>')
                             else:
                                 ofp = None
@@ -297,52 +367,11 @@
                     elif os.WIFSIGNALED(rc):
                         print >> sys.stderr, '(signal %s)' % os.WTERMSIG(rc)
                 else:
-                    open(result_name(self.name + '.run'), 'w')
+                    wopen(result_name(self.name + '.run'))
                 return err
         finally:
             shutil.rmtree(tmpdir)
 
-    def rename_output(self, base, ignore):
-        mangle_re = re.compile('(?:' + '|'.join(ignore) + ')')
-        def mangle(s):
-            return mangle_re.sub('', s)
-        def matchfp(fp1, fp2):
-            while True:
-                s1 = mangle(fp1.readline())
-                s2 = mangle(fp2.readline())
-                if cmp(s1, s2):
-                    break
-                if not s1:
-                    return True
-            return False
-
-        oldname = result_name(base + '.out')
-        tmpname = result_name(base + '.tmp')
-        errname = result_name(base + '.err')
-        errfp = open(errname, 'w+')
-        for line in open(tmpname):
-            errfp.write(mangle_re.sub('', line))
-        os.rename(tmpname, result_name(base + '.lxo'))
-        errfp.seek(0)
-        try:
-            oldfp = open(oldname)
-        except IOError, err:
-            if err.errno != errno.ENOENT:
-                raise
-            os.rename(errname, oldname)
-            return False
-        if matchfp(oldfp, errfp):
-            os.unlink(errname)
-            return False
-        else:
-            print >> sys.stderr, '\nOutput of %s has changed!' % base
-            if self.keep_change:
-                os.rename(errname, oldname)
-                return False
-            else:
-                os.system('diff -u %s %s 1>&2' % (oldname, errname))
-            return True
-
 def print_help(exit, msg=None):
     if msg:
         print >> sys.stderr, 'Error:', msg
@@ -383,18 +412,20 @@
                 print >> sys.stderr, '%s: %s' % (a, err.strerror)
                 errs += 1
                 continue
-            if stat.S_ISREG(st.st_mode) and st.st_mode & 0111:
-                if example(a, verbose, keep_change).run():
-                    errs += 1
+            if stat.S_ISREG(st.st_mode):
+                if st.st_mode & 0111:
+                    if shell_example(a, verbose, keep_change).run():
+                        errs += 1
+                elif a.endswith('.lst'):
+                    static_example(a, verbose, keep_change).run()
             else:
                 print >> sys.stderr, '%s: not a file, or not executable' % a
                 errs += 1
     elif run_all:
-        names = os.listdir(path)
+        names = glob.glob("*") + glob.glob("app*/*") + glob.glob("ch*/*")
         names.sort()
         for name in names:
-            if name == 'run-example' or name.startswith('.'): continue
-            if name.endswith('~'): continue
+            if name == 'run-example' or name.endswith('~'): continue
             pathname = os.path.join(path, name)
             try:
                 st = os.lstat(pathname)
@@ -403,14 +434,17 @@
                 if err.errno != errno.ENOENT:
                     raise
                 continue
-            if stat.S_ISREG(st.st_mode) and st.st_mode & 0111:
-                if example(pathname, verbose, keep_change).run():
-                    errs += 1
-        print >> open(os.path.join(path, '.run'), 'w'), time.asctime()
+            if stat.S_ISREG(st.st_mode):
+                if st.st_mode & 0111:
+                    if shell_example(pathname, verbose, keep_change).run():
+                        errs += 1
+                elif pathname.endswith('.lst'):
+                    static_example(pathname, verbose, keep_change).run()
+        print >> wopen(os.path.join(path, '.run')), time.asctime()
     else:
         print_help(1, msg='no test names given, and --all not provided')
 
-    fp = open('auto-snippets.xml', 'w')
+    fp = wopen('auto-snippets.xml')
     for key in sorted(example.entities.iterkeys()):
         print >> fp, key
     fp.close()