From 8a08813d6c92e583d9ed6ccaffc80effe0dc9669 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Fri, 11 May 2012 17:39:06 -0400
Subject: [PATCH] Manual updates

---
 doc/manual/installation.xml            | 38 +++++-----
 doc/manual/introduction.xml            | 42 +++++------
 doc/manual/manual.xml                  |  5 +-
 doc/manual/quick-start.xml             | 17 +++--
 doc/manual/style.css                   |  6 +-
 doc/manual/writing-nix-expressions.xml | 99 ++++++++++++++++++++------
 6 files changed, 132 insertions(+), 75 deletions(-)

diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 5e29abe9f5..959a950ea8 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -15,11 +15,11 @@
   <listitem><para>Linux (particularly on x86, x86_64, and
   PowerPC).</para></listitem>
 
-  <listitem><para>Mac OS X, both on Intel and
-  PowerPC.</para></listitem>
+  <listitem><para>Mac OS X.</para></listitem>
 
   <listitem><para>FreeBSD (only tested on Intel).</para></listitem>
 
+  <!--
   <listitem><para>Windows through <link
   xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
 
@@ -28,6 +28,7 @@
   partition.</para></warning>
 
   </listitem>
+  -->
 
 </itemizedlist>
 
@@ -47,7 +48,7 @@ for Red Hat, SuSE, and Fedora Core are also available.</para>
 
 <para>Alternatively, the most recent sources of Nix can be obtained
 from its <link
-xlink:href="https://github.com/NixOS/nix">git
+xlink:href="https://github.com/NixOS/nix">Git
 repository</link>.  For example, the following command will check out
 the latest revision into a directory called
 <filename>nix</filename>:</para>
@@ -56,8 +57,8 @@ the latest revision into a directory called
 $ git clone https://github.com/NixOS/nix</screen>
 
 <para>Likewise, specific releases can be obtained from the <link
-xlink:href="https://github.com/NixOS/nix/tags">tags
-</link> of the repository.</para>
+xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the
+repository.</para>
 
 </section>
 
@@ -85,9 +86,9 @@ installed, including development headers and libraries.  If your
 distribution does not provide these, you can obtain bzip2 from <link
 xlink:href="http://www.bzip.org/"/>.</para>
 
-<para>Nix requires the SQLite embedded database library.  If your
-distribution does not provide it, please install it from <link
-xlink:href="http://www.sqlite.org/" />.</para>
+<para>Nix requires the SQLite embedded database library, version
+3.6.19 or higher.  If your distribution does not provide it, please
+install it from <link xlink:href="http://www.sqlite.org/" />.</para>
 
 <para>Nix requires the Perl DBI and DBD::SQLite libraries, which are
 available from <link xlink:href="http://search.cpan.org/">CPAN</link>
@@ -109,21 +110,20 @@ xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook XSL
 stylesheets</link> and optionally the <link
 xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
 schemas</link>.  Note that these are only required if you modify the
-manual sources or when you are building from the Subversion
+manual sources or when you are building from the Git
 repository.</para>
 
 <para>To build the parser, very <emphasis>recent</emphasis> versions
 of Bison and Flex are required.  (This is because Nix needs GLR
 support in Bison and reentrancy support in Flex.)  For Bison, you need
 version 2.3 or higher (1.875 does <emphasis>not</emphasis> work),
-which can be obtained from
-the <link xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP
-server</link>.  For Flex, you need version 2.5.33, which is available
-on <link xlink:href="http://lex.sourceforge.net/">SourceForge</link>.
-Slightly older versions may also work, but ancient versions like the
-ubiquitous 2.5.4a won't.  Note that these are only required if you
-modify the parser or when you are building from the Subversion
-repository.</para>
+which can be obtained from the <link
+xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP server</link>.
+For Flex, you need version 2.5.33, which is available on <link
+xlink:href="http://lex.sourceforge.net/">SourceForge</link>.  Slightly
+older versions may also work, but ancient versions like the ubiquitous
+2.5.4a won't.  Note that these are only required if you modify the
+parser or when you are building from the Git repository.</para>
 
 </section>
 
@@ -140,8 +140,8 @@ $ make install</screen>
 
 </para>
 
-<para>When building from the Subversion repository, these should be
-preceded by the command:
+<para>When building from the Git repository, these should be preceded
+by the command:
 
 <screen>
 $ ./bootstrap.sh</screen>
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index bdd71e5c3e..5641d110ba 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -17,10 +17,10 @@ store</emphasis>, usually the directory
 subdirectory such as
 
 <programlisting>
