* Convert to DocBook 5.

* Use Jing for RelaxNG validation, xmllint seems buggy.

23 files changed, 364 insertions, 299 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 079872f64431..e06fbf5cd323 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -1,7 +1,5 @@
-ENV = SGML_CATALOG_FILES=$(docbookcatalog)
-
-XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs
-XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
+XMLLINT = $(xmllint) $(xmlflags)
+XSLTPROC = $(xsltproc) $(xmlflags) \
  --param section.autolabel 1 \
  --param section.label.includes.component.label 1 \
  --param html.stylesheet \'style.css\' \
@@ -24,7 +22,12 @@ MANUAL_SRCS = manual.xml introduction.xml installation.xml \
  style.css images
 
 manual.is-valid: $(MANUAL_SRCS) version.txt
-	$(XMLLINT) --xinclude $< | $(XMLLINT) --noout --nonet --valid -
+#	$(XMLLINT) --xinclude $< | $(XMLLINT) --noout --nonet --relaxng $(docbookrng)/docbook.rng -
+	if test "$(jing)" != "false"; then \
+		$(XMLLINT) --xinclude $< | $(jing) $(docbookrng)/docbook.rng /dev/stdin; \
+	else \
+		echo "Not validating."; \
+	fi
 	touch $@
 
 version.txt:
diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml
index 9f8faae96ba8..d21603559ddc 100644
--- a/doc/manual/bugs.xml
+++ b/doc/manual/bugs.xml
@@ -1,4 +1,8 @@
-<appendix><title>Bugs / To-Do</title>
+<appendix xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Bugs / To-Do</title>
+
 
 <itemizedlist>
 
@@ -15,11 +19,12 @@ implemented; generations form a linear sequence.</para></listitem>
 is already possible to do build management using Nix (by writing
 builders that perform appropriate build steps), but the Nix expression
 language is not yet powerful enough to make this pleasant (?).  The
-language should be extended with features from the <ulink
-url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>.
-Another interesting idea is to write a <command>make</command>
-implementation that uses Nix as a back-end to support <ulink
-url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
+language should be extended with features from the <link
+xlink:href='http://www.cs.uu.nl/~eelco/maak/'>Maak build
+manager</link>.  Another interesting idea is to write a
+<command>make</command> implementation that uses Nix as a back-end to
+support <link
+xlink:href='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</link>
 build files.</para></listitem>
 
 <listitem><para>For security, <command>nix-push</command> manifests
diff --git a/doc/manual/build-farm.xml b/doc/manual/build-farm.xml
index c86e19cdf3b9..cfca63f360cd 100644
--- a/doc/manual/build-farm.xml
+++ b/doc/manual/build-farm.xml
@@ -1,4 +1,9 @@
-<chapter id='chap-build-farm'><title>Setting up a Build Farm</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id='chap-build-farm'>
+
+<title>Setting up a Build Farm</title>
+
 
 <para>This chapter provides some sketchy information on how to set up
 a Nix-based build farm.  Nix is particularly suited as a basis for a
@@ -50,13 +55,13 @@ build farm, since:
 
 <para>TODO</para>
 
-<para>The sources of the Nix build farm are at <ulink
-url='https://svn.cs.uu.nl:12443/repos/trace/release/trunk' />.</para>
+<para>The sources of the Nix build farm are at <link
+xlink:href='https://svn.cs.uu.nl:12443/repos/trace/release/trunk'/>.</para>
 
 </section>
 
 
-<section id='sec-distributed-builds'><title>Setting up distributed builds</title>
+<section xml:id='sec-distributed-builds'><title>Setting up distributed builds</title>
 
 <para>You can enable distributed builds by setting the environment
 variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix
@@ -70,7 +75,7 @@ the documentation of the <link
 linkend="envar-build-hook"><envar>NIX_BUILD_HOOK</envar>
 variable</link>.</para>
 
-<example id='ex-remote-systems'><title>Remote machine configuration:
+<example xml:id='ex-remote-systems'><title>Remote machine configuration:
 <filename>remote-systems.conf</filename></title>
 <programlisting>
 nix@mcflurry.labs.cs.uu.nl  powerpc-darwin  /home/nix/.ssh/id_quarterpounder_auto  2
@@ -79,8 +84,8 @@ nix@scratchy.labs.cs.uu.nl  i686-linux      /home/nix/.ssh/id_scratchy_auto
 </example>
 
 <para>An example build hook can be found in the Nix build farm
-sources: <ulink
-url='https://svn.cs.uu.nl:12443/repos/trace/release/trunk/common/distributed/build-remote.pl'
+sources: <link
+xlink:href='https://svn.cs.uu.nl:12443/repos/trace/release/trunk/common/distributed/build-remote.pl'
 />.  It should be suitable for most purposes, with maybe some minor
 adjustments.  It uses <command>ssh</command> and
 <command>rsync</command> to copy the build inputs and outputs and
diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml
index 9ff34324f20f..61b096520b4b 100644
--- a/doc/manual/conf-file.xml
+++ b/doc/manual/conf-file.xml
@@ -1,4 +1,9 @@
-<sect1 id="sec-conf-file"><title>Nix configuration file</title>
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-conf-file">
+
+<title>Nix configuration file</title>
+
 
 <para>A number of persistent settings of Nix are stored in the file
 <filename><replaceable>prefix</replaceable>/etc/nix/nix.conf</filename>.
@@ -7,7 +12,7 @@ This file is a list of <literal><replaceable>name</replaceable> =
 Comments start with a <literal>#</literal> character.  An example
 configuration file is shown in <xref linkend="ex-nix-conf" />.</para>
 
-<example id='ex-nix-conf'><title>Nix configuration file</title>
+<example xml:id='ex-nix-conf'><title>Nix configuration file</title>
 
 <programlisting>
 gc-keep-outputs = true       # Nice for developers
@@ -20,7 +25,7 @@ env-keep-derivations = false
 
 <variablelist>
 
-  <varlistentry id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term>
+  <varlistentry xml:id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term>
 
     <listitem><para>If <literal>true</literal>, the garbage collector
     will keep the outputs of non-garbage derivations.  If
@@ -36,7 +41,7 @@ env-keep-derivations = false
 
   </varlistentry>
 
-  <varlistentry id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term>
+  <varlistentry xml:id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term>
 
     <listitem><para>If <literal>true</literal> (default), the garbage
     collector will keep the derivations from which non-garbage store
@@ -52,7 +57,7 @@ env-keep-derivations = false
 
   </varlistentry>
 
-  <varlistentry id="conf-gc-reserved-space"><term><literal>gc-reserved-space</literal></term>
+  <varlistentry xml:id="conf-gc-reserved-space"><term><literal>gc-reserved-space</literal></term>
 
     <listitem><para>This option specifies how much space should be
     reserved in normal use so that the garbage collector can run
