9 files changed, 110 insertions, 20 deletions
diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml
index 6638bf61e454..431c0e6d3570 100644
--- a/doc/manual/command-ref/conf-file.xml
+++ b/doc/manual/command-ref/conf-file.xml
@@ -456,6 +456,36 @@ builtins.fetchurl {
 
   </varlistentry>
 
+  <varlistentry xml:id="conf-narinfo-cache-negative-ttl"><term><literal>narinfo-cache-negative-ttl</literal></term>
+
+    <listitem>
+
+      <para>The TTL in seconds for negative lookups. If a store path is
+      queried from a substituter but was not found, there will be a
+      negative lookup cached in the local disk cache database for the
+      specified duration.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+  <varlistentry xml:id="conf-narinfo-cache-positive-ttl"><term><literal>narinfo-cache-positive-ttl</literal></term>
+
+    <listitem>
+
+      <para>The TTL in seconds for positive lookups. If a store path is
+      queried from a substituter, the result of the query will be cached
+      in the local disk cache database including some of the NAR
+      metadata. The default TTL is a month, setting a shorter TTL for
+      positive lookups can be useful for binary caches that have
+      frequent garbage collection, in which case having a more frequent
+      cache invalidation would prevent trying to pull the path again and
+      failing with a hash mismatch if the build isn't reproducible.
+      </para>
+
+    </listitem>
+
+  </varlistentry>
 
   <varlistentry xml:id="conf-netrc-file"><term><literal>netrc-file</literal></term>
 
@@ -511,7 +541,6 @@ password <replaceable>my-password</replaceable>
 
   </varlistentry>
 
-
   <varlistentry xml:id="conf-pre-build-hook"><term><literal>pre-build-hook</literal></term>
 
     <listitem>
@@ -788,7 +817,6 @@ password <replaceable>my-password</replaceable>
 
   </varlistentry>
 
-
 </variablelist>
 
 </para>
diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml
index d4563ac47551..eac7739558be 100644
--- a/doc/manual/command-ref/nix-env.xml
+++ b/doc/manual/command-ref/nix-env.xml
@@ -456,7 +456,7 @@ $ nix-env -f ~/foo.nix -i '.*'</screen>
 from another profile:
 
 <screen>
-$ nix-env -i --from-profile /nix/var/nix/profiles/foo -i gcc</screen>
+$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc</screen>
 
 </para>
 
diff --git a/doc/manual/command-ref/opt-common-syn.xml b/doc/manual/command-ref/opt-common-syn.xml
index 168bef080f4f..b610b54b9620 100644
--- a/doc/manual/command-ref/opt-common-syn.xml
+++ b/doc/manual/command-ref/opt-common-syn.xml
@@ -9,6 +9,9 @@
   </group>
 </arg>
 <arg>
+  <arg choice='plain'><option>--quiet</option></arg>
+</arg>
+<arg>
   <group choice='plain'>
     <arg choice='plain'><option>--no-build-output</option></arg>
     <arg choice='plain'><option>-Q</option></arg>
diff --git a/doc/manual/command-ref/opt-common.xml b/doc/manual/command-ref/opt-common.xml
index bcb60b30125c..4c572e129445 100644
--- a/doc/manual/command-ref/opt-common.xml
+++ b/doc/manual/command-ref/opt-common.xml
@@ -75,6 +75,23 @@
 </varlistentry>
 
 
+<varlistentry><term><option>--quiet</option></term>
+
+  <listitem>
+
+  <para>Decreases the level of verbosity of diagnostic messages
+  printed on standard error.  This is the inverse option to
+  <option>-v</option> / <option>--verbose</option>.
+  </para>
+
+  <para>This option may be specified repeatedly.  See the previous
+  verbosity levels list.</para>
+
+  </listitem>
+
+</varlistentry>
+
+
 <varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term>
 
   <listitem><para>By default, output written by builders to standard
diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml
index 47b98460adf6..ac1fe7e2fafe 100644
--- a/doc/manual/expressions/builtins.xml
+++ b/doc/manual/expressions/builtins.xml
@@ -1203,7 +1203,10 @@ in foo</programlisting>
 
     This is not allowed because it would cause a cyclic dependency in
     the computation of the cryptographic hashes for
-    <varname>foo</varname> and <varname>bar</varname>.</para></listitem>
+    <varname>foo</varname> and <varname>bar</varname>.</para>
+    <para>It is also not possible to reference the result of a derivation. 
+    If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to 
+    do that.</para></listitem>
 
   </varlistentry>
 
diff --git a/doc/manual/glossary/glossary.xml b/doc/manual/glossary/glossary.xml
index e0636044cc25..4977825578f1 100644
--- a/doc/manual/glossary/glossary.xml
+++ b/doc/manual/glossary/glossary.xml
@@ -85,29 +85,48 @@
 
 <glossentry xml: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>
+  <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. The <emphasis>references</emphasis> of a store path are
+    the set of store paths to which it has a reference.
+    </para>
+    <para>A derivation can reference other derivations and sources
+    (but not output paths), whereas an output path only references other
+    output paths.
+    </para>
+  </glossdef>
 
 </glossentry>
 
+<glossentry xml:id="gloss-reachable"><glossterm>reachable</glossterm>
+
+  <glossdef><para>A store path <varname>Q</varname> is reachable from
+  another store path <varname>P</varname> if <varname>Q</varname> is in the
+  <link linkend="gloss-closure">closure</link> of the
+  <link linkend="gloss-reference">references</link> relation.
+  </para></glossdef>
+</glossentry>
 
 <glossentry xml: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; 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>
+  linkend="gloss-reference">references</link> relation. For a package, the
+  closure of its derivation is equivalent to the build-time
+  dependencies, while the closure of its output path is equivalent to its
+  runtime dependencies. 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>
+  <para>As an example, 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>. Further, if <varname>Q</varname>
+  references <varname>R</varname> then <varname>R</varname> is also in
+  the closure of <varname>P</varname>.
+  </para></glossdef>
 
 </glossentry>
 
@@ -147,7 +166,7 @@
   linkend="sec-profiles" />.</para>
 
   </glossdef>
-  
+
 </glossentry>
 
 
diff --git a/doc/manual/installation/prerequisites-source.xml b/doc/manual/installation/prerequisites-source.xml
index 49660c36e397..01e9688d635f 100644
--- a/doc/manual/installation/prerequisites-source.xml
+++ b/doc/manual/installation/prerequisites-source.xml
@@ -9,6 +9,9 @@
 <itemizedlist>
 
   <listitem><para>GNU Make.</para></listitem>
+  
+  <listitem><para>Bash Shell. The <literal>./configure</literal> script
+  relies on bashisms, so Bash is required.</para></listitem>
 
   <listitem><para>A version of GCC or Clang that supports C++14.</para></listitem>
 
@@ -28,6 +31,14 @@
   distribution does not provide these, you can obtain bzip2 from <link
   xlink:href="http://www.bzip.org/"/>.</para></listitem>
 
+  <listitem><para><literal>liblzma</literal>, which is provided by
+  XZ Utils. If your distribution does not provide this, you can
+  get it from <link xlink:href="https://tukaani.org/xz/"/>.</para></listitem>
+  
+  <listitem><para>cURL and its library. If your distribution does not
+  provide it, you can get it from <link
+  xlink:href="https://curl.haxx.se/"/>.</para></listitem>
+      
   <listitem><para>The SQLite embedded database library, version 3.6.19
   or higher.  If your distribution does not provide it, please install
   it from <link xlink:href="http://www.sqlite.org/" />.</para></listitem>
diff --git a/doc/manual/introduction/about-nix.xml b/doc/manual/introduction/about-nix.xml
index 83a2b6786ac0..e8c0a29753a1 100644
--- a/doc/manual/introduction/about-nix.xml
+++ b/doc/manual/introduction/about-nix.xml
@@ -60,7 +60,8 @@ This is because tools such as compilers don’t search in per-packages
 directories such as
 <filename>/nix/store/5lbfaxb722zp…-openssl-0.9.8d/include</filename>,
 so if a package builds correctly on your system, this is because you
-specified the dependency explicitly.</para>
+specified the dependency explicitly. This takes care of the build-time
+dependencies.</para>
 
 <para>Once a package is built, runtime dependencies are found by
 scanning binaries for the hash parts of Nix store paths (such as
diff --git a/doc/manual/packages/garbage-collection.xml b/doc/manual/packages/garbage-collection.xml
index 03b8e4c976c1..a1b0ef22a11e 100644
--- a/doc/manual/packages/garbage-collection.xml
+++ b/doc/manual/packages/garbage-collection.xml
@@ -52,6 +52,14 @@ garbage collector as follows:
 <screen>
 $ nix-store --gc</screen>
 
+The behaviour of the gargage collector is affected by the <literal>keep-
+derivations</literal> (default: true) and <literal>keep-outputs</literal>
+(default: false) options in the Nix configuration file. The defaults will ensure
+that all derivations that are not build-time dependencies of garbage collector roots
+will be collected but that all output paths that are not runtime dependencies
+will be collected. (This is usually what you want, but while you are developing
+it may make sense to keep outputs to ensure that rebuild times are quick.)
+
 If you are feeling uncertain, you can also first view what files would
 be deleted: