diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml
index 1c2c283f07..b26d286044 100644
--- a/doc/manual/overview.xml
+++ b/doc/manual/overview.xml
@@ -9,18 +9,234 @@
Basic package management
- Let's start from the perspective of an end-user. Common operations at
+ 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.
+ installed or available for installation, and so on. These are operations
+ on the user environment: the set of packages that a
+ user sees. In a command line Unix environment, this means
+ the set of programs that are available through the
+ PATH environment variable. (In other environments it
+ might mean the set of programs available on the desktop, through the
+ start menu, and so on.)
+
+ The terms installation and uninstallation
+ are used in this context to denote the act of adding or removing packages
+ from the user environment. In Nix, these operations are dissociated from
+ the physical copying or deleting of files. Installation requires that
+ the files constituting the package are present, but they may be present
+ beforehand. Likewise, uninstallation does not actually delete any files;
+ this is done automatically by running a garbage collector.
+
+
+
+ User environments are manipulated through the nix-env
+ command. The query operation can be used to see what packages are
+ currently installed.
+
+
+
+$ nix-env -q
+MozillaFirebird-0.7
+sylpheed-0.9.7
+pan-0.14.2
+
+
+ ( is actually short for .) The package names are symbolic: they don't have
+ any particular significance to Nix (as they shouldn't, since they are not
+ unique—there can be many derivations with the same name). Note that
+ these packages have many dependencies (e.g., Mozilla uses the
+ gtk+ package) but these have not been installed in the
+ user environment, though they are present on the system. Generally,
+ there is no need to install such packages; only packages containing
+ programs should be installed.
+
+
To install packages, a Nix expression is required
that tells Nix how to build that package. There is a standard
- distribution of Nix expressions for many common packages.
+ url='https://svn.cs.uu.nl:12443/dist/trace/trace-nixpkgs-trunk.tar.bz2'>set
+ of standard of Nix expressions for many common packages.
+ Assuming that you have downloaded and unpacked these, you can view the
+ set of available packages:
+
+$ nix-env -qf pkgs/system/i686-suse-linux.nix
+gettext-0.12.1
+sylpheed-0.9.7
+aterm-2.0
+gtk+-1.2.10
+apache-httpd-2.0.48
+pan-0.14.2
+...
+
+
+ The Nix expression in the file i686-suse-linux.nix
+ yields the set of packages for a SuSE Linux system running on x86
+ hardware. For other platforms, copy and modify this file for your
+ platform as appropriate. [TODO: improve this]
+
+
+
+ It is also possible to see the status of available
+ packages, i.e., whether they are installed into the user environment
+ and/or present in the system:
+
+
+
+$ nix-env -qf pkgs/system/i686-suse-linux.nix
+-P gettext-0.12.1
+IP sylpheed-0.9.7
+-- aterm-2.0
+-P gtk+-1.2.10
+
+
+ This reveals that the sylpheed package is already
+ installed, or more precisely, that exactly the same instantiation of
+ sylpheed is installed. This guarantees that the
+ available package is exactly the same as the installed package with
+ regard to sources, dependencies, build flags, and so on. Similarly, we
+ see that the gettext and gtk+
+ packages are present but not installed in the user environment, while the
+ aterm package is not installed or present at all (so,
+ if we were to install it, it would have to be built or downloaded first).
+
+
+
+ The install operation is used install available packages from a Nix
+ environment. To install the pan package (a
+ newsreader), you would do:
+
+
+
+$ nix-env -i pkgs/system/i686-suse-linux.nix pan-0.14.2
+
+
+ Since installation may take a long time, depending on whether any
+ packages need to be built or downloaded, it's a good idea to make
+ nix-env run verbosely by using the
+ () option. This option may be repeated to
+ increase the level of verbosity. A good value is 3
+ ().
+
+
+
+ In fact, if you run this command verbosely you will observe that Nix
+ starts to build many packages, including large and fundamental ones such
+ as glibc and gcc. I.e., you are
+ performing a source installation. This is generally undesirable, since
+ installation from sources may require large amounts of disk and CPU
+ resources. Therefore a binary installation is generally
+ preferable.
+
+
+
+ Rather than provide different mechanisms to create and perform
+ the installation of binary packages, Nix supports binary deployment
+ transparently through a generic mechanism of
+ substitute expressions. If an request is made to
+ build some Nix expression, Nix will first try to build any substitutes
+ for that expression. These substitutes presumably perform an identical
+ build operation with respect to the result, but require less resources.
+ For instance, a substitute that downloads a pre-built package from the
+ network requires less CPU and disk resources, and possibly less time.
+
+
+
+ Nix's use of cryptographic hashes makes this entirely safe. It is not
+ possible, for instance, to accidentally substitute a build of some
+ package for a Solaris or Windows system for a build on a SuSE/x86 system.
+
+
+
+ While the substitute mechanism is a generic mechanism, Nix provides two
+ standard tools called nix-push and
+ nix-push that maintain and use a shared cache of
+ prebuilt derivations on some network site (reachable through HTTP). If
+ you attempt to install some package that someone else has previously
+ built and pushed into the cache, and you have done a
+ pull to register substitutes that download these prebuilt
+ packages, then the installation will automatically use these.
+
+
+
+ For example, to pull from our cache of
+ prebuilt packages (at the time of writing, for SuSE Linux/x86), use the
+ following command:
+
+
+
+$ nix-pull http://losser.st-lab.cs.uu.nl/~eelco/nix-dist/
+obtaining list of Nix archives at http://losser.st-lab.cs.uu.nl/~eelco/nix-dist...
+...
+
+
+ If nix-pull is run without any arguments, it will pull
+ from the URLs specified in the file
+ prefix/etc/nix/prebuilts.conf.
+
+
+
+ Assuming that the pan installation produced no errors,
+ it can be used immediately, that is, it now appears in a directory in the
+ PATH environment variable. Specifically,
+ PATH includes the entry
+ prefix/var/nix/links/current/bin,
+ where
+ prefix/var/nix/links/current
+ is just a symlink to the current user environment:
+
+
+
+$ ls -l /nix/var/nix/links/
+...
+lrwxrwxrwx 1 eelco ... 15 -> /nix/store/1871...12b0-user-environment
+lrwxrwxrwx 1 eelco ... 16 -> /nix/store/59ba...df6b-user-environment
+lrwxrwxrwx 1 eelco ... current -> /nix/var/nix/links/16
+
+
+ That is, current in this example is a link to
+ 16, which is the current user environment. Before
+ the installation, it pointed to 15. Note that this
+ means that you can atomically roll-back to the previous user environment
+ by pointing the symlink current at
+ 15 again. This also shows that operations such as
+ installation are atomic in the Nix system: any arbitrarily complex
+ set of installation, uninstallation, or upgrade actions eventually boil
+ down to the single operation of pointing a symlink somewhere else (which
+ can be implemented atomically in Unix).
+
+
+
+ What's in a user environment? It's just a set of symlinks to the files
+ that constitute the installed packages. For instance:
+
+
+
+$ ls -l /nix/var/nix/links/16/bin
+lrwxrwxrwx 1 eelco ... MozillaFirebird -> /nix/store/35f8...4ae6-MozillaFirebird-0.7/bin/MozillaFirebird
+lrwxrwxrwx 1 eelco ... svn -> /nix/store/3829...fb5d-subversion-0.32.1/bin/svn
+...
+
+
+ Note that, e.g., svn =
+ /nix/var/nix/links/current/bin/svn =
+ /nix/var/nix/links/16/bin/svn =
+ /nix/store/59ba...df6b-user-environment/bin/svn =
+ /nix/store/3829...fb5d-subversion-0.32.1/bin/svn.
+
+
+
+ Naturally, packages can also be uninstalled:
+
+
+
+$ nix-env -u pan-0.14.2
+