@@ -99,4 +104,5 @@ env-keep-derivations = false
 
 </para>
 
-</sect1>
+
+</section>
diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml
index 2d25d3b283da..75ce39f40654 100644
--- a/doc/manual/env-common.xml
+++ b/doc/manual/env-common.xml
@@ -1,4 +1,9 @@
-<sect1 id="sec-common-env"><title>Common environment variables</title>
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-common-env">
+
+<title>Common environment variables</title>
+
 
 <para>Most Nix commands interpret the following environment variables:</para>
 
@@ -118,7 +123,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 </varlistentry>
 
 
-<varlistentry id="envar-build-hook"><term><envar>NIX_BUILD_HOOK</envar></term>
+<varlistentry xml:id="envar-build-hook"><term><envar>NIX_BUILD_HOOK</envar></term>
 
   <listitem>
 
@@ -271,4 +276,5 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 
 </variablelist>
 
-</sect1>
+
+</section>
diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml
index a659e7e4a90b..e76f99a2616f 100644
--- a/doc/manual/glossary.xml
+++ b/doc/manual/glossary.xml
@@ -1,9 +1,13 @@
-<appendix><title>Glossary</title>
+<appendix xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Glossary</title>
+
 
 <glosslist>
 
 
-<glossentry id="gloss-derivation"><glossterm>derivation</glossterm>
+<glossentry xml:id="gloss-derivation"><glossterm>derivation</glossterm>
 
   <glossdef><para>A description of a build action.  The result of a
   derivation is a store object.  Derivations are typically specified
@@ -46,7 +50,7 @@
 </glossentry>
 
 
-<glossentry id="gloss-substitute"><glossterm>substitute</glossterm>
+<glossentry xml:id="gloss-substitute"><glossterm>substitute</glossterm>
 
   <glossdef><para>A substitute is a command invocation stored in the
   Nix database that describes how to build a store object, bypassing
@@ -79,7 +83,7 @@
 </glossentry>
 
 
-<glossentry id="gloss-reference"><glossterm>reference</glossterm>
+<glossentry xml:id="gloss-reference"><glossterm>reference</glossterm>
 
   <glossdef><para>A store path <varname>P</varname> is said to have a
   reference to a store path <varname>Q</varname> if the store object
@@ -92,7 +96,7 @@
 </glossentry>
 
 
-<glossentry id="gloss-closure"><glossterm>closure</glossterm>
+<glossentry xml:id="gloss-closure"><glossterm>closure</glossterm>
 
   <glossdef><para>The closure of a store path is the set of store
   paths that are directly or indirectly “reachable” from that store
@@ -108,14 +112,14 @@
 </glossentry>
 
 
-<glossentry id="gloss-output-path"><glossterm>output path</glossterm>
+<glossentry xml:id="gloss-output-path"><glossterm>output path</glossterm>
 
   <glossdef><para>A store path produced by a derivation.</para></glossdef>
 
 </glossentry>
 
 
-<glossentry id="gloss-deriver"><glossterm>deriver</glossterm>
+<glossentry xml:id="gloss-deriver"><glossterm>deriver</glossterm>
 
   <glossdef><para>The deriver of an <link
   linkend="gloss-output-path">output path</link> is the store
@@ -124,7 +128,7 @@
 </glossentry>
 
 
-<glossentry id="gloss-validity"><glossterm>validity</glossterm>
+<glossentry xml:id="gloss-validity"><glossterm>validity</glossterm>
 
   <glossdef><para>A store path is considered
   <emphasis>valid</emphasis> if it exists in the file system, is
@@ -134,7 +138,7 @@
 </glossentry>
 
 
-<glossentry id="gloss-user-env"><glossterm>user environment</glossterm>
+<glossentry xml:id="gloss-user-env"><glossterm>user environment</glossterm>
 
   <glossdef><para>An automatically generated store object that
   consists of a set of symlinks to “active” applications, i.e., other
@@ -147,7 +151,7 @@
 </glossentry>
 
 
-<glossentry id="gloss-profile"><glossterm>profile</glossterm>
+<glossentry xml:id="gloss-profile"><glossterm>profile</glossterm>
 
   <glossdef><para>A symlink to the current <link
   linkend="gloss-user-env">user environment</link> of a user, e.g.,
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 491d044cde8a..483c24e98715 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -1,33 +1,38 @@
-<chapter id='chap-installation'><title>Installation</title>
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="chap-installation">
 
+<title>Installation</title>
 
-<sect1><title>Obtaining Nix</title>
 
-<para>The easiest way to obtain Nix is to download a <ulink
-url='http://www.cs.uu.nl/groups/ST/Trace/Nix'>source
-distribution</ulink>.  RPMs for Red Hat, SuSE, and Fedore Core are
+<section><info><title>Obtaining Nix</title></info>
+
+<para>The easiest way to obtain Nix is to download a <link xlink:href="http://www.cs.uu.nl/groups/ST/Trace/Nix">source
+distribution</link>.  RPMs for Red Hat, SuSE, and Fedore Core are
 also available.</para>
 
 <para>Alternatively, the most recent sources of Nix can be obtained
-from its <ulink
-url='https://svn.cs.uu.nl:12443/repos/trace/nix/trunk'>Subversion
-repository</ulink>.  For example, the following command will check out
-the latest revision into a directory called <filename>nix</filename>:</para>
+from its <link
+xlink:href="https://svn.cs.uu.nl:12443/repos/trace/nix/trunk">Subversion
+repository</link>.  For example, the following command will check out
+the latest revision into a directory called
+<filename>nix</filename>:</para>
 
 <screen>
 $ svn checkout https://svn.cs.uu.nl:12443/repos/trace/nix/trunk nix</screen>
 
-<para>Likewise, specific releases can be obtained from the <ulink
-url='https://svn.cs.uu.nl:12443/repos/trace/nix/tags'>tags
-directory</ulink> of the repository.  If you don't have Subversion,
-you can also download an automatically generated <ulink
-url='https://svn.cs.uu.nl:12443/dist/trace/'>compressed
-tar-file</ulink> of the head revision of the trunk.</para>
+<para>Likewise, specific releases can be obtained from the <link
+xlink:href="https://svn.cs.uu.nl:12443/repos/trace/nix/tags">tags
+directory</link> of the repository.  If you don't have Subversion, you
+can also download an automatically generated <link
+xlink:href="https://svn.cs.uu.nl:12443/dist/trace/">compressed
+tar-file</link> of the head revision of the trunk.</para>
 
-</sect1>
+</section>
 
 
-<sect1><title>Prerequisites</title>
+<section><info><title>Prerequisites</title></info>
 
 <para>The following prerequisites only apply when you build from
 source.  Binary releases (e.g., RPMs) have no prerequisites.</para>
