From 95b49f804456cf532e61478d7f604aed381173d7 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <e.dolstra@tudelft.nl>
Date: Wed, 13 Aug 2003 15:17:57 +0000
Subject: [PATCH] * Manual updates.

---
 doc/manual/book.xml         | 32 ++++++++----
 doc/manual/installation.xml |  9 ++--
 doc/manual/introduction.xml | 98 ++++++++++++++++++++++++++++++++++---
 3 files changed, 120 insertions(+), 19 deletions(-)

diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index eb0475a62..63aaa8a07 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -11,27 +11,41 @@
 <book>
   <title>Nix: The Manual</title>
 
+  <bookinfo>
+    <author>
+      <firstname>Eelco</firstname>
+      <surname>Dolstra</surname>
+    </author>
+    <copyright>
+      <year>2003</year>
+      <holder>Eelco Dolstra</holder>
+    </copyright>
+  </bookinfo>
+
   &introduction;
   &installation;
 
   <chapter>
     <title>A Guided Tour</title>
     <para>
-      Bla bla
-    </para>
-  </chapter>
-
-  <chapter>
-    <title>Fix Language Reference</title>
-    <para>
-      Bla bla
     </para>
   </chapter>
 
   <chapter>
     <title>Nix Syntax and Semantics</title>
     <para>
-      Bla bla
+    </para>
+  </chapter>
+
+  <chapter>
+    <title>Fix Language Reference</title>
+    <para>
+    </para>
+  </chapter>
+
+  <chapter>
+    <title>Writing Builders</title>
+    <para>
     </para>
   </chapter>
 
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 7d8821d47..bec9ebb21 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -26,8 +26,7 @@
     </para>
 
     <screen>
-      $ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk
-      nix</screen>
+$ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk nix</screen>
 
     <para>
       Likewise, specific releases can be obtained from the <ulink
@@ -48,8 +47,10 @@
     </para>
 
     <screen>
-      $ autoreconf -i $ ./configure <replaceable>options...</replaceable> $
-      make $ make install</screen>
+$ autoreconf -i
+$ ./configure <replaceable>options...</replaceable>
+$ make
+$ make install</screen>
 
     <para>
       Currently, the only useful switch for <command>configure</command> is
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index 77a5f917e..974cdedd8 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -15,17 +15,17 @@
       <title>Build management</title>
 
       <para>
-	  Build management tools are used to perform <emphasis>software
+	Build management tools are used to perform <emphasis>software
 	  builds</emphasis>, that is, the construction of derived products such
 	as executable programs from source code.  A commonly used build tool is
 	Make, which is a standard tool on Unix systems. These tools have to
 	deal with several issues:
-	  <itemizedlist>
+	<itemizedlist>
 	  <listitem>
 	    <para>
 	    </para>
 	  </listitem>
-	  </itemizedlist>
+	</itemizedlist>
       </para>
 
     </sect2>
@@ -34,12 +34,12 @@
       <title>Package management</title>
 
       <para>
-	  After software has been built, is must also be
+	After software has been built, is must also be
 	<emphasis>deployed</emphasis> in the intended target environment, e.g.,
 	the user's workstation.  Examples include the Red Hat package manager
 	(RPM), Microsoft's MSI, and so on.  Here also we have to deal with
 	several issues:
-	  <itemizedlist>
+	<itemizedlist>
 	  <listitem>
 	    <para>
 	      The <emphasis>creation</emphasis> of packages from some formal
@@ -60,12 +60,98 @@
 	      the system administrator should be constant, not linear).
 	    </para>
 	  </listitem>
-	  </itemizedlist>
+	</itemizedlist>
       </para>
     </sect2>
 
   </sect1>
 
+
+  <!--######################################################################-->
+
+  <sect1>
+    <title>What Nix can do for you</title>
+
+    <para>
+      Here is a summary of what Nix provides:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+	<para>
+	  <emphasis>Reliable dependencies.</emphasis>
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>
+	  <emphasis>Support for variability.</emphasis>
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>
+	  <emphasis>Transparent source/binary deployment.</emphasis>
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>
+	  <emphasis>Easy configuration duplication.</emphasis>
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>
+	  <emphasis>Automatic storage management.</emphasis>
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>
+	  <emphasis>Atomic upgrades and rollbacks.</emphasis>
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>
+	  <emphasis>Support for many simultaneous configurations.</emphasis>
+	</para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Here is what Nix doesn't yet provide, but will:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+	<para>
+	  <emphasis>Build management.</emphasis>  In principle it is already
+	  possible to do build management using Fix (by writing builders that
+	  perform appropriate build steps), but the Fix language is not yet
+	  powerful enough to make this pleasant.  The <ulink
+	    url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>
+	  should be retargeted to produce Nix expressions, or alternatively,
+	  extend Fix with Maak's semantics and concrete syntax (since Fix needs
+	  a concrete syntax anyway).  Another interesting idea is to write a
+	  <command>make</command> implementation that uses Nix as a back-end to
+	  support <ulink
+	    url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink> 
+	  build files.
+	</para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+
+  <!--######################################################################-->
+
   <sect1>
     <title>The Nix system</title>