* Manual updates.

10 files changed, 813 insertions, 786 deletions

diff --git a/NEWS b/NEWS
index b7b4477ad2dd..81813c8652d8 100644
--- a/NEWS
+++ b/NEWS
@@ -159,6 +159,8 @@ Nix 0.8 has the following improvements:
 * `fetchurl' allows SHA-1 and SHA-256 in addition to MD5.  Just
   specify the attribute `sha1' or `sha256' instead of `md5'.
 
+* Manual updates.
+
   
 Version 0.7 (January 12, 2005)
 
diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml
index cee6dac254d6..a659e7e4a90b 100644
--- a/doc/manual/glossary.xml
+++ b/doc/manual/glossary.xml
@@ -134,6 +134,29 @@
 </glossentry>
 
 
+<glossentry id="gloss-user-env"><glossterm>user environment</glossterm>
+
+  <glossdef><para>An automatically generated store object that
+  consists of a set of symlinks to “active” applications, i.e., other
+  store paths.  These are generated automatically by <link
+  linkend="sec-nix-env"><command>nix-env</command></link>.  See <xref
+  linkend="sec-profiles" />.</para>
+
+  </glossdef>
+  
+</glossentry>
+
+
+<glossentry id="gloss-profile"><glossterm>profile</glossterm>
+
+  <glossdef><para>A symlink to the current <link
+  linkend="gloss-user-env">user environment</link> of a user, e.g.,
+  <filename>/nix/var/nix/profiles/default</filename>.</para></glossdef>
+
+</glossentry>
+
+
+
 </glosslist>
 
 
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index a9e4473e020a..d6dd437edda4 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -36,7 +36,7 @@
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml" />
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="env-common.xml" />
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conf-file.xml" />
-    <sect1>
+    <sect1 id="sec-nix-env">
       <title>nix-env</title>
       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-env.xml" />
     </sect1>
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index 2a5af6adb3d7..447ef126bfed 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -8,6 +8,8 @@
 <refsynopsisdiv>
   <cmdsynopsis>
     <command>nix-build</command>
+    <arg><option>--add-drv-link</option></arg>
+    <arg><option>--no-link</option></arg>
     <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index 6d145a2129ff..8111775cedb8 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -1,387 +1,417 @@
 <refentry>
-  <refnamediv>
-    <refname>nix-env</refname>
-    <refpurpose>manipulate or query Nix user environments</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>nix-env</command>
-      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
-      <arg>
-        <group choice='req'>
-          <arg choice='plain'><option>--file</option></arg>
-          <arg choice='plain'><option>-f</option></arg>
-        </group>
-        <replaceable>path</replaceable>
-      </arg>
-      <arg>
-        <group choice='req'>
-          <arg choice='plain'><option>--profile</option></arg>
-          <arg choice='plain'><option>-p</option></arg>
-        </group>
-        <replaceable>path</replaceable>
-      </arg>
-      <arg><option>--preserve-installed</option></arg>
-      <arg>
-        <arg choice='plain'><option>--system-filter</option></arg>
-        <replaceable>system</replaceable>
-      </arg>
-      <arg><option>--dry-run</option></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>
+  
+<refnamediv>
+  <refname>nix-env</refname>
+  <refpurpose>manipulate or query Nix user environments</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-env</command>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
+    <arg>
+      <group choice='req'>
+        <arg choice='plain'><option>--file</option></arg>
+        <arg choice='plain'><option>-f</option></arg>
+      </group>
+      <replaceable>path</replaceable>
+    </arg>
+    <arg>
+      <group choice='req'>
+        <arg choice='plain'><option>--profile</option></arg>
+        <arg choice='plain'><option>-p</option></arg>
+      </group>
+      <replaceable>path</replaceable>
+    </arg>
+    <arg><option>--preserve-installed</option></arg>
+    <arg>
+      <arg choice='plain'><option>--system-filter</option></arg>
+      <replaceable>system</replaceable>
+    </arg>
+    <arg><option>--dry-run</option></arg>
+    <arg><option>--from-expression</option></arg>
+    <arg><option>-E</option></arg>
+    <arg><option>--from-profile</option> <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><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>
 
 
 
-  <!--######################################################################-->
+<!--######################################################################-->
 
-  <refsection>
-    <title>Common options</title>
+<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.  See also <xref
-      linkend="sec-common-options" />.
-    </para>
+<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.  See also <xref
+linkend="sec-common-options" />.</para>
 
-    <variablelist>
+<variablelist>
 
-      <varlistentry>
-        <term><option>--file</option> / <option>-f</option></term>
-        <listitem>
-          <para>
-            Specifies the Nix expression (designated below as the
-            <emphasis>active Nix expression</emphasis>) 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>
-      
-      <varlistentry>
-        <term><option>--profile</option> / <option>-p</option></term>
-        <listitem>
-          <para>
-            Specifies the profile to be used by those operations that
-            operate on a profile (designated below as the
-            <emphasis>active profile</emphasis>).  A profile is
-            sequence of user environments called
-            <emphasis>generations</emphasis>, one of which is the
-            <emphasis>current generation</emphasis>.  The default
-            profile is the target of the symbolic link
-            <filename>~/.nix-profile</filename> (see below).
-          </para>
-        </listitem>
-      </varlistentry>
+  <varlistentry><term><option>--file</option></term>
+    <term><option>-f</option></term>
+  
+    <listitem><para>Specifies the Nix expression (designated below as
+    the <emphasis>active Nix expression</emphasis>) 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>
       
-      <varlistentry>
-        <term><option>--dry-run</option></term>
-        <listitem>
-          <para>
-            For the <option>--install</option>,
-            <option>--upgrade</option>, <option>--uninstall</option>,
-            <option>--switch-generation</option> and
-            <option>--rollback</option> operations, this flag will
-            cause <command>nix-env</command> to print what
-            <emphasis>would</emphasis> be done if this flag had not
-            been specified, without actually doing it.
-          </para>
-        </listitem>
-      </varlistentry>
+  <varlistentry><term><option>--profile</option></term>
+    <term><option>-p</option></term>
+  
+    <listitem><para>Specifies the profile to be used by those
+    operations that operate on a profile (designated below as the
+    <emphasis>active profile</emphasis>).  A profile is sequence of
+    user environments called <emphasis>generations</emphasis>, one of
+    which is the <emphasis>current generation</emphasis>.  The default
+    profile is the target of the symbolic link
+    <filename>~/.nix-profile</filename> (see below).</para></listitem>
+    
+  </varlistentry>
       
-      <varlistentry>
-        <term><option>--preserve-installed</option></term>
-        <listitem>
-          <para>
-            By default, when you install a derivation with the
-            <option>--install</option> operation, it will replace
-            previously installed versions with the same derivation
-            name (regardless of the version number).  This option
-            causes those previously installed versions to be kept in
-            the new generation of the profile.  Note that this will
-            generally cause conflicts in the creation of the user
-            environment (since multiple versions of a package
-            typically contain the same programs).
-          </para>
-        </listitem>
-      </varlistentry>
+  <varlistentry><term><option>--dry-run</option></term>
+  
+    <listitem><para>For the <option>--install</option>,
+    <option>--upgrade</option>, <option>--uninstall</option>,
+    <option>--switch-generation</option> and
+    <option>--rollback</option> operations, this flag will cause
+    <command>nix-env</command> to print what
+    <emphasis>would</emphasis> be done if this flag had not been
+    specified, without actually doing it.</para></listitem>
+    
+  </varlistentry>
       
-      <varlistentry>
-        <term><option>--system-filter</option> <replaceable>system</replaceable></term>
-        <listitem>
-          <para>
-            By default, operations such as <option>--query
-            --available</option> only include derivations matching the
-            current platform.  This option allows you to use
-            derivations for the specified platform
-            <replaceable>system</replaceable>.  The special value
-            <literal>*</literal> causes derivations for any platform
-            to be included.
-          </para>
-        </listitem>
-      </varlistentry>
+  <varlistentry><term><option>--preserve-installed</option></term>
+  
+    <listitem><para>By default, when you install a derivation with the
+    <option>--install</option> operation, it will replace previously
+    installed versions with the same derivation name (regardless of
+    the version number).  This option causes those previously
+    installed versions to be kept in the new generation of the
+    profile.  Note that this will generally cause conflicts in the
+    creation of the user environment (since multiple versions of a
+    package typically contain the same programs).</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-profile</filename></term>
-        <listitem>
-          <para>
-            A symbolic link to the user's current profile.  By
-            default, this symlink points to
-            <filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename>.
-            The <envar>PATH</envar> environment variable should
-            include <filename>~/.nix-profile/bin</filename> for the
-            user environment to be visible to the user.
-          </para>
-        </listitem>
-      </varlistentry>
-
-    </variablelist>
+  <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term>
+  
+    <listitem><para>By default, operations such as <option>--query
+    --available</option> only include derivations matching the current
+    platform.  This option allows you to use derivations for the
+    specified platform <replaceable>system</replaceable>.  The special
+    value <literal>*</literal> causes derivations for any platform to
+    be included.</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-profile</filename></term>
+  
+    <listitem><para>A symbolic link to the user's current profile.  By
+    default, this symlink points to
+    <filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename>.
+    The <envar>PATH</envar> environment variable should include
+    <filename>~/.nix-profile/bin</filename> for the user environment
+    to be visible to the user.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
         
-  </refsection>
+</refsection>
 
   
 
-  <!--######################################################################-->
+<!--######################################################################-->
+
+<refsection id="rsec-nix-env-install"><title>Operation <option>--install</option></title>
+
+<refsection><title>Synopsis</title>
 
-  <refsection>
-    <title>Operation <option>--install</option></title>
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--install</option></arg>
+    <arg choice='plain'><option>-i</option></arg>
+  </group>
+  <group choice='opt'>
+    <arg choice='plain'><option>--preserve-installed</option></arg>
+    <arg choice='plain'><option>-P</option></arg>
+  </group>
+  <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
+</cmdsynopsis>
 
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <group choice='req'>
-          <arg choice='plain'><option>--install</option></arg>
-          <arg choice='plain'><option>-i</option></arg>
-        </group>
-        <group choice='opt'>
-          <arg choice='plain'><option>--preserve-installed</option></arg>
-          <arg choice='plain'><option>-P</option></arg>
-        </group>
-        <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
-      </cmdsynopsis>
-    </refsection>
+</refsection>
 
-    <refsection>
-      <title>Description</title>
+
+<refsection><title>Description</title>
             
-      <para>
-        The install operation creates a new user environment, based on
-        the current generation of the active profile, to which the
-        derivations designated by <replaceable>drvnames</replaceable>
-        in the active Nix expression are added.
-      </para>
-
-      <para>
-        Currently installed derivations with a name equal to the name
-        of a derivation being added are removed unless the option
-        <option>--preserve-installed</option> is specified.
-      </para>
-
-    </refsection>
-
-    <refsection>
-      <title>Flags</title>
-
-      <variablelist>
-
-        <varlistentry>
-          <term><option>--preserve-installed</option> / <option>-P</option></term>
-          <listitem>
-            <para>
-              Do not remove derivations with a name matching one of
-              the derivations being installed.  Usually, trying to
-              have two versions of the same package installed in the
-              same generation of a profile will lead to an error in
-              building the generation, due to file name clashes
-              between the two versions.  However, this is not the case
-              for all packages.
-            </para>
-          </listitem>
-        </varlistentry>
-
-      </variablelist>
-    </refsection>
+<para>The install operation creates a new user environment, based on
+the current generation of the active profile, to which a set of store
+paths described by <replaceable>args</replaceable> is added.  The
+arguments <replaceable>args</replaceable> map to store paths in a
+number of possible ways:
+
+<itemizedlist>
+
+  <listitem><para>By default, <replaceable>args</replaceable> is a set
+  of derivation names denoting derivations in the active Nix
+  expression.  These are realised, and the resulting output paths are
+  installed.  Currently installed derivations with a name equal to the
+  name of a derivation being added are removed unless the option
+  <option>--preserve-installed</option> is
+  specified.</para></listitem>
+
+  <listitem><para>If <option>--from-profile</option>
+  <replaceable>path</replaceable> is given,
+  <replaceable>args</replaceable> is a set of names denoting installed
+  store paths in the profile <replaceable>path</replaceable>.  This is
+  an easy way to copy user environment elements from one profile to
+  another.</para></listitem>
+
+  <listitem><para>If <option>--from-expression</option> is given,
+  <replaceable>args</replaceable> are Nix <link
+  linkend="ss-functions">functions</link> that are called with the
+  active Nix expression as their single argument.  The derivations
+  returned by those function calls are installed.  This allows
+  derivations to be specified in a unambiguous way, which is necessary
+  if there are multiple derivations with the same
+  name.</para></listitem>
+
+  <listitem><para>If <replaceable>args</replaceable> are store
+  derivations, then these are <link
+  linkend="rsec-nix-store-realise">realised</link>, and the resulting
+  output paths are installed.</para></listitem>
+
+  <listitem><para>If <replaceable>args</replaceable> are store paths
+  that are not store derivations, then these are <link
+  linkend="rsec-nix-store-realise">realised</link> and
+  installed.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</refsection>
+
+
+<refsection><title>Flags</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--preserve-installed</option></term>
+    <term><option>-P</option></term>
+  
+    <listitem><para>Do not remove derivations with a name matching one
+    of the derivations being installed.  Usually, trying to have two
+    versions of the same package installed in the same generation of a
+    profile will lead to an error in building the generation, due to
+    file name clashes between the two versions.  However, this is not
+    the case for all packages.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
             
-    <refsection>
-      <title>Examples</title>
 
-      <screen>
-$ nix-env --install gcc-3.3.2 <lineannotation>(install specific version)</lineannotation>
+<refsection><title>Examples</title>
+
+<para>To install a specific version of <command>gcc</command> from the
+active Nix expression:
+
+<screen>
+$ nix-env --install gcc-3.3.2 
 installing `gcc-3.3.2'
