* Split the book.xml into several xml files.

7 files changed, 481 insertions, 470 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index a4e3f24ceec8..a29592f1e1e9 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -2,17 +2,20 @@ DOCBOOK_DTD = /nix/current/xml/dtd/docbook
 DOCBOOK_XSL = /nix/current/xml/xsl/docbook
 XML = /usr/share/doc/packages/sp/html-xml/xml.soc
 
-%.is-valid: %.xml
+SOURCES = book.xml introduction.xml installation.xml nix-reference.xml \
+ troubleshooting.xml bugs.xml
+
+book.is-valid: $(SOURCES)
 	SP_CHARSET_FIXED=YES SP_ENCODING=XML \
 	nsgmls -wxml -c $(XML) -c $(DOCBOOK_DTD)/docbook.cat -ges $<
 	touch $@
 
 man1_MANS = nix.1
 
-man nix.1: book.is-valid
+man nix.1: $(SOURCES) book.is-valid
 	xsltproc $(DOCBOOK_XSL)/manpages/docbook.xsl book.xml
 
-%.html: %.xml %.is-valid
+book.html: $(SOURCES) book.is-valid
 	xsltproc --output book.html $(DOCBOOK_XSL)/html/docbook.xsl book.xml
 
 all-local: book.html
diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index 3d54edfcb685..eb0475a62005 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -1,503 +1,46 @@
 <?xml version="1.0"?>
 <!DOCTYPE book SYSTEM "/nix/current/xml/dtd/docbook/docbookx.dtd"
 [
+<!ENTITY introduction SYSTEM "introduction.xml">
+<!ENTITY installation SYSTEM "installation.xml">
+<!ENTITY nix-reference SYSTEM "nix-reference.xml">
+<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
+<!ENTITY bugs SYSTEM "bugs.xml">
 ]>
 
 <book>
   <title>Nix: The Manual</title>
 
-
-  <!--======================================================================-->
-
-  <chapter>
-    <title>Introduction</title>
-
-    <sect1>
-      <title>The problem space</title>
-
-      <para>
-	Nix is a system for controlling the automatic creation and distribution
-	of data, such as computer programs and other software artifacts.  This
-	is a very general problem, and there are many applications that fall
-	under this description.
-      </para>
-
-      <sect2>
-	<title>Build management</title>
-
-	<para>
-	  Build management tools are used to perform <emphasis>software
-	    builds</emphasis>, that is, the construction of derived products
-	  such as executable programs from source code.  A commonly used build
-	  tool is Make, which is a standard tool on Unix systems. These tools
-	  have to deal with several issues:
-	  <itemizedlist>
-	    <listitem>
-	      <para>
-	      </para>
-	    </listitem>
-	  </itemizedlist>
-	</para>
-
-      </sect2>
-
-      <sect2>
-	<title>Package management</title>
-
-	<para>
-	  After software has been built, is must also be
-	  <emphasis>deployed</emphasis> in the intended target environment,
-	  e.g., the user's workstation.  Examples include the Red Hat package
-	  manager (RPM), Microsoft's MSI, and so on.  Here also we have to deal
-	  with several issues:
-	  <itemizedlist>
-	    <listitem>
-	      <para>
-		The <emphasis>creation</emphasis> of packages from some formal
-		description of what artifacts should be distributed in the
-		package.
-	      </para>
-	    </listitem>
-	    <listitem>
-	      <para>
-		The <emphasis>deployment</emphasis> of packages, that is, the
-		mechanism by which we get them onto the intended target
-		environment.  This can be as simple as copying a file, but
-		complexity comes from the wide range of possible installation
-		media (such as a network install), and the scalability of the
-		process (if a program must be installed on a thousand systems,
-		we do not want to visit each system and perform some manual
-		steps to install the program on that system; that is, the
-		complexity for the system administrator should be constant, not
-		linear).
-	      </para>
-	    </listitem>
-	  </itemizedlist>
-	</para>
-      </sect2>
-
-    </sect1>
-
-    <sect1>
-      <title>The Nix system</title>
-
-      <para>
-	...
-      </para>
-
-      <para>
-	Existing tools in this field generally both a underlying model (such as
-	the derivation graph of build tools, or the versioning scheme that
-	determines when two packages are <quote>compatible</quote> in a package
-	management system) and a formalism that allows ...
-      </para>
-
-      <para>
-	Following the principle of separation of mechanism and policy, the Nix
-	system separates the <emphasis>low-level aspect</emphasis> of file
-	system object management form the <emphasis>high-level
-	  aspect</emphasis> of the ...
-      </para>
-
-    </sect1>
-
-  </chapter>
-
-
-  <!--======================================================================-->
+  &introduction;
+  &installation;
 
   <chapter>
     <title>A Guided Tour</title>
