* Refactoring.

* Convert tabs to spaces.

7 files changed, 643 insertions, 664 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 8b3060ac7245..8e2fff208747 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -3,16 +3,17 @@ ENV = SGML_CATALOG_FILES=$(docbookcatalog)
 XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs
 XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs
 
-SOURCES = book.xml introduction.xml installation.xml nix-reference.xml \
+SOURCES = book.xml introduction.xml installation.xml \
+ nix-store-reference.xml \
  troubleshooting.xml bugs.xml
 
 book.is-valid: $(SOURCES)
 	$(XMLLINT) --noout --valid book.xml
 	touch $@
 
-man1_MANS = nix.1 fix.1
+man1_MANS = nix-store.1 nix-instantiate.1
 
-man nix.1 fix.1: $(SOURCES) book.is-valid
+man $(MANS): $(SOURCES) book.is-valid
 	$(XSLTPROC) $(docbookxsl)/manpages/docbook.xsl book.xml
 
 book.html: $(SOURCES) book.is-valid
@@ -24,4 +25,6 @@ install-data-local: book.html
 	$(INSTALL) -d $(datadir)/nix/manual
 	$(INSTALL_DATA) book.html $(datadir)/nix/manual
 
-EXTRA_DIST = $(SOURCES) book.html nix.1 fix.1 book.is-valid
+EXTRA_DIST = $(SOURCES) book.html book.is-valid $(MANS) 
+
+DISTCLEANFILES = book.html book.is-valid $(MANS)
diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index a2035fca7f1c..1dc69d0041a1 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -5,8 +5,8 @@
 [
 <!ENTITY introduction SYSTEM "introduction.xml">
 <!ENTITY installation SYSTEM "installation.xml">
-<!ENTITY nix-reference SYSTEM "nix-reference.xml">
-<!ENTITY fix-reference SYSTEM "fix-reference.xml">
+<!ENTITY nix-store-reference SYSTEM "nix-store-reference.xml">
+<!ENTITY nix-instantiate-reference SYSTEM "nix-instantiate-reference.xml">
 <!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
 <!ENTITY bugs SYSTEM "bugs.xml">
 ]>
@@ -28,34 +28,10 @@
   &introduction;
   &installation;
 
-  <chapter>
-    <title>A Guided Tour</title>
-    <para>
-    </para>
-  </chapter>
-
-  <chapter>
-    <title>Nix Syntax and Semantics</title>
-    <para>
-    </para>
-  </chapter>
-
-  <chapter>
-    <title>Fix Language Reference</title>
-    <para>
-    </para>
-  </chapter>
-
-  <chapter>
-    <title>Writing Builders</title>
-    <para>
-    </para>
-  </chapter>
-
   <appendix>
     <title>Command Reference</title>
-    &nix-reference;
-    &fix-reference;
+    &nix-store-reference;
+    &nix-instantiate-reference;
   </appendix>
 
   &troubleshooting;
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index bec9ebb212c1..f9bd0a742fdf 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -20,8 +20,8 @@
 
     <para>
       Nix can be obtained from its <ulink
-	url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk'>Subversion 
-	repository</ulink>.  For example, the following command will check out
+        url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk'>Subversion 
+        repository</ulink>.  For example, the following command will check out
       the latest revision into a directory called <filename>nix</filename>:
     </para>
 
@@ -30,11 +30,11 @@ $ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk nix</sc
 
     <para>
       Likewise, specific releases can be obtained from the <ulink
-	url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags
-	directory</ulink> of the repository.  If you don't have Subversion, you
+        url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags
+        directory</ulink> of the repository.  If you don't have Subversion, you
       can download a <ulink
-	url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
-	tar-file</ulink> of the latest revision of the repository.
+        url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
+        tar-file</ulink> of the latest revision of the repository.
     </para>
 
   </sect1>
@@ -63,9 +63,9 @@ $ make install</screen>
 
     <warning>
       <para>
-	It is advisable <emphasis>not</emphasis> to change the installation
-	prefix, since doing so will in all likelihood make it impossible to use
-	derivates built on other systems.
+        It is advisable <emphasis>not</emphasis> to change the installation
+        prefix, since doing so will in all likelihood make it impossible to use
+        derivates built on other systems.
       </para>
     </warning>
 
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index 5eea764592bd..feabeef9cdc2 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -15,74 +15,74 @@
       <title>Build management</title>
 
       <para>
