* Lots of manual updates, in particular the new `nix-store --query'

  options were documented, as well as the Nix configuration file.

11 files changed, 465 insertions, 177 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 60853df05dfa..f5a93cf308c8 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -20,6 +20,7 @@ MANUAL_SRCS = manual.xml introduction.xml installation.xml \
  $(man1_MANS:.1=.xml) \
  troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \
  env-common.xml quick-start.xml nix-lang-ref.xml glossary.xml \
+ conf-file.xml \
  style.css images
 
 manual.is-valid: $(MANUAL_SRCS) version.txt
diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml
index 8a56a28c5079..9f8faae96ba8 100644
--- a/doc/manual/bugs.xml
+++ b/doc/manual/bugs.xml
@@ -2,36 +2,25 @@
 
 <itemizedlist>
 
-    <listitem>
-      <para>
-        The man-pages generated from the DocBook documentation are ugly.
-      </para>
-    </listitem>
-
-    <listitem>
-      <para>
-        Generations properly form a tree.  E.g., if after switching to
-        generation 39, we perform an installation action, a generation
-        43 is created which is a descendant of 39, not 42.  So a
-        rollback from 43 ought to go back to 39.  This is not
-        currently implemented; generations form a linear sequence.
-      </para>
-    </listitem>
-
-    <listitem>
-      <para>
-        <emphasis>Build management.</emphasis>  In principle it is already
-        possible to do build management using Nix (by writing builders that
-        perform appropriate build steps), but the Nix expression language is
-        not yet powerful enough to make this pleasant (?).  The language should
-        be extended with features from the <ulink
-          url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>.
-        Another interesting idea is to write a <command>make</command>
-        implementation that uses Nix as a back-end to support <ulink
-          url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink> 
-        build files.
-      </para>
-    </listitem>
+<listitem><para>The man-pages generated from the DocBook documentation
+are ugly.</para></listitem>
+
+<listitem><para>Generations properly form a tree.  E.g., if after
+switching to generation 39, we perform an installation action, a
+generation 43 is created which is a descendant of 39, not 42.  So a
+rollback from 43 ought to go back to 39.  This is not currently
+implemented; generations form a linear sequence.</para></listitem>
+
+<listitem><para><emphasis>Build management.</emphasis> In principle it
+is already possible to do build management using Nix (by writing
+builders that perform appropriate build steps), but the Nix expression
+language is not yet powerful enough to make this pleasant (?).  The
+language should be extended with features from the <ulink
+url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>.
+Another interesting idea is to write a <command>make</command>
+implementation that uses Nix as a back-end to support <ulink
+url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
+build files.</para></listitem>
 
 <listitem><para>For security, <command>nix-push</command> manifests
 should be digitally signed, and <command>nix-pull</command> should
@@ -44,6 +33,14 @@ them).</para></listitem>
 <command>nix-env --delete-generations</command> to remove non-current
 generations older than a certain age.</para></listitem>
 
+<listitem><para>There should be a flexible way to change the user
+environment builder.  Currently, you have to replace
+<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>,
+which is hard-coded into <command>nix-env</command>.  Also, the
+default builder should be more powerful.  For instance, there should
+be some way to specify priorities to resolve
+collisions.</para></listitem>
+
 </itemizedlist>
 
 </appendix>
diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml
new file mode 100644
index 000000000000..13fac53356c9
--- /dev/null
+++ b/doc/manual/conf-file.xml
@@ -0,0 +1,82 @@
+<sect1 id="sec-conf-file"><title>Nix configuration file</title>
+
+<para>A number of persistent settings of Nix are stored in the file
+<filename><replaceable>prefix</replaceable>/etc/nix/nix.conf</filename>.
+This file is a list of <literal><replaceable>name</replaceable> =
+<replaceable>value</replaceable></literal> pairs, one per line.
+Comments start with a <literal>#</literal> character.  An example
+configuration file is shown in <xref linkend="ex-nix-conf" />.</para>
+
+<example id='ex-nix-conf'><title>Nix expression for GNU Hello</title>
+
+<programlisting>
+gc-keep-outputs = true       # Nice for developers
+gc-keep-derivations = true   # Idem
+env-keep-derivations = false
+</programlisting>
+</example>
+
+<para>The following variables are currently available: 
+
+<variablelist>
+
+  <varlistentry id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term>
+
+    <listitem><para>If <literal>true</literal>, the garbage collector
+    will keep the outputs of non-garbage derivations.  If
+    <literal>false</literal> (default), outputs will be deleted unless
+    they are GC roots themselves (or reachable from other roots).</para>
+ 
+    <para>In general, outputs must be registered as roots separately.
+    However, even if the output of a derivation is registered as a
+    root, the collector will still delete store paths that are used
+    only at build time (e.g., the C compiler, or source tarballs
+    downloaded from the network).  To prevent it from doing so, set
+    this option to <literal>true</literal>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term>
+
+    <listitem><para>If <literal>true</literal> (default), the garbage
+    collector will keep the derivations from which non-garbage store
+    paths were built.  If <literal>false</literal>, they will be
+    deleted unless explicitly registered as a root (or reachable from
+    other roots).</para>
+
+    <para>Keeping derivation around is useful for querying and
+    traceability (e.g., it allows you to ask with what dependencies or
+    options a store path was built), so by default this option is on.
+    Turn it off to safe a bit of disk space (or a lot if
+    <literal>gc-keep-outputs</literal> is also turned on).</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>env-keep-derivations</literal></term>
+
+    <listitem><para>If <literal>false</literal> (default), derivations
+    are not stored in Nix user environments.  That is, the derivation
+    any build-time-only dependencies may be garbage-collected.</para>
+
+    <para>If <literal>true</literal>, when you add a Nix derivation to
+    a user environment, the path of the derivation is stored in the
+    user environment.  Thus, the derivation will not be
+    garbage-collected until the user environment generation is deleted
+    (<command>nix-env --delete-generations</command>).  To prevent
+    build-time-only dependencies from being collected, you should also
+    turn on <literal>gc-keep-outputs</literal>.</para>
+
+    <para>The difference between this option and
+    <literal>gc-keep-derivations</literal> is that this one is
+    “sticky”: it applies to any user environment created while this
+    option was enabled, while <literal>gc-keep-derivations</literal>
+    only applies at the moment the garbage collector is
+    run.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+</sect1>
diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml
index c3dc36fb3f2f..cee6dac254d6 100644
--- a/doc/manual/glossary.xml
+++ b/doc/manual/glossary.xml
@@ -79,17 +79,47 @@
 </glossentry>
 
 
-<glossentry><glossterm>closure</glossterm>
+<glossentry id="gloss-reference"><glossterm>reference</glossterm>
+
+  <glossdef><para>A store path <varname>P</varname> is said to have a
+  reference to a store path <varname>Q</varname> if the store object
+  at <varname>P</varname> contains the path <varname>Q</varname>
+  somewhere.  This implies than an execution involving
+  <varname>P</varname> potentially needs <varname>Q</varname> to be
+  present.  The <emphasis>references</emphasis> of a store path are
+  the set of store paths to which it has a reference.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-closure"><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>
+  path; that is, it’s the closure of the path under the <link
+  linkend="gloss-reference">references</link> relation.  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>
+
+
+<glossentry id="gloss-output-path"><glossterm>output path</glossterm>
+
+  <glossdef><para>A store path produced by a derivation.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-deriver"><glossterm>deriver</glossterm>
+
+  <glossdef><para>The deriver of an <link
+  linkend="gloss-output-path">output path</link> is the store
+  derivation that built it.</para></glossdef>
 
 </glossentry>
 
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index b71798e80ac9..f1dd0430a14d 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -35,6 +35,7 @@
     <title>Command Reference</title>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml" />
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="env-common.xml" />
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conf-file.xml" />
     <sect1>
       <title>nix-env</title>
       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-env.xml" />
diff --git a/doc/manual/nix-push.xml b/doc/manual/nix-push.xml
index c9c4b40c62ce..f683784ada91 100644
--- a/doc/manual/nix-push.xml
+++ b/doc/manual/nix-push.xml
@@ -10,14 +10,14 @@
     <command>nix-push</command>
     <group choice='req'>
       <arg choice='req'>
-        <arg choice='plain'><replaceable>archives-put-url</replaceable></arg>
-        <arg choice='plain'><replaceable>archives-get-url</replaceable></arg>
-        <arg choice='plain'><replaceable>manifest-put-url</replaceable></arg>
+        <arg choice='plain'><replaceable>archivesPutURL</replaceable></arg>
+        <arg choice='plain'><replaceable>archivesGetURL</replaceable></arg>
+        <arg choice='plain'><replaceable>manifestPutURL</replaceable></arg>
       </arg>
       <arg choice='req'>
         <arg choice='plain'><option>--copy</option></arg>
-        <arg choice='plain'><replaceable>archives-dir</replaceable></arg>
-        <arg choice='plain'><replaceable>manifest-file</replaceable></arg>
+        <arg choice='plain'><replaceable>archivesDir</replaceable></arg>
+        <arg choice='plain'><replaceable>manifestFile</replaceable></arg>
       </arg>
     </group>
     <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
@@ -59,20 +59,20 @@ machines using the <command>nix-pull</command> command.</para>
   archives.</para></listitem>
 
   <listitem><para>Each store path is uploaded to the remote directory
-  specified by <replaceable>archives-put-url</replaceable>.  HTTP PUT
+  specified by <replaceable>archivesPutURL</replaceable>.  HTTP PUT
   requests are used to do this.  However, before a file
   <varname>x</varname> is uploaded to
-  <literal><replaceable>archives-put-url</replaceable>/<varname>x</varname></literal>,
+  <literal><replaceable>archivesPutURL</replaceable>/<varname>x</varname></literal>,
   <command>nix-push</command> first determines whether this upload is
   unnecessary by issuing a HTTP HEAD request on
-  <literal><replaceable>archives-get-url</replaceable>/<varname>x</varname></literal>.
+  <literal><replaceable>archivesGetURL</replaceable>/<varname>x</varname></literal>.
   This allows a cache to be shared between many partially overlapping
   <command>nix-push</command> invocations.  (We use two URLs because
   the upload URL typically refers to a CGI script, while the download
   URL just refers to a file system directory on the server.)</para></listitem>
 
   <listitem><para>The manifest is uploaded using an HTTP PUT request
-  to <replaceable>manifest-put-url</replaceable>.  The corresponding
+  to <replaceable>manifestPutURL</replaceable>.  The corresponding
   URL to download the manifest can then be used by
   <command>nix-pull</command>.</para></listitem>
         
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index 0fec253bd974..614d30b6aceb 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -168,7 +168,8 @@ produced by <link
 linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>:
     
 <screen>
-$ nix-store -r $(nix-instantiate ./foo.nix)</screen>
+$ nix-store -r $(nix-instantiate ./test.nix)
+/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1</screen>
 
 This is essentially what <link
 linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
@@ -213,7 +214,9 @@ the Nix store not reachable via file system references from a set of
   <varlistentry><term><option>--print-roots</option></term>
   
     <listitem><para>This operation prints on standard output the set
-    of roots used by the garbage collector.</para></listitem>
+    of roots used by the garbage collector.  What constitutes a root
+    is described in <xref linkend="ssec-gc-roots"
+    />.</para></listitem>
     
   </varlistentry>
 
@@ -247,35 +250,11 @@ the Nix store not reachable via file system references from a set of
 
 </variablelist>
 
-</refsection>
-
-
-<refsection><title>Roots</title>
-
-<para>The roots of the garbage collector are all store paths to which
-there are symlinks in the directory
-<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>.
-For instance, the following command makes the path
-<filename>/nix/store/d718ef...-foo</filename> a root of the collector:
-
-<screen>
-$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen>
-	
-That is, after this command, the garbage collector will not remove
-<filename>/nix/store/d718ef...-foo</filename> or any of its
-dependencies.</para>
-
-<para>Subdirectories of
-<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>
-are also searched for symlinks.  Symlinks to non-store paths are
-followed and searched for roots, but TODO.</para>
-
-</refsection>
-
-
-<refsection><title>Configuration file</title>
-
-<para>TODO</para>
+<para>The behaviour of the collector is influenced by the <link
+linkend="conf-gc-keep-outputs"><literal>gc-keep-outputs</literal></link>
+and <link
+linkend="conf-gc-keep-derivations"><literal>gc-keep-derivations</literal></link>
+variables in the Nix configuration file.</para>
 
 </refsection>
 
@@ -309,18 +288,24 @@ $ nix-store --gc</screen>
     <arg choice='plain'><option>-q</option></arg>
   </group>
   <group choice='req'>
-    <arg choice='plain'><option>--list</option></arg>
-    <arg choice='plain'><option>-l</option></arg>
+    <arg choice='plain'><option>--outputs</option></arg>
     <arg choice='plain'><option>--requisites</option></arg>
     <arg choice='plain'><option>-R</option></arg>
-    <arg choice='plain'><option>--predecessors</option></arg>
+    <arg choice='plain'><option>--references</option></arg>
+    <arg choice='plain'><option>--referers</option></arg>
+    <arg choice='plain'><option>--referers-closure</option></arg>
+    <arg choice='plain'><option>--deriver</option></arg>
+    <arg choice='plain'><option>--deriver</option></arg>
     <arg choice='plain'><option>--graph</option></arg>
+    <arg choice='plain'><option>--tree</option></arg>
+    <arg choice='plain'><option>--binding</option> <replaceable>name</replaceable></arg>
+    <arg choice='plain'><option>--hash</option></arg>
   </group>
-  <arg><option>--normalise</option></arg>
-  <arg><option>-n</option></arg>
+  <arg><option>--use-output</option></arg>
+  <arg><option>-u</option></arg>
   <arg><option>--force-realise</option></arg>
   <arg><option>-f</option></arg>
-  <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
+  <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
 </cmdsynopsis>
 
 </refsection>
@@ -329,9 +314,14 @@ $ nix-store --gc</screen>
 <refsection><title>Description</title>
             
 <para>The operation <option>--query</option> displays various bits of
-information about store paths.  The queries are described below.  At
+information about the store paths .  The queries are described below.  At
 most one query can be specified.  The default query is
-<option>--list</option>.</para>
+<option>--outputs</option>.</para>
+
+<para>The paths <replaceable>paths</replaceable> may also be symlinks
+from outside of the Nix store, to the Nix store.  In that case, the
+query is applied to the target of the symlink.</para>
+
 
 </refsection>
 
@@ -365,47 +355,21 @@ most one query can be specified.  The default query is
             
 <variablelist>
 
-  <varlistentry><term><option>--list</option> / <option>-l</option></term>
+  <varlistentry><term><option>--outputs</option></term>
 
-    <listitem><para>Prints out the <emphasis>output paths</emphasis>
-    of the store expressions indicated by the identifiers
-    <replaceable>args</replaceable>.  In the case of a derivation
-    expression, these are the paths that will be produced when the
-    derivation is realised.  In the case of a closure expression,
-    these are the paths that were produced the derivation expression
-    of which the closure expression is a successor.</para></listitem>
+    <listitem><para>Prints out the <link
+    linkend="gloss-output-path">output paths</link> of the store
+    derivations <replaceable>paths</replaceable>.  These are the paths
+    that will be produced when the derivation is
+    built.</para></listitem>
     
   </varlistentry>
 
   <varlistentry><term><option>--requisites</option> / <option>-R</option></term>
 
-    <listitem><para>Prints out the requisite paths of the store
-    expressions indicated by the identifiers
-    <replaceable>args</replaceable>.  The requisite paths of a Nix
-    expression are the paths that need to be present in the system to
-    be able to realise the expression.  That is, they form the
-    <emphasis>closure</emphasis> of the expression in the file system
-    (i.e., no path in the set of requisite paths points to anything
-    outside the set of requisite paths).</para>
-
-    <para>The notion of requisite paths is very useful when one wants
-    to distribute store expressions.  Since they form a closure, they
-    are the only paths one needs to distribute to another system to be
-    able to realise the expression on the other system.</para>
-
-    <para>This query is generally used to implement various kinds of
-    deployment.  A <emphasis>source deployment</emphasis> is obtained
-    by distributing the requisite paths of a derivation expression.  A
-    <emphasis>binary deployment</emphasis> is obtained by distributing
-    the requisite paths of a closure expression.  A <emphasis>cache
-    deployment</emphasis> is obtained by distributing the requisite
-    paths of a derivation expression and specifying the option
-    <option>--include-successors</option>.  This will include not just
-    the paths of a source and binary deployment, but also all
-    expressions and paths of subterms of the source.  This is useful
-    if one wants to realise on the target system a Nix expression that
-    is similar but not quite the same as the one being distributed,
-    since any common subterms will be reused.</para>
+    <listitem><para>Prints out the <link
+    linkend="gloss-closure">closure</link> of the store path
+    <replaceable>paths</replaceable>.</para>
 
     <para>This query has one option:</para>
 
@@ -420,17 +384,104 @@ most one query can be specified.  The default query is
 
     </variablelist>
 
+    <para>This query can be used to implement various kinds of
+    deployment.  A <emphasis>source deployment</emphasis> is obtained
+    by distributing the closure of a store derivation.  A
+    <emphasis>binary deployment</emphasis> is obtained by distributing
+    the closure of an output path.  A <emphasis>cache
+    deployment</emphasis> (combined source/binary deployment,
+    including binaries of build-time-only dependencies) is obtained by
+    distributing the closure of a store derivation and specifying the
+    option <option>--include-outputs</option>.</para>
+    
     </listitem>
 
   </varlistentry>
 
+  <varlistentry><term><option>--references</option></term>
+  
+    <listitem><para>Prints the set of <link
+    linkend="gloss-reference">references</link> of the store paths
+    <replaceable>paths</replaceable>, that is, their immediate
+    dependencies.  (For <emphasis>all</emphasis> dependencies, use
+    <option>--requisites</option>.)</para></listitem>
+
+  </varlistentry>
+  
+  <varlistentry><term><option>--referers</option></term>
+  
+    <listitem><para>Prints the set of <emphasis>referers</emphasis> of
+    the store paths <replaceable>paths</replaceable>, that is, the
+    store paths currently existing in the Nix store that refer to one
+    of <replaceable>paths</replaceable>.  Note that contrary to the
+    references, the set of referers is not constant; it can change as
+    store paths are added or removed.</para></listitem>
+
+  </varlistentry>
+  
+  <varlistentry><term><option>--referers-closure</option></term>
+  
+    <listitem><para>Prints the closure of the set of store paths
+    <replaceable>paths</replaceable> under the referers relation; that
+    is, all store paths that directly or indirectly refer to one of
+    <replaceable>paths</replaceable>.  These are all the path currently
+    in the Nix store that are dependent on
+    <replaceable>paths</replaceable>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--deriver</option></term>
+  
+    <listitem><para>Prints the <link
+    linkend="gloss-deriver">deriver</link> of the store paths
+    <replaceable>paths</replaceable>.  If the path has no deriver
+    (e.g., if it is a source file), or if the deriver is not known
+    (e.g., in the case of a binary-only deployment), the string
+    <literal>unknown-deriver</literal> is printed.</para></listitem>
+
+  </varlistentry>
 
   <varlistentry><term><option>--graph</option></term>
   
-    <listitem><para>Prints a graph of the closure of the store
-    expressions identified by <replaceable>args</replaceable> in the
-    format of the <command>dot</command> tool of AT&amp;T's GraphViz
-    package.</para></listitem>
+    <listitem><para>Prints the references graph of the store paths
+    <replaceable>paths</replaceable> in the format of the
+    <command>dot</command> tool of AT&amp;T's <ulink
+    url="http://www.graphviz.org/">Graphviz package</ulink>.  This can
+    be used to visualise dependency graphs.  To obtain a build-time
+    dependency graph, apply this to a store derivation.  To obtain a
+    runtime dependency graph, apply it to an output
+    path.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--tree</option></term>
+  
+    <listitem><para>Prints the references graph of the store paths
+    <replaceable>paths</replaceable> as a nested ASCII tree.
+    References are ordered by descending closure size; this tends to
+    flatten the tree, making it more readable.  The query only
+    recurses into a store path when it is first encountered; this
+    prevents a blowup of the tree representation of the
+    graph.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--binding</option> <replaceable>name</replaceable></term>
+  
+    <listitem><para>Prints the value of the attribute
+    <replaceable>name</replaceable> (i.e., environment variable) of
+    the store derivations <replaceable>paths</replaceable>.  It is an
+    error for a derivation to not have the specified
+    attribute.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--hash</option></term>
+  
+    <listitem><para>Prints the SHA-256 hash of the contents of the
+    store path <replaceable>paths</replaceable>.  Since the hash is
+    stored in the Nix database, this is a fast
+    operation.</para></listitem>
 
   </varlistentry>
 
@@ -439,6 +490,81 @@ most one query can be specified.  The default query is
 </refsection>
 
 
+<refsection><title>Examples</title>
+
+<para>Print the closure (runtime dependencies) of the
+<command>svn</command> program in the current user environment:
+    
+<screen>
+$ nix-store -qR $(which svn)
+/nix/store/4mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
+/nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
+<replaceable>...</replaceable></screen>
+
+</para>
+
+<para>Print the build-time dependencies of <command>svn</command>:
+
+<screen>
+$ nix-store -qR $(nix-store -qd $(which svn))
+/nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv
+/nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh
+/nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv
+<replaceable>... lots of other paths ...</replaceable></screen>
+
+The difference with the previous example is that we ask the closure of
+the derivation (<option>-qd</option>), not the closure of the output
+path that contains <command>svn</command>.</para>
+
+<para>Show the build-time dependencies as a tree:
+
+<screen>
+$ nix-store -q --tree $(nix-store -qd $(which svn))
+/nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv
++---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh
++---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv
+|   +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash
+|   +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh
+<replaceable>...</replaceable></screen>
+
+</para>
+
+<para>Show all paths that depend on the same OpenSSL library as
+<command>svn</command>:
+
+<screen>
+$ nix-store -q --referers $(nix-store -q --binding openssl $(nix-store -qd $(which svn)))
+/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0
+/nix/store/4mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
+/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3
+/nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5</screen>
+
+</para>
+
+<para>Show all paths that directly or indirectly depend on the Glibc
+(C library) used by <command>svn</command>:
+
+<screen>
+$ nix-store -q --referers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}')
+/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2
+/nix/store/05l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4
+<replaceable>...</replaceable></screen>
+
+Note that <command>ldd</command> is a command that prints out the
+dynamic libraries used by an ELF executable.</para>
+
+<para>Make a picture of the runtime dependency graph of the current
+user environment:
+
+<screen>
+$ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps
+$ gv graph.ps</screen>
+
+</para>
+
+</refsection>
+
+
 </refsection>
 
   
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index fb35c1a743ad..467959f19628 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -35,33 +35,33 @@
   <variablelist>
     
     <varlistentry><term>0</term>
-    <listitem><para><quote>Errors only</quote>: only print messages
+    <listitem><para>“Errors only”: only print messages
     explaining why the Nix invocation failed.</para></listitem>
     </varlistentry>
       
     <varlistentry><term>1</term>
-    <listitem><para><quote>Informational</quote>: print
+    <listitem><para>“Informational”: print
     <emphasis>useful</emphasis> messages about what Nix is doing.
     This is the default.</para></listitem>
     </varlistentry>
       
     <varlistentry><term>2</term>
-    <listitem><para><quote>Talkative</quote>: print more informational
+    <listitem><para>“Talkative”: print more informational
     messages.</para></listitem>
     </varlistentry>
 
     <varlistentry><term>3</term>
-    <listitem><para><quote>Chatty</quote>: print even more
+    <listitem><para>“Chatty”: print even more
     informational messages.</para></listitem>
     </varlistentry>
 
     <varlistentry><term>4</term>
-    <listitem><para><quote>Debug</quote>: print debug
+    <listitem><para>“Debug”: print debug
     information.</para></listitem>
     </varlistentry>
 
     <varlistentry><term>5</term>
-    <listitem><para><quote>Vomit</quote>: print vast amounts of debug
+    <listitem><para>“Vomit”: print vast amounts of debug
     information.</para></listitem>
     </varlistentry>
     
@@ -120,19 +120,21 @@
 
   <listitem>
 
-  <para>Whenever Nix attempts to realise a derivation for which a
-  closure is already known, but this closure cannot be realised, fall
-  back on normalising the derivation.</para>
+  <para>Whenever Nix attempts to build a derivation for which
+  substitutes are known for each output path, but realising the output
+  paths through the substitutes fails, fall back on building the
+  derivation.</para>
 
   <para>The most common scenario in which this is useful is when we
   have registered substitutes in order to perform binary distribution
   from, say, a network repository.  If the repository is down, the
   realisation of the derivation will fail.  When this option is
-  specified, Nix will build the derivation instead.  Thus, binary
-  installation falls back on a source installation.  This option is
-  not the default since it is generally not desirable for a transient
-  failure in obtaining the substitutes to lead to a full build from
-  source (with the related consumption of resources).</para>
+  specified, Nix will build the derivation instead.  Thus,
+  installation from binaries falls back on nstallation from source.
+  This option is not the default since it is generally not desirable
+  for a transient failure in obtaining the substitutes to lead to a
+  full build from source (with the related consumption of
+  resources).</para>
 
   </listitem>
   
diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml
index 0b0e57504a37..b827ae75b6c5 100644
--- a/doc/manual/package-management.xml
+++ b/doc/manual/package-management.xml
@@ -369,30 +369,39 @@ $ nix-env --delete-generations 10 11 14</screen>
 garbage collector as follows:
 
 <screen>
-$ nix-collect-garbage</screen>
+$ nix-store --gc</screen>
 
-You can alo first view what files would be deleted:
+If you are feeling uncertain, you can also first view what files would
+be deleted:
 
 <screen>
-$ nix-collect-garbage --print-dead</screen>
+$ nix-store --gc --print-dead</screen>
 
 Likewise, the option <option>--print-live</option> will show the paths
 that <emphasis>won’t</emphasis> be deleted.</para>
 
+
 <sect2 id="ssec-gc-roots"><title>Garbage collector roots</title>
 
-<para>TODO</para>
-
-<para>The garbage collector uses as roots all store expressions
-mentioned in all files with extension <filename>.gcroot</filename> in
-the directory
-<filename><replaceable>prefix</replaceable>/var/nix/gcroots/</filename>,
-or in any file or directory symlinked to from that directory.  E.g.,
-by default,
-<filename><replaceable>prefix</replaceable>/var/nix/gcroots/</filename>
-contains a symlink to
-<filename><replaceable>prefix</replaceable>/var/nix/profiles/</filename>,
-so all generations of all profiles are also roots of the collector.</para>
+<para>The roots of the garbage collector are all store paths to which
+there are symlinks in the directory
+<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>.
+For instance, the following command makes the path
+<filename>/nix/store/d718ef...-foo</filename> a root of the collector:
+
+<screen>
+$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen>
+	
+That is, after this command, the garbage collector will not remove
+<filename>/nix/store/d718ef...-foo</filename> or any of its
+dependencies.</para>
+
+<para>Subdirectories of
+<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>
+are also searched for symlinks.  Symlinks to non-store paths are
+followed and searched for roots, but symlinks to non-store paths
+<emphasis>inside</emphasis> the paths reached in that way are not
+followed to prevent infinite recursion.</para>
 
 </sect2>
 
diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start.xml
index e12b28da25bb..a6433ae42fe9 100644
--- a/doc/manual/quick-start.xml
+++ b/doc/manual/quick-start.xml
@@ -88,8 +88,8 @@ $ nix-channel --update
 $ nix-env -u '*'</screen>
 
 The latter command will upgrade each installed component for which
-there is a <quote>newer</quote> version (as determined by comparing
-the version numbers).</para></listitem>
+there is a “newer” version (as determined by comparing the version
+numbers).</para></listitem>
 
 <listitem><para>If you're unhappy with the result of a
 <command>nix-env</command> action (e.g., an upgraded component turned
@@ -106,12 +106,12 @@ actually delete them:
 
 <screen>
 $ nix-env --delete-generations old
-$ nix-collect-garbage</screen>
+$ nix-store --gc</screen>
 
-The first command deletes old <quote>generations</quote> of your
-profile (making rollbacks impossible, but also making the components
-in those old generations available for garbage collection), while the
-second command actually deletes them.</para></listitem>
+The first command deletes old “generations” of your profile (making
+rollbacks impossible, but also making the components in those old
+generations available for garbage collection), while the second
+command actually deletes them.</para></listitem>
 
 </orderedlist>
 
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
index cd0bafe3d663..4179eb8411d3 100644
--- a/doc/manual/troubleshooting.xml
+++ b/doc/manual/troubleshooting.xml
@@ -1,31 +1,71 @@
-<appendix>
-  <title>Troubleshooting</title>
+<appendix><title>Troubleshooting</title>
 
-  <para>This section provides solutions for some common problems.</para>
+<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:
+<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:
+</para>
+
+<para>Possible solution: make sure that no Nix processes are running,
+then do:
 
 <screen>
 $ cd /nix/var/nix/db
 $ rm __db.00*</screen>
 
-  </para>
+</para>
+
+</sect1>
+
+
+<sect1><title>Collisions in <command>nix-env</command></title>
+
+<para>Symptom: when installing or upgrading, you get an error message such as
+
+<screen>
+$ nix-env -i docbook-xml
+...
+adding /nix/store/s5hyxgm62gk2...-docbook-xml-4.2
+collission between `/nix/store/s5hyxgm62gk2...-docbook-xml-4.2/xml/dtd/docbook/calstblx.dtd'
+  and `/nix/store/06h377hr4b33...-docbook-xml-4.3/xml/dtd/docbook/calstblx.dtd'
+  at /nix/store/...-builder.pl line 62.</screen>
+
+</para>
+
+<para>The cause is that two installed packages in the user environment
+have overlapping filenames (e.g.,
+<filename>xml/dtd/docbook/calstblx.dtd</filename>.  This usually
+happens when you accidentally try to install two versions of the same
+package.  For instance, in the example above, the Nix Packages
+collection contains two versions of <literal>docbook-xml</literal>, so
+<command>nix-env -i</command> will try to install both.  The default
+user environment builder has no way to way to resolve such conflicts,
+so it just gives up.</para>
+
+<para>Solution: remove one of the offending packages from the user
+environment (if already installed) using <command>nix-env
+-u</command>, or specify exactly which version should be installed
+(e.g., <literal>nix-env -i docbook-xml-4.2</literal>).</para>
+
+<para>Alternatively, you can modify the user environment builder
+script (in
+<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>)
+to implement some conflict resolution policy.  E.g., the script could
+be modified to rename conflicting file names, or to pick one over the
+other.</para>
+
+</sect1>
+
 
-  
-  </sect1>
-  
-	
 </appendix>