* Manual updates.

3 files changed, 175 insertions, 8 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 51ed7c05f73a..53a913ce6b03 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -1,7 +1,9 @@
 ENV = SGML_CATALOG_FILES=$(docbookcatalog)
 
 XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs
-XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs
+XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
+ --param section.autolabel 1 \
+ --param section.label.includes.component.label 1
 
 SOURCES = book.xml introduction.xml installation.xml \
  overview.xml \
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 7d11fa43e0a5..a9a30b09dacf 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -117,7 +117,7 @@ $ autoreconf -i</screen>
 
     <para>
       To use Nix, some environment variables should be set.  In particular,
-      <literal>PATH</literal> should contain the directories
+      <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
diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml
index b26d286044d6..64368fe2db0e 100644
--- a/doc/manual/overview.xml
+++ b/doc/manual/overview.xml
@@ -14,10 +14,9 @@
       installed or available for installation, and so on.  These are operations
       on the <emphasis>user environment</emphasis>: the set of packages that a
       user <quote>sees</quote>.  In a command line Unix environment, this means
-      the set of programs that are available through the
-      <literal>PATH</literal> environment variable.  (In other environments it
-      might mean the set of programs available on the desktop, through the
-      start menu, and so on.)
+      the set of programs that are available through the <envar>PATH</envar>
+      environment variable.  (In other environments it might mean the set of
+      programs available on the desktop, through the start menu, and so on.)
     </para>
 
     <para>
@@ -183,8 +182,8 @@ obtaining list of Nix archives at http://losser.st-lab.cs.uu.nl/~eelco/nix-dist.
     <para>
       Assuming that the <literal>pan</literal> installation produced no errors,
       it can be used immediately, that is, it now appears in a directory in the
-      <literal>PATH</literal> environment variable.  Specifically,
-      <literal>PATH</literal> includes the entry
+      <envar>PATH</envar> environment variable.  Specifically,
+      <envar>PATH</envar> includes the entry
       <filename><replaceable>prefix</replaceable>/var/nix/links/current/bin</filename>, 
       where
       <filename><replaceable>prefix</replaceable>/var/nix/links/current</filename> 
@@ -239,6 +238,172 @@ $ nix-env -u pan-0.14.2</screen>
 
   </sect1>
 