@@ -39,10 +44,11 @@ and higher should work.</para>
 <command>xmllint</command> and <command>xsltproc</command> programs,
 which are part of the <literal>libxml2</literal> and
 <literal>libxslt</literal> packages, respectively.  You also need the
-<ulink url='http://docbook.sourceforge.net/projects/xsl/'>DocBook XSL
-stylesheets</ulink> and optionally the <ulink
-url='http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip'>
-DocBook XML 4.2 DTD</ulink>.  Note that these are only required if you
+<link
+xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook XSL
+stylesheets</link> and optionally the <link
+xlink:href="http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip">
+DocBook XML 4.2 DTD</link>.  Note that these are only required if you
 modify the manual sources or when you are building from the Subversion
 repository.</para>
 
@@ -50,11 +56,11 @@ repository.</para>
 of Bison and Flex are required.  (This is because Nix needs GLR
 support in Bison and reentrancy support in Flex.)  For Bison, you need
 version 1.875c or higher (1.875 does <emphasis>not</emphasis> work),
-which can be obtained from the <ulink
-url='ftp://alpha.gnu.org/pub/gnu/bison'>GNU FTP server</ulink>.  For
-Flex, you need version 2.5.31, which is available on <ulink
-url='http://lex.sourceforge.net/'>SourceForge</ulink>.  Slightly older
-versions may also work, but ancient versions like the ubiquitous
+which can be obtained from the <link
+xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP server</link>.
+For Flex, you need version 2.5.31, which is available on <link
+xlink:href="http://lex.sourceforge.net/">SourceForge</link>.  Slightly
+older versions may also work, but ancient versions like the ubiquitous
 2.5.4a won't.  Note that these are only required if you modify the
 parser or when you are building from the Subversion repository.</para>
 
@@ -69,10 +75,10 @@ and <option>--with-aterm</option> options to point to their respective
 locations.  Note that Berkeley DB <emphasis>must</emphasis> be version
 4.4; other versions may not have compatible database formats.</para>
 
-</sect1>
+</section>
 
 
-<sect1><title>Building Nix from source</title>
+<section><info><title>Building Nix from source</title></info>
 
 <para>After unpacking or checking out the Nix sources, issue the
 following commands:
@@ -110,17 +116,17 @@ and
 <option>--with-docbook-xsl=<replaceable>path</replaceable></option>
 options.</para>
 
-</sect1>
+</section>
 
 
-<sect1><title>Installing from RPMs</title>
+<section><info><title>Installing from RPMs</title></info>
 
-<para>RPM packages of Nix can be downloaded from <ulink
-url='http://www.cs.uu.nl/groups/ST/Trace/Nix' />.  These RPMs should
-work for most fairly recent releases of SuSE and Red Hat Linux.  They
-have been known to work work on SuSE Linux 8.1 and 9.0, and Red Hat
-9.0.  In fact, it should work on any RPM-based Linux distribution
-based on <literal>glibc</literal> 2.3 or later.</para>
+<para>RPM packages of Nix can be downloaded from <uri
+xlink:href="http://www.cs.uu.nl/groups/ST/Trace/Nix">http://www.cs.uu.nl/groups/ST/Trace/Nix</uri>.
+These RPMs should work for most fairly recent releases of SuSE and Red
+Hat Linux.  They have been known to work work on SuSE Linux 8.1 and
+9.0, and Red Hat 9.0.  In fact, it should work on any RPM-based Linux
+distribution based on <literal>glibc</literal> 2.3 or later.</para>
 
 <para>Once downloaded, the RPMs can be installed or upgraded using
 <command>rpm -U</command>.  For example,</para>
@@ -137,28 +143,27 @@ auxiliary data:</para>
 $ rm -rf /nix/store
 $ rm -rf /nix/var</screen>
 
-</sect1>
+</section>
 
 
-<sect1><title>Permissions</title>
+<section><info><title>Permissions</title></info>
 
 <para>All Nix operations must be performed under the user ID that owns
 the Nix store and database
 (<filename><replaceable>prefix</replaceable>/store</filename> and
 <filename><replaceable>prefix</replaceable>/var/nix/db</filename>,
 respectively).  When installed from the RPM packages, these
-directories are owned by <systemitem
-class='username'>root</systemitem>.</para>
+directories are owned by <systemitem class="username">root</systemitem>.</para>
 
-<sect2><title>Setuid installation</title>
+<section><info><title>Setuid installation</title></info>
 
 <para>As a somewhat <emphasis>ad hoc</emphasis> hack, you can also
 install the Nix binaries <quote>setuid</quote> so that a Nix store can
 be shared among several users.  To do this, configure Nix with the
 <emphasis>--enable-setuid</emphasis> option.  Nix will be installed as
 owned by a user and group specified by the
-<option>--with-nix-user=<parameter>user</parameter></option> and
-<option>--with-nix-group=<parameter>group</parameter></option>
+<option>--with-nix-user=</option><parameter>user</parameter> and
+<option>--with-nix-group=</option><parameter>group</parameter>
 options.  E.g.,
 
 <screen>
@@ -184,12 +189,12 @@ on systems that have the <function>setresuid()</function> system call
 (such as Linux and FreeBSD), so on those systems the binaries are
 simply owned by the Nix user.</para></warning>
 
-</sect2>
+</section>
 
-</sect1>
+</section>
 
 
-<sect1><title>Using Nix</title>
+<section><info><title>Using Nix</title></info>
 
 <para>To use Nix, some environment variables should be set.  In
 particular, <envar>PATH</envar> should contain the directories
@@ -206,7 +211,7 @@ in your <filename>~/.bashrc</filename> (or similar), like this:</para>
 <screen>
 source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
 
-</sect1>
+</section>
 
 
 </chapter>
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index fb6e79fcb59f..644e62e3c08e 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -1,4 +1,7 @@
-<chapter><title>Introduction</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Introduction</title>
 
 <!--
 <epigraph><para><quote>The number of Nix installations in the world
@@ -131,23 +134,22 @@ up a Nix-based build farm, and doing service deployment using
 Nix.</para>
 
 <note><para>Some background information on Nix can be found in a