-/nix/store/r8vvq9kq18pz08v249h8my6r9vs7s0n3-firefox-2.0.0.1/
+/nix/store/nlc4z5y1hm8w9s8vm6m1f5hy962xjmp5-firefox-12.0
 </programlisting>
 
-where <literal>r8vvq9kq…</literal> is a unique identifier for the
+where <literal>nlc4z5…</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>
@@ -72,15 +72,14 @@ sounds risky, but it works extremely well.</para>
 
 <simplesect><title>Multi-user support</title>
 
-<para>Starting at version 0.11, Nix has multi-user support.  This
-means that non-privileged users can securely install software.  Each
-user can have a different <emphasis>profile</emphasis>, a set of
-packages in the Nix store that appear in the user’s
-<envar>PATH</envar>.  If a user installs a package that another user
-has already installed previously, the package won’t be built or
-downloaded a second time.  At the same time, it is not possible for
-one user to inject a Trojan horse into a package that might be used by
-another user.</para>
+<para>Nix has multi-user support.  This means that non-privileged
+users can securely install software.  Each user can have a different
+<emphasis>profile</emphasis>, a set of packages in the Nix store that
+appear in the user’s <envar>PATH</envar>.  If a user installs a
+package that another user has already installed previously, the
+package won’t be built or downloaded a second time.  At the same time,
+it is not possible for one user to inject a Trojan horse into a
+package that might be used by another user.</para>
 
 <!--
 <para>More details can be found in Section 3 of our <a
@@ -264,8 +263,10 @@ xlink:href="http://www.cs.uu.nl/wiki/Trace/WebHome">TraCE
 project</link> (2003-2008).  The project was funded by the Software
 Engineering Research Program <link
 xlink:href="http://www.jacquard.nl/">Jacquard</link> to improve the
-support for variability in software systems.  Further funding is now
-provided by the NIRICT LaQuSo Build Farm project.</para>
+support for variability in software systems.  Further funding was
+provided by the NIRICT LaQuSo Build Farm project.  Development is
+currently supported by <link
+xlink:href="http://www.logicblox.com/">LogicBlox</link>.</para>
 
 </section>
 
@@ -275,7 +276,7 @@ provided by the NIRICT LaQuSo Build Farm project.</para>
 <para>This manual tells you how to install and use Nix and how to
 write Nix expressions for software not already in the Nix Packages
 collection.  It also discusses some advanced topics, such as setting
-up a Nix-based build farm.</para>
+up distributed multi-platform building.</para>
 
 </section>
 
@@ -315,13 +316,12 @@ Upgrading in a Purely Functional Component Deployment Model
 paper <citetitle
 xlink:href='http://www.st.ewi.tudelft.nl/~dolstra/pubs/servicecm-scm12-final.pdf'>
 Service Configuration Management</citetitle> shows how services (e.g.,
-web servers) can be deployed and managed through Nix.  A short
-overview of NixOS is given in the HotOS XI paper <citetitle
-xlink:href="http://www.st.ewi.tudelft.nl/~dolstra/pubs/hotos-final.pdf">Purely
-Functional System Configuration Management</citetitle>.  The Nix
-homepage has <link
-xlink:href="http://nixos.org/docs/papers.html">an up-to-date list
-of Nix-related papers</link>.</para>
+web servers) can be deployed and managed through Nix.  An overview of
+NixOS is given in the JFP article <citetitle
+xlink:href="http://www.st.ewi.tudelft.nl/~dolstra/pubs/nixos-jfp-final.pdf">NixOS:
+A Purely Functional Linux Distribution</citetitle>.  The Nix homepage
+has <link xlink:href="http://nixos.org/docs/papers.html">an up-to-date
+list of Nix-related papers</link>.</para>
 
 <para>Nix is the subject of Eelco Dolstra’s PhD thesis <citetitle
 xlink:href="http://igitur-archive.library.uu.nl/dissertations/2006-0118-200031/index.htm">The
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index fa80a3651d..95fbe7d904 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -5,8 +5,7 @@
 
     <title>Nix User's Guide</title>
 
-    <subtitle>Draft (Version <xi:include href="version.txt"
-    parse="text" />)</subtitle>
+    <edition>Version <xi:include href="version.txt" parse="text" /></edition>
 
     <author>
       <personname>
@@ -24,7 +23,7 @@
       <holder>Eelco Dolstra</holder>
     </copyright>
 
