* Start of nix-env reference.

* Some CSS tweaks.

5 files changed, 215 insertions, 16 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index a0fa19406a93..f0344ef64919 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -7,7 +7,7 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
  --param html.stylesheet \'style.css\'
 
 SOURCES = manual.xml introduction.xml installation.xml overview.xml \
- nix-store.xml nix-instantiate.xml \
+ nix-env.xml nix-store.xml nix-instantiate.xml \
  troubleshooting.xml bugs.xml opt-verbose.xml \
  style.css images
 
@@ -18,7 +18,7 @@ manual.is-valid: $(SOURCES) version.xml
 version.xml:
 	echo -n $(VERSION) > version.xml
 
-man1_MANS = nix-store.1 nix-instantiate.1
+man1_MANS = nix-env.1 nix-store.1 nix-instantiate.1
 
 man $(MANS): $(SOURCES) manual.is-valid
 	$(XSLTPROC) $(docbookxsl)/manpages/docbook.xsl manual.xml
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 1df0d1fc9124..e95b0fc91d84 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -7,6 +7,7 @@
 <!ENTITY installation SYSTEM "installation.xml">
 <!ENTITY overview SYSTEM "overview.xml">
 <!ENTITY opt-verbose SYSTEM "opt-verbose.xml">
+<!ENTITY nix-env SYSTEM "nix-env.xml">
 <!ENTITY nix-store SYSTEM "nix-store.xml">
 <!ENTITY nix-instantiate SYSTEM "nix-instantiate.xml">
 <!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
@@ -37,6 +38,10 @@
   <appendix>
     <title>Command Reference</title>
     <sect1>
+      <title>nix-env</title>
+      &nix-env;
+    </sect1>
+    <sect1>
       <title>nix-store</title>
       &nix-store;
     </sect1>
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
new file mode 100644
index 000000000000..d8b50bf3cd07
--- /dev/null
+++ b/doc/manual/nix-env.xml
@@ -0,0 +1,166 @@
+<refentry>
+  <refnamediv>
+    <refname>nix-env</refname>
+    <refpurpose>manipulate or query Nix user environments</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>nix-env</command>
+      <group choice='opt' rep='repeat'>
+        <arg><option>--verbose</option></arg>
+        <arg><option>-v</option></arg>
+      </group>
+      <group choice='opt'>
+        <arg><option>--keep-failed</option></arg>
+        <arg><option>-K</option></arg>
+      </group>
+      <arg>
+        <group choice='opt'>
+          <arg><option>--file</option></arg>
+          <arg><option>-f</option></arg>
+        </group>
+        <replaceable>path</replaceable>
+      </arg>
+      <arg choice='plain'><replaceable>operation</replaceable></arg>
+      <arg rep='repeat'><replaceable>options</replaceable></arg>
+      <arg rep='repeat'><replaceable>arguments</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>
+      The command <command>nix-env</command> is used to manipulate Nix
+      user environments.  User environments are sets of software
+      components available to a user at some point in time.  In other
+      words, they are a synthesised view of the programs available in
+      the Nix store.  There may be many user environments: different
+      users can have different environments, and individual users can
+      switch between different environments.
+    </para>
+
+<!--    <para>
+      Environments are manipulated by operations such as the
+      installation and removal of components (hereafter called
+      <emphasis>derivations</emphasis>).  These operations are not
+      destructive: rather than overwrite the current environment, they
+      create a new environment to which we can then atomically
+      <emphasis>switch</emphasis> by flipping a symlink.
+    </para> -->
+
+    <para>
+      <command>nix-env</command> takes exactly one
+      <emphasis>operation</emphasis> flag which indicates the
+      subcommand to be performed.  These are documented below.
+    </para>
+    
+  </refsection>
+
+
+
+  <!--######################################################################-->
+
+  <refsection>
+    <title>Common options</title>
+
+    <para>
+      This section lists the options that are common to all
+      operations.  These options are allowed for every subcommand,
+      though they may not always have an effect.
+    </para>
+
+    <variablelist>
+
+      &opt-verbose;
+
+      <varlistentry>
+        <term><option>--file</option></term>
+        <listitem>
+          <para>
+            Specifies the Nix expression used by the
+            <option>--install</option>, <option>--upgrade</option>,
+            and <option>--query --available</option> operations to
+            obtain derivations.  The default is
+            <filename>~/.nix-defexpr</filename>.
+          </para>
+        </listitem>
+      </varlistentry>
+      
+    </variablelist>
+
+  </refsection>
+
+  
+
+  <!--######################################################################-->
+
+  <refsection>
+    <title>Files</title>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><filename>~/.nix-defexpr</filename></term>
+        <listitem>
+          <para>
+            The default Nix expression used by the
+            <option>--install</option>, <option>--upgrade</option>,
+            and <option>--query --available</option> operations to
+            obtain derivations.  It is generally a symbolic link to
+            some other location set using the
+            <option>--import</option> operation.  The
+            <option>--file</option> option may be used to override
+            this default.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><filename>~/.nix-userenv</filename></term>
+        <listitem>
+          <para>
+            A symbolic link to the user's current user environment.
+            By default, it points to
+            <filename><replaceable>prefix</replaceable>/var/nix/links/current</filename>.
+            The <envar>PATH</envar> environment variable should
+            include <filename>~/.nix-userenv</filename> for the use
+            environments to be visible to the user.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+        
+  </refsection>
+
+  
+
+  <!--######################################################################-->
+
+  <refsection>
+    <title>Operation <option>--install</option></title>
+
+    <refsection>
+      <title>Synopsis</title>
+      <cmdsynopsis>
+        <command>nix-env</command>
+        <group>
+          <arg><option>--install</option></arg>
+        </group>
+      </cmdsynopsis>
+    </refsection>
+
+    <refsection>
+      <title>Description</title>
+            
+      <para>
+      </para>
+
+    </refsection>
+            
+  </refsection>
+
+  
+</refentry>
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index 36abf7af3659..cbd38cd2380a 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -11,7 +11,7 @@
         <arg><option>--verbose</option></arg>
         <arg><option>-v</option></arg>
       </group>