-number of papers.  The ICSE 2004 paper <ulink
-url='http://www.cs.uu.nl/~eelco/pubs/immdsd-icse2004-final.pdf'><citetitle>Imposing
-a Memory Management Discipline on Software
-Deployment</citetitle></ulink> discusses the hashing mechanism used to
-ensure reliable dependency identification and non-interference between
-different versions and variants of packages.  The LISA 2004 paper
-<ulink
-url='http://www.cs.uu.nl/~eelco/pubs/nspfssd-lisa2004-final.pdf'><citetitle>Nix:
-A Safe and Policy-Free System for Software
-Deployment</citetitle></ulink> gives a more general discussion of Nix
-from a system-administration perspective.  The CBSE 2005 paper <ulink
-url='http://www.cs.uu.nl/~eelco/pubs/eupfcdm-cbse2005-final.pdf'><citetitle>Efficient
+number of papers.  The ICSE 2004 paper <citetitle
+xlink:href='http://www.cs.uu.nl/~eelco/pubs/immdsd-icse2004-final.pdf'>Imposing
+a Memory Management Discipline on Software Deployment</citetitle>
+discusses the hashing mechanism used to ensure reliable dependency
+identification and non-interference between different versions and
+variants of packages.  The LISA 2004 paper <citetitle
+xlink:href='http://www.cs.uu.nl/~eelco/pubs/nspfssd-lisa2004-final.pdf'>Nix:
+A Safe and Policy-Free System for Software Deployment</citetitle>
+gives a more general discussion of Nix from a system-administration
+perspective.  The CBSE 2005 paper <citetitle
+xlink:href='http://www.cs.uu.nl/~eelco/pubs/eupfcdm-cbse2005-final.pdf'>Efficient
 Upgrading in a Purely Functional Component Deployment Model
-</citetitle></ulink> is about transparent patch deployment in Nix.
-Finally, the SCM-12 paper <ulink
-url='http://www.cs.uu.nl/~eelco/pubs/servicecm-scm12-final.pdf'>
-Service Configuration Management</ulink> shows how services (e.g., web
-servers) can be deployed and managed through Nix.</para></note>
+</citetitle> is about transparent patch deployment in Nix.  Finally,
+the SCM-12 paper <citetitle
+xlink:href='http://www.cs.uu.nl/~eelco/pubs/servicecm-scm12-final.pdf'>
+Service Configuration Management</citetitle> shows how services (e.g.,
+web servers) can be deployed and managed through Nix.</para></note>
 
 </chapter>
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index e1eaf0135503..5ca7f491feb7 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -1,89 +1,89 @@
-<?xml version="1.0"?>
-<!DOCTYPE book
-    PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-    "http://www.docbook.org/xml/4.3/docbook-xml-4.3.zip"
-[
-]>
+<book xmlns="http://docbook.org/ns/docbook"
+      xmlns:xi="http://www.w3.org/2001/XInclude">
 
-<book>
-  <title>Nix User's Guide</title>
+  <info>
+
+    <title>Nix User's Guide</title>
+
+    <subtitle>Draft (Version <xi:include href="version.txt"
+    parse="text" />)</subtitle>
 
-  <subtitle>Draft (Version <xi:include
-  xmlns:xi="http://www.w3.org/2001/XInclude"
-  href="version.txt" parse="text" />)</subtitle>
-  
-  <bookinfo>
     <author>
-      <firstname>Eelco</firstname>
-      <surname>Dolstra</surname>
+      <personname>
+        <firstname>Eelco</firstname>
+        <surname>Dolstra</surname>
+      </personname>
     </author>
+
     <copyright>
       <year>2004</year>
       <year>2005</year>
       <year>2006</year>
       <holder>Eelco Dolstra</holder>
     </copyright>
-  </bookinfo>
+    
+  </info>
+
   
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quick-start.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="installation.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="package-management.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="writing-nix-expressions.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="build-farm.xml" />
+  <xi:include href="introduction.xml" />
+  <xi:include href="quick-start.xml" />
+  <xi:include href="installation.xml" />
+  <xi:include href="package-management.xml" />
+  <xi:include href="writing-nix-expressions.xml" />
+  <xi:include href="build-farm.xml" />
+
 
   <appendix>
     <title>Command Reference</title>
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml" />
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="env-common.xml" />
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conf-file.xml" />
-    <sect1 id="sec-nix-env">
+    <xi:include href="opt-common.xml" />
+    <xi:include href="env-common.xml" />
+    <xi:include href="conf-file.xml" />
+    <section xml:id="sec-nix-env">
       <title>nix-env</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-env.xml" />
-    </sect1>
-    <sect1 id="sec-nix-build">
+      <xi:include href="nix-env.xml" />
+    </section>
+    <section xml:id="sec-nix-build">
       <title>nix-build</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-build.xml" />
-    </sect1>
-    <sect1>
+      <xi:include href="nix-build.xml" />
+    </section>
+    <section>
       <title>nix-store</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-store.xml" />
-    </sect1>
-    <sect1 id="sec-nix-instantiate">
+      <xi:include href="nix-store.xml" />
+    </section>
+    <section xml:id="sec-nix-instantiate">
       <title>nix-instantiate</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-instantiate.xml" />
-    </sect1>
-    <sect1>
+      <xi:include href="nix-instantiate.xml" />
+    </section>
+    <section>
       <title>nix-collect-garbage</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-collect-garbage.xml" />
-    </sect1>
-    <sect1 id="sec-nix-channel">
+      <xi:include href="nix-collect-garbage.xml" />
+    </section>
+    <section xml:id="sec-nix-channel">
       <title>nix-channel</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-channel.xml" />
-    </sect1>
-    <sect1>
+      <xi:include href="nix-channel.xml" />
+    </section>
+    <section>
       <title>nix-push</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-push.xml" />
-    </sect1>
-    <sect1>
+      <xi:include href="nix-push.xml" />
+    </section>
+    <section>
       <title>nix-pull</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-pull.xml" />
-    </sect1>
-    <sect1>
+      <xi:include href="nix-pull.xml" />
+    </section>
+    <section>
       <title>nix-prefetch-url</title>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-prefetch-url.xml" />
-    </sect1>
+      <xi:include href="nix-prefetch-url.xml" />
+    </section>
   </appendix>
 
-  <!--  &nix-lang-ref; -->
-
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="troubleshooting.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="bugs.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml" />
+  <xi:include href="troubleshooting.xml" />
+  <xi:include href="bugs.xml" />
+  <xi:include href="glossary.xml" />
 
   <appendix>
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="release-notes.xml"
-                xpointer="xpointer(article/*)" />
+    <title>Nix Release Notes</title>
+    <xi:include href="release-notes.xml"
+                xpointer="xmlns(x=http://docbook.org/ns/docbook)xpointer(x:article/x:section)" />
   </appendix>
     
 </book>
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index 0462401bcabb..03d0d97fe99b 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -1,5 +1,6 @@
-<refentry>
-  
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+
 <refnamediv>
   <refname>nix-build</refname>
   <refpurpose>build a Nix expression</refpurpose>
diff --git a/doc/manual/nix-channel.xml b/doc/manual/nix-channel.xml
index 059832a86c1d..f3fb7c1f6d43 100644
--- a/doc/manual/nix-channel.xml
+++ b/doc/manual/nix-channel.xml
@@ -1,4 +1,5 @@
-<refentry>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
   
 <refnamediv>
   <refname>nix-channel</refname>
