5 files changed, 60 insertions, 6 deletions
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index e26f9b1af6e5..dc4a5ac874b6 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -11,6 +11,13 @@
     <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>
+      <group choice='req'>
+        <arg choice='plain'><option>--attr</option></arg>
+        <arg choice='plain'><option>-A</option></arg>
+      </group>
+      <replaceable>attrPath</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>
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index 5aa38c81c842..6106d15f4215 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -13,6 +13,13 @@
     <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
     <arg>
       <group choice='req'>
+        <arg choice='plain'><option>--attr</option></arg>
+        <arg choice='plain'><option>-A</option></arg>
+      </group>
+      <replaceable>attrPath</replaceable>
+    </arg>
+    <arg>
+      <group choice='req'>
         <arg choice='plain'><option>--file</option></arg>
         <arg choice='plain'><option>-f</option></arg>
       </group>
@@ -252,7 +259,7 @@ number of possible ways:
 </refsection>
             
 
-<refsection><title>Examples</title>
+<refsection xml:id='refsec-nix-env-install-examples'><title>Examples</title>
 
 <para>To install a specific version of <command>gcc</command> from the
 active Nix expression:
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index aab2049344ea..5f3874308164 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -11,6 +11,13 @@
     <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>
+      <group choice='req'>
+        <arg choice='plain'><option>--attr</option></arg>
+        <arg choice='plain'><option>-A</option></arg>
+      </group>
+      <replaceable>attrPath</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.xml b/doc/manual/opt-common.xml
index d9c29a19e11e..95e8f78d99cc 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -224,8 +224,8 @@
   <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> ?
+  argument has a <link linkend='ss-functions'>default value</link>
+  (e.g., <literal>{<replaceable>argName</replaceable> ?
   <replaceable>defaultValue</replaceable>}:
   <replaceable>...</replaceable></literal>).  With
   <option>--arg</option>, you can also call functions that have
@@ -257,6 +257,32 @@
 </varlistentry>
 
 
+<varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option>
+<replaceable>attrPath</replaceable></term>
+
+  <listitem><para>In <command>nix-env</command>,
+  <command>nix-instantiate</command> and <command>nix-build</command>,
+  <option>--attr</option> allows you to select an attribute from the
+  top-level Nix expression being evaluated.  The <emphasis>attribute
+  path</emphasis> <replaceable>attrPath</replaceable> is a sequence of
+  attribute names separated by dots.  For instance, given a top-level
+  Nix expression <replaceable>e</replaceable>, the attribute path
+  <literal>xorg.xorgserver</literal> would cause the expression
+  <literal><replaceable>e</replaceable>.xorg.xorgserver</literal> to
+  be used.  See <link
+  linkend='refsec-nix-env-install-examples'><command>nix-env
+  --install</command></link> for some concrete examples.</para>
+
+  <para>In addition to attribute names, you can also specify array
+  indices.  For instance, the attribute path
+  <literal>foo.3.bar</literal> selects the <literal>bar</literal>
+  attribute of the fourth element of the array in the
+  <literal>foo</literal> attribute of the top-level
+  expression.</para></listitem>
+
+</varlistentry>
+
+
 </variablelist>
 
 
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index 2294fc69aef3..cf590190ca56 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -428,7 +428,14 @@ lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
 $ ./result/bin/hello
 Hello, world!</screen>
 
-</para>
+The <link linkend='opt-attr'><option>-A</option></link> option selects
+the <literal>hello</literal> attribute from
+<filename>all-packages.nix</filename>.  This is faster than using the
+symbolic package name specified by the <literal>name</literal>
+attribute (which also happens to be <literal>hello</literal>) and is
+unambiguous (there can be multiple packages with the symbolic name
+<literal>hello</literal>, but there can be only one attribute in a set
+named <literal>hello</literal>).</para>
 
 <para><command>nix-build</command> registers the
 <filename>./result</filename> symlink as a garbage collection root, so
@@ -470,8 +477,8 @@ So it is always safe to run multiple instances of Nix in parallel
 
 <para>If you have a system with multiple CPUs, you may want to have
 Nix build different derivations in parallel (insofar as possible).
-Just pass the option <option linkend='opt-max-jobs'>-j
-<replaceable>N</replaceable></option>, where
+Just pass the option <link linkend='opt-max-jobs'><option>-j
+<replaceable>N</replaceable></option></link>, where
 <replaceable>N</replaceable> is the maximum number of jobs to be run
 in parallel, or set.  Typically this should be the number of
 CPUs.</para>