Restructuring the Nix manual

1 files changed, 0 insertions, 200 deletions

diff --git a/doc/manual/nix-shell.xml b/doc/manual/nix-shell.xml
deleted file mode 100644
index d5f70a9e6..000000000
--- a/doc/manual/nix-shell.xml
+++ /dev/null
@@ -1,200 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-shell">
-
-<refmeta>
-  <refentrytitle>nix-shell</refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>nix-shell</refname>
-  <refpurpose>start an interactive shell based on a Nix expression</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-  <cmdsynopsis>
-    <command>nix-shell</command>
-    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
-    <arg><option>--argstr</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>--command</option> <replaceable>cmd</replaceable></arg>
-    <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
-    <arg><option>--pure</option></arg>
-    <group choice='req'>
-      <group choice='plain'>
-        <group>
-          <arg choice='plain'><option>--packages</option></arg>
-          <arg choice='plain'><option>-p</option></arg>
-        </group>
-        <replaceable>packages</replaceable>
-      </group>
-      <arg><replaceable>path</replaceable></arg>
-    </group>
-  </cmdsynopsis>
-</refsynopsisdiv>
-
-<refsection><title>Description</title>
-
-<para>The command <command>nix-shell</command> will build the
-dependencies of the specified derivation, but not the derivation
-itself.  It will then start an interactive shell in which all
-environment variables defined by the derivation
-<replaceable>path</replaceable> have been set to their corresponding
-values, and the script <literal>$stdenv/setup</literal> has been
-sourced.  This is useful for reproducing the environment of a
-derivation for development.</para>
-
-<para>If <replaceable>path</replaceable> is not given,
-<command>nix-shell</command> defaults to
-<filename>shell.nix</filename> if it exists, and
-<filename>default.nix</filename> otherwise.</para>
-
-<para>If the derivation defines the variable
-<varname>shellHook</varname>, it will be evaluated after
-<literal>$stdenv/setup</literal> has been sourced.  Since this hook is
-not executed by regular Nix builds, it allows you to perform
-initialisation specific to <command>nix-shell</command>.  For example,
-the derivation attribute
-
-<programlisting>
-shellHook =
-  ''
-    echo "Hello shell"
-  '';
-</programlisting>
-
-will cause <command>nix-shell</command> to print <literal>Hello shell</literal>.</para>
-
-</refsection>
-
-
-<refsection><title>Options</title>
-
-<para>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>.  <phrase condition="manual">See
-also <xref linkend="sec-common-options" />.</phrase></para>
-
-<variablelist>
-
-  <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
-
-    <listitem><para>In the environment of the derivation, run the
-    shell command <replaceable>cmd</replaceable> instead of starting
-    an interactive shell.  However, if you end the shell command with
-    <literal>return</literal>, you still get an interactive shell.
-    This can be useful for doing any additional
-    initialisation.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term>
-
-    <listitem><para>Do not build any dependencies whose store path
-    matches the regular expression <replaceable>regexp</replaceable>.
-    This option may be specified multiple times.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--pure</option></term>
-
-    <listitem><para>If this flag is specified, the environment is
-    almost entirely cleared before the interactive shell is started,
-    so you get an environment that more closely corresponds to the
-    “real” Nix build.  A few variables, in particular
-    <envar>HOME</envar>, <envar>USER</envar> and
-    <envar>DISPLAY</envar>, are retained.  Note that
-    <filename>~/.bashrc</filename> and (depending on your Bash
-    installation) <filename>/etc/bashrc</filename> are still sourced,
-    so any variables set there will affect the interactive
-    shell.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--packages</option> / <option>-p</option></term>
-
-    <listitem><para>Set up an environment in which the specified
-    packages are present.  The command line arguments are interpreted
-    as attribute names inside the Nix Packages collection.  Thus,
-    <literal>nix-shell -p libjpeg openjdk</literal> will start a shell
-    in which the packages denoted by the attribute names
-    <varname>libjpeg</varname> and <varname>openjdk</varname> are
-    present.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-<para>The following common options are supported:</para>
-
-<variablelist condition="manpage">
-  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
-</variablelist>
-
-</refsection>
-
-
-<refsection><title>Examples</title>
-
-<para>To build the dependencies of the package Pan, and start an
-interactive shell in which to build it:
-
-<screen>
-$ nix-shell '&lt;nixpkgs>' -A pan
-[nix-shell]$ unpackPhase
-[nix-shell]$ cd pan-*
-[nix-shell]$ configurePhase
-[nix-shell]$ buildPhase
-[nix-shell]$ ./pan/gui/pan
-</screen>
-
-To clear the environment first, and do some additional automatic
-initialisation of the interactive shell:
-
-<screen>
-$ 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
-<literal>sqlite</literal> and <literal>libX11</literal>:
-
-<screen>
-$ nix-shell -E 'with import &lt;nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
-</screen>
-
-A shorter way to do the same is:
-
-<screen>
-$ nix-shell -p sqlite xorg.libX11
-[nix-shell]$ echo $NIX_LDFLAGS
-… -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
-</screen>
-
-</para>
-
-</refsection>
-
-
-<refsection condition="manpage"><title>Environment variables</title>
-
-<variablelist>
-  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
-</variablelist>
-
-</refsection>
-
-
-</refentry>