-
     <para>
       Bla bla
     </para>
   </chapter>
 
-
-  <!--======================================================================-->
-
   <chapter>
     <title>Fix Language Reference</title>
-
     <para>
       Bla bla
     </para>
   </chapter>
 
-
-  <!--======================================================================-->
-
   <chapter>
     <title>Nix Syntax and Semantics</title>
-
     <para>
       Bla bla
     </para>
   </chapter>
 
-
-  <!--======================================================================-->
-
-  <chapter>
-    <title>Installation</title>
-
-    <sect1>
-      <title>Prerequisites</title>
-
-      <para>
-	Nix uses Sleepycat's Berkeley DB and CWI's ATerm library.  However,
-	these are fetched automatically as part of the build process.
-      </para>
-
-      <para>
-	Other than that, you need a good C++ compiler.  GCC 2.95 does not
-	appear to work; please use GCC 3.x.
-      </para>
-    </sect1>
-
-    <sect1>
-      <title>Obtaining Nix</title>
-
-      <para>
-	Nix can be obtained from its <ulink
-	  url='http://losser.st-lab.cs.uu.nl:12080/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>
-
-      <screen>
-$ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk nix</screen>
-
-      <para>
-	Likewise, specific releases can be obtained from the <ulink
-	  url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags
-	  directory</ulink> of the repository.  If you don't have Subversion,
-	you can download a <ulink
-	  url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
-	  tar-file</ulink> of the latest revision of the repository.
-      </para>
-
-    </sect1>
-
-    <sect1>
-      <title>Building Nix</title>
-
-      <para>
-	To build Nix, do the following:
-      </para>
-
-      <screen>
-$ autoreconf -i
-$ ./configure <replaceable>options...</replaceable>
-$ make
-$ make install</screen>
-
-      <para>
-	Currently, the only useful switch for <command>configure</command> is
-	<option>--prefix=<replaceable>prefix</replaceable></option> to specify
-	where Nix is to be installed.  The default installation directory is
-	<filename>/nix</filename>.  You can change this to any location you
-	like.  You should ensure that you have write permission to the
-	installation prefix. 
-      </para>
-
-      <warning>
-	<para>
-	  It is advisable <emphasis>not</emphasis> to change the installation
-	  prefix, since doing so will in all likelihood make it impossible to
-	  use derivates built on other systems.
-	</para>
-      </warning>
-
-    </sect1>
-
-  </chapter>
-
-
-  <!--======================================================================-->
-
   <appendix>
     <title>Command Reference</title>
