diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml
index c1b172b70..77dd32653 100644
--- a/doc/manual/command-ref/nix-shell.xml
+++ b/doc/manual/command-ref/nix-shell.xml
@@ -149,6 +149,15 @@ also .
+ interpreter
+
+ The chained script interpreter to be invoked by
+ nix-shell. Only applicable in
+ #!-scripts (described below).
+
+
+
The following common options are supported:
@@ -203,6 +212,121 @@ $ nix-shell -p sqlite xorg.libX11
+Use as a <literal>#!</literal>-interpreter
+
+You can use nix-shell as a script interpreter
+to allow scripts written in arbitrary languages to obtain their own
+dependencies via Nix. This is done by starting the script with the
+following lines:
+
+
+#! /usr/bin/env nix-shell
+#! nix-shell -i real-interpreter -p packages
+
+
+where real-interpreter is the “real” script
+interpreter that will be invoked by nix-shell after
+it has obtained the dependencies and initialised the environment, and
+packages are the attribute names of the
+dependencies in Nixpkgs.
+
+The lines starting with #! nix-shell specify
+nix-shell options (see above). Note that you cannot
+write #1 /usr/bin/env nix-shell -i ... because
+/usr/bin/env does not support passing options to
+the interpreter.
+
+For example, here is a Python script that depends on Python and
+the prettytable package:
+
+
+#! /usr/bin/env nix-shell
+#! nix-shell -i python -p python pythonPackages.prettytable
+
+import prettytable
+
+# Print a simple table.
+t = prettytable.PrettyTable(["N", "N^2"])
+for n in range(1, 10): t.add_row([n, n * n])
+print t
+
+
+
+
+Similarly, the following is a Perl script that specifies that it
+requires Perl and the HTML::TokeParser::Simple and
+LWP packages:
+
+
+#! /usr/bin/env nix-shell
+#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
+
+use HTML::TokeParser::Simple;
+
+# Fetch nixos.org and print all hrefs.
+my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
+
+while (my $token = $p->get_tag("a")) {
+ my $href = $token->get_attr("href");
+ print "$href\n" if $href;
+}
+
+
+
+
+Finally, the following Haskell script uses a specific branch of
+Nixpkgs/NixOS (the 14.12 stable branch):
+
+
+
+If you want to be even more precise, you can specify a specific
+revision of Nixpkgs:
+
+
+#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz
+
+
+
+
+The examples above all used to get
+dependencies from Nixpkgs. You can also use a Nix expression to build
+your own dependencies. For example, the Python example could have been
+written as:
+
+
+#! /usr/bin/env nix-shell
+#! nix-shell deps.nix -i python
+
+
+where the file deps.nix in the same directory
+as the #!-script contains:
+
+
+with import <nixpkgs> {};
+
+runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
+
+
+
+
+
+
+
Environment variables