From 07294e988cc54f1c2570c567662cf39eabbd610c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niklas=20Hamb=C3=BCchen?= <mail@nh2.me>
Date: Sun, 10 Nov 2019 17:29:13 +0100
Subject: [PATCH] manual: nix-shell: Elaborate on using `-p` with expressions.

This documents the outcome of the change in
https://github.com/NixOS/nix/issues/454:

> We can also automatically add parentheses in the generated
> `buildInputs`, so you can type `nix-shell -p "expr"`
> instead of `"(expr").
---
 doc/manual/command-ref/nix-shell.xml  | 24 +++++++++++++++++++-----
 doc/manual/command-ref/opt-common.xml |  9 ++++++++-
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml
index bb4a4e420..766482460 100644
--- a/doc/manual/command-ref/nix-shell.xml
+++ b/doc/manual/command-ref/nix-shell.xml
@@ -39,7 +39,12 @@
           <arg choice='plain'><option>--packages</option></arg>
           <arg choice='plain'><option>-p</option></arg>
         </group>
-        <arg choice='plain' rep='repeat'><replaceable>packages</replaceable></arg>
+        <arg choice='plain' rep='repeat'>
+          <group choice='req'>
+            <arg choice="plain"><replaceable>packages</replaceable></arg>
+            <arg choice="plain"><replaceable>expressions</replaceable></arg>
+          </group>
+        </arg>
       </arg>
       <arg><replaceable>path</replaceable></arg>
     </group>
@@ -189,8 +194,8 @@ also <xref linkend="sec-common-options" />.</phrase></para>
 <variablelist>
 
   <varlistentry><term><envar>NIX_BUILD_SHELL</envar></term>
-    
-    <listitem><para>Shell used to start the interactive environment. 
+
+    <listitem><para>Shell used to start the interactive environment.
     Defaults to the <command>bash</command> found in <envar>PATH</envar>.</para></listitem>
 
   </varlistentry>
@@ -222,8 +227,9 @@ $ nix-shell '&lt;nixpkgs>' -A pan --pure \
     --command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
 </screen>
 
-Nix expressions can also be given on the command line.  For instance,
-the following starts a shell containing the packages
+Nix expressions can also be given on the command line using the
+<command>-E</command> and <command>-p</command> flags.
+For instance, the following starts a shell containing the packages
 <literal>sqlite</literal> and <literal>libX11</literal>:
 
 <screen>
@@ -238,6 +244,14 @@ $ nix-shell -p sqlite xorg.libX11
 … -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
 </screen>
 
+Note that <command>-p</command> accepts multiple full nix expressions that
+are valid in the <literal>buildInputs = [ ... ]</literal> shown above,
+not only package names. So the following is also legal:
+
+<screen>
+$ nix-shell -p sqlite 'git.override { withManual = false; }'
+</screen>
+
 The <command>-p</command> flag looks up Nixpkgs in the Nix search
 path. You can override it by passing <option>-I</option> or setting
 <envar>NIX_PATH</envar>. For example, the following gives you a shell
diff --git a/doc/manual/command-ref/opt-common.xml b/doc/manual/command-ref/opt-common.xml
index 6a8107be9..0383bfaed 100644
--- a/doc/manual/command-ref/opt-common.xml
+++ b/doc/manual/command-ref/opt-common.xml
@@ -323,7 +323,14 @@
   Nix expressions to be parsed and evaluated, rather than as a list
   of file names of Nix expressions.
   (<command>nix-instantiate</command>, <command>nix-build</command>
-  and <command>nix-shell</command> only.)</para></listitem>
+  and <command>nix-shell</command> only.)</para>
+
+  <para>For <command>nix-shell</command>, this option is commonly used
+  to give you a shell in which you can build the packages returned
+  by the expression. If you want to get a shell which contain the
+  <emphasis>built</emphasis> packages ready for use, give your
+  expression to the <command>nix-shell -p</command> convenience flag
+  instead.</para></listitem>
 
 </varlistentry>