-	Build management tools are used to perform <emphasis>software
-	  builds</emphasis>, that is, the construction of derived products
-	(<emphasis>derivates)</emphasis>) 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:
-	<itemizedlist>
-
-	  <listitem>
-	    <para>
-	      <emphasis>Efficiency</emphasis>.  Since building large systems
-	      can take a substantial amount of time, it is desirable that build
-	      steps that have been performed in the past are not repeated
-	      unnecessarily, i.e., if a new build differs from a previous build
-	      only with respect to certain sources, then only the build steps
-	      that (directly or indirectly) <emphasis>depend</emphasis> on
-	      those sources should be redone.
-	    </para>
-	  </listitem>
-
-	  <listitem>
-	    <para>
-	      <emphasis>Correctness</emphasis> is this context means that the
-	      derivates produced by a build are always consistent with the
-	      sources, that is, they are equal to what we would get if we were
-	      to build the derivates from those sources.  This requirement is
-	      trivially met when we do a full, unconditional build, but is far
-	      from trivial under the requirement of efficiency, since it is not
-	      easy to determine which derivates are affected by a change to a
-	      source.
-	    </para>
-	  </listitem>
-
-	  <listitem>
-	    <para>
-	      <emphasis>Variability</emphasis> is the property that a software
-	      system can be built in a (potentially large) number of variants.
-	      Variation exists both in <emphasis>time</emphasis>---the
-	      evolution of different versions of an artifact---and in
-	      <emphasis>space</emphasis>---the artifact might have
-	      configuration options that lead to variants that differ in the
-	      features they support (for example, a system might be built with
-	      or without debugging information).
-	    </para>
-
-	    <para>
-	      Build managers historically have had good support for variation
-	      in time (rebuilding the system in an intelligent way when sources
-	      change is one of the primary reasons to use a build manager), but
-	      not always for variation in space.  For example,
-	      <command>make</command> will not automatically ensure that
-	      variant builds are properly isolated from each other (they will
-	      in fact overwrite each other unless special precautions are
-	      taken).
-	    </para>
-	  </listitem>
-
-	  <listitem>
-	    <para>
-	      <emphasis>High-level system modelling language</emphasis>.  The
-	      language in which one describes what and how derivates are to be
-	      produced should have sufficient abstraction facilities to make it
-	      easy to specify the derivation of even very large systems.  Also,
-	      the language should be <emphasis>modular</emphasis> to enable
-	      components from possible different sources to be easily combined.
-	    </para>
-	  </listitem>
-
-	</itemizedlist>
+        Build management tools are used to perform <emphasis>software
+          builds</emphasis>, that is, the construction of derived products
+        (<emphasis>derivates)</emphasis>) 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:
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <emphasis>Efficiency</emphasis>.  Since building large systems
+              can take a substantial amount of time, it is desirable that build
+              steps that have been performed in the past are not repeated
+              unnecessarily, i.e., if a new build differs from a previous build
+              only with respect to certain sources, then only the build steps
+              that (directly or indirectly) <emphasis>depend</emphasis> on
+              those sources should be redone.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis>Correctness</emphasis> is this context means that the
+              derivates produced by a build are always consistent with the
+              sources, that is, they are equal to what we would get if we were
+              to build the derivates from those sources.  This requirement is
+              trivially met when we do a full, unconditional build, but is far
+              from trivial under the requirement of efficiency, since it is not
+              easy to determine which derivates are affected by a change to a
+              source.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis>Variability</emphasis> is the property that a software
+              system can be built in a (potentially large) number of variants.
+              Variation exists both in <emphasis>time</emphasis>---the
+              evolution of different versions of an artifact---and in
+              <emphasis>space</emphasis>---the artifact might have
+              configuration options that lead to variants that differ in the
+              features they support (for example, a system might be built with
+              or without debugging information).
+            </para>
+
+            <para>
+              Build managers historically have had good support for variation
+              in time (rebuilding the system in an intelligent way when sources
+              change is one of the primary reasons to use a build manager), but
+              not always for variation in space.  For example,
+              <command>make</command> will not automatically ensure that
+              variant builds are properly isolated from each other (they will
+              in fact overwrite each other unless special precautions are
+              taken).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis>High-level system modelling language</emphasis>.  The
+              language in which one describes what and how derivates are to be
+              produced should have sufficient abstraction facilities to make it
+              easy to specify the derivation of even very large systems.  Also,
+              the language should be <emphasis>modular</emphasis> to enable
+              components from possible different sources to be easily combined.
+            </para>
+          </listitem>
+
+        </itemizedlist>
       </para>
 
     </sect2>
@@ -91,33 +91,33 @@
       <title>Package management</title>
 
       <para>
-	After software has been built, is must also be
-	<emphasis>deployed</emphasis> 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 several issues to
-	contend with:
-	<itemizedlist>
-	  <listitem>
-	    <para>
-	      The <emphasis>creation</emphasis> of packages from some formal
-	      description of what artifacts should be distributed in the
-	      package.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-	      The <emphasis>deployment</emphasis> 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).
-	    </para>
-	  </listitem>
-	</itemizedlist>
+        After software has been built, is must also be
+        <emphasis>deployed</emphasis> 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 several issues to
+        contend with:
+        <itemizedlist>
+          <listitem>
+            <para>
+              The <emphasis>creation</emphasis> of packages from some formal
+              description of what artifacts should be distributed in the
+              package.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              The <emphasis>deployment</emphasis> 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).
+            </para>
+          </listitem>
+        </itemizedlist>
       </para>
     </sect2>
 