diff --git a/doc/manual/nix-collect-garbage.xml b/doc/manual/nix-collect-garbage.xml
index 3e4ab092588d..73739182d491 100644
--- a/doc/manual/nix-collect-garbage.xml
+++ b/doc/manual/nix-collect-garbage.xml
@@ -1,4 +1,5 @@
-<refentry>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
   
 <refnamediv>
   <refname>nix-collect-garbage</refname>
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index 6fb894e2be5f..ee228f37425e 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -1,4 +1,5 @@
-<refentry>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
   
 <refnamediv>
   <refname>nix-env</refname>
@@ -172,7 +173,7 @@ linkend="sec-common-options" />.</para>
 
 <!--######################################################################-->
 
-<refsection id="rsec-nix-env-install"><title>Operation <option>--install</option></title>
+<refsection xml:id="rsec-nix-env-install"><title>Operation <option>--install</option></title>
 
 <refsection><title>Synopsis</title>
 
@@ -725,7 +726,7 @@ $ nix-env -qas <lineannotation>(show status of available derivations)</lineannot
 IP- ORBit2-2.8.3    <lineannotation>(installed and by definition present)</lineannotation>
 ...
 
-$ nix-env -f ./foo.nix -qa <lineannotation>(show available derivations in the Nix expression <filename>foo.nix</filename>)</lineannotation>
+$ nix-env -f ./foo.nix -qa <lineannotation>(show available derivations in the Nix expression <!-- !!! <filename>-->foo.nix<!-- </filename> -->)</lineannotation>
 foo-1.2.3
 
 $ nix-env -qc <lineannotation>(compare installed versions to what’s available)</lineannotation>
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index ffee27beb8de..230f03682523 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -1,4 +1,5 @@
-<refentry>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
   
 <refnamediv>
   <refname>nix-instantiate</refname>
diff --git a/doc/manual/nix-pull.xml b/doc/manual/nix-pull.xml
index 448ab0065eee..28b5e354bb66 100644
--- a/doc/manual/nix-pull.xml
+++ b/doc/manual/nix-pull.xml
@@ -1,43 +1,41 @@
-<refentry>
-  <refnamediv>
-    <refname>nix-pull</refname>
-    <refpurpose>pull substitutes from a network cache</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>nix-pull</command>
-      <arg choice='plain'><replaceable>url</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-
-  <refsection>
-    <title>Description</title>
-
-    <para>
-      The command <command>nix-pull</command> obtains a list of
-      pre-built store paths from the URL
-      <replaceable>url</replaceable>, and for each of these store
-      paths, registers a substitute derivation that downloads and
-      unpacks it into the Nix store.  This is used to speed up
-      installations: if you attempt to install something that has
-      already been built and stored into the network cache, Nix can
-      transparently re-use the pre-built store paths.
-    </para>
-
-    <para>
-      The file at <replaceable>url</replaceable> must be compatible
-      with the files created by <replaceable>nix-push</replaceable>.
-    </para>
-
-  </refsection>
-
-  <refsection>
-    <title>Examples</title>
-
-    <screen>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<refnamediv>
+  <refname>nix-pull</refname>
+  <refpurpose>pull substitutes from a network cache</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-pull</command>
+    <arg choice='plain'><replaceable>url</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-pull</command> obtains a list of
+pre-built store paths from the URL <replaceable>url</replaceable>, and
+for each of these store paths, registers a substitute derivation that
+downloads and unpacks it into the Nix store.  This is used to speed up
+installations: if you attempt to install something that has already
+been built and stored into the network cache, Nix can transparently
+re-use the pre-built store paths.</para>
+
+<para>The file at <replaceable>url</replaceable> must be compatible
+with the files created by <replaceable>nix-push</replaceable>.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
 $ nix-pull http://nix.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST</screen>
 
-  </refsection>
-    
+</refsection>
+
+
 </refentry>
diff --git a/doc/manual/nix-push.xml b/doc/manual/nix-push.xml
index f683784ada91..0b2a368e9f02 100644
--- a/doc/manual/nix-push.xml
+++ b/doc/manual/nix-push.xml
@@ -1,4 +1,5 @@
-<refentry>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
 
 <refnamediv>
   <refname>nix-push</refname>
@@ -62,14 +63,15 @@ machines using the <command>nix-pull</command> command.</para>
   specified by <replaceable>archivesPutURL</replaceable>.  HTTP PUT
   requests are used to do this.  However, before a file
   <varname>x</varname> is uploaded to
-  <literal><replaceable>archivesPutURL</replaceable>/<varname>x</varname></literal>,
+  <literal><replaceable>archivesPutURL</replaceable>/</literal><varname>x</varname>,
   <command>nix-push</command> first determines whether this upload is
   unnecessary by issuing a HTTP HEAD request on
-  <literal><replaceable>archivesGetURL</replaceable>/<varname>x</varname></literal>.
+  <literal><replaceable>archivesGetURL</replaceable>/</literal><varname>x</varname>.
   This allows a cache to be shared between many partially overlapping
   <command>nix-push</command> invocations.  (We use two URLs because
   the upload URL typically refers to a CGI script, while the download
-  URL just refers to a file system directory on the server.)</para></listitem>
+  URL just refers to a file system directory on the
+  server.)</para></listitem>
 
   <listitem><para>The manifest is uploaded using an HTTP PUT request
   to <replaceable>manifestPutURL</replaceable>.  The corresponding
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index cd7de90fd687..b8ee297242d9 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -1,4 +1,5 @@
-<refentry>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
 
 <refnamediv>
   <refname>nix-store</refname>
@@ -43,7 +44,7 @@ linkend="sec-common-options" /> for a list of common options.</para>
 
 <variablelist>
 
-  <varlistentry id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term>
+  <varlistentry xml:id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term>
 
     <listitem><para>Causes the result of a realisation
     (<option>--realise</option> and <option>--force-realise</option>)
@@ -108,7 +109,7 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
 
 <!--######################################################################-->
 
-<refsection id='rsec-nix-store-realise'><title>Operation
+<refsection xml:id='rsec-nix-store-realise'><title>Operation
 <option>--realise</option></title>
 
 <refsection><title>Synopsis</title>
@@ -183,7 +184,7 @@ linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
 
 <!--######################################################################-->
 
-<refsection id='rsec-nix-store-gc'><title>Operation <option>--gc</option></title>
+<refsection xml:id='rsec-nix-store-gc'><title>Operation <option>--gc</option></title>
 
 <refsection><title>Synopsis</title>
 
@@ -353,7 +354,7 @@ query is applied to the target of the symlink.</para>
 </refsection>
     
 
-<refsection id='nixref-queries'><title>Queries</title>
+<refsection xml:id='nixref-queries'><title>Queries</title>
             
 <variablelist>
 
