* Manual updates.

* Updated the README.  Now it just refers to the manual.

3 files changed, 120 insertions, 39 deletions

diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index a9a30b09dacf..ebc4f168a7c4 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -6,8 +6,9 @@
 
     <para>
       The easiest way to obtain Nix is to download a <ulink
-        url='http://www.cs.uu.nl/groups/ST/Trace/Nix'>source
-        distribution.</ulink>  
+      url='http://www.cs.uu.nl/groups/ST/Trace/Nix'>source
+      distribution</ulink>.  RPMs for SuSE and Red Hat are also
+      available.  These distributions are generated automatically.
     </para>
 
     <para>
@@ -35,8 +36,13 @@ $ svn checkout https://svn.cs.uu.nl:12443/repos/trace/nix/trunk nix</screen>
     <title>Prerequisites</title>
 
     <para>
-      A fairly recent version of GCC/G++ is required.  Version 2.95 and higher
-      should work.
+      The following prerequisites only apply when you build from
+      source.  Binary releases (e.g., RPMs) have no prerequisites.
+    </para>
+
+    <para>
+      A fairly recent version of GCC/G++ is required.  Version 2.95
+      and higher should work.
     </para>
 
     <para>
@@ -63,7 +69,7 @@ $ svn checkout https://svn.cs.uu.nl:12443/repos/trace/nix/trunk nix</screen>
   </sect1>
 
   <sect1>
-    <title>Building Nix</title>
+    <title>Building Nix from source</title>
 
     <para>
       After unpacking or checking out the Nix sources, issue the following
@@ -113,19 +119,70 @@ $ autoreconf -i</screen>
 
 
   <sect1>
+    <title>Installing from RPMs</title>
+
+    <para>
+      RPM packages of Nix can be downloaded from <ulink
+      url='http://www.cs.uu.nl/groups/ST/Trace/Nix' />.  These RPMs
+      should work for most fairly recent releases of SuSE and Red Hat
+      Linux.  They have been known to work work on SuSE Linux 8.1 and
+      9.0, and Red Hat 9.0.  In fact, it should work on any RPM-based
+      Linux distribution based on <literal>glibc</literal> 2.3 or
+      later.
+    </para>
+
+    <para>
+      Once downloaded, the RPMs can be installed or upgraded using
+      <command>rpm -U</command>.  For example,
+    </para>
+
+    <screen>
+rpm -U nix-0.5pre664-1.i386.rpm</screen>
+
+    <para>
+      The RPMs install into the directory <filename>/nix</filename>.
+      Nix can be uninstalled using <command>rpm -e nix</command>.
+      After this it will be necessary to manually remove the Nix store
+      and other auxiliary data:
+    </para>
+
+    <screen>
+rm -rf /nix/store
+rm -rf /nix/var</screen>
+
+  </sect1>
+
+  <sect1>
+    <title>Permissions</title>
+
+    <para>
+      All Nix operations must be performed under the user ID that owns
+      the Nix store and database
+      (<filename><replaceable>prefix</replaceable>/store</filename>
+      and
+      <filename><replaceable>prefix</replaceable>/var/nix/db</filename>,
+      respectively).  When installed from the RPM packages, these
+      directories are owned by <systemitem
+      class='username'>root</systemitem>.
+    </para>
+
+  </sect1>
+
+  <sect1>
     <title>Using Nix</title>
 
     <para>
-      To use Nix, some environment variables should be set.  In particular,
-      <envar>PATH</envar> should contain the directories
+      To use Nix, some environment variables should be set.  In
+      particular, <envar>PATH</envar> should contain the directories
       <filename><replaceable>prefix</replaceable>/bin</filename> and
-      <filename><replaceable>prefix</replaceable>/var/nix/links/current/bin</filename>. 
-      The first directory contains the Nix tools themselves, while the second
-      contains to the current <emphasis>user environment</emphasis> (an
-      automatically generated package consisting of symlinks to installed
-      packages).  The simplest way to set the required environment variables is
-      to include the file
-      <filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename> 
+      <filename>~/.nix-userenv/bin</filename>.  The first directory
+      contains the Nix tools themselves, while
+      <filename>~/.nix-userenv</filename> is a symbolic link to the
+      current <emphasis>user environment</emphasis> (an automatically
+      generated package consisting of symlinks to installed packages).
+      The simplest way to set the required environment variables is to
+      include the file
+      <filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename>
       in your <filename>~/.bashrc</filename> (or similar), like this:
     </para>
 