-    <date>January 2012</date>
+    <date>May 2012</date>
     
   </info>
 
diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start.xml
index d2431151f3..bc43dea618 100644
--- a/doc/manual/quick-start.xml
+++ b/doc/manual/quick-start.xml
@@ -11,9 +11,9 @@ to the following chapters.</para>
 
 <orderedlist>
 
-<listitem><para>Download a source tarball, RPM or Deb from <link
-xlink:href='http://nixos.org/'/>.  Build source distributions using
-the regular sequence:
+<listitem><para>Download a source tarball or RPM or Debian/Ubuntu
+package from <link xlink:href='http://nixos.org/'/>.  Build source
+distributions using the regular sequence:
         
 <screen>
 $ tar xvfj nix-<replaceable>version</replaceable>.tar.bz2
@@ -41,8 +41,7 @@ file).</para></listitem>
 <listitem><para>Subscribe to the Nix Packages channel.
 
 <screen>
-$ nix-channel --add \
-    http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable</screen>
+$ nix-channel --add http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable</screen>
 
 </para></listitem>
 
@@ -108,10 +107,10 @@ numbers).</para></listitem>
 
 <listitem><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
-<filename>/nix/bin/nix-install-package</filename>.  A window should
+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></listitem>
diff --git a/doc/manual/style.css b/doc/manual/style.css
index fe2471eaab..ac76a64bbb 100644
--- a/doc/manual/style.css
+++ b/doc/manual/style.css
@@ -234,7 +234,6 @@ div.glosslist dt
 
 span.command strong
 {
-    font-family: monospace;
     font-weight: normal;
     color: #400000;
 }
@@ -249,3 +248,8 @@ table
     border-collapse: collapse;
     box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
 }
+
+div.affiliation
+{
+    font-style: italic;
+}
\ No newline at end of file
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index 310dd5ae0e..3c2d06eec4 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -11,6 +11,13 @@ the things that tell Nix how to build packages.  It starts with a
 simple example (a Nix expression for GNU Hello), and then moves
 on to a more in-depth look at the Nix expression language.</para>
 
+<note><para>This chapter is mostly about the Nix expression language.
+For more extensive information on adding packages to the Nix Packages
+collection (such as functions in the standard environment and coding
+conventions), please consult <link
+xlink:href="http://hydra.nixos.org/job/nixpkgs/trunk/tarball/latest/download-by-type/doc/manual">its
+manual</link>.</para></note>
+
 
 <section><title>A simple Nix expression</title>
 