-uninstalling `gcc-3.1' <lineannotation>(previously installed version is removed)</lineannotation>
+uninstalling `gcc-3.1'</screen>
+
+Note the the previously installed version is removed, since
+<option>--preserve-installed</option> was not specified.</para>
+
+<para>To install an arbitrary version:
+
+<screen>
+$ nix-env --install gcc
+installing `gcc-3.3.2'</screen>
+
+</para>
+
+<para>To install all derivations in the Nix expression <filename>foo.nix</filename>:
+
+<screen>
+$ nix-env -f ~/foo.nix -i '*'</screen>
+
+</para>
+
+<para>To copy the store path with symbolic name <literal>gcc</literal>
+from another profile:
+
+<screen>
+$ nix-env -i --from-profile /nix/var/nix/profiles/foo -i gcc</screen>
+
+</para>
+
+<para>To install a specific store derivation (typically created by
+<command>nix-instantiate</command>):
+
+<screen>
+$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv</screen>
+
+</para>
+
+<para>To install a specific output path:
+
+<screen>
+$ nix-env -i /nix/store/x3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3</screen>
+
+</para>
+
+<para>To install from a Nix expression specified on the command-line:
 
-$ nix-env --install gcc <lineannotation>(just pick any version)</lineannotation>
+<screen>
+$ nix-env -f ./foo.nix -i -E \
+    'f: (f {system = "i686-linux";}).subversionWithJava'</screen>
 
-$ nix-env -f ~/foo.nix -i '*' <lineannotation>(install everything in <filename>foo.nix</filename>)</lineannotation></screen>
+I.e., this evaluates to <literal>(f: (f {system =
+"i686-linux";}).subversionWithJava) (import ./foo.nix)</literal>, thus
+selecting the <literal>subversionWithJava</literal> attribute from the
+attribute set returned by calling the function defined in
+<filename>./foo.nix</filename>.</para>
 
-    </refsection>
+</refsection>
     
-  </refsection>
-
-
-  
-  <!--######################################################################-->
-
-  <refsection>
-    <title>Operation <option>--upgrade</option></title>
-
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <group choice='req'>
-          <arg choice='plain'><option>--upgrade</option></arg>
-          <arg choice='plain'><option>-u</option></arg>
-        </group>
-        <group choice='opt'>
-          <arg choice='plain'><option>--lt</option></arg>
-          <arg choice='plain'><option>--leq</option></arg>
-          <arg choice='plain'><option>--always</option></arg>
-        </group>
-        <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
-      </cmdsynopsis>
-    </refsection>
-
-    <refsection>
-      <title>Description</title>
+</refsection>
+
+
+  
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--upgrade</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--upgrade</option></arg>
+    <arg choice='plain'><option>-u</option></arg>
+  </group>
+  <group choice='opt'>
+    <arg choice='plain'><option>--lt</option></arg>
+    <arg choice='plain'><option>--leq</option></arg>
+    <arg choice='plain'><option>--always</option></arg>
+  </group>
+  <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+<refsection><title>Description</title>
             
-      <para>
-        The upgrade operation creates a new user environment, based on
-        the current generation of the active profile, in which all
-        derivations designated by <replaceable>drvnames</replaceable>
-        for which there are newer versions in the active Nix
-        expression are replaced by those newer versions.  Matching
-        derivations for which there are no newer versions are left
-        untouched; this is not an error.  It is also not an error if
-        an element of <replaceable>drvnames</replaceable> matches no
-        installed derivations.
-      </para>
-
-      <para>
-        If multiple derivations in the active Nix expression match an
-        installed derivation, the one with the highest version is
-        selected.
-      </para>
-
-    </refsection>
+<para>The upgrade operation creates a new user environment, based on
+the current generation of the active profile, in which all store paths
+are replaced for which there are newer versions in the set of paths
+described by <replaceable>args</replaceable>.  Paths for which there
+are no newer versions are left untouched; this is not an error.  It is
+also not an error if an element of <replaceable>args</replaceable>
+matches no installed derivations.</para>
+
+<para>For a description of how <replaceable>args</replaceable> is
+mapped to a set of store paths, see <link
+linkend="rsec-nix-env-install"><option>--install</option></link>.  If
+<replaceable>args</replaceable> describes multiple store paths with
+the same symbolic name, only the one with the highest version is
+installed.</para>
+
+</refsection>
             
-    <refsection>
-      <title>Flags</title>
-
-      <variablelist>
-
-        <varlistentry>
-          <term><option>--lt</option></term>
-          <listitem>
-            <para>
-              Only upgrade a derivation to newer versions.  This is
-              the default.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><option>--leq</option></term>
-          <listitem>
-            <para>
-              In addition to upgrading to newer versions, also
-              <quote>upgrade</quote> to derivations that have the same
-              version.  Version are not a unique identification of a
-              derivation, so there may be many derivations that have
-              the same version.  This flag may be useful to force
-              <quote>synchronisation</quote> between the installed and
-              available derivations.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><option>--always</option></term>
-          <listitem>
-            <para>
-              In addition to upgrading to newer versions, also
-              <quote>upgrade</quote> to derivations that have the same
-              or a lower version.  I.e., derivations may actually be
-              downgraded depending on what is available in the active
-              Nix expression.
-            </para>
-          </listitem>
-        </varlistentry>
-
-      </variablelist>
-
-    </refsection>
-
-    <refsection>
-      <title>Examples</title>
-
-      <screen>
+<refsection><title>Flags</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--lt</option></term>
+  
+    <listitem><para>Only upgrade a derivation to newer versions.  This
+    is the default.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--leq</option></term>
+  
+    <listitem><para>In addition to upgrading to newer versions, also
+    “upgrade” to derivations that have the same version.  Version are
+    not a unique identification of a derivation, so there may be many
+    derivations that have the same version.  This flag may be useful
+    to force “synchronisation” between the installed and available
+    derivations.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--always</option></term>
+  
+    <listitem><para>In addition to upgrading to newer versions, also
+    “upgrade” to derivations that have the same or a lower version.
+    I.e., derivations may actually be downgraded depending on what is
+    available in the active Nix expression.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+<refsection><title>Examples</title>
+
+<screen>
 $ nix-env --upgrade gcc
 upgrading `gcc-3.3.1' to `gcc-3.4'
 