@@ -136,95 +136,95 @@
     <itemizedlist>
 
       <listitem>
-	<para>
-	  <emphasis>Reliable dependencies.</emphasis>  Builds of file system
-	  objects depend on other file system object, such as source files,
-	  tools, and so on.  We would like to ensure that a build does not
-	  refer to any objects that have not been declared as inputs for that
-	  build.  This is important for several reasons.  First, if any of the
-	  inputs change, we need to rebuild the things that depend on them to
-	  maintain consistency between sources and derivates.  Second, when we
-	  <emphasis>deploy</emphasis> file system objects (that is, copy them
-	  to a different system), we want to be certain that we copy everything
-	  that we need.
-	</para>
-
-	<para>
-	  Nix ensures this by building and storing file system objects in paths
-	  that are infeasible to predict in advance.  For example, the
-	  artifacts of a package <literal>X</literal> might be stored in
-	  <filename>/nix/store/d58a0606ed616820de291d594602665d-X</filename>,
-	  rather than in, say, <filename>/usr/lib</filename>.  The path
-	  component <filename>d58a...</filename> is actually a cryptographic
-	  hash of all the inputs (i.e., sources, requisites, and build flags)
-	  used in building <literal>X</literal>, and as such is very fragile:
-	  any change to the inputs will change the hash.  Therefore it is not
-	  sensible to <emphasis>hard-code</emphasis> such a path into the build
-	  scripts of a package <literal>Y</literal> that uses
-	  <literal>X</literal> (as does happen with <quote>fixed</quote> paths
-	  such as <filename>/usr/lib</filename>).  Rather, the build script of
-	  package <literal>Y</literal> is parameterised with the actual
-	  location of <literal>X</literal>, which is supplied by the Nix
-	  system.
-	</para>
+        <para>
+          <emphasis>Reliable dependencies.</emphasis>  Builds of file system
+          objects depend on other file system object, such as source files,
+          tools, and so on.  We would like to ensure that a build does not
+          refer to any objects that have not been declared as inputs for that
+          build.  This is important for several reasons.  First, if any of the
+          inputs change, we need to rebuild the things that depend on them to
+          maintain consistency between sources and derivates.  Second, when we
+          <emphasis>deploy</emphasis> file system objects (that is, copy them
+          to a different system), we want to be certain that we copy everything
+          that we need.
+        </para>
+
+        <para>
+          Nix ensures this by building and storing file system objects in paths
+          that are infeasible to predict in advance.  For example, the
+          artifacts of a package <literal>X</literal> might be stored in
+          <filename>/nix/store/d58a0606ed616820de291d594602665d-X</filename>,
+          rather than in, say, <filename>/usr/lib</filename>.  The path
+          component <filename>d58a...</filename> is actually a cryptographic
+          hash of all the inputs (i.e., sources, requisites, and build flags)
+          used in building <literal>X</literal>, and as such is very fragile:
+          any change to the inputs will change the hash.  Therefore it is not
+          sensible to <emphasis>hard-code</emphasis> such a path into the build
+          scripts of a package <literal>Y</literal> that uses
+          <literal>X</literal> (as does happen with <quote>fixed</quote> paths
+          such as <filename>/usr/lib</filename>).  Rather, the build script of
+          package <literal>Y</literal> is parameterised with the actual
+          location of <literal>X</literal>, which is supplied by the Nix
+          system.
+        </para>
       </listitem>
 
       <listitem>
-	<para>
-	  <emphasis>Support for variability.</emphasis>  
-	</para>
-	
-	<para>
-	  As stated above, the path name of a file system object contain a
-	  cryptographic hash of all inputs involved in building it.  A change to
-	  any of the inputs will cause the hash to change--and by extension,
-	  the path name.  These inputs include both sources (variation in time)
-	  and configuration options (variation in space).  Therefore variants
-	  of the same package don't clash---they can co-exist peacefully within
-	  the same file system.  So thanks to Nix's mechanism for reliably
-	  dealing with dependencies, we obtain management of variants for free
-	  (or, to quote Simon Peyton-Jone, it's not free, but it has already
-	  been paid for).
-	</para>
+        <para>
+          <emphasis>Support for variability.</emphasis>  
+        </para>
+        
+        <para>
+          As stated above, the path name of a file system object contain a
+          cryptographic hash of all inputs involved in building it.  A change to
+          any of the inputs will cause the hash to change--and by extension,
+          the path name.  These inputs include both sources (variation in time)
+          and configuration options (variation in space).  Therefore variants
+          of the same package don't clash---they can co-exist peacefully within
+          the same file system.  So thanks to Nix's mechanism for reliably
+          dealing with dependencies, we obtain management of variants for free
+          (or, to quote Simon Peyton-Jone, it's not free, but it has already
+          been paid for).
+        </para>
 
       </listitem>
 
       <listitem>