-      <group choice='opt' rep='repeat'>
+      <group choice='opt'>
         <arg><option>--keep-failed</option></arg>
         <arg><option>-K</option></arg>
       </group>
@@ -32,18 +32,21 @@
 
     <para>
       <command>nix-store</command> takes exactly one
-      <emphasis>operation</emphasis> flag which indicated the
-      subcommand to be performed.  These are individually
-      documented below.
+      <emphasis>operation</emphasis> flag which indicates the
+      subcommand to be performed.  These are documented below.
     </para>
 
   </refsection>
 
+
+
+  <!--######################################################################-->
+
   <refsection>
     <title>Common options</title>
 
     <para>
-      This section lists the options that are common to all Nix
+      This section lists the options that are common to all
       operations.  These options are allowed for every subcommand,
       though they may not always have an effect.
     </para>
@@ -68,6 +71,9 @@
 
   </refsection>
 
+  
+
+  <!--######################################################################-->
 
   <refsection>
     <title>Environment variables</title>
@@ -221,10 +227,10 @@
       <title>Description</title>
             
       <para>
-        The operation <option>--query</option> displays various bits of
-        information about store expressions or store paths.  The queries
-        are described in <xref linkend='nixref-queries' />.  At most one query
-        can be specified.  The default query is <option>--list</option>.
+        The operation <option>--query</option> displays various bits
+        of information about store expressions or store paths.  The
+        queries are described below.  At most one query can be
+        specified.  The default query is <option>--list</option>.
       </para>
 
     </refsection>
diff --git a/doc/manual/style.css b/doc/manual/style.css
index a7d8809f0b06..3ff9edbd406a 100644
--- a/doc/manual/style.css
+++ b/doc/manual/style.css
@@ -20,19 +20,41 @@ h1,h2,h3
     text-align: left;
 }
 
-h1
+h1 /* title */
 {
-    font-size: 185%;
+    font-size: 200%;
 }
 
-h2
+h2 /* chapters, appendices, subtitle */
+{
+    font-size: 180%;
+}
+
+/* Extra space between chapters, appendices. */
+div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 
+{ 
+    margin-top: 1.5em;
+/*    border-top: solid #005aa0; */
+}
+
+div.sect1 h2 /* sections */
 {
     font-size: 150%;
 }
 
-h3
+div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */
+{
+    font-size: 125%;
+}
+
+div.refsection h3
+{
+    font-size: 110%;
+}
+
+h3 /* subsections */
 {
-    font-size: 120%;
+    font-size: 125%;
 }