* More manual updates.

6 files changed, 154 insertions, 30 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index f5dfdb1dd876..60853df05dfa 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -5,9 +5,10 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
  --param section.autolabel 1 \
  --param section.label.includes.component.label 1 \
  --param html.stylesheet \'style.css\' \
- --param xref.with.number.and.title 0
+ --param xref.with.number.and.title 0 \
+ --param toc.section.depth 3
 
-man1_MANS = nix-env.1 nix-store.1 nix-instantiate.1 \
+man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
  nix-collect-garbage.1 nix-push.1 nix-pull.1 \
  nix-prefetch-url.1
 
diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml
index cf0da38245b1..c3dc36fb3f2f 100644
--- a/doc/manual/glossary.xml
+++ b/doc/manual/glossary.xml
@@ -46,7 +46,7 @@
 </glossentry>
 
 
-<glossentry><glossterm>substitute</glossterm>
+<glossentry id="gloss-substitute"><glossterm>substitute</glossterm>
 
   <glossdef><para>A substitute is a command invocation stored in the
   Nix database that describes how to build a store object, bypassing
@@ -94,6 +94,16 @@
 </glossentry>
 
 
+<glossentry id="gloss-validity"><glossterm>validity</glossterm>
+
+  <glossdef><para>A store path is considered
+  <emphasis>valid</emphasis> if it exists in the file system, is
+  listed in the Nix database as being valid, and if all paths in its
+  closure are also valid.</para></glossdef>
+
+</glossentry>
+
+
 </glosslist>
 
 
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 9f0e4ae94c50..b71798e80ac9 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -39,11 +39,15 @@
       <title>nix-env</title>
       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-env.xml" />
     </sect1>
+    <sect1 id="sec-nix-build">
+      <title>nix-build</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-build.xml" />
+    </sect1>
     <sect1>
       <title>nix-store</title>
       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-store.xml" />
     </sect1>
-    <sect1>
+    <sect1 id="sec-nix-instantiate">
       <title>nix-instantiate</title>
       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-instantiate.xml" />
     </sect1>
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
new file mode 100644
index 000000000000..2a5af6adb3d7
--- /dev/null
+++ b/doc/manual/nix-build.xml
@@ -0,0 +1,72 @@
+<refentry>
+  
+<refnamediv>
+  <refname>nix-build</refname>
+  <refpurpose>build a Nix expression</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-build</command>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsection><title>Description</title>
+
+<para>The <command>nix-build</command> command builds the derivations
+described by the Nix expressions in <replaceable>paths</replaceable>.
+If the build succeeds, it places a symlink to the result in the
+current directory.  The symlink is called <filename>result</filename>.
+If there are multiple Nix expressions, or the Nix expressions evaluate
+to multiple derivations, multiple sequentially numbered symlinks are
+created (<filename>result</filename>, <filename>result-2</filename>,
+and so on).</para>
+
+<note><para><command>nix-build</command> is essentially a wrapper
+around <link
+linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>
+(to translate a high-level Nix expression to a low-level store
+derivation) and <link
+linkend="rsec-nix-store-realise"><command>nix-store
+--realise</command></link> (to build the store
+derivation).</para></note>
+
+<warning><para>The result of the build is automatically registered as
+a root of the Nix garbage collector.  This root disappears
+automatically when the <filename>result</filename> symlink is deleted
+or renamed.  So don’t rename the symlink.</para></warning>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--add-drv-link</option></term>
+  
+    <listitem><para>Add a symlink in the current directory to the
+    store derivation produced by <command>nix-instantiate</command>.
+    The symlink is called <filename>derivation</filename> (which is
+    numbered in the case of multiple derivations).  The derivation is
+    a root of the garbage collector until the symlink is deleted or
+    renamed.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--no-link</option></term>
+  
+    <listitem><para>Do not create a symlink to the output path.  Note
+    that as a result the output does not become a root of the garbage
+    collector, and so might be deleted by <command>nix-store
+    --gc</command>.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+</refentry>
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index d9ef17e26ec3..c67e20266ff5 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -45,7 +45,7 @@ linkend="sec-common-options" /> for a list of common options.</para>
 
   <varlistentry id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term>
 
-    <listitem><para>Causes the result of a build action
+    <listitem><para>Causes the result of a realisation
     (<option>--realise</option> and <option>--force-realise</option>)
     to be registered as a root of the garbage collector (see <xref
     linkend="ssec-gc-roots" />).  The root is stored in
@@ -54,7 +54,12 @@ linkend="sec-common-options" /> for a list of common options.</para>
     typically in a subdirectory of
     <filename>/nix/var/nix/gcroots/</filename>)
     <emphasis>unless</emphasis> the <option>--indirect</option> flag