-
-    <refentry>
-      <refnamediv>
-	<refname>nix</refname>
-	<refpurpose>manipulate or query the Nix store</refpurpose>
-      </refnamediv>
-
-      <refsynopsisdiv>
-	<cmdsynopsis>
-	  <command>nix</command>
-	  <group choice='opt'>
-	    <arg><option>--path</option></arg>
-	    <arg><option>-p</option></arg>
-	  </group>
-	  <group choice='opt' rep='repeat'>
-	    <arg><option>--verbose</option></arg>
-	    <arg><option>-v</option></arg>
-	  </group>
-	  <arg choice='plain'><replaceable>operation</replaceable></arg>
-	  <arg rep='repeat'><replaceable>options</replaceable></arg>
-	  <arg rep='repeat'><replaceable>arguments</replaceable></arg>
-	</cmdsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-	<title>Description</title>
-
-	<para>
-	  The command <command>nix</command> provides access to the Nix store.
-	  This is the (set of) path(s) where Nix expressions and the file
-	  system objects built by them are stored.
-	</para>
-
-	<para>
-	  <command>nix</command> has many subcommands called
-	  <emphasis>operations</emphasis>.  These are individually documented
-	  below.  Exactly one operation must always be provided.
-	</para>
-
-      </refsect1>
-
-      <refsect1>
-	<title>Common Options</title>
-
-	<para>
-	  In this section the options that are common to all Nix operations are
-	  listed.  These options are allowed for every subcommand (although
-	  they may not always have an effect).
-	</para>
-
-	<variablelist>
-
-	  <varlistentry>
-	    <term><option>--path</option></term>
-	    <listitem>
-	      <para>
-		Indicates that any identifier arguments to the operation are
-		paths in the store rather than identifiers.
-	      </para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>--verbose</option></term>
-	    <listitem>
-	      <para>
-		Increases the level of verbosity of diagnostic messages printed
-		on standard error.  For each Nix operation, the information
-		printed on standard output is well-defined and specified below
-		in the respective sections.  Any diagnostic information is
-		printed on standard error, never on standard output.
-	      </para>
-
-	      <para>
-		This option may be specified repeatedly.  Currently, the
-		following verbosity levels exist:
-	      </para>
-
-	      <variablelist>
-		<varlistentry>
-		  <term>0</term>
-		  <listitem>
-		    <para>
-		      Print error messages only.
-		    </para>
-		  </listitem>
-		</varlistentry>
-		<varlistentry>
-		  <term>1</term>
-		  <listitem>
-		    <para>
-		      Print informational messages.
-		    </para>
-		  </listitem>
-		</varlistentry>
-		<varlistentry>
-		  <term>2</term>
-		  <listitem>
-		    <para>
-		      Print even more informational messages.
-		    </para>
-		  </listitem>
-		</varlistentry>
-		<varlistentry>
-		  <term>3</term>
-		  <listitem>
-		    <para>
-		      Print messages that should only be useful for debugging.
-		    </para>
-		  </listitem>
-		</varlistentry>
-		<varlistentry>
-		  <term>4</term>
-		  <listitem>
-		    <para>
-		      <quote>Vomit mode</quote>: print vast amounts of debug
-		      information.
-		    </para>
-		  </listitem>
-		</varlistentry>
-	      </variablelist>
-
-	    </listitem>
-	  </varlistentry>
-	</variablelist>
-
-      </refsect1>
-
-
-      <refsect1>
-	<title>Operation <option>--install</option></title>
-
-	<refsect2>
-	  <title>Synopsis</title>
-	  <cmdsynopsis>
-	    <command>nix</command>
-	    <group>
-	      <arg><option>--install</option></arg>
-	      <arg><option>-i</option></arg>
-	    </group>
-	    <arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg>
-	  </cmdsynopsis>
-	</refsect2>
-
-	<refsect2>
-	  <title>Description</title>
-	    
-	  <para>
-	    The operation <option>--install</option> realises the Nix
-	    expressions identified by <replaceable>ids</replaceable> in the
-	    file system.  If these expressions are derivation expressions, they
-	    are first normalised.  That is, their target paths are are built,
-	    unless a normal form is already known.
-	  </para>
-
-	  <para>
-	    The identifiers of the normal forms of the given Nix expressions
-	    are printed on standard output.
-	  </para>
-
-	</refsect2>
-	    
-      </refsect1>
-
-
-      <refsect1>
-	<title>Operation <option>--delete</option></title>
-
-	<refsect2>
-	  <title>Synopsis</title>
-	  <cmdsynopsis>
-	    <command>nix</command>
-	    <group>
-	      <arg><option>--delete</option></arg>
-	      <arg><option>-d</option></arg>
-	    </group>
-	    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
-	  </cmdsynopsis>
-	</refsect2>
-
-	<refsect2>
-	  <title>Description</title>
-	    
-	  <para>
-	    The operation <option>--delete</option> unconditionally deletes
-	    the paths <replaceable>paths</replaceable> from the Nix store.
-	    It is an error to attempt to delete paths outside of the store.
-	  </para>
-
-	  <warning>
-	    <para>
-	      This operation should almost never be called directly, since no
-	      attempt is made to check whether any references exist to the
-	      paths to be deleted.  Therefore, an inconsistent system could be
-	      the result.  Deletion of paths in the store is done by the
-	      garbage collector (which uses <option>--delete</option> to delete
-	      unreferenced paths).  
-	    </para>
-	  </warning>
-
-	</refsect2>
-	    
-      </refsect1>
-
-
-    </refentry>
-
+    &nix-reference;
   </appendix>
 
