4 files changed, 59 insertions, 1 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 8e2fff208747..51ed7c05f73a 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -4,7 +4,8 @@ XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs
 XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs
 
 SOURCES = book.xml introduction.xml installation.xml \
- nix-store-reference.xml \
+ overview.xml \
+ nix-store-reference.xml nix-instantiate-reference.xml \
  troubleshooting.xml bugs.xml
 
 book.is-valid: $(SOURCES)
diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index 710246ca1bfa..7248e5e18b43 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -5,6 +5,7 @@
 [
 <!ENTITY introduction SYSTEM "introduction.xml">
 <!ENTITY installation SYSTEM "installation.xml">
+<!ENTITY overview SYSTEM "overview.xml">
 <!ENTITY nix-store-reference SYSTEM "nix-store-reference.xml">
 <!ENTITY nix-instantiate-reference SYSTEM "nix-instantiate-reference.xml">
 <!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
@@ -27,6 +28,7 @@
 
   &introduction;
   &installation;
+  &overview;
 
   <appendix>
     <title>Command Reference</title>
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 3872a7fb8bf5..7d11fa43e0a5 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -111,6 +111,29 @@ $ autoreconf -i</screen>
 
   </sect1>
 
+
+  <sect1>
+    <title>Using Nix</title>
+
+    <para>
+      To use Nix, some environment variables should be set.  In particular,
+      <literal>PATH</literal> 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> 
+      in your <filename>~/.bashrc</filename> (or similar), like this:
+    </para>
+
+    <screen>
+. <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
+
+  </sect1>
+
 </chapter>
 
 <!--
diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml
new file mode 100644
index 000000000000..1c2c283f071e
--- /dev/null
+++ b/doc/manual/overview.xml
@@ -0,0 +1,32 @@
+<chapter>
+  <title>Overview</title>
+
+  <para>
+    This chapter provides a guided tour of Nix.
+  </para>
+
+  <sect1>
+    <title>Basic package management</title>
+
+    <para>
+      Let's start from the perspective of an end-user.  Common operations at
+      this level are to install and remove packages, ask what packages are
+      installed or available for installation, and so on.
+    </para>
+
+    <para>
+      To install packages, a <emphasis>Nix expression</emphasis> is required
+      that tells Nix how to build that package.  There is a <ulink
+        url='https://svn.cs.uu.nl:12443/dist/trace/trace-nixpkgs-trunk.tar.bz2'>standard 
+        distribution of Nix expressions</ulink> for many common packages.
+    </para>
+
+  </sect1>
+
+</chapter>
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "chapter")
+end:
+-->