-	<para>
-	  <emphasis>Transparent source/binary deployment.</emphasis>
-	</para>
+        <para>
+          <emphasis>Transparent source/binary deployment.</emphasis>
+        </para>
       </listitem>
 
       <listitem>
-	<para>
-	  <emphasis>Easy configuration duplication.</emphasis>
-	</para>
+        <para>
+          <emphasis>Easy configuration duplication.</emphasis>
+        </para>
       </listitem>
 
       <listitem>
-	<para>
-	  <emphasis>Automatic storage management.</emphasis>
-	</para>
+        <para>
+          <emphasis>Automatic storage management.</emphasis>
+        </para>
       </listitem>
 
       <listitem>
-	<para>
-	  <emphasis>Atomic upgrades and rollbacks.</emphasis>
-	</para>
+        <para>
+          <emphasis>Atomic upgrades and rollbacks.</emphasis>
+        </para>
       </listitem>
 
       <listitem>
-	<para>
-	  <emphasis>Support for many simultaneous configurations.</emphasis>
-	</para>
+        <para>
+          <emphasis>Support for many simultaneous configurations.</emphasis>
+        </para>
       </listitem>
 
       <listitem>
-	<para>
-	  <emphasis>Portability.</emphasis>  Nix is quite portable.  Contrary
-	  to build systems like those in, e.g., Vesta and ClearCase [sic?], it
-	  does not rely on operating system extensions.
-	</para>
+        <para>
+          <emphasis>Portability.</emphasis>  Nix is quite portable.  Contrary
+          to build systems like those in, e.g., Vesta and ClearCase [sic?], it
+          does not rely on operating system extensions.
+        </para>
       </listitem>
 
     </itemizedlist>
@@ -236,20 +236,20 @@
     <itemizedlist>
 
       <listitem>
-	<para>
-	  <emphasis>Build management.</emphasis>  In principle it is already
-	  possible to do build management using Fix (by writing builders that
-	  perform appropriate build steps), but the Fix language is not yet
-	  powerful enough to make this pleasant.  The <ulink
-	    url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>
-	  should be retargeted to produce Nix expressions, or alternatively,
-	  extend Fix with Maak's semantics and concrete syntax (since Fix needs
-	  a concrete syntax anyway).  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>
+        <para>
+          <emphasis>Build management.</emphasis>  In principle it is already
+          possible to do build management using Fix (by writing builders that
+          perform appropriate build steps), but the Fix language is not yet
+          powerful enough to make this pleasant.  The <ulink
+            url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>
+          should be retargeted to produce Nix expressions, or alternatively,
+          extend Fix with Maak's semantics and concrete syntax (since Fix needs
+          a concrete syntax anyway).  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>
 
     </itemizedlist>
diff --git a/doc/manual/fix-reference.xml b/doc/manual/nix-instantiate-reference.xml
index aac1be64828b..2e2749e43441 100644
--- a/doc/manual/fix-reference.xml
+++ b/doc/manual/nix-instantiate-reference.xml
@@ -1,6 +1,6 @@
 <refentry>
   <refnamediv>
-    <refname>fix</refname>
+    <refname>nix-instantiate</refname>
     <refpurpose>generate Nix expressions from a high-level description</refpurpose>
   </refnamediv>
 
@@ -8,8 +8,8 @@
     <cmdsynopsis>
       <command>fix</command>
       <group choice='opt' rep='repeat'>
-	<arg><option>--verbose</option></arg>
-	<arg><option>-v</option></arg>
+        <arg><option>--verbose</option></arg>
+        <arg><option>-v</option></arg>
       </group>
       <arg rep='repeat'><replaceable>files</replaceable></arg>
     </cmdsynopsis>
