* Split the book.xml into several xml files.

1 files changed, 10 insertions, 467 deletions

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>