diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index 51fddadf1..3f6c4f549 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -12,11 +12,128 @@
Introduction
-
- Nix is a system for the automatic creation and distribution of data, such
- as computer programs and other software artifacts.
-
+
+ The problem space
+
+ 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.
+
+
+
+ Build management
+
+
+ Build management tools are used to perform software
+ builds, 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:
+
+
+
+
+
+
+
+
+
+
+
+ Package management
+
+
+ After software has been built, is must also be
+ deployed 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:
+
+
+
+ The creation of packages from some formal
+ description of what artifacts should be distributed in the
+ package.
+
+
+
+
+ The deployment 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).
+
+
+
+
+
+
+
+
+
+ The Nix system
+
+
+ ...
+
+
+
+ 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 compatible
in a package
+ management system) and a formalism that allows ...
+
+
+
+ Following the principle of separation of mechanism and policy, the Nix
+ system separates the low-level aspect of file
+ system object management form the high-level
+ aspect of the ...
+
+
+
+
+
+
+
+
+
+
+ A Guided Tour
+
+
+ Bla bla
+
+
+
+
+
+
+
+ Fix Language Reference
+
+
+ Bla bla
+
+
+
+
+
+
+
+ Nix Syntax and Semantics
+
+
+ Bla bla
+
@@ -99,4 +216,74 @@ $ make install
+
+
+
+ Troubleshooting
+
+
+ Database hangs
+
+
+ If Nix or Fix appear to hang immediately after they are started, Nix's
+ database is probably wedged
, 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:
+
+
+
+$ db_recover -e -h prefix/var/nix/db
+
+
+ Here, prefix should be replaced by Nix's
+ installation prefix.
+
+
+
+
+
+
+ Database logfile removal
+
+
+ Every time a Nix database transaction takes place, Nix writes a record
+ of this transaction to a log 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:
+
+
+
+$ rm `db_archive -a -h prefix/var/nix/db`
+
+
+
+
+
+
+
+
+
+
+ Known problems
+
+
+
+
+
+ Nix should automatically recover the Berkeley DB database.
+
+
+
+
+
+ Nix should automatically remove Berkeley DB logfiles.
+
+
+
+
+
+