-
-  <!--======================================================================-->
-
-  <appendix>
-    <title>Troubleshooting</title>
-
-    <sect1>
-      <title>Database hangs</title>
-
-      <para>
-	If Nix or Fix appear to hang immediately after they are started, Nix's
-	database is probably <quote>wedged</quote>, i.e., some process died
-	while it held a lock on the database.  The solution is to ensure that
-	no other processes are accessing the database and then run the
-	following command:
-      </para>
-
-      <screen>
-$ db_recover -e -h <replaceable>prefix</replaceable>/var/nix/db</screen>
-
-      <para>
-	Here, <replaceable>prefix</replaceable> should be replaced by Nix's
-	installation prefix.
-      </para>
-
-    </sect1>
-
-
-    <sect1>
-      <title>Database logfile removal</title>
-
-      <para>
-	Every time a Nix database transaction takes place, Nix writes a record
-	of this transaction to a <emphasis>log</emphasis> in its database
-	directory to ensure that the operation can be replayed in case of a
-	application or system crash.  However, without manual intervention,
-	the log grows indefinitely.  Hence, unused log files should be deleted
-	periodically.  This can be accomplished using the following command:
-      </para>
-
-      <screen>
-$ rm `db_archive -a -h <replaceable>prefix</replaceable>/var/nix/db`</screen>
-
-    </sect1>
-	
-
-  </appendix>
-
-
-  <!--======================================================================-->
-
-  <appendix>
-    <title>Bugs</title>
-
-    <itemizedlist>
-
-      <listitem>
-	<para>
-	  Nix should automatically recover the Berkeley DB database.
-	</para>
-      </listitem>
-
-      <listitem>
-	<para>
-	  Nix should automatically remove Berkeley DB logfiles.
-	</para>
-      </listitem>
-
-    </itemizedlist>
-  </appendix>
+  &troubleshooting;
+  &bugs;
 
 </book>
diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml
new file mode 100644
index 000000000000..33c6e767baca
--- /dev/null
+++ b/doc/manual/bugs.xml
@@ -0,0 +1,26 @@
+<appendix>
+  <title>Bugs</title>
+
+  <itemizedlist>
+
+    <listitem>
+      <para>
+	Nix should automatically recover the Berkeley DB database.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+	Nix should automatically remove Berkeley DB logfiles.
+      </para>
+    </listitem>
+
+  </itemizedlist>
+
+</appendix>
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "appendix")
+end:
+-->
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
new file mode 100644
index 000000000000..7d8821d4700c
--- /dev/null
+++ b/doc/manual/installation.xml
@@ -0,0 +1,79 @@
+<chapter>
+  <title>Installation</title>
+
+  <sect1>
+    <title>Prerequisites</title>
+
+    <para>
+      Nix uses Sleepycat's Berkeley DB and CWI's ATerm library.  However, these
+      are fetched automatically as part of the build process.
+    </para>
+
+    <para>
+      Other than that, you need a good C++ compiler.  GCC 2.95 does not appear
+      to work; please use GCC 3.x.
+    </para>
+  </sect1>
+
+  <sect1>
+    <title>Obtaining Nix</title>
+
+    <para>
+      Nix can be obtained from its <ulink
+	url='http://losser.st-lab.cs.uu.nl:12080/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>
+
+    <screen>
+      $ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk
+      nix</screen>
+
+    <para>
+      Likewise, specific releases can be obtained from the <ulink
+	url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags
+	directory</ulink> of the repository.  If you don't have Subversion, you
+      can download a <ulink
+	url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
+	tar-file</ulink> of the latest revision of the repository.
+    </para>
+
+  </sect1>
+
+  <sect1>
+    <title>Building Nix</title>
+
+    <para>
+      To build Nix, do the following:
+    </para>
+
+    <screen>
+      $ autoreconf -i $ ./configure <replaceable>options...</replaceable> $
+      make $ make install</screen>
+
+    <para>
+      Currently, the only useful switch for <command>configure</command> is
+      <option>--prefix=<replaceable>prefix</replaceable></option> to specify
+      where Nix is to be installed.  The default installation directory is
+      <filename>/nix</filename>.  You can change this to any location you like.
+      You should ensure that you have write permission to the installation
+      prefix. 
+    </para>
+
+    <warning>
+      <para>
+	It is advisable <emphasis>not</emphasis> to change the installation
+	prefix, since doing so will in all likelihood make it impossible to use
+	derivates built on other systems.
+      </para>
+    </warning>
+
+  </sect1>
+
+</chapter>
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "chapter")
+end:
+-->
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
new file mode 100644
index 000000000000..77a5f917ee71
--- /dev/null
+++ b/doc/manual/introduction.xml
@@ -0,0 +1,98 @@
+<chapter>
+  <title>Introduction</title>
+
+  <sect1>
+    <title>The problem space</title>
+
+    <para>
+      Nix is a system for controlling the automatic creation and distribution
+      of data, such as computer programs and other software artifacts.  This is
+      a very general problem, and there are many applications that fall under
+      this description.
+    </para>
+
+    <sect2>
+      <title>Build management</title>
+
+      <para>
+	  Build management tools are used to perform <emphasis>software
+	  builds</emphasis>, that is, the construction of derived products such
+	as executable programs from source code.  A commonly used build tool is
+	Make, which is a standard tool on Unix systems. These tools have to
+	deal with several issues:
+	  <itemizedlist>
+	  <listitem>
+	    <para>
+	    </para>
+	  </listitem>
+	  </itemizedlist>
+      </para>
+
+    </sect2>
+
+    <sect2>
+      <title>Package management</title>
+
+      <para>
+	  After software has been built, is must also be
+	<emphasis>deployed</emphasis> in the intended target environment, e.g.,
+	the user's workstation.  Examples include the Red Hat package manager
+	(RPM), Microsoft's MSI, and so on.  Here also we have to deal with
+	several issues:
+	  <itemizedlist>
+	  <listitem>
+	    <para>
+	      The <emphasis>creation</emphasis> of packages from some formal
+	      description of what artifacts should be distributed in the
+	      package.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      The <emphasis>deployment</emphasis> of packages, that is, the
+	      mechanism by which we get them onto the intended target
+	      environment.  This can be as simple as copying a file, but
+	      complexity comes from the wide range of possible installation
+	      media (such as a network install), and the scalability of the
+	      process (if a program must be installed on a thousand systems, we
+	      do not want to visit each system and perform some manual steps to
+	      install the program on that system; that is, the complexity for
+	      the system administrator should be constant, not linear).
+	    </para>
+	  </listitem>
+	  </itemizedlist>
+      </para>
+    </sect2>
+
+  </sect1>
+
+  <sect1>
+    <title>The Nix system</title>
+
+    <para>
+      ...
+    </para>
+
+    <para>
+      Existing tools in this field generally both a underlying model (such as
+      the derivation graph of build tools, or the versioning scheme that
+      determines when two packages are <quote>compatible</quote> in a package
+      management system) and a formalism that allows ...
+    </para>
+
+    <para>
+      Following the principle of separation of mechanism and policy, the Nix
+      system separates the <emphasis>low-level aspect</emphasis> of file system
+      object management form the <emphasis>high-level aspect</emphasis> of the
+      ...
+    </para>
+
+  </sect1>
+
+</chapter>
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "chapter")
+end:
+-->
diff --git a/doc/manual/nix-reference.xml b/doc/manual/nix-reference.xml
new file mode 100644
index 000000000000..39c83518c3ba
--- /dev/null
+++ b/doc/manual/nix-reference.xml
@@ -0,0 +1,213 @@
+<refentry>
+  <refnamediv>
+    <refname>nix</refname>
+    <refpurpose>manipulate or query the Nix store</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>nix</command>
+      <group choice='opt'>
+	<arg><option>--path</option></arg>
+	<arg><option>-p</option></arg>
+      </group>
+      <group choice='opt' rep='repeat'>
+	<arg><option>--verbose</option></arg>
+	<arg><option>-v</option></arg>
+      </group>
+      <arg choice='plain'><replaceable>operation</replaceable></arg>
+      <arg rep='repeat'><replaceable>options</replaceable></arg>
+      <arg rep='repeat'><replaceable>arguments</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      The command <command>nix</command> provides access to the Nix store. This
+      is the (set of) path(s) where Nix expressions and the file system objects
+      built by them are stored.
+    </para>
+
+    <para>
+      <command>nix</command> has many subcommands called
+      <emphasis>operations</emphasis>.  These are individually documented
+      below.  Exactly one operation must always be provided.
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Common Options</title>
+
+    <para>
+      In this section the options that are common to all Nix operations are
+      listed.  These options are allowed for every subcommand (although they
+      may not always have an effect).
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+	<term><option>--path</option></term>
+	<listitem>
+	  <para>
+	    Indicates that any identifier arguments to the operation are paths
+	    in the store rather than identifiers.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><option>--verbose</option></term>
+	<listitem>
+	  <para>
+	    Increases the level of verbosity of diagnostic messages printed on
+	    standard error.  For each Nix operation, the information printed on
+	    standard output is well-defined and specified below in the
+	    respective sections.  Any diagnostic information is printed on
+	    standard error, never on standard output.
+	  </para>
+
+	  <para>
+	    This option may be specified repeatedly.  Currently, the following
+	    verbosity levels exist:
+	  </para>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term>0</term>
+	      <listitem>
+		<para>
+		  Print error messages only.
+		</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term>1</term>
+	      <listitem>
+		<para>
+		  Print informational messages.
+		</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term>2</term>
+	      <listitem>
+		<para>
+		  Print even more informational messages.
+		</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term>3</term>
+	      <listitem>
+		<para>
+		  Print messages that should only be useful for debugging.
+		</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term>4</term>
+	      <listitem>
+		<para>
+		  <quote>Vomit mode</quote>: print vast amounts of debug
+		  information.
+		</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1>
+
+
+  <refsect1>
+    <title>Operation <option>--install</option></title>
+
+    <refsect2>
+      <title>Synopsis</title>
+      <cmdsynopsis>
+	<command>nix</command>
+	<group>
+	  <arg><option>--install</option></arg>
+	  <arg><option>-i</option></arg>
+	</group>
+	<arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg>
+      </cmdsynopsis>
+    </refsect2>
+
+    <refsect2>
+      <title>Description</title>
+	    
+      <para>
+	The operation <option>--install</option> realises the Nix expressions
+	identified by <replaceable>ids</replaceable> in the file system.  If
+	these expressions are derivation expressions, they are first
+	normalised.  That is, their target paths are are built, unless a normal
+	form is already known.
+      </para>
+
+      <para>
+	The identifiers of the normal forms of the given Nix expressions are
+	printed on standard output.
+      </para>
+
+    </refsect2>
+	    
+  </refsect1>
+
+
+  <refsect1>
+    <title>Operation <option>--delete</option></title>
+
+    <refsect2>
+      <title>Synopsis</title>
+      <cmdsynopsis>
+	<command>nix</command>
+	<group>
+	  <arg><option>--delete</option></arg>
+	  <arg><option>-d</option></arg>
+	</group>
+	<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+      </cmdsynopsis>
+    </refsect2>
+
+    <refsect2>
+      <title>Description</title>
+	    
+      <para>
+	The operation <option>--delete</option> unconditionally deletes the
+	paths <replaceable>paths</replaceable> from the Nix store. It is an
+	error to attempt to delete paths outside of the store.
+      </para>
+
+      <warning>
+	<para>
+	  This operation should almost never be called directly, since no
+	  attempt is made to verify that no references exist to the paths to
+	  be deleted.  Therefore, careless deletion can result in an
+	  inconsistent system. Deletion of paths in the store is done by the
+	  garbage collector (which uses <option>--delete</option> to delete
+	  unreferenced paths).
+	  
+	</para>
+      </warning>
+
+    </refsect2>
+	    
+  </refsect1>
+
+
+</refentry>
+
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "refentry")
+end:
+-->
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
new file mode 100644
index 000000000000..018b3555fc18
--- /dev/null
+++ b/doc/manual/troubleshooting.xml
@@ -0,0 +1,49 @@
+<appendix>
+  <title>Troubleshooting</title>
+
+  <sect1>
+    <title>Database hangs</title>
+
+    <para>
+      If Nix or Fix appear to hang immediately after they are started, Nix's
+      database is probably <quote>wedged</quote>, i.e., some process died while
+      it held a lock on the database.  The solution is to ensure that no other
+      processes are accessing the database and then run the following command:
+    </para>
+
+    <screen>
+      $ db_recover -e -h <replaceable>prefix</replaceable>/var/nix/db</screen>
+
+    <para>
+      Here, <replaceable>prefix</replaceable> should be replaced by Nix's
+      installation prefix.
+    </para>
+
+  </sect1>
+
+
+  <sect1>
+    <title>Database logfile removal</title>
+
+    <para>
+      Every time a Nix database transaction takes place, Nix writes a record of
+      this transaction to a <emphasis>log</emphasis> in its database directory
+      to ensure that the operation can be replayed in case of a application or
+      system crash.  However, without manual intervention, the log grows
+      indefinitely.  Hence, unused log files should be deleted periodically.
+      This can be accomplished using the following command:
+    </para>
+
+    <screen>
+      $ rm `db_archive -a -h
+      <replaceable>prefix</replaceable>/var/nix/db`</screen>
+
+  </sect1>
+	
+</appendix>
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "appendix")
+end:
+-->