diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index d3514b625..b6f426d66 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -499,6 +499,234 @@ run in parallel. Typically this should be the number of CPUs.
+The generic builder
+
+TODO
+
+
+
+
+
+
+
+
+The Nix expression language
+
+The Nix expression language is a pure, lazy, functional
+language. Purity means that operations in the language don't have
+side-effects (for instance, there is no variable assignment).
+Laziness means that arguments to functions are evaluated only when
+they are needed. Functional means that functions are
+normal
values that can be passed around and
+manipulated in interesting ways.
+
+The language is not a full-featured, general purpose language.
+It's main job is to describe components, compositions of components,
+and the variability within components. For this a functional language
+is perfectly suited.
+
+This section presents the various features of the
+language.
+
+
+Simple values
+
+Nix has the following basic datatypes:
+
+
+
+ Strings, enclosed between
+ double quotes, e.g., "foo bar".
+
+ Integers, e.g.,
+ 123.
+
+ URIs as defined in appendix B
+ of RFC
+ 2396, e.g.,
+ https://svn.cs.uu.nl:12443/dist/trace/trace-nix-trunk.tar.bz2.
+
+ Paths, e.g.,
+ /bin/sh or ./builder.sh.
+ A path must contain at least one slash to be recognised as such; for
+ instance, builder.sh is not a
+ pathIt's parsed as an expression that selects the
+ attribute sh from the variable
+ builder.. If the filename is
+ relative, i.e., if it does not begin with a slash, it is made
+ absolute at parse time relative to the directory of the Nix
+ expression that contained it. For instance, if a Nix expression in
+ /foo/bar/bla.nix refers to
+ ../xyzzy/fnord.nix, the absolutised path is
+ /foo/xyzzy/fnord.nix.
+
+
+
+
+
+
+
+
+Lists
+
+Lists are formed by enclosing a whitespace-separated list of
+values between square bracktes. For example,
+
+
+[ 123 ./foo.nix "abc" (f {x=y;}) ]
+
+defines a list of four elements, the last being the result of a call
+to the function f. Note that function calls have
+to be enclosed in parentheses. If they had been omitted, e.g.,
+
+
+[ 123 ./foo.nix "abc" f {x=y;} ]
+
+the result would be a list of five elements, the fourth one being a
+function and the fifth being an attribute set.
+
+
+
+
+Attribute sets
+
+Attribute sets are really the core of the language, since
+ultimately it's all about creating derivations, which are really just
+sets of attributes to be passed to build scripts.
+
+Attribute sets are just a list of name/value pairs enclosed in
+curly brackets, where each value is an arbitrary expression terminated
+by a semicolon. For example:
+
+
+{ x = 123;
+ text = "Hello";
+ y = f { bla = 456; };
+}
+
+This defines an attribute set with attributes named
+x, test, y.
+The order of the attributes is irrelevant. An attribute name may only
+occur once.
+
+Attributes can be selected from an attribute set using the
+. operator. For instance,
+
+
+{ a = "Foo"; b = "Bar"; }.a
+
+evaluates to "Foo".
+
+
+
+
+Recursive attribute sets
+
+Recursive attribute sets are just normal attribute sets, but the
+attributes can refer to each other. For example,
+
+
+rec {
+ x = y;
+ y = 123;
+}.x
+
+
+evaluates to 123. Note that without
+rec the binding x = y; would
+refer to the variable y in the surrounding scope,
+if one exists, and would be invalid if no such variable exists. That
+is, in a normal (non-recursive) attribute set, attributes are not
+added to the lexical scope; in a recursive set, they are.
+
+Recursive attribute sets of course introduce the danger of
+infinite recursion. For example,
+
+
+rec {
+ x = y;
+ y = x;
+}.x
+
+does not terminateActually, Nix detects infinite
+recursion in this case and aborts (infinite recursion
+encountered
)..
+
+
+
+
+
+
+Lets
+
+TODO
+
+
+
+
+Inheriting attributes
+
+TODO
+
+
+
+
+Functions
+
+TODO
+
+Higher-order functions; map
+
+
+
+
+Conditionals
+
+TODO
+
+
+
+
+<quote>With</quote> expressions
+
+TODO
+
+
+
+
+Operators
+
+TODO
+
+
+
+
+Derivations
+
+TODO
+
+
+
+
+Miscelleneous built-in functions
+
+TODO
+
+
+
+
+
+
+
+
+The standard environment
+
+TODO
+