* Started on the introduction.

1 files changed, 189 insertions, 2 deletions

diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index 51fddadf17..3f6c4f5498 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -12,11 +12,128 @@
   <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>
+
+
+  <!--======================================================================-->
+
+  <chapter>
+    <title>A Guided Tour</title>
+
     <para>
-      Nix is a system for the automatic creation and distribution of data, such
-      as computer programs and other software artifacts.
+      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>
 
 
@@ -99,4 +216,74 @@ $ make install</screen>
   </chapter>
 
 
+  <!--======================================================================-->
+
+  <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>Known problems</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>
+
 </book>