* Split the book.xml into several xml files.

doc/manual/nix-reference.xml

@@ -0,0 +1,213 @@
+<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>
+      <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>
+    </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>
+
+
+</refentry>
+
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "refentry")
+end:
+-->