* Manual updates.

5 files changed, 137 insertions, 85 deletions

diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml
index 2c4f55c7e7f0..cf0da38245b1 100644
--- a/doc/manual/glossary.xml
+++ b/doc/manual/glossary.xml
@@ -3,10 +3,16 @@
 <glosslist>
 
 
-<glossentry><glossterm>derivation</glossterm>
+<glossentry id="gloss-derivation"><glossterm>derivation</glossterm>
 
   <glossdef><para>A description of a build action.  The result of a
-  derivation is a store object.</para></glossdef>
+  derivation is a store object.  Derivations are typically specified
+  in Nix expressions using the <link
+  linkend="ssec-derivation"><function>derivation</function>
+  primitive</link>.  These are translated into low-level
+  <emphasis>store derivations</emphasis> (implicitly by
+  <command>nix-env</command> and <command>nix-build</command>, or
+  explicitly by <command>nix-instantiate</command>).</para></glossdef>
 
 </glossentry>
 
@@ -73,7 +79,22 @@
 </glossentry>
 
 
+<glossentry><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
+  path.  For instance, if the store object at path
+  <varname>P</varname> contains a reference to path
+  <varname>Q</varname>, then <varname>Q</varname> is in the closure of
+  <varname>P</varname>.  For correct deployment it is necessary to
+  deploy whole closures, since otherwise at runtime files could be
+  missing.  The command <command>nix-store -qR</command> prints out
+  closures of store paths.</para></glossdef>
+
+</glossentry>
+
+
 </glosslist>
 
 
-</appendix>
\ No newline at end of file
+</appendix>
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index d854941a09bd..d6cbe77c93de 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -1,89 +1,97 @@
 <refentry>
-  <refnamediv>
-    <refname>nix-instantiate</refname>
-    <refpurpose>instantiate store expressions from Nix expressions</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>nix-instantiate</command>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
-      <group choice='opt'>
-        <arg choice='plain'><option>--parse-only</option></arg>
-        <arg choice='plain'><option>--eval-only</option></arg>
-      </group>
-      <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-
-  <refsection>
-    <title>Description</title>
-
-    <para>
-      The command <command>nix-instantiate</command> generates
-      (low-level) store expressions from (high-level) Nix expressions.
-      It loads and evaluates the Nix expressions in each of
-      <replaceable>files</replaceable>.  Each top-level expression
-      should evaluate to a derivation, a list of derivations, or a set
-      of derivations.  The paths of the resulting store expressions
-      are printed on standard output.
-    </para>
-
-    <para>
-      This command is generally used for testing Nix expression before
-      they are used with <command>nix-env</command>.  See also <xref
-      linkend="sec-common-options" />.
-    </para>
-
-  </refsection>
-
-  <refsection>
-    <title>Options</title>
-
-    <variablelist>
-
-      <varlistentry>
-        <term><option>--parse-only</option></term>
-        <listitem>
-          <para>
-            Just parse the input files, and print their abstract
-            syntax trees on standard output in ATerm format.
-          </para>
-        </listitem>
-      </varlistentry>
+  
+<refnamediv>
+  <refname>nix-instantiate</refname>
+  <refpurpose>instantiate store derivations from Nix expressions</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-instantiate</command>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
+    <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
+    <arg><option>--indirect</option></arg>
+    <group choice='opt'>
+      <arg choice='plain'><option>--parse-only</option></arg>
+      <arg choice='plain'><option>--eval-only</option></arg>
+    </group>
+    <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-instantiate</command> generates <link
+linkend="gloss-derivation">store derivations</link> from (high-level)
+Nix expressions.  It loads and evaluates the Nix expressions in each
+of <replaceable>files</replaceable>.  Each top-level expression should
+evaluate to a derivation, a list of derivations, or a set of
+derivations.  The paths of the resulting store derivations are printed
+on standard output.</para>
+
+<para>Most users and developers don’t need to use this command
+(<command>nix-env</command> and <command>nix-build</command> perform
+store derivation instantiation from Nix expressions automatically).
+It is most commonly used for implementing new deployment
+policies.</para>
+
+<para>See also <xref linkend="sec-common-options" /> for a list of
+common options.</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>--add-root</option> <replaceable>path</replaceable></term>
+    <term><option>--indirect</option></term>
+
+    <listitem><para>See the <link linkend="opt-add-root">corresponding
+    options</link> in <command>nix-store</command>.</para></listitem>
+
+  </varlistentry>
+
+    
+  <varlistentry><term><option>--parse-only</option></term>
+  
+    <listitem><para>Just parse the input files, and print their
+    abstract syntax trees on standard output in ATerm
+    format.</para></listitem>
+    
+  </varlistentry>
       
