6 files changed, 53 insertions, 15 deletions
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index 5ec6237b033b..e26f9b1af6e5 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -9,6 +9,8 @@
 <refsynopsisdiv>
   <cmdsynopsis>
     <command>nix-build</command>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
+    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
     <arg><option>--add-drv-link</option></arg>
     <arg><option>--drv-link </option><replaceable>drvlink</replaceable></arg>
     <arg><option>--no-out-link</option></arg>
@@ -56,6 +58,12 @@ or renamed.  So don’t rename the symlink.</para></warning>
 
 <refsection><title>Options</title>
 
+<para>See also <xref linkend="sec-common-options" />.  All options not
+listed here are passed to <command>nix-store --realise</command>,
+except for <option>--arg</option> and <option>--attr</option> /
+<option>-A</option> which are passed to
+<command>nix-instantiate</command>.</para>
+
 <variablelist>
 
   <varlistentry><term><option>--add-drv-link</option></term>
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index ee228f37425e..5aa38c81c842 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -10,6 +10,7 @@
   <cmdsynopsis>
     <command>nix-env</command>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
+    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
     <arg>
       <group choice='req'>
         <arg choice='plain'><option>--file</option></arg>
@@ -24,7 +25,6 @@
       </group>
       <replaceable>path</replaceable>
     </arg>
-    <arg><option>--preserve-installed</option></arg>
     <arg>
       <arg choice='plain'><option>--system-filter</option></arg>
       <replaceable>system</replaceable>
@@ -106,19 +106,6 @@ linkend="sec-common-options" />.</para>
     
   </varlistentry>
       
-  <varlistentry><term><option>--preserve-installed</option></term>
-  
-    <listitem><para>By default, when you install a derivation with the
-    <option>--install</option> operation, it will replace previously
-    installed versions with the same derivation name (regardless of
-    the version number).  This option causes those previously
-    installed versions to be kept in the new generation of the
-    profile.  Note that this will generally cause conflicts in the
-    creation of the user environment (since multiple versions of a
-    package typically contain the same programs).</para></listitem>
-    
-  </varlistentry>
-      
   <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term>
   
     <listitem><para>By default, operations such as <option>--query
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index 230f03682523..aab2049344ea 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -10,6 +10,7 @@
   <cmdsynopsis>
     <command>nix-instantiate</command>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
+    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
     <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
     <arg><option>--indirect</option></arg>
     <group choice='opt'>
diff --git a/doc/manual/opt-common-syn.xml b/doc/manual/opt-common-syn.xml
index 8fa66e9becc4..2e02d0038b18 100644
--- a/doc/manual/opt-common-syn.xml
+++ b/doc/manual/opt-common-syn.xml
@@ -20,5 +20,6 @@
 <arg><option>--fallback</option></arg>
 <arg><option>--readonly-mode</option></arg>
 <arg><option>--log-type</option> <replaceable>type</replaceable></arg>
+<sbr />
 
 </nop>
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index 04cda15310fb..d9c29a19e11e 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -217,6 +217,46 @@
 </varlistentry>
 
 
+<varlistentry><term><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
+
+  <listitem><para>This option is accepted by
+  <command>nix-env</command>, <command>nix-instantiate</command> and
+  <command>nix-build</command>.  When evaluating Nix expressions, the
+  expression evaluator will automatically try to call functions that
+  it encounters.  It can automatically call functions for which every
+  argument has a default value (e.g.,
+  <literal>{<replaceable>argName</replaceable> ?
+  <replaceable>defaultValue</replaceable>}:
+  <replaceable>...</replaceable></literal>).  With
+  <option>--arg</option>, you can also call functions that have
+  arguments without a default value (or override a default value).
+  That is, if the evaluator encounters a function with an argument
+  named <replaceable>name</replaceable>, it will call it with value
+  <replaceable>value</replaceable>.</para>
+
+  <para>For instance, the file
+  <literal>pkgs/top-level/all-packages.nix</literal> in Nixpkgs is
+  actually a function:
+
+<programlisting>
+{ # The system (e.g., `i686-linux') for which to build the packages.
+  system ? __currentSystem
+  <replaceable>...</replaceable>
+}: <replaceable>...</replaceable></programlisting>
+
+  So if you call this Nix expression (e.g., when you do
+  <literal>nix-env -i <replaceable>pkgname</replaceable></literal>),
+  the function will be called automatically using the value <link
+  linkend='builtin-currentSystem'><literal>__currentSystem</literal></link>
+  for the <literal>system</literal> argument.  You can override this
+  using <option>--arg</option>, e.g., <literal>nix-env -i
+  <replaceable>pkgname</replaceable> --arg system
+  \"i686-freebsd\"</literal>.  (Note that since the argument is a Nix
+  string literal, you have to escape the quotes.)</para></listitem>
+
+</varlistentry>
+
+
 </variablelist>
 
 
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index 41b1723105f1..2294fc69aef3 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -1387,7 +1387,8 @@ if builtins ? getEnv then __getEnv "PATH" else ""</programlisting>
   </varlistentry>
 
   
-  <varlistentry><term><varname>currentSystem</varname></term>
+  <varlistentry
+  xml:id='builtin-currentSystem'><term><varname>builtins.currentSystem</varname></term>
 
     <listitem><para>The built-in value <varname>currentSystem</varname>
     evaluates to the Nix platform identifier for the Nix installation