-    is used.</para></listitem>
+    is used.</para>
+
+    <para>If there are multiple results, then multiple symlinks will
+    be created by sequentially numbering symlinks beyond the first one
+    (e.g., <filename>foo</filename>, <filename>foo-2</filename>,
+    <filename>foo-3</filename>, and so on).</para></listitem>
 
   </varlistentry>
 
@@ -121,25 +126,56 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
 
 <refsection><title>Description</title>
             
-<para>The operation <option>--install</option> realises in the file
-system the store expressions stored in
-<replaceable>paths</replaceable>.  If these expressions are derivation
-expressions, they are first <emphasis>normalised</emphasis> into a
-closure expression.  This may happen in two ways.  First, the
-corresponding closure expression (the <emphasis>successor</emphasis>)
-may already known (either because the build has already been
-performed, or because a successor was explicitly registered through
-the <option>--successor</option> operation).  Otherwise, the build
-action described by the derivation is performed, and a closure
-expression is computed by scanning the result of the build for
-references to other paths in the store.</para>
-
-<para>The paths of the closure expression corresponding to each
-expression in <replaceable>paths</replaceable> is printed on standard
-output.</para>
+<para>The operation <option>--realise</option> essentially “builds”
+the specified store paths.  Realisation is a somewhat overloaded term:
+
+<itemizedlist>
+
+  <listitem><para>If the store path is a
+  <emphasis>derivation</emphasis>, realisation ensures that the output
+  paths of the derivation are <link
+  linkend="gloss-validity">valid</link> (i.e., the output path and its
+  closure exist in the file system).  This can be done in several
+  ways.  First, it is possible that the outputs are already valid, in
+  which case we are done immediately.  Otherwise, there may be <link
+  linkend="gloss-substitute">substitutes</link> that produce the
+  outputs (e.g., by downloading them).  Finally, the outputs can be
+  produced by performing the build action described by the
+  derivation.</para></listitem>
+
+  <listitem><para>If the store path is not a derivation, realisation
+  ensures that the specified path is valid (i.e., it and its closure
+  exist in the file system).  If the path is already valid, we are
+  done immediately.  Otherwise, the path and any missing paths in its
+  closure may be produced through substitutes.  If there are no
+  (succesful) subsitutes, realisation fails.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>The output path of each derivation is printed on standard
+output.  (For non-derivations argument, the argument itself is
+printed.)</para>
 
 </refsection>
             
+
+<refsection><title>Examples</title>
+
+<para>This operation is typically used to build store derivations
+produced by <link
+linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>:
+    
+<screen>
+$ nix-store -r $(nix-instantiate ./foo.nix)</screen>
+
+This is essentially what <link
+linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
+
+</refsection>
+
+
 </refsection>
 
   
@@ -168,7 +204,7 @@ output.</para>
 <para>Without additional flags, the operation <option>--gc</option>
 performs a garbage collection on the Nix store.  That is, all paths in
 the Nix store not reachable via file system references from a set of
-<quote>roots</quote>, are deleted.</para>
+“roots”, are deleted.</para>
 
 <para>The following suboperations may be specified:</para>
 
@@ -184,9 +220,9 @@ the Nix store not reachable via file system references from a set of
   <varlistentry><term><option>--print-live</option></term>
   
     <listitem><para>This operation prints on standard output the set
-    of <quote>live</quote> store paths, which are all the store paths
-    reachable from the roots.  Live paths should never be deleted,
-    since that would break consistency — it would become possible that
+    of “live” store paths, which are all the store paths reachable
+    from the roots.  Live paths should never be deleted, since that
+    would break consistency — it would become possible that
     applications are installed that reference things that are no
     longer present in the store.</para></listitem>
     
@@ -195,9 +231,9 @@ the Nix store not reachable via file system references from a set of
   <varlistentry><term><option>--print-dead</option></term>
   
     <listitem><para>This operation prints out on standard output the
-    set of <quote>dead</quote> store paths, which is just the opposite
-    of the set of live paths: any path in the store that is not live
-    (with respect to the roots) is dead.</para></listitem>
+    set of “dead” store paths, which is just the opposite of the set
+    of live paths: any path in the store that is not live (with
+    respect to the roots) is dead.</para></listitem>
     
   </varlistentry>
 
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index 1b177c7dab6b..a664f1e3256e 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -447,7 +447,8 @@ following:
 (import pkgs/system/i686-linux.nix).hello</programlisting>
 
 Call it <filename>test.nix</filename>.  You can then build it without
-installing it using the command <command>nix-build</command>:
+installing it using the command <link
+linkend="sec-nix-build"><command>nix-build</command></link>:
 
 <screen>
 $ nix-build ./test.nix