+
+  <sect1>
+    <title>Writing Nix expressions</title>
+
+    <sect2>
+      <title>A simple Nix expression</title>
+
+      <para>
+        This section shows how to write simple Nix expressions&mdash;the things
+        that describe how to build a package.
+      </para>
+
+      <example id='ex-hello-nix'>
+        <title>Nix expression for GNU Hello</title>
+        <programlisting>
+{stdenv, fetchurl, perl}: <co id='ex-hello-nix-co-1' />
+
+derivation { <co id='ex-hello-nix-co-2' />
+  name = "hello-2.1.1"; <co id='ex-hello-nix-co-3' />
+  system = stdenv.system; <co id='ex-hello-nix-co-4' />
+  builder = ./builder.sh; <co id='ex-hello-nix-co-5' />
+  src = fetchurl { <co id='ex-hello-nix-co-6' />
+    url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
+    md5 = "70c9ccf9fac07f762c24f2df2290784d";
+  };
+  stdenv = stdenv; <co id='ex-hello-nix-co-7' />
+  perl = perl;
+}
+        </programlisting>
+      </example>
+
+      <para>
+        A simple Nix expression is shown in <xref linkend='ex-hello-nix' />. It
+        describes how to the build the <ulink
+          url='http://www.gnu.org/directory/GNU/hello.html'>GNU Hello
+          package</ulink>.  This package has several dependencies.  First, it
+        requires a number of other packages, such as a C compiler, standard
+        Unix shell tools, and Perl.  Rather than have this Nix expression refer
+        to and use specific versions of these packages, it should be generic;
+        that is, it should be a <emphasis>function</emphasis> that takes the
+        required packages as inputs and yield a build of the GNU Hello package
+        as a result.  This Nix expression defines a function with three
+        arguments <xref linkend='ex-hello-nix-co-1' />, namely:
+        <orderedlist>
+          <listitem><para><varname>stdenv</varname>, which should be a
+              <emphasis>standard environment package</emphasis>.  The standard
+              environment is a set of tools and other components that would be
+              expected in a fairly minimal Unix-like environment: a C compiler
+              and linker, Unix shell tools, and so on.</para>
+          </listitem>
+          <listitem><para><varname>fetchurl</varname>, which should be a
+              function that given parameters <varname>url</varname> and
+              <varname>md5</varname>, will fetch a file from the specified
+              location and check that this file has the given MD5 hash code.
+              The hash is required because build operations must be
+              <emphasis>pure</emphasis>: given the same inputs they should
+              always yield the same output.  Since network resources can change
+              at any time, we must in some way guarantee what the result will
+              be.</para>
+          </listitem>
+          <listitem><para><varname>perl</varname>, which should be a Perl
+              interpreter.</para>
+          </listitem>
+        </orderedlist>
+      </para>
+
+      <para>
+        The remainder of the file is the body of the function, which happens to
+        be a <emphasis>derivation</emphasis> <xref
+        linkend='ex-hello-nix-co-2' />, which is the built-in function
+        <varname>derivation</varname> applied to a set of attributes that
+        encode all the necessary information for building the GNU Hello
+        package. 
+      </para>
+
+      <example>
+        <title>Build script (<filename>builder.sh</filename>) for GNU
+          Hello</title>
+        <programlisting>
+#! /bin/sh
+
+buildinputs="$perl"
+. $stdenv/setup || exit 1
+
+tar xvfz $src || exit 1
+cd hello-* || exit 1
+./configure --prefix=$out || exit 1
+make || exit 1
+make install || exit 1
+        </programlisting>
+      </example>
+
+    </sect2>
+
+    <sect2>
+      <title>A more complex Nix expression</title>
+
+      <example id='ex-svn-nix'>
+        <title>Nix expression for Subversion</title>
+        <programlisting>
+{ localServer ? false <co id='ex-svn-nix-co-1' />
+, httpServer ? false
+, sslSupport ? false
+, swigBindings ? false
+, stdenv, fetchurl
+, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null
+}:
+
+assert !isNull expat; <co id='ex-svn-nix-co-2' />
+assert localServer -> !isNull db4;
+assert httpServer -> !isNull httpd &amp;&amp; httpd.expat == expat; <co id='ex-svn-nix-co-3' />
+assert sslSupport -> !isNull openssl &amp;&amp; (httpServer -> httpd.openssl == openssl);
+assert swigBindings -> !isNull swig;
+
+derivation {
+  name = "subversion-0.32.1";
+  system = stdenv.system;
+
+  builder = ./builder.sh;
+  src = fetchurl {
+    url = http://svn.collab.net/tarballs/subversion-0.32.1.tar.gz;
+    md5 = "b06717a8ef50db4b5c4d380af00bd901";
+  };
+
+  localServer = localServer;
+  httpServer = httpServer;
+  sslSupport = sslSupport;
+  swigBindings = swigBindings;
+
+  stdenv = stdenv;
+  openssl = if sslSupport then openssl else null; <co id='ex-svn-nix-co-4' />
+  httpd = if httpServer then httpd else null;
+  expat = expat;
+  db4 = if localServer then db4 else null;
+  swig = if swigBindings then swig else null;
+}
+        </programlisting>
+      </example>
+
+      <para>
+        This example shows several features.  Default parameters <xref
+          linkend='ex-svn-nix-co-1'/> can be used to simplify call sites: if an
+        argument that has a default is omitted, its default value is used.
+      </para>
+
+      <para>
+        You can use <emphasis>assertions</emphasis> to test whether arguments
+        satisfy certain constraints.  The simple assertion <xref
+          linkend='ex-svn-nix-co-2'/> tests whether the
+        <varname>expat</varname> argument is not a null value.  The more
+        complex assertion <xref linkend='ex-svn-nix-co-3'/> says that if
+        Subversion is built with Apache support, then <varname>httpd</varname>
+        (the Apache package) must not be null and it must have been built using
+        the same instance of the <varname>expat</varname> library as was passed
+        to the Subversion expression.  This is since the Subversion code is
+        dynamically linked against the Apache code and they both use Expat,
+        they must be linked against the same instance&mdash;otherwise a
+        conflict might occur. 
+      </para>
+
+    </sect2>
+
+  </sect1>
+
+
+
 </chapter>
 
 <!--