From 99ef620c8c453949719c45229a8bd4f1cd5a66a8 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <e.dolstra@tudelft.nl>
Date: Thu, 5 Oct 2006 20:41:57 +0000
Subject: [PATCH] * Documented nix-instantiate --xml, --strict. * Added an
 example to the nix-build section.

---
 doc/manual/nix-build.xml               | 16 +++++
 doc/manual/nix-instantiate.xml         | 90 ++++++++++++++++++++++++--
 doc/manual/opt-common.xml              |  2 +-
 doc/manual/writing-nix-expressions.xml |  2 +-
 4 files changed, 104 insertions(+), 6 deletions(-)

diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index dc4a5ac87..bb64085f8 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -117,4 +117,20 @@ except for <option>--arg</option> and <option>--attr</option> /
 </refsection>
 
 
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-build pkgs/top-level/all-packages.nix -A firefox
+store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
+/nix/store/d18hyl92g30l...-firefox-1.5.0.7
+
+$ ls -l result
+lrwxrwxrwx  <replaceable>...</replaceable>  result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7
+
+$ ls ./result/bin/
+firefox  firefox-config</screen>
+
+</refsection>
+
+
 </refentry>
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index 5f3874308..71c8d3ec3 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -20,10 +20,16 @@
     </arg>
     <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
     <arg><option>--indirect</option></arg>
-    <group choice='opt'>
-      <arg choice='plain'><option>--parse-only</option></arg>
-      <arg choice='plain'><option>--eval-only</option></arg>
-    </group>
+    <arg>
+      <group choice='req'>
+        <arg choice='plain'><option>--parse-only</option></arg>
+        <arg choice='plain'>
+          <option>--eval-only</option>
+          <arg><option>--strict</option></arg>
+        </arg>
+      </group>
+      <arg><option>--xml</option></arg>
+    </arg>
     <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
@@ -85,6 +91,31 @@ common options.</para>
     
   </varlistentry>
 
+  <varlistentry><term><option>--xml</option></term>
+
+    <listitem><para>When used with <option>--parse-only</option> and
+    <option>--eval-only</option>, print the resulting expression as an
+    XML representation of the abstract syntax tree rather than as an
+    ATerm.  The schema is the same as that used by the <link
+    linkend="builtin-toXML"><function>toXML</function>
+    built-in</link>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--strict</option></term>
+
+    <listitem><para>When used with <option>--eval-only</option>,
+    recursively evaluate list elements and attributes.  Normally, such
+    sub-expressions are left unevaluated (since the Nix expression
+    language is lazy).</para>
+
+    <warning><para>This option can cause non-termination, because lazy
+    data structures can be infinitely large.</para></warning>
+
+    </listitem>
+
+  </varlistentry>
+
 </variablelist>
 
 </refsection>
@@ -92,6 +123,9 @@ common options.</para>
 
 <refsection><title>Examples</title>
 
+<para>Instantiating store derivations from a Nix expression, and
+building them using <command>nix-store</command>:
+
 <screen>
 $ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation>
 /nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
@@ -104,6 +138,54 @@ $ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
 dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
 ...</screen>
 
+</para>
+
+<para>Parsing and evaluating Nix expressions:
+
+<screen>
+$ echo '"foo" + "bar"' | nix-instantiate --parse-only -
+OpPlus(Str("foo"),Str("bar"))
+
+$ echo '"foo" + "bar"' | nix-instantiate --eval-only -
+Str("foobar")
+
+$ echo '"foo" + "bar"' | nix-instantiate --eval-only --xml -
+<![CDATA[<?xml version='1.0' encoding='utf-8'?>
+<expr>
+  <string value="foobar" />
+</expr>]]></screen>
+
+</para>
+
+<para>The difference between non-strict and strict evaluation:
+
+<screen>
+$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml -
+<replaceable>...</replaceable><![CDATA[
+    <attr name="x">
+      <string value="foo" />
+    </attr>
+    <attr name="y">
+      <unevaluated />
+    </attr>]]>
+<replaceable>...</replaceable></screen>
+
+Note that <varname>y</varname> is left unevaluated (the XML
+representation doesn’t attempt to show non-normal forms).
+
+<screen>
+$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict -
+<replaceable>...</replaceable><![CDATA[
+    <attr name="x">
+      <string value="foo" />
+    </attr>
+    <attr name="y">
+      <string value="foo" />
+    </attr>]]>
+<replaceable>...</replaceable></screen>
+
+</para>
+
 </refsection>
 
 
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index 95e8f78d9..1d09fef95 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -286,4 +286,4 @@
 </variablelist>
 
 
-</section>
\ No newline at end of file
+</section>
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index cf590190c..e8d84164e 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -1769,7 +1769,7 @@ in foo</programlisting>
   </varlistentry>
 
   
-  <varlistentry><term><function>builtins.toXML</function> <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-toXML'><term><function>builtins.toXML</function> <replaceable>e</replaceable></term>
 
     <listitem><para>Return a string containing an XML representation
     of <replaceable>e</replaceable>.  The main application for