@@ -448,11 +449,11 @@ query is applied to the target of the symlink.</para>
   
     <listitem><para>Prints the references graph of the store paths
     <replaceable>paths</replaceable> in the format of the
-    <command>dot</command> tool of AT&amp;T's <ulink
-    url="http://www.graphviz.org/">Graphviz package</ulink>.  This can
-    be used to visualise dependency graphs.  To obtain a build-time
-    dependency graph, apply this to a store derivation.  To obtain a
-    runtime dependency graph, apply it to an output
+    <command>dot</command> tool of AT&amp;T's <link
+    xlink:href="http://www.graphviz.org/">Graphviz package</link>.
+    This can be used to visualise dependency graphs.  To obtain a
+    build-time dependency graph, apply this to a store derivation.  To
+    obtain a runtime dependency graph, apply it to an output
     path.</para></listitem>
 
   </varlistentry>
@@ -575,7 +576,7 @@ $ gv graph.ps</screen>
 <!--######################################################################-->
 
 <!--
-<refsection id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title>
+<refsection xml:id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title>
 
 <refsection><title>Synopsis</title>
 
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index 052ae4cf983f..2c514cad25cb 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -1,4 +1,7 @@
-<sect1 id="sec-common-options"><title>Common options</title>
+<section xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
+
+<title>Common options</title>
+
 
 <para>Most Nix commands accept the following command-line options:</para>
 
@@ -86,7 +89,7 @@
 </varlistentry>
 
 
-<varlistentry id="opt-max-jobs"><term><option>--max-jobs</option></term>
+<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option></term>
   <term><option>-j</option></term>
 
   <listitem><para>Sets the maximum number of build jobs that Nix will
@@ -155,7 +158,7 @@
 </varlistentry>
 
 
-<varlistentry id="opt-log-type"><term><option>--log-type</option>
+<varlistentry xml:id="opt-log-type"><term><option>--log-type</option>
 <replaceable>type</replaceable></term>
 
   <listitem>
@@ -213,4 +216,4 @@
 </variablelist>
 
 
-</sect1>
\ No newline at end of file
+</section>
\ No newline at end of file
diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml
index 7127dd34ead6..2b2e04c11f24 100644
--- a/doc/manual/package-management.xml
+++ b/doc/manual/package-management.xml
@@ -1,4 +1,9 @@
-<chapter id='chap-package-management'><title>Package Management</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id='chap-package-management'>
+
+<title>Package Management</title>
+
 
 <para>This chapter discusses how to do package management with Nix,
 i.e., how to obtain, install, upgrade, and erase components.  This is
@@ -7,7 +12,7 @@ who want to <emphasis>create</emphasis> components should consult
 <xref linkend='chap-writing-nix-expressions' />.</para>
 
 
-<sect1><title>Basic package management</title>
+<section><title>Basic package management</title>
 
 <para>The main command for package management is <link
 linkend="sec-nix-env"><command>nix-env</command></link>.  You can use
@@ -32,8 +37,8 @@ components ranging from basic development stuff such as GCC and Glibc,
 to end-user applications like Mozilla Firefox.  (Nix is however not
 tied to the Nix Package collection; you could write your own Nix
 expressions based on it, or completely new ones.)  You can download
-the latest version from <ulink url='http://nix.cs.uu.nl/dist/nix'
-/>.</para>
+the latest version from <link
+xlink:href='http://nix.cs.uu.nl/dist/nix' />.</para>
 
 <para>Assuming that you have downloaded and unpacked a release of Nix
 Packages, you can view the set of available components in the release:
@@ -83,9 +88,9 @@ components contained in them.  This is done using <literal>nix-env
 $ nix-env -f nixpkgs-<replaceable>version</replaceable> -i subversion</screen>
 
 will install the component called <literal>subversion</literal> (which
-is, of course, the <ulink
-url='http://subversion.tigris.org/'>Subversion version management
-system</ulink>).</para>
+is, of course, the <link
+xlink:href='http://subversion.tigris.org/'>Subversion version
+management system</link>).</para>
 
 <para>When you do this for the first time, Nix will start building
 Subversion and all its dependencies.  This will take quite a while —
@@ -96,8 +101,8 @@ available somewhere.  This is done using the
 <command>nix-pull</command> command, which must be supplied with a URL
 containing a <emphasis>manifest</emphasis> describing what binaries
 are available.  This URL should correspond to the Nix Packages release
-that you’re using.  For instance, if you obtained a release from
-<ulink url='http://nix.cs.uu.nl/dist/nix/nixpkgs-0.6pre1554/' />, then
+that you’re using.  For instance, if you obtained a release from <link
+xlink:href='http://nix.cs.uu.nl/dist/nix/nixpkgs-0.6pre1554/' />, then
 you should do:
 
 <screen>
@@ -105,8 +110,8 @@ $ nix-pull http://nix.cs.uu.nl/dist/nix/nixpkgs-0.6pre1554/MANIFEST</screen>
 
 If you then issue the installation command, it should start
 downloading binaries from <systemitem
-class='fqdomainname'>nix.cs.uu.nl</systemitem>, instead of
-building them from source.  This might still take a while since all
+class='fqdomainname'>nix.cs.uu.nl</systemitem>, instead of building
+them from source.  This might still take a while since all
 dependencies must be downloaded, but on a reasonably fast connection
 such as an DSL line it’s on the order of a few minutes.</para>
 
@@ -169,10 +174,10 @@ since <literal>nix-channel --update</literal> calls <literal>nix-env
 from the channel, replacing whatever default you had
 set.</para></footnote></para>
 
-</sect1>
+</section>
 
 
-<sect1 id="sec-profiles"><title>Profiles</title>
+<section xml:id="sec-profiles"><title>Profiles</title>
 
 <para>Profiles and user environments are Nix’s mechanism for
 implementing the ability to allow different users to have different
@@ -195,7 +200,7 @@ the file system, so they don’t interfere with each other.  <xref
 linkend='fig-user-environments' /> shows a part of a typical Nix
 store.</para>
 
-<figure id='fig-user-environments'><title>User environments</title>
+<figure xml:id='fig-user-environments'><title>User environments</title>
   <mediaobject>
     <imageobject>
       <imagedata fileref='figures/user-environments.png' format='PNG' />
@@ -324,10 +329,10 @@ $ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen>
 This will <emphasis>not</emphasis> change the
 <command>~/.nix-profile</command> symlink.</para>
 
-</sect1>
+</section>
 
 
-<sect1 id='sec-garbage-collection'><title>Garbage collection</title>
+<section xml:id='sec-garbage-collection'><title>Garbage collection</title>
 
 <para><command>nix-env</command> operations such as upgrades
 (<option>-u</option>) and uninstall (<option>-e</option>) never
@@ -378,7 +383,7 @@ Likewise, the option <option>--print-live</option> will show the paths
 that <emphasis>won’t</emphasis> be deleted.</para>
 
 
