* Documented some Nix operations.

1 files changed, 159 insertions, 10 deletions

diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index f08ffc3b0631..3d54edfcb685 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -230,7 +230,17 @@ $ make install</screen>
       <refsynopsisdiv>
 	<cmdsynopsis>
 	  <command>nix</command>
-	  <arg>--verbose</arg>
+	  <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>
 
@@ -242,27 +252,151 @@ $ make install</screen>
 	  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>
-	  <command>nix</command> has many subcommands.  These are listed below.
-	  In this section the common options are listed.  These options are
-	  allowed for every subcommand (although they may not always have an
-	  effect).
+	  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>Subcommand <command>--install</command></title>
+	<title>Operation <option>--delete</option></title>
 
 	<refsect2>
 	  <title>Synopsis</title>
 	  <cmdsynopsis>
-	    <command>nix --install</command>
-	    <arg rep='repeat'><replaceable>id</replaceable></arg>
+	    <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>
 
@@ -270,12 +404,27 @@ $ make install</screen>
 	  <title>Description</title>
 	    
 	  <para>
-	    <command>nix --install</command> realises the given Nix expressions
-	    in the file system.
+	    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 check whether any references exist to the
+	      paths to be deleted.  Therefore, an inconsistent system could be
+	      the result.  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>
 
   </appendix>