3 files changed, 199 insertions, 21 deletions
diff --git a/doc/manual/introduction/about-nix.xml b/doc/manual/introduction/about-nix.xml
index 4860b3d38fab..efd6cf2bb347 100644
--- a/doc/manual/introduction/about-nix.xml
+++ b/doc/manual/introduction/about-nix.xml
@@ -4,7 +4,7 @@
       version="5.0"
       xml:id="ch-about-nix">
 
-<title>Introduction</title>
+<title>About Nix</title>
 
 <para>Nix is a <emphasis>purely functional package manager</emphasis>.
 This means that it treats packages like values in purely functional
@@ -16,10 +16,10 @@ store</emphasis>, usually the directory
 subdirectory such as
 
 <programlisting>
-/nix/store/nlc4z5y1hm8w9s8vm6m1f5hy962xjmp5-firefox-12.0
+/nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
 </programlisting>
 
-where <literal>nlc4z5…</literal> is a unique identifier for the
+where <literal>b6gvzjyb2pg0…</literal> is a unique identifier for the
 package that captures all its dependencies (it’s a cryptographic hash
 of the package’s build dependency graph).  This enables many powerful
 features.</para>
@@ -161,19 +161,19 @@ library and the compiler) would have to built, at least if they are
 not already in the Nix store.  This is a <emphasis>source deployment
 model</emphasis>.  For most users, building from source is not very
 pleasant as it takes far too long.  However, Nix can automatically
-skip building from source and download a pre-built binary instead if
-it knows about it.  <emphasis>Nix channels</emphasis> provide Nix
-expressions along with pre-built binaries.</para>
-
-<!--
-<para>source deployment model (like <a
-href="http://www.gentoo.org/">Gentoo</a>) and a binary model (like
-RPM)</para>
--->
+skip building from source and instead use a <emphasis>binary
+cache</emphasis>, a web server that provides pre-built binaries. For
+instance, when asked to build
+<literal>/nix/store/b6gvzjyb2pg0…-firefox-33.1</literal> from source,
+Nix would first check if the file
+<uri>https://cache.nixos.org/b6gvzjyb2pg0….narinfo</uri> exists, and
+if so, fetch the pre-built binary referenced from there; otherwise, it
+would fall back to building from source.</para>
 
 </simplesect>
 
 
+<!--
 <simplesect><title>Binary patching</title>
 
 <para>In addition to downloading binaries automatically if they’re
@@ -182,6 +182,7 @@ package in the Nix store into a new version.  This speeds up
 upgrades.</para>
 
 </simplesect>
+-->
 
 
 <simplesect><title>Nix Packages collection</title>
@@ -193,10 +194,48 @@ collection</emphasis> (Nixpkgs).</para>
 </simplesect>
 
 
+<simplesect><title>Managing build environments</title>
+
+<para>Nix is extremely useful for developers as it makes it easy to
+automatically set up the the build environment for a package. Given a
+Nix expression that describes the dependencies of your package, the
+command <command>nix-shell</command> will build or download those
+dependencies if they’re not already in your Nix store, and then start
+a Bash shell in which all necessary environment variables (such as
+compiler search paths) are set.</para>
+
+<para>For example, the following command gets all dependencies of the
+Pan newsreader, as described by <link
+xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix">its
+Nix expression</link>:</para>
+
+<screen>
+$ nix-shell '&lt;nixpkgs>' -A pan
+</screen>
+
+<para>You’re then dropped into a shell where you can edit, build and test
+the package:</para>
+
+<screen>
+[nix-shell]$ tar xf $src
+[nix-shell]$ cd pan-*
+[nix-shell]$ ./configure
+[nix-shell]$ make
+[nix-shell]$ ./pan/gui/pan
+</screen>
+
+<!--
+<para>Since Nix packages are reproducible and have complete dependency
+specifications, Nix makes an excellent basis for <a
+href="[%root%]hydra">a continuous build system</a>.</para>
+-->
+
+</simplesect>
+
+
 <simplesect><title>Portability</title>
 
-<para>Nix should run on most Unix systems, including Linux and Mac OS
-X.</para>
+<para>Nix runs on Linux and Mac OS X.</para>
 
 </simplesect>
 
@@ -206,20 +245,22 @@ X.</para>
 <para>NixOS is a Linux distribution based on Nix.  It uses Nix not
 just for package management but also to manage the system
 configuration (e.g., to build configuration files in
-<filename>/etc</filename>).  This means, among other things, that it’s
-possible to easily roll back the entire configuration of the system to
-an earlier state.  Also, users can install software without root
+<filename>/etc</filename>).  This means, among other things, that it
+is easy to roll back the entire configuration of the system to an
+earlier state.  Also, users can install software without root
 privileges.  For more information and downloads, see the <link
 xlink:href="http://nixos.org/">NixOS homepage</link>.</para>
 
 </simplesect>
 
 
-<!-- other features:
+<simplesect><title>License</title>
 
-- build farms
-- reproducibility (Nix expressions allows whole configuration to be rebuilt)
+<para>Nix is released under the terms of the <link
+xlink:href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">GNU
+LGPLv2.1 or (at your option) any later version</link>.</para>
+
+</simplesect>
 
--->
 
 </chapter>
diff --git a/doc/manual/introduction/introduction.xml b/doc/manual/introduction/introduction.xml
index 665fef2fb990..12b2cc761063 100644
--- a/doc/manual/introduction/introduction.xml
+++ b/doc/manual/introduction/introduction.xml
@@ -7,5 +7,6 @@
 <title>Introduction</title>
 
 <xi:include href="about-nix.xml" />
+<xi:include href="quick-start.xml" />
 
 </part>
diff --git a/doc/manual/introduction/quick-start.xml b/doc/manual/introduction/quick-start.xml
new file mode 100644
index 000000000000..0d13651e0ab3
--- /dev/null
+++ b/doc/manual/introduction/quick-start.xml
@@ -0,0 +1,136 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="chap-quick-start">
+
+<title>Quick Start</title>
+
+<para>This chapter is for impatient people who don't like reading
+documentation.  For more in-depth information you are kindly referred
+to subsequent chapters.</para>
+
+<procedure>
+
+<step><para>Install single-user Nix by running the following:
+
+<screen>
+$ curl https://nixos.org/nix/install | sh
+</screen>
+
+This will install Nix in <filename>/nix</filename>. The install script
+will create <filename>/nix</filename> using <command>sudo</command>,
+so make sure you have sufficient rights.  (For other installation
+methods, see <xref linkend="chap-installation"/>.)</para></step>
+
+<step><para>See what installable packages are currently available
+in the channel:
+
+<screen>
+$ nix-env -qa
+docbook-xml-4.3
+docbook-xml-4.5
+firefox-33.0.2
+hello-2.9
+libxslt-1.1.28
+<replaceable>...</replaceable></screen>
+
+</para></step>
+
+<step><para>Install some packages from the channel:
+
+<screen>
+$ nix-env -i hello <replaceable>...</replaceable> </screen>
+
+This should download pre-built packages; it should not build them
+locally (if it does, something went wrong).</para></step>
+
+<step><para>Test that they work:
+
+<screen>
+$ which hello
+/home/eelco/.nix-profile/bin/hello
+$ hello
+Hello, world!
+</screen>
+
+</para></step>
+
+<step><para>Uninstall a package:
+
+<screen>
+$ nix-env -e hello</screen>
+
+</para></step>
+
+<step><para>You can also test a package without installing it:
+
+<screen>
+$ nix-shell -p hello
+</screen>
+
+This builds or downloads GNU Hello and its dependencies, then drops
+you into a Bash shell where the <command>hello</command> command is
+present, all without affecting your normal environment:
+
+<screen>
+[nix-shell:~]$ hello
+Hello, world!
+
+[nix-shell:~]$ exit
+
+$ hello
+hello: command not found
+</screen>
+
+</para></step>
+
+<step><para>To keep up-to-date with the channel, do:
+
+<screen>
+$ nix-channel --update nixpkgs
+$ nix-env -u '*'</screen>
+
+The latter command will upgrade each installed package for which there
+is a “newer” version (as determined by comparing the version
+numbers).</para></step>
+
+<!--
+<step><para>You can also install specific packages directly from
+your web browser.  For instance, you can go to <link
+xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
+/> and click on any link for the individual packages for your
+platform.  Associate <literal>application/nix-package</literal> with
+the program <command>nix-install-package</command>.  A window should
+appear asking you whether it’s okay to install the package.  Say
+<literal>Y</literal>.  The package and all its dependencies will be
+installed.</para></step>
+-->
+
+<step><para>If you're unhappy with the result of a
+<command>nix-env</command> action (e.g., an upgraded package turned
+out not to work properly), you can go back:
+
+<screen>
+$ nix-env --rollback</screen>
+
+</para></step>
+
+<step><para>You should periodically run the Nix garbage collector
+to get rid of unused packages, since uninstalls or upgrades don't
+actually delete them:
+
+<screen>
+$ nix-collect-garbage -d</screen>
+
+<!--
+The first command deletes old “generations” of your profile (making
+rollbacks impossible, but also making the packages in those old
+generations available for garbage collection), while the second
+command actually deletes them.-->
+
+</para></step>
+
+</procedure>
+
+</chapter>