4 files changed, 89 insertions, 12 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 000000000..e76efafdb
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = manual
diff --git a/doc/manual/Makefile b/doc/manual/Makefile
deleted file mode 100644
index 52f17c65a..000000000
--- a/doc/manual/Makefile
+++ /dev/null
@@ -1,11 +0,0 @@
-DOCBOOK_DTD = /nix/current/xml/dtd/docbook
-DOCBOOK_XSL = /nix/current/xml/xsl/docbook
-
-all: check html
-
-check:
-	SP_CHARSET_FIXED=YES SP_ENCODING=XML \
-	nsgmls -wxml -c /usr/share/doc/packages/sp/html-xml/xml.soc -c $(DOCBOOK_DTD)/docbook.cat -ges book.xml
-
-html:
-	xsltproc --output book.html $(DOCBOOK_XSL)/html/docbook.xsl book.xml
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
new file mode 100644
index 000000000..a4e3f24ce
--- /dev/null
+++ b/doc/manual/Makefile.am
@@ -0,0 +1,22 @@
+DOCBOOK_DTD = /nix/current/xml/dtd/docbook
+DOCBOOK_XSL = /nix/current/xml/xsl/docbook
+XML = /usr/share/doc/packages/sp/html-xml/xml.soc
+
+%.is-valid: %.xml
+	SP_CHARSET_FIXED=YES SP_ENCODING=XML \
+	nsgmls -wxml -c $(XML) -c $(DOCBOOK_DTD)/docbook.cat -ges $<
+	touch $@
+
+man1_MANS = nix.1
+
+man nix.1: book.is-valid
+	xsltproc $(DOCBOOK_XSL)/manpages/docbook.xsl book.xml
+
+%.html: %.xml %.is-valid
+	xsltproc --output book.html $(DOCBOOK_XSL)/html/docbook.xsl book.xml
+
+all-local: book.html
+
+install-data-local: book.html
+	$(INSTALL) -d $(datadir)/nix/manual
+	$(INSTALL_DATA) book.html $(datadir)/nix/manual
diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index 3f6c4f549..f08ffc3b0 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -219,6 +219,71 @@ $ make install</screen>
   <!--======================================================================-->
 
   <appendix>
+    <title>Command Reference</title>
+
+    <refentry>
+      <refnamediv>
+	<refname>nix</refname>
+	<refpurpose>manipulate or query the Nix store</refpurpose>
+      </refnamediv>
+
+      <refsynopsisdiv>
+	<cmdsynopsis>
+	  <command>nix</command>
+	  <arg>--verbose</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>
+      </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).
+	</para>
+      </refsect1>
+
+      <refsect1>
+	<title>Subcommand <command>--install</command></title>
+
+	<refsect2>
+	  <title>Synopsis</title>
+	  <cmdsynopsis>
+	    <command>nix --install</command>
+	    <arg rep='repeat'><replaceable>id</replaceable></arg>
+	  </cmdsynopsis>
+	</refsect2>
+
+	<refsect2>
+	  <title>Description</title>
+	    
+	  <para>
+	    <command>nix --install</command> realises the given Nix expressions
+	    in the file system.
+	  </para>
+	</refsect2>
+      </refsect1>
+
+    </refentry>
+
+  </appendix>
+
+
+  <!--======================================================================-->
+
+  <appendix>
     <title>Troubleshooting</title>
 
     <sect1>
@@ -267,7 +332,7 @@ $ rm `db_archive -a -h <replaceable>prefix</replaceable>/var/nix/db`</screen>
   <!--======================================================================-->
 
   <appendix>
-    <title>Known problems</title>
+    <title>Bugs</title>
 
     <itemizedlist>