@@ -135,9 +192,3 @@ $ autoreconf -i</screen>
   </sect1>
 
 </chapter>
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "chapter")
-end:
--->
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index b41cad0a80fc..02a4383361ca 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -91,11 +91,3 @@
   </para>
 
 </chapter>
-
-
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "chapter")
-end:
--->
diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml
index 85f164587790..9925be994349 100644
--- a/doc/manual/overview.xml
+++ b/doc/manual/overview.xml
@@ -5,6 +5,10 @@
     This chapter provides a guided tour of Nix.
   </para>
 
+
+  
+  <!--######################################################################-->
+
   <sect1>
     <title>Basic package management</title>
 
@@ -63,7 +67,7 @@ pan-0.14.2</screen>
     </para>
 
     <screen>
-$ nix-env -qf pkgs/system/i686-linux.nix
+$ nix-env -qaf pkgs/system/i686-linux.nix
 gettext-0.12.1
 sylpheed-0.9.7
 aterm-2.0
@@ -86,7 +90,7 @@ pan-0.14.2
     </para>
 
     <screen>
-$ nix-env -qsf pkgs/system/i686-linux.nix
+$ nix-env -qasf pkgs/system/i686-linux.nix
 -P gettext-0.12.1
 IP sylpheed-0.9.7
 -- aterm-2.0
@@ -111,7 +115,7 @@ IP sylpheed-0.9.7
     </para>
 
     <screen>
-$ nix-env -i pkgs/system/i686-linux.nix pan-0.14.2</screen>
+$ nix-env -if pkgs/system/i686-linux.nix pan</screen>
 
     <para>
       Since installation may take a long time, depending on whether any
@@ -234,11 +238,52 @@ lrwxrwxrwx  1 eelco ... svn -> /nix/store/3829...fb5d-subversion-0.32.1/bin/svn
     </para>
 
     <screen>
-$ nix-env -u pan-0.14.2</screen>
+$ nix-env -e pan</screen>
+
+    <para>
+      This means that the package is removed from the user
+      environment.  It is <emphasis>not</emphasis> yet removed from
+      the system.  When a package is uninstalled from a user
+      environment, it may still be used by other packages, or may
+      still be present in other user environments.  Deleting it under
+      such conditions would break those other packages or user
+      environments.  To prevent this, packages are only
+      <quote>physically</quote> deleted by running the Nix garbage
+      collector, which searches for all packages in the Nix store that
+      are no longer <quote>reachable</quote> from outside the store.
+      Thus, uninstalling a package is always safe: it cannot break
+      other packages.
+    </para>
+
+    <para>
+      Upgrading packages is easy.  Given a Nix expression that
+      contains newer versions of installed packages (that is, packages
+      with the same package name, but a higher version number),
+      <command>nix-env -u</command> will replace the installed package
+      in the user environment with the newer package.  For example,
+      
+      <screen>
+$ nix-env -uf pkgs/system/i686-linux.nix pan</screen>
+
+      looks for a newer version of Pan, and installs it if found.
+      Also useful is the ability to upgrade <emphasis>all</emphasis>
+      packages:
+      
+      <screen>
+$ nix-env -uf pkgs/system/i686-linux.nix '*'</screen>
+
+      The asterisk matches all installed packages<footnote><para>No,
+      we don't support arbitrary regular
+      expressions</para></footnote>.  Note that <literal>*</literal>
+      must be quoted to prevent shell globbing.
+    </para>
 
   </sect1>
 
 
+  
+  <!--######################################################################-->
+
   <sect1>
     <title>Writing Nix expressions</title>
 
@@ -400,11 +445,4 @@ derivation {
   </sect1>
 
 
-
 </chapter>
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "chapter")
-end:
--->