@@ -315,15 +322,15 @@ error check.</para>
 
 rec { <co xml:id='ex-hello-composition-co-1' />
   
-  hello = (import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' />) { <co xml:id='ex-hello-composition-co-3' />
+  hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' />
     inherit fetchurl stdenv perl;
   };
 
-  perl = (import ../development/interpreters/perl) { <co xml:id='ex-hello-composition-co-4' />
+  perl = import ../development/interpreters/perl { <co xml:id='ex-hello-composition-co-4' />
     inherit fetchurl stdenv;
   };
 
-  fetchurl = (import ../build-support/fetchurl) { 
+  fetchurl = import ../build-support/fetchurl { 
     inherit stdenv; ...
   };
   
@@ -390,6 +397,23 @@ some fragments of
     <varname>stdenv.mkDerivation</varname> in <xref
     linkend='ex-hello-nix' />).</para>
 
+    <note><para>Nixpkgs has a convenience function
+    <function>callPackage</function> that imports and calls a
+    function, filling in any missing arguments by passing the
+    corresponding attribute from the Nixpkgs set, like this:
+
+<programlisting>
+hello = callPackage ../applications/misc/hello/ex-1 { };
+</programlisting>
+
+    If necessary, you can set or override arguments:
+
+<programlisting>
+hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
+</programlisting>
+
+    </para></note>
+
   </callout>
 
   <callout arearefs='ex-hello-composition-co-4'>
@@ -813,7 +837,23 @@ occur once.</para>
 <programlisting>
 { a = "Foo"; b = "Bar"; }.a</programlisting>
 
-evaluates to <literal>"Foo"</literal>.</para>
+evaluates to <literal>"Foo"</literal>.  It is possible to provide a
+default value in an attribute selection using the
+<literal>or</literal> keyword.  For example,
+
+<programlisting>
+{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting>
+
+will evaluate to <literal>"Xyzzy"</literal> because there is no
+<varname>c</varname> attribute in the set.</para>
+
+<para>You can use arbitrary string constants as attribute names by
+enclosing them in quotes:
+
+<programlisting>
+{ "foo bar" = 123; "nix-1.0" = 456; }."foo bar" </programlisting>
+
+This will evaluate to <literal>123</literal>.</para>
 
 </simplesect>
 
@@ -1189,12 +1229,17 @@ weakest binding).</para>
     </thead>
     <tbody>
       <row>
-        <entry><replaceable>e</replaceable> .
-        <replaceable>id</replaceable></entry>
+        <entry><replaceable>e</replaceable> <literal>.</literal>
+        <replaceable>attrpath</replaceable>
+        [ <literal>or</literal> <replaceable>def</replaceable> ]
+        </entry>
         <entry>none</entry>
-        <entry>Select attribute named <replaceable>id</replaceable>
-        from attribute set <replaceable>e</replaceable>.  Abort
-        evaluation if the attribute doesn’t exist.</entry>
+        <entry>Select attribute denoted by the attribute path
+        <replaceable>attrpath</replaceable> from attribute set
+        <replaceable>e</replaceable>.  (An attribute path is a
+        dot-separated list of attribute names.)  If the attribute
+        doesn’t exist, return <replaceable>def</replaceable> if
+        provided, otherwise abort evaluation.</entry>
       </row>
       <row>
         <entry><replaceable>e1</replaceable> <replaceable>e2</replaceable></entry>
@@ -1203,31 +1248,31 @@ weakest binding).</para>
         argument <replaceable>e2</replaceable>.</entry>
       </row>
       <row>
-        <entry><replaceable>e</replaceable> ?
-        <replaceable>id</replaceable></entry>
+        <entry><replaceable>e</replaceable> <literal>?</literal>
+        <replaceable>attrpath</replaceable></entry>
         <entry>none</entry>
         <entry>Test whether attribute set <replaceable>e</replaceable>
-        contains an attribute named <replaceable>id</replaceable>;
+        contains the attribute denoted by <replaceable>attrpath</replaceable>;
         return <literal>true</literal> or
         <literal>false</literal>.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> ++ <replaceable>e2</replaceable></entry>
+        <entry><replaceable>e1</replaceable> <literal>++</literal> <replaceable>e2</replaceable></entry>
         <entry>right</entry>
         <entry>List concatenation.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> + <replaceable>e2</replaceable></entry>
+        <entry><replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable></entry>
         <entry>left</entry>
         <entry>String or path concatenation.</entry>
       </row>
       <row>
-        <entry>! <replaceable>e</replaceable></entry>
+        <entry><literal>!</literal> <replaceable>e</replaceable></entry>
         <entry>left</entry>
         <entry>Boolean negation.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> //
+        <entry><replaceable>e1</replaceable> <literal>//</literal>
         <replaceable>e2</replaceable></entry>
         <entry>right</entry>
         <entry>Return an attribute set consisting of the attributes in
@@ -1236,31 +1281,31 @@ weakest binding).</para>
         precedence over the former in case of equally named attributes).</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> ==
+        <entry><replaceable>e1</replaceable> <literal>==</literal>
         <replaceable>e2</replaceable></entry>
         <entry>none</entry>
         <entry>Equality.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> !=
+        <entry><replaceable>e1</replaceable> <literal>!=</literal>
         <replaceable>e2</replaceable></entry>
         <entry>none</entry>
         <entry>Inequality.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> &amp;&amp;
+        <entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
         <replaceable>e2</replaceable></entry>
         <entry>left</entry>
         <entry>Logical AND.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> ||
+        <entry><replaceable>e1</replaceable> <literal>||</literal>
         <replaceable>e2</replaceable></entry>
         <entry>left</entry>
         <entry>Logical OR.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> ->
+        <entry><replaceable>e1</replaceable> <literal>-></literal>
         <replaceable>e2</replaceable></entry>
         <entry>none</entry>
         <entry>Logical implication (equivalent to
@@ -1662,7 +1707,17 @@ impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ];
   </varlistentry>
 
   
-  
+  <varlistentry><term><varname>preferLocalBuild</varname></term>
+
+    <listitem><para>If this attribute is set to
+    <literal>true</literal> and <link
+    linkend="chap-distributed-builds">distributed building is
+    enabled</link>, then, if possible, perform this build locally
+    instead of forwarding it to a remote machine.  This is appropriate
+    for trivial builders where the cost of doing a remote build would
+    exceed the cost of building locally.</para></listitem>
+
+  </varlistentry>
 
 </variablelist>