diff --git a/doc/manual/nix-reference.xml b/doc/manual/nix-reference.xml
deleted file mode 100644
index d9c78ff07344..000000000000
--- a/doc/manual/nix-reference.xml
+++ /dev/null
@@ -1,444 +0,0 @@
-<refentry>
-  <refnamediv>
-    <refname>nix</refname>
-    <refpurpose>manipulate or query the Nix store</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>nix</command>
-      <group choice='opt'>
-	<arg><option>--path</option></arg>
-	<arg><option>-p</option></arg>
-      </group>
-      <group choice='opt' rep='repeat'>
-	<arg><option>--verbose</option></arg>
-	<arg><option>-v</option></arg>
-      </group>
-      <group choice='opt' rep='repeat'>
-	<arg><option>--keep-failed</option></arg>
-	<arg><option>-K</option></arg>
-      </group>
-      <arg choice='plain'><replaceable>operation</replaceable></arg>
-      <arg rep='repeat'><replaceable>options</replaceable></arg>
-      <arg rep='repeat'><replaceable>arguments</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-
-  <refsect1>
-    <title>Description</title>
-
-    <para>
-      The command <command>nix</command> provides access to the Nix store. This
-      is the (set of) path(s) where Nix expressions and the file system objects
-      built by them are stored.
-    </para>
-
-    <para>
-      <command>nix</command> has many subcommands called
-      <emphasis>operations</emphasis>.  These are individually documented
-      below.  Exactly one operation must always be provided.
-    </para>
-
-  </refsect1>
-
-  <refsect1>
-    <title>Common Options</title>
-
-    <para>
-      In this section the options that are common to all Nix operations are
-      listed.  These options are allowed for every subcommand (although they
-      may not always have an effect).
-    </para>
-
-    <variablelist>
-
-      <varlistentry>
-	<term><option>--path</option></term>
-	<listitem>
-	  <para>
-	    Indicates that any identifier arguments to the operation are paths
-	    in the store rather than identifiers.
-	  </para>
-	</listitem>
-      </varlistentry>
-
-      <varlistentry>
-	<term><option>--verbose</option></term>
-	<listitem>
-	  <para>
-	    Increases the level of verbosity of diagnostic messages printed on
-	    standard error.  For each Nix operation, the information printed on
-	    standard output is well-defined and specified below in the
-	    respective sections.  Any diagnostic information is printed on
-	    standard error, never on standard output.
-	  </para>
-
-	  <para>
-	    This option may be specified repeatedly.  Currently, the following
-	    verbosity levels exist:
-	  </para>
-
-	  <variablelist>
-	    <varlistentry>
-	      <term>0</term>
-	      <listitem>
-		<para>
-		  Print error messages only.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>1</term>
-	      <listitem>
-		<para>
-		  Print informational messages.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>2</term>
-	      <listitem>
-		<para>
-		  Print even more informational messages.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>3</term>
-	      <listitem>
-		<para>
-		  Print messages that should only be useful for debugging.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>4</term>
-	      <listitem>
-		<para>
-		  <quote>Vomit mode</quote>: print vast amounts of debug
-		  information.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	  </variablelist>
-
-	</listitem>
-      </varlistentry>
-
-      <varlistentry>
-	<term><option>--keep-failed</option></term>
-	<listitem>
-	  <para>
-	    Specifies that in case of a build failure, the temporary directory
-            (usually in <filename>/tmp</filename>) in which the build takes
-            place should not be deleted.  The path of the build directory is
-            printed as an informational message.
-	  </para>
-	</listitem>
-      </varlistentry>
-
-    </variablelist>
-
-  </refsect1>
-
-
-  <!--######################################################################-->
-
-  <refsect1>
-    <title>Operation <option>--install</option></title>
-
-    <refsect2>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-	<command>nix</command>
-	<group>
-	  <arg><option>--install</option></arg>
-	  <arg><option>-i</option></arg>
-	</group>
-	<arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg>
-      </cmdsynopsis>
-    </refsect2>
-
-    <refsect2>
-      <title>Description</title>
-	    
-      <para>
-	The operation <option>--install</option> realises the Nix expressions
-	identified by <replaceable>ids</replaceable> in the file system.  If
-	these expressions are derivation expressions, they are first
-	normalised.  That is, their target paths are are built, unless a normal
-	form is already known.
-      </para>
-
-      <para>
-	The identifiers of the normal forms of the given Nix expressions are
-	printed on standard output.
-      </para>
-
-    </refsect2>
-	    
-  </refsect1>
-
-
-  <!--######################################################################-->
-
-  <refsect1>
-    <title>Operation <option>--delete</option></title>
-
-    <refsect2>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-	<command>nix</command>
-	<group>
-	  <arg><option>--delete</option></arg>
-	  <arg><option>-d</option></arg>
-	</group>
-	<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
-      </cmdsynopsis>
-    </refsect2>
-
-    <refsect2>
-      <title>Description</title>
-	    
-      <para>
-	The operation <option>--delete</option> unconditionally deletes the
-	paths <replaceable>paths</replaceable> from the Nix store. It is an
-	error to attempt to delete paths outside of the store.
-      </para>
-
-      <warning>
-	<para>
-	  This operation should almost never be called directly, since no
-	  attempt is made to verify that no references exist to the paths to
-	  be deleted.  Therefore, careless deletion can result in an
-	  inconsistent system. Deletion of paths in the store is done by the
-	  garbage collector (which uses <option>--delete</option> to delete
-	  unreferenced paths).
-	  
-	</para>
-      </warning>
-
-    </refsect2>
-	    
-  </refsect1>
-
-
-  <!--######################################################################-->
-
-  <refsect1>
-    <title>Operation <option>--query</option></title>
-
-    <refsect2>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-	<command>nix</command>
-	<group>
-	  <arg><option>--query</option></arg>
-	  <arg><option>-q</option></arg>
-	</group>
-	<group>
-	  <group>
-	    <arg><option>--list</option></arg>
-	    <arg><option>-l</option></arg>
-	  </group>
-	  <group>
-	    <arg><option>--requisites</option></arg>
-	    <arg><option>-r</option></arg>
-	  </group>
-	  <group>
-	    <arg><option>--expansion</option></arg>
-	    <arg><option>-e</option></arg>
-	  </group>
-	  <group>
-	    <arg><option>--graph</option></arg>
-	    <arg><option>-g</option></arg>
-	  </group>
-	</group>
-	<arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
-      </cmdsynopsis>
-    </refsect2>
-
-    <refsect2>
-      <title>Description</title>
-	    
-      <para>
-	The operation <option>--query</option> displays various bits of
-	information about Nix expressions or paths in the store.  The queries
-	are described in <xref linkend='nixref-queries' />.  At most one query
-	can be specified; the default query is <option>--list</option>.
-      </para>
-
-    </refsect2>
-
-    <refsect2 id='nixref-queries'>
-      <title>Queries</title>
-	    
-      <variablelist>
-
-	<varlistentry>
-	  <term><option>--list</option></term>
-	  <listitem>
-	    <para>
-	      Prints out the target paths of the Nix expressions indicated by
-	      the identifiers <replaceable>args</replaceable>.  In the case of
-	      a derivation expression, these are the paths that will be
-	      produced by the builder of the expression.  In the case of a
-	      slice expression, these are the root paths (which are generally
-	      the paths that were produced by the builder of the derivation
-	      expression of which the slice is a normal form).
-	    </para>
-
-	    <para>
-	      This query has one option:
-	    </para>
-
-	    <variablelist>
-
-	      <varlistentry>
-		<term><option>--normalise</option></term>
-		<listitem>
-		  <para>
-		    Causes the target paths of the <emphasis>normal
-		      forms</emphasis> of the expressions to be printed, rather
-		    than the target paths of the expressions themselves.
-		  </para>
-		</listitem>
-	      </varlistentry>
-
-	    </variablelist>
-	    
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term><option>--requisites</option></term>
-	  <listitem>
-	    <para>
-	      Prints out the requisite paths of the Nix 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 Nix 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
-	      distribution.  A <emphasis>source distribution</emphasis> is
-	      obtained by distributing the requisite paths of a derivation
-	      expression.  A <emphasis>binary distribution</emphasis> is
-	      obtained by distributing the requisite paths of a slice
-	      expression (i.e., the normal form of a derivation expression; you
-	      can directly specify the identifier of the slice expression, or
-	      use <option>--normalise</option> and specify the identifier of a
-	      derivation expression).  A <emphasis>cache
-		distribution</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 distribution, 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>
-
-	    <para>
-	      This query has a number of options:
-	    </para> 
-
-	    <variablelist>
-
-	      <varlistentry>
-		<term><option>--normalise</option></term>
-		<listitem>
-		  <para>
-		    Causes the requisite paths of the <emphasis>normal
-		      forms</emphasis> of the expressions to be printed, rather
-		    than the requisite paths of the expressions themselves.
-		  </para>
-		</listitem>
-	      </varlistentry>
-
-	      <varlistentry>
-		<term><option>--exclude-exprs</option></term>
-		<listitem>
-		  <para>
-		    Excludes the paths of Nix expressions.  This causes the
-		    closure property to be lost, that is, the resulting set of
-		    paths is not enough to ensure realisibility.
-		  </para>
-		</listitem>
-	      </varlistentry>
-
-	      <varlistentry>
-		<term><option>--include-successors</option></term>
-		<listitem>
-		  <para>
-		    Also include the requisites of successors (normal forms).
-		    Only the requisites of <emphasis>known</emphasis>
-		    successors are included, i.e., the normal forms of
-		    derivation expressions that have never been normalised will
-		    not be included.
-		  </para>
-
-		  <para>
-		    Note that not just the successor of a derivation expression
-		    will be included, but also the successors of all input
-		    expressions of that derivation expression.  I.e., all
-		    normal forms of subterms involved in the normalisation of
-		    the top-level term are included.
-		  </para>
-		</listitem>
-	      </varlistentry>
-
-	    </variablelist>
-
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term><option>--expansion</option></term>
-	  <listitem>
-	    <para>
-	      For each identifier in <replaceable>args</replaceable>, prints
-	      all expansions of that identifier, that is, all paths whose
-	      current content matches the identifier.
-	    </para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term><option>--graph</option></term>
-	  <listitem>
-	    <para>
-	      Prints a graph of the closure of the expressions identified by
-	      <replaceable>args</replaceable> in the format of the
-	      <command>dot</command> tool of AT&amp;T's GraphViz package.
-	    </para>
-	  </listitem>
-	</varlistentry>
-
-      </variablelist>
-
-    </refsect2>
-
-  </refsect1>
-
-
-</refentry>
-
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "refentry")
-end:
--->
diff --git a/doc/manual/nix-store-reference.xml b/doc/manual/nix-store-reference.xml
new file mode 100644
index 000000000000..686fe4c15643
--- /dev/null
+++ b/doc/manual/nix-store-reference.xml
@@ -0,0 +1,444 @@
+<refentry>
+  <refnamediv>
+    <refname>nix-store</refname>
+    <refpurpose>manipulate or query the Nix store</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>nix-store</command>
+      <group choice='opt'>
+        <arg><option>--path</option></arg>
+        <arg><option>-p</option></arg>
+      </group>
+      <group choice='opt' rep='repeat'>
+        <arg><option>--verbose</option></arg>
+        <arg><option>-v</option></arg>
+      </group>
+      <group choice='opt' rep='repeat'>
+        <arg><option>--keep-failed</option></arg>
+        <arg><option>-K</option></arg>
+      </group>
+      <arg choice='plain'><replaceable>operation</replaceable></arg>
+      <arg rep='repeat'><replaceable>options</replaceable></arg>
+      <arg rep='repeat'><replaceable>arguments</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      The command <command>nix</command> provides access to the Nix store. This
+      is the (set of) path(s) where Nix expressions and the file system objects
+      built by them are stored.
+    </para>
+
+    <para>
+      <command>nix</command> has many subcommands called
+      <emphasis>operations</emphasis>.  These are individually documented
+      below.  Exactly one operation must always be provided.
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Common Options</title>
+
+    <para>
+      In this section the options that are common to all Nix operations are
+      listed.  These options are allowed for every subcommand (although they
+      may not always have an effect).
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--path</option></term>
+        <listitem>
+          <para>
+            Indicates that any identifier arguments to the operation are paths
+            in the store rather than identifiers.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--verbose</option></term>
+        <listitem>
+          <para>
+            Increases the level of verbosity of diagnostic messages printed on
+            standard error.  For each Nix operation, the information printed on
+            standard output is well-defined and specified below in the
+            respective sections.  Any diagnostic information is printed on
+            standard error, never on standard output.
+          </para>
+
+          <para>
+            This option may be specified repeatedly.  Currently, the following
+            verbosity levels exist:
+          </para>
+
+          <variablelist>
+            <varlistentry>
+              <term>0</term>
+              <listitem>
+                <para>
+                  Print error messages only.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>1</term>
+              <listitem>
+                <para>
+                  Print informational messages.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>2</term>
+              <listitem>
+                <para>
+                  Print even more informational messages.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>3</term>
+              <listitem>
+                <para>
+                  Print messages that should only be useful for debugging.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>4</term>
+              <listitem>
+                <para>
+                  <quote>Vomit mode</quote>: print vast amounts of debug
+                  information.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--keep-failed</option></term>
+        <listitem>
+          <para>
+            Specifies that in case of a build failure, the temporary directory
+            (usually in <filename>/tmp</filename>) in which the build takes
+            place should not be deleted.  The path of the build directory is
+            printed as an informational message.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
+
+  <!--######################################################################-->
+
+  <refsect1>
+    <title>Operation <option>--install</option></title>
+
+    <refsect2>
+      <title>Synopsis</title>
+      <cmdsynopsis>
+        <command>nix</command>
+        <group>
+          <arg><option>--install</option></arg>
+          <arg><option>-i</option></arg>
+        </group>
+        <arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg>
+      </cmdsynopsis>
+    </refsect2>
+
+    <refsect2>
+      <title>Description</title>
+            
+      <para>
+        The operation <option>--install</option> realises the Nix expressions
+        identified by <replaceable>ids</replaceable> in the file system.  If
+        these expressions are derivation expressions, they are first
+        normalised.  That is, their target paths are are built, unless a normal
+        form is already known.
+      </para>
+
+      <para>
+        The identifiers of the normal forms of the given Nix expressions are
+        printed on standard output.
+      </para>
+
+    </refsect2>
+            
+  </refsect1>
+
+
+  <!--######################################################################-->
+
+  <refsect1>
+    <title>Operation <option>--delete</option></title>
+
+    <refsect2>
+      <title>Synopsis</title>
+      <cmdsynopsis>
+        <command>nix</command>
+        <group>
+          <arg><option>--delete</option></arg>
+          <arg><option>-d</option></arg>
+        </group>
+        <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+      </cmdsynopsis>
+    </refsect2>
+
+    <refsect2>
+      <title>Description</title>
+            
+      <para>
+        The operation <option>--delete</option> unconditionally deletes the
+        paths <replaceable>paths</replaceable> from the Nix store. It is an
+        error to attempt to delete paths outside of the store.
+      </para>
+
+      <warning>
+        <para>
+          This operation should almost never be called directly, since no
+          attempt is made to verify that no references exist to the paths to
+          be deleted.  Therefore, careless deletion can result in an
+          inconsistent system. Deletion of paths in the store is done by the
+          garbage collector (which uses <option>--delete</option> to delete
+          unreferenced paths).
+          
+        </para>
+      </warning>
+
+    </refsect2>
+            
+  </refsect1>
+
+
+  <!--######################################################################-->
+
+  <refsect1>
+    <title>Operation <option>--query</option></title>
+
+    <refsect2>
+      <title>Synopsis</title>
+      <cmdsynopsis>
+        <command>nix</command>
+        <group>
+          <arg><option>--query</option></arg>
+          <arg><option>-q</option></arg>
+        </group>
+        <group>
+          <group>
+            <arg><option>--list</option></arg>
+            <arg><option>-l</option></arg>
+          </group>
+          <group>
+            <arg><option>--requisites</option></arg>
+            <arg><option>-r</option></arg>
+          </group>
+          <group>
+            <arg><option>--expansion</option></arg>
+            <arg><option>-e</option></arg>
+          </group>
+          <group>
+            <arg><option>--graph</option></arg>
+            <arg><option>-g</option></arg>
+          </group>
+        </group>
+        <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
+      </cmdsynopsis>
+    </refsect2>
+
+    <refsect2>
+      <title>Description</title>
+            
+      <para>
+        The operation <option>--query</option> displays various bits of
+        information about Nix expressions or paths in the store.  The queries
+        are described in <xref linkend='nixref-queries' />.  At most one query
+        can be specified; the default query is <option>--list</option>.
+      </para>
+
+    </refsect2>
+
+    <refsect2 id='nixref-queries'>
+      <title>Queries</title>
+            
+      <variablelist>
+
+        <varlistentry>
+          <term><option>--list</option></term>
+          <listitem>
+            <para>
+              Prints out the target paths of the Nix expressions indicated by
+              the identifiers <replaceable>args</replaceable>.  In the case of
+              a derivation expression, these are the paths that will be
+              produced by the builder of the expression.  In the case of a
+              slice expression, these are the root paths (which are generally
+              the paths that were produced by the builder of the derivation
+              expression of which the slice is a normal form).
+            </para>
+
+            <para>
+              This query has one option:
+            </para>
+
+            <variablelist>
+
+              <varlistentry>
+                <term><option>--normalise</option></term>
+                <listitem>
+                  <para>
+                    Causes the target paths of the <emphasis>normal
+                      forms</emphasis> of the expressions to be printed, rather
+                    than the target paths of the expressions themselves.
+                  </para>
+                </listitem>
+              </varlistentry>
+
+            </variablelist>
+            
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><option>--requisites</option></term>
+          <listitem>
+            <para>
+              Prints out the requisite paths of the Nix 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 Nix 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
+              distribution.  A <emphasis>source distribution</emphasis> is
+              obtained by distributing the requisite paths of a derivation
+              expression.  A <emphasis>binary distribution</emphasis> is
+              obtained by distributing the requisite paths of a slice
+              expression (i.e., the normal form of a derivation expression; you
+              can directly specify the identifier of the slice expression, or
+              use <option>--normalise</option> and specify the identifier of a
+              derivation expression).  A <emphasis>cache
+                distribution</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 distribution, 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>
+
+            <para>
+              This query has a number of options:
+            </para> 
+
+            <variablelist>
+
+              <varlistentry>
+                <term><option>--normalise</option></term>
+                <listitem>
+                  <para>
+                    Causes the requisite paths of the <emphasis>normal
+                      forms</emphasis> of the expressions to be printed, rather
+                    than the requisite paths of the expressions themselves.
+                  </para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term><option>--exclude-exprs</option></term>
+                <listitem>
+                  <para>
+                    Excludes the paths of Nix expressions.  This causes the
+                    closure property to be lost, that is, the resulting set of
+                    paths is not enough to ensure realisibility.
+                  </para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term><option>--include-successors</option></term>
+                <listitem>
+                  <para>
+                    Also include the requisites of successors (normal forms).
+                    Only the requisites of <emphasis>known</emphasis>
+                    successors are included, i.e., the normal forms of
+                    derivation expressions that have never been normalised will
+                    not be included.
+                  </para>
+
+                  <para>
+                    Note that not just the successor of a derivation expression
+                    will be included, but also the successors of all input
+                    expressions of that derivation expression.  I.e., all
+                    normal forms of subterms involved in the normalisation of
+                    the top-level term are included.
+                  </para>
+                </listitem>
+              </varlistentry>
+
+            </variablelist>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><option>--expansion</option></term>
+          <listitem>
+            <para>
+              For each identifier in <replaceable>args</replaceable>, prints
+              all expansions of that identifier, that is, all paths whose
+              current content matches the identifier.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><option>--graph</option></term>
+          <listitem>
+            <para>
+              Prints a graph of the closure of the expressions identified by
+              <replaceable>args</replaceable> in the format of the
+              <command>dot</command> tool of AT&amp;T's GraphViz package.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+    </refsect2>
+
+  </refsect1>
+
+
+</refentry>
+
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "refentry")
+end:
+-->