-      <varlistentry>
-        <term><option>--eval-only</option></term>
-        <listitem>
-          <para>
-            Just parse and evaluate the input files, and print the
-            resulting values on standard output.  No instantiation of
-            store expressions takes place.
-          </para>
-        </listitem>
-      </varlistentry>
+  <varlistentry><term><option>--eval-only</option></term>
+  
+    <listitem><para>Just parse and evaluate the input files, and print
+    the resulting values on standard output.  No instantiation of
+    store derivations takes place.</para></listitem>
+    
+  </varlistentry>
 
-    </variablelist>
+</variablelist>
 
-  </refsection>
+</refsection>
 
-  <refsection>
-    <title>Examples</title>
 
-    <screen>
-$ nix-instantiate gcc.nix <lineannotation>(instantiate)</lineannotation>
-/nix/store/468abdcb93aa22bb721142615b97698b-d-gcc-3.3.2.store
+<refsection><title>Examples</title>
 
-$ nix-store -r $(nix-instantiate gcc.nix) <lineannotation>(build)</lineannotation>
+<screen>
+$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation>
+/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
 
-$ nix-store -r $(nix-instantiate gcc.nix) <lineannotation>(print output path)</lineannotation>
-/nix/store/9afa718cddfdfe94b5b9303d0430ceb1-gcc-3.3.2
+$ nix-store -r $(nix-instantiate test.nix) <lineannotation>(build)</lineannotation>
+<replaceable>...</replaceable>
+/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <lineannotation>(output path)</lineannotation>
 
-$ ls -l /nix/store/9afa718cddfdfe94b5b9303d0430ceb1-gcc-3.3.2
-dr-xr-xr-x    2 eelco    users         360 2003-12-01 16:12 bin
-dr-xr-xr-x    3 eelco    users          72 2003-12-01 16:12 include
+$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
+dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
 ...</screen>
 
-  </refsection>
-    
+</refsection>
+
+
 </refentry>
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index da96630a5367..0ad0f32a5f8f 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -39,11 +39,11 @@ be performed.  These are documented below.</para>
 <para>This section lists the options that are common to all
 operations.  These options are allowed for every subcommand, though
 they may not always have an effect.  See also <xref
-linkend="sec-common-options" />.</para>
+linkend="sec-common-options" /> for a list of common options.</para>
 
 <variablelist>
 
-  <varlistentry><term><option>--add-root</option> <replaceable>path</replaceable></term>
+  <varlistentry id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term>
 
     <listitem><para>Causes the result of a build action
     (<option>--realise</option> and <option>--force-realise</option>)
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
index cc3cd361f8b5..cd0bafe3d663 100644
--- a/doc/manual/troubleshooting.xml
+++ b/doc/manual/troubleshooting.xml
@@ -1,8 +1,31 @@
 <appendix>
   <title>Troubleshooting</title>
 
-  <para>
-    (Nothing.)
+  <para>This section provides solutions for some common problems.</para>
+
+  <sect1><title>Berkeley DB: <quote>Cannot allocate memory</quote></title>
+
+  <para>Symptom: Nix operations (in particular the
+  <command>nix-store</command> operations <option>--gc</option>,
+  <option>--verify</option>, and <option>--clear-substitutes</option>
+  — the latter being called by <command>nix-channel
+  --update</command>) failing:
+
+<screen>
+$ nix-store --verify
+error: Db::del: Cannot allocate memory</screen>
+
+   Possible solution: make sure that no Nix processes are running,
+   then do:
+
+<screen>
+$ cd /nix/var/nix/db
+$ rm __db.00*</screen>
+
   </para>
+
+  
+  </sect1>
+  
 	
 </appendix>
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index a465177f30f6..50cbc4249d7f 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -1103,7 +1103,7 @@ weakest binding).</para>
 </simplesect>
 
 
-<simplesect><title>Derivations</title>
+<simplesect id="ssec-derivation"><title>Derivations</title>
 
 <para>The most important built-in function is
 <function>derivation</function>, which is used to describe a