@@ -395,48 +425,39 @@ $ nix-env -u '*' <lineannotation>(try to upgrade everything)</lineannotation>
 upgrading `hello-2.1.2' to `hello-2.1.3'
 upgrading `mozilla-1.2' to `mozilla-1.4'</screen>        
 
-    </refsection>
+</refsection>
     
-    <refsection>
-      <title>Versions</title>
-
-      <para>
-        The upgrade operation determines whether a derivation
-        <varname>y</varname> is an upgrade of a derivation
-        <varname>x</varname> by looking at their respective
-        <literal>name</literal> attributes.  The names (e.g.,
-        <literal>gcc-3.3.1</literal> are split into two parts: the
-        package name (<literal>gcc</literal>), and the version
-        (<literal>3.3.1</literal>).  The version part starts after the
-        first dash not following by a letter.  <varname>x</varname> is
-        considered an upgrade of <varname>y</varname> if their package
-        names match, and the version of <varname>y</varname> is higher
-        that that of <varname>x</varname>.
-      </para>
-
-      <para>
-        The versions are compared by splitting them into contiguous
-        components of numbers and letters.  E.g.,
-        <literal>3.3.1pre5</literal> is split into <literal>[3, 3, 1,
-        "pre", 5]</literal>.  These lists are then compared
-        lexicographically (from left to right).  Corresponding
-        components <varname>a</varname> and <varname>b</varname> are
-        compared as follows.  If they are both numbers, integer
-        comparison is used.  If <varname>a</varname> is an empty
-        string and <varname>b</varname> is a number,
-        <varname>a</varname> is considered less than
-        <varname>b</varname>.  The special string component
-        <literal>pre</literal> (for <emphasis>pre-release</emphasis>)
-        is considered to be less than other components.  String
-        components are considered less than number components.
-        Otherwise, they are compared lexicographically (i.e., using
-        case-sensitive string comparison).
-      </para>
-
-      <para>
-        This is illustrated by the following examples:
-
-        <screen>
+<refsection><title>Versions</title>
+
+<para>The upgrade operation determines whether a derivation
+<varname>y</varname> is an upgrade of a derivation
+<varname>x</varname> by looking at their respective
+<literal>name</literal> attributes.  The names (e.g.,
+<literal>gcc-3.3.1</literal> are split into two parts: the package
+name (<literal>gcc</literal>), and the version
+(<literal>3.3.1</literal>).  The version part starts after the first
+dash not following by a letter.  <varname>x</varname> is considered an
+upgrade of <varname>y</varname> if their package names match, and the
+version of <varname>y</varname> is higher that that of
+<varname>x</varname>.</para>
+
+<para>The versions are compared by splitting them into contiguous
+components of numbers and letters.  E.g., <literal>3.3.1pre5</literal>
+is split into <literal>[3, 3, 1, "pre", 5]</literal>.  These lists are
+then compared lexicographically (from left to right).  Corresponding
+components <varname>a</varname> and <varname>b</varname> are compared
+as follows.  If they are both numbers, integer comparison is used.  If
+<varname>a</varname> is an empty string and <varname>b</varname> is a
+number, <varname>a</varname> is considered less than
+<varname>b</varname>.  The special string component
+<literal>pre</literal> (for <emphasis>pre-release</emphasis>) is
+considered to be less than other components.  String components are
+considered less than number components.  Otherwise, they are compared
+lexicographically (i.e., using case-sensitive string comparison).</para>
+
+<para>This is illustrated by the following examples:
+
+<screen>
 1.0 &lt; 2.3
 2.1 &lt; 2.3
 2.3 = 2.3
@@ -450,199 +471,189 @@ upgrading `mozilla-1.2' to `mozilla-1.4'</screen>
 2.3pre1 &lt; 2.3c
 2.3pre1 &lt; 2.3q</screen>
         
-      </para>
+</para>
 
-    </refsection>
+</refsection>
             
-  </refsection>
+</refsection>
 
   
 
-  <!--######################################################################-->
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--uninstall</option></title>
 
-  <refsection>
-    <title>Operation <option>--uninstall</option></title>
+<refsection><title>Synopsis</title>
 
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <group choice='req'>
-          <arg choice='plain'><option>--uninstall</option></arg>
-          <arg choice='plain'><option>-e</option></arg>
-        </group>
-        <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
-      </cmdsynopsis>
-    </refsection>
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--uninstall</option></arg>
+    <arg choice='plain'><option>-e</option></arg>
+  </group>
+  <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
+</cmdsynopsis>
+</refsection>
 
-    <refsection>
-      <title>Description</title>
+<refsection><title>Description</title>
             
-      <para>
-        The uninstall operation creates a new user environment, based
-        on the current generation of the active profile, from which the
-        derivations designated by <replaceable>drvnames</replaceable>
-        are removed.
-      </para>
-
-    </refsection>
+<para>The uninstall operation creates a new user environment, based on
+the current generation of the active profile, from which the store
+paths designated by the symbolic names
+<replaceable>names</replaceable> are removed.</para>
+
+</refsection>
             
-    <refsection>
-      <title>Examples</title>
+<refsection><title>Examples</title>
 
-      <screen>
+<screen>
 $ nix-env --uninstall gcc
 $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
 
-    </refsection>
+</refsection>
     
-  </refsection>
-
-
-  
-  <!--######################################################################-->
-
-  <refsection>
-    <title>Operation <option>--query</option></title>
-
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <group choice='req'>
-          <arg choice='plain'><option>--query</option></arg>
-          <arg choice='plain'><option>-q</option></arg>
-        </group>
-        <group choice='opt'>
-          <arg choice='plain'><option>--installed</option></arg>
-          <arg choice='plain'><option>--available</option></arg>
-          <arg choice='plain'><option>-a</option></arg>
-        </group>
-        <group choice='req'>
-          <arg choice='plain'><option>--name</option></arg>
-          <arg choice='plain'><option>--expr</option></arg>
-          <arg choice='plain'><option>--status</option></arg>
-          <arg choice='plain'><option>-s</option></arg>
-        </group>
-      </cmdsynopsis>
-    </refsection>
-
-    <refsection>
-      <title>Description</title>
+</refsection>
+
+
+  
+<!--######################################################################-->
+  
+<refsection><title>Operation <option>--query</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--query</option></arg>
+    <arg choice='plain'><option>-q</option></arg>
+  </group>
+  <group choice='opt'>
+    <arg choice='plain'><option>--installed</option></arg>
+    <arg choice='plain'><option>--available</option></arg>
+    <arg choice='plain'><option>-a</option></arg>
+  </group>
+  <group choice='req'>
+    <arg choice='plain'><option>--name</option></arg>
+    <arg choice='plain'><option>--expr</option></arg>
+    <arg choice='plain'><option>--status</option></arg>
+    <arg choice='plain'><option>-s</option></arg>
+  </group>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
             
-      <para>
-        The query operation displays information about either the
-        derivations that are installed in the current generation of
-        the active profile (<option>--installed</option>), or the
-        derivations that are available for installation in the active
-        Nix expression (<option>--available</option>).
-      </para>
-
-      <para>
-        The derivations are sorted by their <literal>name</literal>
-        attributes.
-      </para>
-
-    </refsection>
-
-    <refsection>
-      <title>Source selection</title>
-
-      <para>
-        The following flags specify the set of derivations on which
-        the query operates.
-      </para>
-
-      <variablelist>
-
-        <varlistentry>
-          <term><option>--installed</option></term>
-          <listitem>
-            <para>
-              The query operates on the derivations that are installed
-              in the current generation of the active profile.  This
-              is the default
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><option>--available</option> / <option>-a</option></term>
-          <listitem>
-            <para>
-              The query operates on the derivations that are available
-              in the active Nix expression.
-            </para>
-          </listitem>
-        </varlistentry>
-
-      </variablelist>
+<para>The query operation displays information about either the store
+paths that are installed in the current generation of the active
+profile (<option>--installed</option>), or the derivations that are
+available for installation in the active Nix expression
+(<option>--available</option>).</para>
+
+<para>The derivations are sorted by their <literal>name</literal>
+attributes.</para>
+
+</refsection>
+
+
+<refsection><title>Source selection</title>
+
+<para>The following flags specify the set of things on which the query
+operates.</para>
+
+<variablelist>
+
+  <varlistentry><term><option>--installed</option></term>
+  
+    <listitem><para>The query operates on the store paths that are
+    installed in the current generation of the active profile.  This
+    is the default.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--available</option></term>
+    <term><option>-a</option></term>
+  
+    <listitem><para>The query operates on the derivations that are
+    available in the active Nix expression.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
             
-    </refsection>
-
-    <refsection>
-      <title>Queries</title>
-
-      <para>
-        The following flags specify what information to display about
-        the selected derivations.  Only one type of query may be
-        specified.
-      </para>
-
-      <variablelist>
-
-        <varlistentry>
-          <term><option>--name</option></term>
-          <listitem>
-            <para>
-              Prints the <literal>name</literal> attribute of each
-              derivation.  This is the default.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><option>--expr</option></term>
-          <listitem>
-            <para>
-              Prints the store expression in the Nix store that
-              described the derivation.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><option>--status</option> / <option>-s</option></term>
-          <listitem>
-            <para>
-              Prints the <emphasis>status</emphasis> of each
-              derivation, followed by its <literal>name</literal>
-              attribute.  The status consists of three characters.
-              The first is <literal>I</literal> or
-              <literal>-</literal>, indicating whether the derivation
-              is currently installed in the current generation of the
-              active profile.  This is by definition the case for
-              <option>--installed</option>, but not for
-              <option>--available</option>.  The second is
-              <literal>P</literal> or <literal>-</literal>, indicating
-              whether the derivation is present on the system.  This
-              indicates whether installation of an available
-              derivation will require the derivation to be built.  The
-              third is <literal>S</literal> or <literal>-</literal>,
-              indicating whether a substitute is available for the
-              derivation.
-            </para>
-          </listitem>
-        </varlistentry>
-
-      </variablelist>
-              
-    </refsection>
-
-    <refsection>
-      <title>Examples</title>
-
-      <screen>
+</refsection>
+
+
+<refsection><title>Queries</title>
+
+<para>The following flags specify what information to display about
+the selected derivations.  Multiple flags may be specified, in which
+case the information is shown in the order given here.  Note that the
+name of the derivation is shown unless <option>--no-name</option> is
+specified.</para>
+
+<!-- TODO: fix the terminology here; i.e., derivations, store paths,
+user environment elements, etc. -->
+
+<variablelist>
+
+  <varlistentry><term><option>--status</option></term>
+    <term><option>-s</option></term>
+  
+    <listitem><para>Print the <emphasis>status</emphasis> of the
+    derivation.  The status consists of three characters.  The first
+    is <literal>I</literal> or <literal>-</literal>, indicating
+    whether the derivation is currently installed in the current
+    generation of the active profile.  This is by definition the case
+    for <option>--installed</option>, but not for
+    <option>--available</option>.  The second is <literal>P</literal>
+    or <literal>-</literal>, indicating whether the derivation is
+    present on the system.  This indicates whether installation of an
+    available derivation will require the derivation to be built.  The
+    third is <literal>S</literal> or <literal>-</literal>, indicating
+    whether a substitute is available for the
+    derivation.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--no-name</option></term>
+  
+    <listitem><para>Suppress printing of the <literal>name</literal>
+    attribute of each derivation.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--system</option></term>
+  
+    <listitem><para>Print the <literal>system</literal> attribute of
+    the derivation.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--drv-path</option></term>
+  
+    <listitem><para>Print the path of the store
+    derivation.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--out-path</option></term>
+  
+    <listitem><para>Print the output path of the
+    derivation.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
 $ nix-env -q <lineannotation>(show installed derivations)</lineannotation>
 MozillaFirebird-0.7
 bison-1.875c
@@ -666,270 +677,251 @@ IP- bison-1.875c <lineannotation>(installed and by definition present)</lineanno
 $ nix-env -f ./foo.nix -qa <lineannotation>(show available derivations in the Nix expression <filename>foo.nix</filename>)</lineannotation>
 foo-1.2.3</screen>
 
-    </refsection>
-    
-  </refsection>
+</refsection>
+
+</refsection>
   
     
 
-  <!--######################################################################-->
-
-  <refsection>
-    <title>Operation <option>--switch-profile</option></title>
-
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <group choice='req'>
-          <arg choice='plain'><option>--switch-profile</option></arg>
-          <arg choice='plain'><option>-S</option></arg>
-        </group>
-        <arg choice='req'><replaceable>path</replaceable></arg>
-      </cmdsynopsis>
-    </refsection>
-
-    <refsection>
-      <title>Description</title>
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--switch-profile</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--switch-profile</option></arg>
+    <arg choice='plain'><option>-S</option></arg>
+  </group>
+  <arg choice='req'><replaceable>path</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
             
-      <para>
-        This operation makes <replaceable>path</replaceable> the
-        current profile for the user.  That is, the symlink
-        <filename>~/.nix-profile</filename> is made to point to
-        <replaceable>path</replaceable>.
-      </para>
-
-    </refsection>
+<para>This operation makes <replaceable>path</replaceable> the current
+profile for the user.  That is, the symlink
+<filename>~/.nix-profile</filename> is made to point to
+<replaceable>path</replaceable>.</para>
+
+</refsection>
             
-    <refsection>
-      <title>Examples</title>
+<refsection><title>Examples</title>
 
-      <screen>
+<screen>
 $ nix-env -S ~/my-profile</screen>
 
-    </refsection>
+</refsection>
     
-  </refsection>
+</refsection>
 
 
   
-  <!--######################################################################-->
+<!--######################################################################-->
 
-  <refsection>
-    <title>Operation <option>--list-generations</option></title>
+<refsection><title>Operation <option>--list-generations</option></title>
 
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <arg choice='req'><option>--list-generations</option></arg>
-      </cmdsynopsis>
-    </refsection>
+<refsection><title>Synopsis</title>
 
-    <refsection>
-      <title>Description</title>
-            
-      <para>
-        This operation print a list of all the currently existing
-        generations for the active profile.  These may be switched to
-        using the <option>--switch-generation</option> operation.  It
-        also prints the creation date of the generation, and indicates
-        the current generation.
-      </para>
-
-    </refsection>
+<cmdsynopsis>
+  <command>nix-env</command>
+  <arg choice='plain'><option>--list-generations</option></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
             
-    <refsection>
-      <title>Examples</title>
+<para>This operation print a list of all the currently existing
+generations for the active profile.  These may be switched to using
+the <option>--switch-generation</option> operation.  It also prints
+the creation date of the generation, and indicates the current
+generation.</para>
+
+</refsection>
+
 
-      <screen>
+<refsection><title>Examples</title>
+
+<screen>
 $ nix-env --list-generations
   95   2004-02-06 11:48:24
   96   2004-02-06 11:49:01
   97   2004-02-06 16:22:45
   98   2004-02-06 16:24:33   (current)</screen>
 
-    </refsection>
+</refsection>
     
-  </refsection>
+</refsection>
 
 
   
-  <!--######################################################################-->
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--delete-generations</option></title>
+
+<refsection><title>Synopsis</title>
 
-  <refsection>
-    <title>Operation <option>--delete-generations</option></title>
+<cmdsynopsis>
+  <command>nix-env</command>
+  <arg choice='plain'><option>--delete-generations</option></arg>
+  <arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg>
+</cmdsynopsis>
 
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <arg choice='req'><option>--delete-generations</option></arg>
-        <arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg>
-      </cmdsynopsis>
-    </refsection>
+</refsection>
 
-    <refsection>
-      <title>Description</title>
+
+<refsection><title>Description</title>
             
-      <para>
-        This operation deletes the specified generations of the
-        current profile.  The generations can be a list of generation
-        numbers, or the special value <literal>old</literal> to delete
-        all non-current generations.  Periodically deleting old
-        generations is important to make garbage collection effective.
-      </para>
-
-    </refsection>
+<para>This operation deletes the specified generations of the current
+profile.  The generations can be a list of generation numbers, or the
+special value <literal>old</literal> to delete all non-current
+generations.  Periodically deleting old generations is important to
+make garbage collection effective.</para>
+
+</refsection>
             
-    <refsection>
-      <title>Examples</title>
+<refsection><title>Examples</title>
 
-      <screen>
+<screen>
 $ nix-env --delete-generations 3 4 8
 
 $ nix-env -p other_profile --delete-generations old</screen>
 
-    </refsection>
+</refsection>
     
-  </refsection>
+</refsection>
 
 
   
-  <!--######################################################################-->
+<!--######################################################################-->
 
-  <refsection>
-    <title>Operation <option>--switch-generation</option></title>
+<refsection><title>Operation <option>--switch-generation</option></title>
 
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <group choice='req'>
-          <arg choice='plain'><option>--switch-generation</option></arg>
-          <arg choice='plain'><option>-G</option></arg>
-        </group>
-        <arg choice='req'><replaceable>generation</replaceable></arg>
-      </cmdsynopsis>
-    </refsection>
+<refsection><title>Synopsis</title>
 
-    <refsection>
-      <title>Description</title>
-            
-      <para>
-        This operation makes generation number
-        <replaceable>generation</replaceable> the current generation
-        of the active profile.  That is, if the
-        <filename><replaceable>profile</replaceable></filename> is the
-        path to the active profile, then the symlink
-        <filename><replaceable>profile</replaceable></filename> is
-        made to point to
-        <filename><replaceable>profile</replaceable>-<replaceable>generation</replaceable>-link</filename>,
-        which is in turn a symlink to the actual user environment in
-        the Nix store.
-      </para>
-
-      <para>
-        Switching will fail if the specified generation does not
-        exist.
-      </para>
-
-    </refsection>
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--switch-generation</option></arg>
+    <arg choice='plain'><option>-G</option></arg>
+  </group>
+  <arg choice='req'><replaceable>generation</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
             
-    <refsection>
-      <title>Examples</title>
+<para>This operation makes generation number
+<replaceable>generation</replaceable> the current generation of the
+active profile.  That is, if the
+<filename><replaceable>profile</replaceable></filename> is the path to
+the active profile, then the symlink
+<filename><replaceable>profile</replaceable></filename> is made to
+point to
+<filename><replaceable>profile</replaceable>-<replaceable>generation</replaceable>-link</filename>,
+which is in turn a symlink to the actual user environment in the Nix
+store.</para>
+
+<para>Switching will fail if the specified generation does not exist.</para>
+
+</refsection>
 
-      <screen>
+
+<refsection><title>Examples</title>
+
+<screen>
 $ nix-env -G 42
 switching from generation 50 to 42</screen>
 
-    </refsection>
+</refsection>
     
-  </refsection>
+</refsection>
 
 
   
-  <!--######################################################################-->
+<!--######################################################################-->
 
-  <refsection>
-    <title>Operation <option>--rollback</option></title>
+<refsection><title>Operation <option>--rollback</option></title>
 
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <arg choice='req'><option>--rollback</option></arg>
-      </cmdsynopsis>
-    </refsection>
+<refsection><title>Synopsis</title>
 
-    <refsection>
-      <title>Description</title>
-            
-      <para>
-        This operation switches to the <quote>previous</quote>
-        generation of the active profile, that is, the highest
-        numbered generation lower than the current generation, if it
-        exists.  It is just a convenience wrapper around
-        <option>--list-generations</option> and
-        <option>--switch-generation</option>.
-      </para>
-
-    </refsection>
+<cmdsynopsis>
+  <command>nix-env</command>
+  <arg choice='plain'><option>--rollback</option></arg>
+</cmdsynopsis>
+
+</refsection>
+
+<refsection><title>Description</title>
             
-    <refsection>
-      <title>Examples</title>
+<para>This operation switches to the “previous” generation of the
+active profile, that is, the highest numbered generation lower than
+the current generation, if it exists.  It is just a convenience
+wrapper around <option>--list-generations</option> and
+<option>--switch-generation</option>.</para>
 
-      <screen>
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
 $ nix-env --rollback
 switching from generation 92 to 91
 
 $ nix-env --rolback
 error: no generation older than the current (91) exists</screen>
 
-    </refsection>
+</refsection>
     
-  </refsection>
+</refsection>
 
 
   
-  <!--######################################################################-->
+<!--######################################################################-->
 
-  <refsection>
-    <title>Operation <option>--import</option></title>
+<refsection><title>Operation <option>--import</option></title>
 
-    <refsection>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-        <command>nix-env</command>
-        <group choice='req'>
-          <arg choice='plain'><option>--import</option></arg>
-          <arg choice='plain'><option>-I</option></arg>
-        </group>
-        <arg choice='req'><replaceable>path</replaceable></arg>
-      </cmdsynopsis>
-    </refsection>
+<refsection><title>Synopsis</title>
 
-    <refsection>
-      <title>Description</title>
-            
-      <para>
-        This operation makes <replaceable>path</replaceable> the
-        default active Nix expression for the user.  That is, the
-        symlink <filename>~/.nix-userenv</filename> is made to point
-        to <replaceable>path</replaceable>.
-      </para>
-
-    </refsection>
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--import</option></arg>
+    <arg choice='plain'><option>-I</option></arg>
+  </group>
+  <arg choice='req'><replaceable>path</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
             
-    <refsection>
-      <title>Examples</title>
+<para>This operation makes <replaceable>path</replaceable> the default
+active Nix expression for the user.  That is, the symlink
+<filename>~/.nix-userenv</filename> is made to point to
+<replaceable>path</replaceable>.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
 
-      <screen>
+<screen>
 $ nix-env -I ~/nixpkgs-0.5/</screen>
 
-    </refsection>
+</refsection>
     
-  </refsection>
+</refsection>
 
 
   
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index eead48397262..2913f1899307 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -330,7 +330,8 @@ query is applied to the target of the symlink.</para>
 
 <variablelist>
 
-  <varlistentry><term><option>--use-output</option> / <option>-u</option></term>
+  <varlistentry><term><option>--use-output</option></term>
+    <term><option>-u</option></term>
   
     <listitem><para>For each argument to the query that is a store
     derivation, apply the query to the output path of the derivation
@@ -338,7 +339,8 @@ query is applied to the target of the symlink.</para>
     
   </varlistentry>
 
-  <varlistentry><term><option>--force-realise</option> / <option>-f</option></term>
+  <varlistentry><term><option>--force-realise</option></term>
+    <term><option>-f</option></term>
   
     <listitem><para>Realise each argument to the query first (see
     <link linkend="rsec-nix-store-realise"><command>nix-store
@@ -365,7 +367,8 @@ query is applied to the target of the symlink.</para>
     
   </varlistentry>
 
-  <varlistentry><term><option>--requisites</option> / <option>-R</option></term>
+  <varlistentry><term><option>--requisites</option></term>
+    <term><option>-R</option></term>
 
     <listitem><para>Prints out the <link
     linkend="gloss-closure">closure</link> of the store path
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index 467959f19628..052ae4cf983f 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -19,7 +19,8 @@
 </varlistentry>
 
 
-<varlistentry><term><option>--verbose</option> / <option>-v</option></term>
+<varlistentry><term><option>--verbose</option></term>
+  <term><option>-v</option></term>
 
   <listitem>
     
@@ -72,7 +73,8 @@
 </varlistentry>
 
 
-<varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term>
+<varlistentry><term><option>--no-build-output</option></term>
+  <term><option>-Q</option></term>
 
   <listitem><para>By default, output written by builders to standard
   output and standard error is echoed to the Nix command's standard
@@ -84,7 +86,8 @@
 </varlistentry>
 
 
-<varlistentry id="opt-max-jobs"><term><option>--max-jobs</option> / <option>-j</option></term>
+<varlistentry id="opt-max-jobs"><term><option>--max-jobs</option></term>
+  <term><option>-j</option></term>
 
   <listitem><para>Sets the maximum number of build jobs that Nix will
   perform in parallel to the specified number.  The default is 1.  A
@@ -93,7 +96,8 @@
 </varlistentry>
 
 
-<varlistentry><term><option>--keep-going</option> / <option>-k</option></term>
+<varlistentry><term><option>--keep-going</option></term>
+  <term><option>-k</option></term>
 
   <listitem><para>Keep going in case of failed builds, to the
   greatest extent possible.  That is, if building an input of some
@@ -105,7 +109,8 @@
 </varlistentry>
 
 
-<varlistentry><term><option>--keep-failed</option> / <option>-K</option></term>
+<varlistentry><term><option>--keep-failed</option></term>
+  <term><option>-K</option></term>
 
   <listitem><para>Specifies that in case of a build failure, the
   temporary directory (usually in <filename>/tmp</filename>) in which
diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml
index 450353337e5a..7620531c0ead 100644
--- a/doc/manual/package-management.xml
+++ b/doc/manual/package-management.xml
@@ -2,23 +2,23 @@
 
 <para>This chapter discusses how to do package management with Nix,
 i.e., how to obtain, install, upgrade, and erase components.  This is
-the <quote>user’s</quote> perspective of the Nix system — people
+the “user’s” perspective of the Nix system — people
 who want to <emphasis>create</emphasis> components should consult
 <xref linkend='chap-writing-nix-expressions' />.</para>
 
 
 <sect1><title>Basic package management</title>
 
-<para>The main command for package management is
-<command>nix-env</command>.  You can use it to install, upgrade, and
-erase components, and to query what components are installed or are
-available for installation.</para>
+<para>The main command for package management is <link
+linkend="sec-nix-env"><command>nix-env</command></link>.  You can use
+it to install, upgrade, and erase components, and to query what
+components are installed or are available for installation.</para>
 
-<para>In Nix, different users can have different <quote>views</quote>
+<para>In Nix, different users can have different “views”
 on the set of installed applications.  That is, there might be lots of
 applications present on the system (possibly in many different
 versions), but users can have a specific selection of those active —
-where <quote>active</quote> just means that it appears in a directory
+where “active” just means that it appears in a directory
 in the user’s <envar>PATH</envar>.  Such a view on the set of
 installed applications is called a <emphasis>user
 environment</emphasis>, which is just a directory tree consisting of
@@ -31,11 +31,9 @@ Nix expressions called the Nix Package collection that contains
 components ranging from basic development stuff such as GCC and Glibc,
 to end-user applications like Mozilla Firefox.  (Nix is however not
 tied to the Nix Package collection; you could write your own Nix
-expression based on it, or completely new ones.)  You can download the
-latest version from <ulink
-url='http://catamaran.labs.cs.uu.nl/dist/nix' />.  You probably want
-the latest unstable release; currently the stable releases tend to lag
-behind quite a bit.</para>
+expressions based on it, or completely new ones.)  You can download
+the latest version from <ulink
+url='http://catamaran.labs.cs.uu.nl/dist/nix' />.</para>
 
 <para>Assuming that you have downloaded and unpacked a release of Nix
 Packages, you can view the set of available components in the release:
@@ -127,7 +125,7 @@ release of Nix Packages, you can do:
 $ nix-env -f nixpkgs-<replaceable>version</replaceable> -u subversion</screen>
 
 This will <emphasis>only</emphasis> upgrade Subversion if there is a
-<quote>newer</quote> version in the new set of Nix expressions, as
+“newer” version in the new set of Nix expressions, as
 defined by some pretty arbitrary rules regarding ordering of version
 numbers (which generally do what you’d expect of them).  To just
 unconditionally replace Subversion with whatever version is in the Nix
@@ -175,7 +173,7 @@ set.</para></footnote></para>
 </sect1>
 
 
-<sect1><title>Profiles</title>
+<sect1 id="sec-profiles"><title>Profiles</title>
 
 <para>Profiles and user environments are Nix’s mechanism for
 implementing the ability to allow differens users to have different
@@ -336,7 +334,7 @@ This will <emphasis>not</emphasis> change the
 (<option>-u</option>) and uninstall (<option>-e</option>) never
 actually delete components from the system.  All they do (as shown
 above) is to create a new user environment that no longer contains
-symlinks to the <quote>deleted</quote> components.</para>
+symlinks to the “deleted” components.</para>
 
 <para>Of course, since disk space is not infinite, unused components
 should be removed at some point.  You can do this by running the Nix
@@ -423,7 +421,7 @@ linkend="sec-nix-channel"><command>nix-channel</command></link> you
 can automatically stay up to date with whatever is available at that
 URL.</para>
 
-<para>You can <quote>subscribe</quote> to a channel using
+<para>You can “subscribe” to a channel using
 <command>nix-channel --add</command>, e.g.,
 
 <screen>
@@ -436,7 +434,7 @@ of the Nix Packages collection.  (Instead of
 stability, but right now is just outdated.)  Subscribing really just
 means that the URL is added to the file
 <filename>~/.nix-channels</filename>.  Right now there is no command
-to <quote>unsubscribe</quote>; you should just edit that file manually
+to “unsubscribe”; you should just edit that file manually
 and delete the offending URL.</para>
 
 <para>To obtain the latest Nix expressions available in a channel, do
diff --git a/doc/manual/style.css b/doc/manual/style.css
index 533104229953..bf6fc3ecf43e 100644
--- a/doc/manual/style.css
+++ b/doc/manual/style.css
@@ -102,6 +102,8 @@ pre.screen
 
 .note,.warning
 {
+    margin-top: 1em;
+    margin-bottom: 1em;
     border: 1px solid #6185a0;
     padding: 0px 1em;
     background: #fffff5;
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index a664f1e3256e..d9c78dbecb9d 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -818,7 +818,7 @@ set.</para>
 </simplesect>
 
 
-<simplesect><title>Functions</title>
+<simplesect id="ss-functions"><title>Functions</title>
 
 <para>Functions have the following form: