* Refactoring.

* Convert tabs to spaces.

1 files changed, 444 insertions, 0 deletions

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:
+-->