-<sect2 id="ssec-gc-roots"><title>Garbage collector roots</title>
+<section xml:id="ssec-gc-roots"><title>Garbage collector roots</title>
 
 <para>The roots of the garbage collector are all store paths to which
 there are symlinks in the directory
@@ -400,12 +405,12 @@ followed and searched for roots, but symlinks to non-store paths
 <emphasis>inside</emphasis> the paths reached in that way are not
 followed to prevent infinite recursion.</para>
 
-</sect2>
+</section>
 
-</sect1>
+</section>
 
 
-<sect1 id="sec-channels"><title>Channels</title>
+<section xml:id="sec-channels"><title>Channels</title>
 
 <para>If you want to stay up to date with a set of packages, it’s not
 very convenient to manually download the latest set of Nix expressions
@@ -455,7 +460,7 @@ $ nix-env -u '*'</screen>
 to upgrade all components in your profile to the latest versions
 available in the subscribed channels.</para>
 
-</sect1>
+</section>
 
 
 </chapter>
diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start.xml
index 3ebc49d3b42a..f520522dbef8 100644
--- a/doc/manual/quick-start.xml
+++ b/doc/manual/quick-start.xml
@@ -1,4 +1,8 @@
-<chapter><title>Quick Start</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Quick Start</title>
+
 
 <para>This chapter is for impatient people who don't like reading
 documentation.  For more in-depth information you are kindly referred
@@ -6,8 +10,8 @@ to the following chapters.</para>
 
 <orderedlist>
 
-<listitem><para>Download a source tarball or RPM from <ulink
-url='http://www.cs.uu.nl/groups/ST/Trace/Nix'/>.  Build source
+<listitem><para>Download a source tarball or RPM from <link
+xlink:href='http://www.cs.uu.nl/groups/ST/Trace/Nix'/>.  Build source
 distributions using the regular sequence:
         
 <screen>
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index c9dcf05edc56..328853a77370 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -1,11 +1,6 @@
-<?xml version="1.0"?>
-<!DOCTYPE book
-    PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-    "http://www.docbook.org/xml/4.3/docbook-xml-4.3.zip"
-[
-]>
+<article xmlns="http://docbook.org/ns/docbook">
 
-<article><title>Nix Release Notes</title>
+<title>Nix Release Notes</title>
 
 
 <section><title>Release 0.10 (TBA)</title>
@@ -32,9 +27,16 @@ irreversible.</para></warning>
   --query</command> to allow you to compare installed versions of
   packages to available versions, or vice versa.  An easy way to see
   if you are up to date with what’s in the channel is <literal>nix-env
-  -qc</literal>.</para></listitem>
+  -qc \*</literal>.</para></listitem>
 
-  <listitem><para>TODO: shared stores.</para></listitem>
+  <listitem><para><literal>nix-env --query</literal> now takes as
+  arguments a list of package names about which to show information,
+  just like <option>--install</option>, etc.: for example,
+  <literal>nix-env -q gcc</literal>.  Note that to show all
+  derivations, you need to specify
+  <literal>\*</literal>.</para></listitem>
+
+  <!--  <listitem><para>TODO: shared stores.</para></listitem> -->
 
   <listitem><para>A performance issue has been fixed with the
   <literal>referer</literal> table, which stores the inverse of the
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
index ebd454a97266..3787ddcd93f5 100644
--- a/doc/manual/troubleshooting.xml
+++ b/doc/manual/troubleshooting.xml
@@ -1,4 +1,8 @@
-<appendix><title>Troubleshooting</title>
+<appendix xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Troubleshooting</title>
+
 
 <para>This section provides solutions for some common problems.</para>
 
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index 56adacba4309..5b522ea1d1f9 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -1,4 +1,9 @@
-<chapter id='chap-writing-nix-expressions'><title>Writing Nix Expressions</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id='chap-writing-nix-expressions'>
+
+<title>Writing Nix Expressions</title>
+
 
 <para>This chapter shows you how to write Nix expressions, which are
 the things that tell Nix how to build components.  It starts with a
@@ -8,9 +13,9 @@ on to a more in-depth look at the Nix expression language.</para>
 
 <sect1><title>A simple Nix expression</title>
 
-<para>This section shows how to add and test the <ulink
-url='http://www.gnu.org/software/hello/hello.html'>GNU Hello
-package</ulink> to the Nix Packages collection.  Hello is a program
+<para>This section shows how to add and test the <link
+xlink:href='http://www.gnu.org/software/hello/hello.html'>GNU Hello
+package</link> to the Nix Packages collection.  Hello is a program
 that prints out the text <quote>Hello, world!</quote>.</para>
 
 <para>To add a component to the Nix Packages collection, you generally
@@ -44,19 +49,19 @@ need to do three things:
 
 <sect2><title>The Nix expression</title>
 
-<example id='ex-hello-nix'><title>Nix expression for GNU Hello
+<example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello
 (<filename>default.nix</filename>)</title>
 <programlisting>
-{stdenv, fetchurl, perl}: <co id='ex-hello-nix-co-1' />
+{stdenv, fetchurl, perl}: <co xml:id='ex-hello-nix-co-1' />
 
-stdenv.mkDerivation { <co id='ex-hello-nix-co-2' />
-  name = "hello-2.1.1"; <co id='ex-hello-nix-co-3' />
-  builder = ./builder.sh; <co id='ex-hello-nix-co-4' />
-  src = fetchurl { <co id='ex-hello-nix-co-5' />
+stdenv.mkDerivation { <co xml:id='ex-hello-nix-co-2' />
+  name = "hello-2.1.1"; <co xml:id='ex-hello-nix-co-3' />
+  builder = ./builder.sh; <co xml:id='ex-hello-nix-co-4' />
+  src = fetchurl { <co xml:id='ex-hello-nix-co-5' />
     url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
     md5 = "70c9ccf9fac07f762c24f2df2290784d";
   };
-  inherit perl; <co id='ex-hello-nix-co-6' />
+  inherit perl; <co xml:id='ex-hello-nix-co-6' />
 }</programlisting>
 </example>
 
@@ -188,17 +193,17 @@ perl = perl;</programlisting>
 
 <sect2><title>The builder</title>
 
-<example id='ex-hello-builder'><title>Build script for GNU Hello
+<example xml:id='ex-hello-builder'><title>Build script for GNU Hello
 (<filename>builder.sh</filename>)</title>
 <programlisting>
-source $stdenv/setup <co id='ex-hello-builder-co-1' />
+source $stdenv/setup <co xml:id='ex-hello-builder-co-1' />
 
-PATH=$perl/bin:$PATH <co id='ex-hello-builder-co-2' />
+PATH=$perl/bin:$PATH <co xml:id='ex-hello-builder-co-2' />
 
-tar xvfz $src <co id='ex-hello-builder-co-3' />
+tar xvfz $src <co xml:id='ex-hello-builder-co-3' />
 cd hello-*
-./configure --prefix=$out <co id='ex-hello-builder-co-4' />
-make <co id='ex-hello-builder-co-5' />
+./configure --prefix=$out <co xml:id='ex-hello-builder-co-4' />
+make <co xml:id='ex-hello-builder-co-5' />
 make install</programlisting>
 </example>
 
@@ -303,18 +308,18 @@ error check.</para>
 
 <sect2><title>Composition</title>
 
-<example id='ex-hello-composition'><title>Composing GNU Hello
+<example xml:id='ex-hello-composition'><title>Composing GNU Hello
 (<filename>all-packages-generic.nix</filename>)</title>
 <programlisting>
 ...
 
-rec { <co id='ex-hello-composition-co-1' />
+rec { <co xml:id='ex-hello-composition-co-1' />
   
-  hello = (import ../applications/misc/hello/ex-1 <co id='ex-hello-composition-co-2' />) { <co id='ex-hello-composition-co-3' />
+  hello = (import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' />) { <co xml:id='ex-hello-composition-co-3' />
     inherit fetchurl stdenv perl;
   };
 
-  perl = (import ../development/interpreters/perl) { <co id='ex-hello-composition-co-4' />
+  perl = (import ../development/interpreters/perl) { <co xml:id='ex-hello-composition-co-4' />
     inherit fetchurl stdenv;
   };
 
@@ -519,14 +524,14 @@ functions that automate the build process.  A builder using the
 generic build facilities in shown in <xref linkend='ex-hello-builder2'
 />.</para>
 
-<example id='ex-hello-builder2'><title>Build script using the generic
+<example xml:id='ex-hello-builder2'><title>Build script using the generic
 build functions</title>
 <programlisting>
-buildInputs="$perl" <co id='ex-hello-builder2-co-1' />
+buildInputs="$perl" <co xml:id='ex-hello-builder2-co-1' />
 
-source $stdenv/setup <co id='ex-hello-builder2-co-2' />
+source $stdenv/setup <co xml:id='ex-hello-builder2-co-2' />
 
-genericBuild <co id='ex-hello-builder2-co-3' /></programlisting>
+genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting>
 </example>
 
 <calloutlist>
@@ -619,8 +624,8 @@ language.</para>
   <literal>123</literal>.</para></listitem>
 
   <listitem><para><emphasis>URIs</emphasis> as defined in appendix B
-  of <ulink url='http://www.ietf.org/rfc/rfc2396.txt'>RFC
-  2396</ulink>, e.g.,
+  of <link xlink:href='http://www.ietf.org/rfc/rfc2396.txt'>RFC
+  2396</link>, e.g.,
   <literal>https://svn.cs.uu.nl:12443/dist/trace/trace-nix-trunk.tar.bz2</literal>.</para></listitem>
 
   <listitem><para><emphasis>Paths</emphasis>, e.g.,
@@ -818,7 +823,7 @@ set.</para>
 </simplesect>
 
 
-<simplesect id="ss-functions"><title>Functions</title>
+<simplesect xml:id="ss-functions"><title>Functions</title>
 
 <para>Functions have the following form:
 
@@ -903,7 +908,7 @@ evaluate to a boolean value.  If it evaluates to
 <literal>true</literal>, <replaceable>e2</replaceable> is returned;
 otherwise expression evaluation is aborted and a backtrace is printed.</para>
 
-<example id='ex-subversion-nix'><title>Nix expression for Subversion</title>
+<example xml:id='ex-subversion-nix'><title>Nix expression for Subversion</title>
 <programlisting>
 { localServer ? false
 , httpServer ? false
@@ -915,9 +920,9 @@ otherwise expression evaluation is aborted and a backtrace is printed.</para>
 , openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null
 }:
 
-assert localServer -> db4 != null; <co id='ex-subversion-nix-co-1' />
-assert httpServer -> httpd != null &amp;&amp; httpd.expat == expat; <co id='ex-subversion-nix-co-2' />
-assert sslSupport -> openssl != null &amp;&amp; (httpServer -> httpd.openssl == openssl); <co id='ex-subversion-nix-co-3' />
+assert localServer -> db4 != null; <co xml:id='ex-subversion-nix-co-1' />
+assert httpServer -> httpd != null &amp;&amp; httpd.expat == expat; <co xml:id='ex-subversion-nix-co-2' />
+assert sslSupport -> openssl != null &amp;&amp; (httpServer -> httpd.openssl == openssl); <co xml:id='ex-subversion-nix-co-3' />
 assert pythonBindings -> swig != null &amp;&amp; swig.pythonSupport;
 assert javaSwigBindings -> swig != null &amp;&amp; swig.javaSupport;
 assert javahlBindings -> j2sdk != null;
@@ -925,7 +930,7 @@ assert javahlBindings -> j2sdk != null;
 stdenv.mkDerivation {
   name = "subversion-1.1.1";
   ...
-  openssl = if sslSupport then openssl else null; <co id='ex-subversion-nix-co-4' />
+  openssl = if sslSupport then openssl else null; <co xml:id='ex-subversion-nix-co-4' />
   ...
 }</programlisting>
 </example>
@@ -1019,7 +1024,7 @@ locally in a <literal>rec</literal>-expression.</para>
 Nix expression language, in order of precedence (from strongest to
 weakest binding).</para>
 
-<table id='table-operators'>
+<table xml:id='table-operators'>
   <title>Operators</title>
   <tgroup cols='3'>
     <thead>
@@ -1109,7 +1114,7 @@ weakest binding).</para>
 </simplesect>
 
 
-<simplesect id="ssec-derivation"><title>Derivations</title>
+<simplesect xml:id="ssec-derivation"><title>Derivations</title>
 
 <para>The most important built-in function is
 <function>derivation</function>, which is used to describe a
@@ -1118,7 +1123,7 @@ set, the attributes of which specify the inputs of the build.</para>
 
 <itemizedlist>
 
-  <listitem id="attr-system"><para>There must be an attribute named
+  <listitem xml:id="attr-system"><para>There must be an attribute named
   <varname>system</varname> whose value must be a string specifying a
   Nix platform identifier, such as <literal>"i686-linux"</literal> or
   <literal>"powerpc-darwin"</literal><footnote><para>To figure out
@@ -1297,7 +1302,7 @@ character, or inline/multi-line, enclosed within <literal>/*
 
 
 
-<sect1 id='sec-standard-environment'><title>The standard environment</title>
+<sect1 xml:id='sec-standard-environment'><title>The standard environment</title>
 
 <para>The standard build environment in the Nix Packages collection
 provides a basic environment for building Unix packages.  It consists