nixpkgs manual: split languages into separate files

There's no change in content except for amending the title of the
section to mention "frameworks", as e.g. I don't consider Qt a language,
and it's likely there will be more of similar cases in future.

To be certain, I checked diff of the generated HTMLs.

12 files changed, 1094 insertions, 1051 deletions

diff --git a/doc/default.nix b/doc/default.nix
index b8dac00eb65..cca68014b0d 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -1,10 +1,12 @@
 with import ./.. { };
 with lib;
-
+let
+  sources = sourceFilesBySuffices ./. [".xml"];
+  sources-langs = ./languages-frameworks;
+in
 stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
-  sources = sourceFilesBySuffices ./. [".xml"];
 
   buildInputs = [ pandoc libxml2 libxslt ];
 
@@ -35,7 +37,9 @@ stdenv.mkDerivation {
       echo "</chapter>"
     } >haskell-users-guide.xml
 
-    ln -s "$sources/"*.xml .
+    ln -s '${sources}/'*.xml .
+    mkdir ./languages-frameworks
+    cp -s '${sources-langs}'/* ./languages-frameworks
 
     echo ${nixpkgsVersion} > .version
 
diff --git a/doc/language-support.xml b/doc/language-support.xml
deleted file mode 100644
index f0d5dbd3e64..00000000000
--- a/doc/language-support.xml
+++ /dev/null
@@ -1,1047 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-language-support">
-
-<title>Support for specific programming languages</title>
-
-<para>The <link linkend="chap-stdenv">standard build
-environment</link> makes it easy to build typical Autotools-based
-packages with very little code.  Any other kind of package can be
-accomodated by overriding the appropriate phases of
-<literal>stdenv</literal>.  However, there are specialised functions
-in Nixpkgs to easily build packages for other programming languages,
-such as Perl or Haskell.  These are described in this chapter.</para>
-
-
-<section xml:id="sec-language-perl"><title>Perl</title>
-
-<para>Nixpkgs provides a function <varname>buildPerlPackage</varname>,
-a generic package builder function for any Perl package that has a
-standard <varname>Makefile.PL</varname>.  It’s implemented in <link
-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.</para>
-
-<para>Perl packages from CPAN are defined in <link
-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>,
-rather than <filename>pkgs/all-packages.nix</filename>.  Most Perl
-packages are so straight-forward to build that they are defined here
-directly, rather than having a separate function for each package
-called from <filename>perl-packages.nix</filename>.  However, more
-complicated packages should be put in a separate file, typically in
-<filename>pkgs/development/perl-modules</filename>.  Here is an
-example of the former:
-
-<programlisting>
-ClassC3 = buildPerlPackage rec {
-  name = "Class-C3-0.21";
-  src = fetchurl {
-    url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
-    sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
-  };
-};
-</programlisting>
-
-Note the use of <literal>mirror://cpan/</literal>, and the
-<literal>${name}</literal> in the URL definition to ensure that the
-name attribute is consistent with the source that we’re actually
-downloading.  Perl packages are made available in
-<filename>all-packages.nix</filename> through the variable
-<varname>perlPackages</varname>.  For instance, if you have a package
-that needs <varname>ClassC3</varname>, you would typically write
-
-<programlisting>
-foo = import ../path/to/foo.nix {
-  inherit stdenv fetchurl ...;
-  inherit (perlPackages) ClassC3;
-};
-</programlisting>
-
-in <filename>all-packages.nix</filename>.  You can test building a
-Perl package as follows:
-
-<screen>
-$ nix-build -A perlPackages.ClassC3
-</screen>
-
-<varname>buildPerlPackage</varname> adds <literal>perl-</literal> to
-the start of the name attribute, so the package above is actually
-called <literal>perl-Class-C3-0.21</literal>.  So to install it, you
-can say:
-
-<screen>
-$ nix-env -i perl-Class-C3
-</screen>
-
-(Of course you can also install using the attribute name:
-<literal>nix-env -i -A perlPackages.ClassC3</literal>.)</para>
-
-<para>So what does <varname>buildPerlPackage</varname> do?  It does
-the following:
-
-<orderedlist>
-
-  <listitem><para>In the configure phase, it calls <literal>perl
-  Makefile.PL</literal> to generate a Makefile.  You can set the
-  variable <varname>makeMakerFlags</varname> to pass flags to
-  <filename>Makefile.PL</filename></para></listitem>
-
-  <listitem><para>It adds the contents of the <envar>PERL5LIB</envar>
-  environment variable to <literal>#! .../bin/perl</literal> line of
-  Perl scripts as <literal>-I<replaceable>dir</replaceable></literal>
-  flags.  This ensures that a script can find its
-  dependencies.</para></listitem>
-
-  <listitem><para>In the fixup phase, it writes the propagated build
-  inputs (<varname>propagatedBuildInputs</varname>) to the file
-  <filename>$out/nix-support/propagated-user-env-packages</filename>.
-  <command>nix-env</command> recursively installs all packages listed
-  in this file when you install a package that has it.  This ensures
-  that a Perl package can find its dependencies.</para></listitem>
-
-</orderedlist>
-
-</para>
-
-<para><varname>buildPerlPackage</varname> is built on top of
-<varname>stdenv</varname>, so everything can be customised in the
-usual way.  For instance, the <literal>BerkeleyDB</literal> module has
-a <varname>preConfigure</varname> hook to generate a configuration
-file used by <filename>Makefile.PL</filename>:
-
-<programlisting>
-{ buildPerlPackage, fetchurl, db }:
-
-buildPerlPackage rec {
-  name = "BerkeleyDB-0.36";
-
-  src = fetchurl {
-    url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
-    sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
-  };
-
-  preConfigure = ''
-    echo "LIB = ${db}/lib" > config.in
-    echo "INCLUDE = ${db}/include" >> config.in
-  '';
-}
-</programlisting>
-
-</para>
-
-<para>Dependencies on other Perl packages can be specified in the
-<varname>buildInputs</varname> and
-<varname>propagatedBuildInputs</varname> attributes.  If something is
-exclusively a build-time dependency, use
-<varname>buildInputs</varname>; if it’s (also) a runtime dependency,
-use <varname>propagatedBuildInputs</varname>.  For instance, this
-builds a Perl module that has runtime dependencies on a bunch of other
-modules:
-
-<programlisting>
-ClassC3Componentised = buildPerlPackage rec {
-  name = "Class-C3-Componentised-1.0004";
-  src = fetchurl {
-    url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
-    sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
-  };
-  propagatedBuildInputs = [
-    ClassC3 ClassInspector TestException MROCompat
-  ];
-};
-</programlisting>
-
-</para>
-
-<section xml:id="ssec-generation-from-CPAN"><title>Generation from CPAN</title>
-
-<para>Nix expressions for Perl packages can be generated (almost)
-automatically from CPAN.  This is done by the program
-<command>nix-generate-from-cpan</command>, which can be installed
-as follows:</para>
-
-<screen>
-$ nix-env -i nix-generate-from-cpan
-</screen>
-
-<para>This program takes a Perl module name, looks it up on CPAN,
-fetches and unpacks the corresponding package, and prints a Nix
-expression on standard output.  For example:
-
-<screen>
-$ nix-generate-from-cpan XML::Simple
-  XMLSimple = buildPerlPackage {
-    name = "XML-Simple-2.20";
-    src = fetchurl {
-      url = mirror://cpan/authors/id/G/GR/GRANTM/XML-Simple-2.20.tar.gz;
-      sha256 = "5cff13d0802792da1eb45895ce1be461903d98ec97c9c953bc8406af7294434a";
-    };
-    propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
-    meta = {
-      description = "Easily read/write XML (esp config files)";
-      license = "perl";
-    };
-  };
-</screen>
-
-The output can be pasted into
-<filename>pkgs/top-level/perl-packages.nix</filename> or wherever else
-you need it.</para>
-
-</section>
-
-</section>
-
-
-<section xml:id="sec-python"><title>Python</title>
-
-<para>
-  Currently supported interpreters are <varname>python26</varname>, <varname>python27</varname>,
-  <varname>python33</varname>, <varname>python34</varname>, <varname>python35</varname>
-  and <varname>pypy</varname>.
-</para>
-
-<para>
-  <varname>python</varname> is an alias to <varname>python27</varname> and <varname>python3</varname> is an alias to <varname>python34</varname>.
-</para>
-
-<para>
-  <varname>python26</varname> and <varname>python27</varname> do not include modules that require
-  external dependencies (to reduce dependency bloat). Following modules need to be added as
-  <varname>buildInput</varname> explicitly:
-</para>
-
-<itemizedlist>
-  <listitem><para><varname>python.modules.bsddb</varname></para></listitem>
-  <listitem><para><varname>python.modules.curses</varname></para></listitem>
-  <listitem><para><varname>python.modules.curses_panel</varname></para></listitem>
-  <listitem><para><varname>python.modules.crypt</varname></para></listitem>
-  <listitem><para><varname>python.modules.gdbm</varname></para></listitem>
-  <listitem><para><varname>python.modules.sqlite3</varname></para></listitem>
-  <listitem><para><varname>python.modules.tkinter</varname></para></listitem>
-  <listitem><para><varname>python.modules.readline</varname></para></listitem>
-</itemizedlist>
-
-<para>For convenience <varname>python27Full</varname> and <varname>python26Full</varname>
-are provided with all modules included.</para>
-
-<para>
-  Python packages that
-  use <link xlink:href="http://pypi.python.org/pypi/setuptools/"><literal>setuptools</literal></link> or <literal>distutils</literal>,
-  can be built using the <varname>buildPythonPackage</varname> function as documented below.
-</para>
-
-<para>
- All packages depending on any Python interpreter get appended <varname>$out/${python.sitePackages}</varname>
- to <literal>$PYTHONPATH</literal> if such directory exists.
-</para>
-
-<variablelist>
-  <title>
-     Useful attributes on interpreters packages:
-  </title>
-
-  <varlistentry>
-    <term><varname>libPrefix</varname></term>
-    <listitem><para>
-        Name of the folder in <literal>${python}/lib/</literal> for corresponding interpreter.
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><varname>interpreter</varname></term>
-    <listitem><para>
-        Alias for <literal>${python}/bin/${executable}.</literal>
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><varname>buildEnv</varname></term>
-    <listitem><para>
-        Function to build python interpreter environments with extra packages bundled together.
-        See <xref linkend="ssec-python-build-env" /> for usage and documentation.
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><varname>sitePackages</varname></term>
-    <listitem><para>
-      Alias for <literal>lib/${libPrefix}/site-packages</literal>.
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><varname>executable</varname></term>
-    <listitem><para>
-      Name of the interpreter executable, ie <literal>python3.4</literal>.
-    </para></listitem>
-  </varlistentry>
-
-</variablelist>
-<section xml:id="ssec-build-python-package"><title><varname>buildPythonPackage</varname> function</title>
-
-  <para>
-  The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/generic/default.nix">
-  <filename>pkgs/development/python-modules/generic/default.nix</filename></link>.
-  Example usage:
-
-<programlisting language="nix">
-twisted = buildPythonPackage {
-  name = "twisted-8.1.0";
-
-  src = pkgs.fetchurl {
-    url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
-    sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
-  };
-
-  propagatedBuildInputs = [ self.ZopeInterface ];
-
-  meta = {
-    homepage = http://twistedmatrix.com/;
-    description = "Twisted, an event-driven networking engine written in Python";
-    license = stdenv.lib.licenses.mit;
-  };
-};
-</programlisting>
-
-  Most of Python packages that use <varname>buildPythonPackage</varname> are defined
-  in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/python-packages.nix"><filename>pkgs/top-level/python-packages.nix</filename></link>
-  and generated for each python interpreter separately into attribute sets <varname>python26Packages</varname>,
-  <varname>python27Packages</varname>, <varname>python35Packages</varname>, <varname>python33Packages</varname>,
-  <varname>python34Packages</varname> and <varname>pypyPackages</varname>.
-  </para>
-
-  <para>
-    <function>buildPythonPackage</function> mainly does four things:
-
-    <orderedlist>
-      <listitem><para>
-        In the <varname>buildPhase</varname>, it calls
-        <literal>${python.interpreter} setup.py bdist_wheel</literal> to build a wheel binary zipfile.
-      </para></listitem>
-
-      <listitem><para>
-        In the <varname>installPhase</varname>, it installs the wheel file using
-        <literal>pip install *.whl</literal>.
-      </para></listitem>
-
-      <listitem><para>
-        In the <varname>postFixup</varname> phase, <literal>wrapPythonPrograms</literal>
-        bash function is called to wrap all programs in <filename>$out/bin/*</filename>
-        directory to include <literal>$PYTHONPATH</literal> and <literal>$PATH</literal>
-        environment variables.
-      </para></listitem>
-
-      <listitem><para>
-        In the <varname>installCheck</varname> phase, <literal>${python.interpreter} setup.py test</literal>
-        is ran.
-      </para></listitem>
-    </orderedlist>
-  </para>
-
-  <para>By default <varname>doCheck = true</varname> is set</para>
-
-  <para>
-    As in Perl, dependencies on other Python packages can be specified in the
-    <varname>buildInputs</varname> and
-    <varname>propagatedBuildInputs</varname> attributes.  If something is
-    exclusively a build-time dependency, use
-    <varname>buildInputs</varname>; if it’s (also) a runtime dependency,
-    use <varname>propagatedBuildInputs</varname>.
-  </para>
-
-  <para>
-    By default <varname>meta.platforms</varname> is set to the same value
-    as the interpreter unless overriden otherwise.
-  </para>
-
-  <variablelist>
-    <title>
-      <varname>buildPythonPackage</varname> parameters
-      (all parameters from <varname>mkDerivation</varname> function are still supported)
-    </title>
-
-    <varlistentry>
-      <term><varname>namePrefix</varname></term>
-      <listitem><para>
-        Prepended text to <varname>${name}</varname> parameter.
-        Defaults to <literal>"python3.3-"</literal> for Python 3.3, etc. Set it to
-        <literal>""</literal>
-        if you're packaging an application or a command line tool.
-      </para></listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><varname>disabled</varname></term>
-      <listitem><para>
-        If <varname>true</varname>, package is not build for
-        particular python interpreter version. Grep around
-        <filename>pkgs/top-level/python-packages.nix</filename>
-        for examples.
-      </para></listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><varname>setupPyBuildFlags</varname></term>
-      <listitem><para>
-        List of flags passed to <command>setup.py build_ext</command> command.
-      </para></listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><varname>pythonPath</varname></term>
-      <listitem><para>
-        List of packages to be added into <literal>$PYTHONPATH</literal>.
-        Packages in <varname>pythonPath</varname> are not propagated
-        (contrary to <varname>propagatedBuildInputs</varname>).
-      </para></listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><varname>preShellHook</varname></term>
-      <listitem><para>
-        Hook to execute commands before <varname>shellHook</varname>.
-      </para></listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><varname>postShellHook</varname></term>
-      <listitem><para>
-        Hook to execute commands after <varname>shellHook</varname>.
-      </para></listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><varname>makeWrapperArgs</varname></term>
-      <listitem><para>
-        A list of strings. Arguments to be passed to
-        <varname>makeWrapper</varname>, which wraps generated binaries. By
-        default, the arguments to <varname>makeWrapper</varname> set
-        <varname>PATH</varname> and <varname>PYTHONPATH</varname> environment
-        variables before calling the binary. Additional arguments here can
-        allow a developer to set environment variables which will be
-        available when the binary is run. For example,
-        <varname>makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]</varname>.
-      </para></listitem>
-    </varlistentry>
-
-  </variablelist>
-
-</section>
-
-<section xml:id="ssec-python-build-env"><title><function>python.buildEnv</function> function</title>
-  <para>
-    Create Python environments using low-level <function>pkgs.buildEnv</function> function. Example <filename>default.nix</filename>:
-
-<programlisting language="nix">
-<![CDATA[with import <nixpkgs> {};
-
-python.buildEnv.override {
-  extraLibs = [ pkgs.pythonPackages.pyramid ];
-  ignoreCollisions = true;
-}]]>
-</programlisting>
-
-    Running <command>nix-build</command> will create
-    <filename>/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env</filename>
-    with wrapped binaries in <filename>bin/</filename>.
-  </para>
-
-  <para>
-  You can also use <varname>env</varname> attribute to create local
-  environments with needed packages installed (somewhat comparable to
-  <literal>virtualenv</literal>). For example, with the following
-  <filename>shell.nix</filename>:
-
-<programlisting language="nix">
-<![CDATA[with import <nixpkgs> {};
-
-(python3.buildEnv.override {
-  extraLibs = with python3Packages;
-    [ numpy
-      requests
-    ];
-}).env]]>
-</programlisting>
-
-  Running <command>nix-shell</command> will drop you into a shell where
-  <command>python</command> will have specified packages in its path.
-  </para>
-
-  <variablelist>
-    <title>
-      <function>python.buildEnv</function> arguments
-    </title>
-
-    <varlistentry>
-      <term><varname>extraLibs</varname></term>
-      <listitem><para>
-        List of packages installed inside the environment.
-      </para></listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><varname>postBuild</varname></term>
-      <listitem><para>
-        Shell command executed after the build of environment.
-      </para></listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><varname>ignoreCollisions</varname></term>
-      <listitem><para>
-         Ignore file collisions inside the environment (default is <varname>false</varname>).
-      </para></listitem>
-    </varlistentry>
-  </variablelist>
-</section>
-
-<section xml:id="ssec-python-tools"><title>Tools</title>
-
-<para>Packages inside nixpkgs are written by hand. However many tools
-exist in community to help save time. No tool is preferred at the moment.
-</para>
-
-<itemizedlist>
-
-  <listitem><para>
-    <link xlink:href="https://github.com/proger/python2nix">python2nix</link>
-    by Vladimir Kirillov
-  </para></listitem>
-
-  <listitem><para>
-    <link xlink:href="https://github.com/garbas/pypi2nix">pypi2nix</link>
-    by Rok Garbas
-  </para></listitem>
-
-  <listitem><para>
-    <link xlink:href="https://github.com/offlinehacker/pypi2nix">pypi2nix</link>
-    by Jaka Hudoklin
-  </para></listitem>
-
-</itemizedlist>
-
-</section>
-
-<section xml:id="ssec-python-development"><title>Development</title>
-
-  <para>
-    To develop Python packages <function>buildPythonPackage</function> has
-    additional logic inside <varname>shellPhase</varname> to run
-    <command>pip install -e . --prefix $TMPDIR/</command> for the package.
-  </para>
-
-  <warning><para><varname>shellPhase</varname> is executed only if <filename>setup.py</filename>
-  exists.</para></warning>
-
-  <para>
-    Given a <filename>default.nix</filename>:
-
-<programlisting language="nix">
-<![CDATA[with import <nixpkgs> {};
-
-buildPythonPackage {
-  name = "myproject";
-
-  buildInputs = with pkgs.pythonPackages; [ pyramid ];
-
-  src = ./.;
-}]]>
-</programlisting>
-
-    Running <command>nix-shell</command> with no arguments should give you
-    the environment in which the package would be build with
-    <command>nix-build</command>.
-  </para>
-
-  <para>
-    Shortcut to setup environments with C headers/libraries and python packages:
-
-    <programlisting language="bash">$ nix-shell -p pythonPackages.pyramid zlib libjpeg git</programlisting>
-  </para>
-
-  <note><para>
-    There is a boolean value <varname>lib.inNixShell</varname> set to
-    <varname>true</varname> if nix-shell is invoked.
-  </para></note>
-
-</section>
-
-<section xml:id="ssec-python-faq"><title>FAQ</title>
-
-<variablelist>
-
-  <varlistentry>
-    <term>How to solve circular dependencies?</term>
-    <listitem><para>
-      If you have packages <varname>A</varname> and <varname>B</varname> that
-      depend on each other, when packaging <varname>B</varname> override package
-      <varname>A</varname> not to depend on <varname>B</varname> as input
-      (and also the other way around).
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><varname>install_data / data_files</varname> problems resulting into <literal>error: could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc': Permission denied</literal></term>
-    <listitem><para>
-      <link xlink:href="https://bitbucket.org/pypa/setuptools/issue/130/install_data-doesnt-respect-prefix">
-      Known bug in setuptools <varname>install_data</varname> does not respect --prefix</link>. Example of
-      such package using the feature is <filename>pkgs/tools/X11/xpra/default.nix</filename>. As workaround
-      install it as an extra <varname>preInstall</varname> step:
-
-      <programlisting>${python.interpreter} setup.py install_data --install-dir=$out --root=$out
-sed -i '/ = data_files/d' setup.py</programlisting>
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term>Rationale of non-existent global site-packages</term>
-    <listitem><para>
-      There is no need to have global site-packages in Nix. Each package has isolated
-      dependency tree and installing any python package will only populate <varname>$PATH</varname>
-      inside user environment. See <xref linkend="ssec-python-build-env" /> to create self-contained
-      interpreter with a set of packages.
-    </para></listitem>
-  </varlistentry>
-
-</variablelist>
-
-</section>
-
-
-<section xml:id="ssec-python-contrib"><title>Contributing guidelines</title>
-<para>
-  Following rules are desired to be respected:
-</para>
-
-<itemizedlist>
-
-  <listitem><para>
-    Make sure package builds for all python interpreters. Use <varname>disabled</varname> argument to
-    <function>buildPythonPackage</function> to set unsupported interpreters.
-  </para></listitem>
-
-  <listitem><para>
-    If tests need to be disabled for a package, make sure you leave a comment about reasoning.
-  </para></listitem>
-
-  <listitem><para>
-    Packages in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/python-packages.nix"><filename>pkgs/top-level/python-packages.nix</filename></link>
-    are sorted quasi-alphabetically to avoid merge conflicts.
-  </para></listitem>
-
-</itemizedlist>
-
-</section>
-
-</section>
-
-
-<section xml:id="sec-language-ruby"><title>Ruby</title>
-  <para>There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a <filename>Gemfile</filename>, let bundler create a <filename>Gemfile.lock</filename>, and then convert
-  this into a nix expression that contains all Gem dependencies automatically.</para>
-
-  <para>For example, to package sensu, we did:</para>
-
-<screen>
-<![CDATA[$ cd pkgs/servers/monitoring
-$ mkdir sensu
-$ cat > Gemfile
-source 'https://rubygems.org'
-gem 'sensu'
-$ bundler package --path /tmp/vendor/bundle
-$ $(nix-build '<nixpkgs>' -A bundix)/bin/bundix
-$ cat > default.nix
-{ lib, bundlerEnv, ruby }:
-
-bundlerEnv {
-  name = "sensu-0.17.1";
-
-  inherit ruby;
-  gemfile = ./Gemfile;
-  lockfile = ./Gemfile.lock;
-  gemset = ./gemset.nix;
-
-  meta = with lib; {
-    description = "A monitoring framework that aims to be simple, malleable,
-and scalable.";
-    homepage    = http://sensuapp.org/;
-    license     = with licenses; mit;
-    maintainers = with maintainers; [ theuni ];
-    platforms   = platforms.unix;
-  };
-}]]>
-</screen>
-
-<para>Please check in the <filename>Gemfile</filename>, <filename>Gemfile.lock</filename> and the <filename>gemset.nix</filename> so future updates can be run easily.
-</para>
-
-</section>
-
-<section xml:id="sec-language-go"><title>Go</title>
-
-<para>The function <varname>buildGoPackage</varname> builds
-standard Go packages.
-</para>
-
-<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
-<programlisting>
-net = buildGoPackage rec {
-  name = "go.net-${rev}";
-  goPackagePath = "golang.org/x/net"; <co xml:id='ex-buildGoPackage-1' />
-  subPackages = [ "ipv4" "ipv6" ]; <co xml:id='ex-buildGoPackage-2' />
-  rev = "e0403b4e005";
-  src = fetchFromGitHub {
-    inherit rev;
-    owner = "golang";
-    repo = "net";
-    sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
-  };
-  goPackageAliases = [ "code.google.com/p/go.net" ]; <co xml:id='ex-buildGoPackage-3' />
-  propagatedBuildInputs = [ goPackages.text ]; <co xml:id='ex-buildGoPackage-4' />
-  buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-5' />
-  disabled = isGo13;<co xml:id='ex-buildGoPackage-6' />
-};
-</programlisting>
-</example>
-
-<para><xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage,
-the following arguments are of special significance to the function:
-
-<calloutlist>
-
-  <callout arearefs='ex-buildGoPackage-1'>
-    <para>
-      <varname>goPackagePath</varname> specifies the package's canonical Go import path.
-    </para>
-  </callout>
-
-  <callout arearefs='ex-buildGoPackage-2'>
-    <para>
-      <varname>subPackages</varname> limits the builder from building child packages that
-      have not been listed. If <varname>subPackages</varname> is not specified, all child
-      packages will be built.
-    </para>
-    <para>
-      In this example only <literal>code.google.com/p/go.net/ipv4</literal> and
-      <literal>code.google.com/p/go.net/ipv6</literal> will be built.
-    </para>
-  </callout>
-
-  <callout arearefs='ex-buildGoPackage-3'>
-    <para>
-      <varname>goPackageAliases</varname> is a list of alternative import paths
-      that are valid for this library.
-      Packages that depend on this library will automatically rename
-      import paths that match any of the aliases to <literal>goPackagePath</literal>.
-    </para>
-    <para>
-      In this example imports will be renamed from
-      <literal>code.google.com/p/go.net</literal> to
-      <literal>golang.org/x/net</literal> in every package that depend on the
-      <literal>go.net</literal> library.
-    </para>
-  </callout>
-
-  <callout arearefs='ex-buildGoPackage-4'>
-    <para>
-      <varname>propagatedBuildInputs</varname> is where the dependencies of a Go library are
-      listed. Only libraries should list <varname>propagatedBuildInputs</varname>. If a standalone
-      program is being built instead, use <varname>buildInputs</varname>. If a library's tests require
-      additional dependencies that are not propagated, they should be listed in <varname>buildInputs</varname>.
-    </para>
-  </callout>
-
-  <callout arearefs='ex-buildGoPackage-5'>
-    <para>
-      <varname>buildFlags</varname> is a list of flags passed to the go build command.
-    </para>
-  </callout>
-
-  <callout arearefs='ex-buildGoPackage-6'>
-    <para>
-      If <varname>disabled</varname> is <literal>true</literal>,
-      nix will refuse to build this package.
-    </para>
-    <para>
-      In this example the package will not be built for go 1.3. The <literal>isGo13</literal>
-      is an utility function that returns <literal>true</literal> if go used to build the
-      package has version 1.3.x.
-    </para>
-  </callout>
-
-</calloutlist>
-
-</para>
-
-<para>
-Reusable Go libraries may be found in the <varname>goPackages</varname> set. You can test
-build a Go package as follows:
-
-<screen>
-$ nix-build -A goPackages.net
-</screen>
-
-</para>
-
-<para>
-You may use Go packages installed into the active Nix profiles by adding
-the following to your ~/.bashrc:
-
-<screen>
-for p in $NIX_PROFILES; do
-    GOPATH="$p/share/go:$GOPATH"
-done
-</screen>
-</para>
-
-  <para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/cstrahan/go2nix">go2nix</link>.</para>
-</section>
-
-
-<section xml:id="sec-language-java"><title>Java</title>
-
-<para>Ant-based Java packages are typically built from source as follows:
-
-<programlisting>
-stdenv.mkDerivation {
-  name = "...";
-  src = fetchurl { ... };
-
-  buildInputs = [ jdk ant ];
-
-  buildPhase = "ant";
-}
-</programlisting>
-
-Note that <varname>jdk</varname> is an alias for the OpenJDK.</para>
-
-<para>JAR files that are intended to be used by other packages should
-be installed in <filename>$out/share/java</filename>.  The OpenJDK has
-a stdenv setup hook that adds any JARs in the
-<filename>share/java</filename> directories of the build inputs to the
-<envar>CLASSPATH</envar> environment variable.  For instance, if the
-package <literal>libfoo</literal> installs a JAR named
-<filename>foo.jar</filename> in its <filename>share/java</filename>
-directory, and another package declares the attribute
-
-<programlisting>
-buildInputs = [ jdk libfoo ];
-</programlisting>
-
-then <envar>CLASSPATH</envar> will be set to
-<filename>/nix/store/...-libfoo/share/java/foo.jar</filename>.</para>
-
-<para>Private JARs
-should be installed in a location like
-<filename>$out/share/<replaceable>package-name</replaceable></filename>.</para>
-
-<para>If your Java package provides a program, you need to generate a
-wrapper script to run it using the OpenJRE.  You can use
-<literal>makeWrapper</literal> for this:
-
-<programlisting>
-buildInputs = [ makeWrapper ];
-
-installPhase =
-  ''
-    mkdir -p $out/bin
-    makeWrapper ${jre}/bin/java $out/bin/foo \
-      --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
-  '';
-</programlisting>
-
-Note the use of <literal>jre</literal>, which is the part of the
-OpenJDK package that contains the Java Runtime Environment.  By using
-<literal>${jre}/bin/java</literal> instead of
-<literal>${jdk}/bin/java</literal>, you prevent your package from
-depending on the JDK at runtime.</para>
-
-<para>It is possible to use a different Java compiler than
-<command>javac</command> from the OpenJDK.  For instance, to use the
-Eclipse Java Compiler:
-
-<programlisting>
-buildInputs = [ jre ant ecj ];
-</programlisting>
-
-(Note that here you don’t need the full JDK as an input, but just the
-JRE.)  The ECJ has a stdenv setup hook that sets some environment
-variables to cause Ant to use ECJ, but this doesn’t work with all Ant
-files.  Similarly, you can use the GNU Java Compiler:
-
-<programlisting>
-buildInputs = [ gcj ant ];
-</programlisting>
-
-Here, Ant will automatically use <command>gij</command> (the GNU Java
-Runtime) instead of the OpenJRE.</para>
-
-</section>
-
-
-<section xml:id="sec-language-lua"><title>Lua</title>
-
-<para>
-  Lua packages are built by the <varname>buildLuaPackage</varname> function.  This function is
-  implemented
-  in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix">
-  <filename>pkgs/development/lua-modules/generic/default.nix</filename></link>
-  and works similarly to <varname>buildPerlPackage</varname>. (See
-  <xref linkend="sec-language-perl"/> for details.)
-</para>
-
-<para>
-  Lua packages are defined
-  in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>.
-  Most of them are simple. For example:
-
-  <programlisting>
-fileSystem = buildLuaPackage {
-  name = "filesystem-1.6.2";
-  src = fetchurl {
-    url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz";
-    sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz";
-  };
-  meta = {
-    homepage = "https://github.com/keplerproject/luafilesystem";
-    hydraPlatforms = stdenv.lib.platforms.linux;
-    maintainers = with maintainers; [ flosse ];
-  };
-};
-  </programlisting>
-</para>
-
-<para>
-  Though, more complicated package should be placed in a seperate file in
-  <link
-  xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename>pkgs/development/lua-modules</filename></link>.
-</para>
-<para>
-  Lua packages accept additional parameter <varname>disabled</varname>, which defines
-  the condition of disabling package from luaPackages. For example, if package has
-  <varname>disabled</varname> assigned to <literal>lua.luaversion != "5.1"</literal>,
-  it will not be included in any luaPackages except lua51Packages, making it
-  only be built for lua 5.1.
-</para>
-
-</section>
-
-<section xml:id="sec-language-coq"><title>Coq</title>
-  <para>
-    Coq libraries should be installed in
-    <literal>$(out)/lib/coq/${coq.coq-version}/user-contrib/</literal>.
-    Such directories are automatically added to the
-    <literal>$COQPATH</literal> environment variable by the hook defined
-    in the Coq derivation.
-  </para>
-  <para>
-    Some libraries require OCaml and sometimes also Camlp5. The exact
-    versions that were used to build Coq are saved in the
-    <literal>coq.ocaml</literal> and <literal>coq.camlp5</literal>
-    attributes.
-  </para>
-  <para>
-    Here is a simple package example. It is a pure Coq library, thus it
-    only depends on Coq. Its <literal>makefile</literal> has been
-    generated using <literal>coq_makefile</literal> so we only have to
-    set the <literal>$COQLIB</literal> variable at install time.
-  </para>
-  <programlisting>
-{stdenv, fetchurl, coq}:
-stdenv.mkDerivation {
-  src = fetchurl {
-    url = http://coq.inria.fr/pylons/contribs/files/Karatsuba/v8.4/Karatsuba.tar.gz;
-    sha256 = "0ymfpv4v49k4fm63nq6gcl1hbnnxrvjjp7yzc4973n49b853c5b1";
-  };
-
-  name = "coq-karatsuba";
-
-  buildInputs = [ coq ];
-
-  installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/";
-}
-</programlisting>
-</section>
-
-<section xml:id="sec-language-qt"><title>Qt</title>
-
-<para>The information in this section applies to Qt 5.5 and later.</para>
-
-<para>Qt is an application development toolkit for C++. Although it is
-not a distinct programming language, there are special considerations
-for packaging Qt-based programs and libraries. A small set of tools
-and conventions has grown out of these considerations.</para>
-
-<section xml:id="ssec-qt-libraries"><title>Libraries</title>
-
-<para>Packages that provide libraries should be listed in
-<varname>qt5LibsFun</varname> so that the library is built with each
-Qt version. A set of packages is provided for each version of Qt; for
-example, <varname>qt5Libs</varname> always provides libraries built
-with the latest version, <varname>qt55Libs</varname> provides
-libraries built with Qt 5.5, and so on. To avoid version conflicts, no
-top-level attributes are created for these packages.</para>
-
-</section>
-
-<section xml:id="ssec-qt-programs"><title>Programs</title>
-
-<para>Application packages do not need to be built with every Qt
-version. To ensure consistency between the package's dependencies,
-call the package with <literal>qt5Libs.callPackage</literal> instead
-of the usual <literal>callPackage</literal>. An older version may be
-selected in case of incompatibility. For example, to build with Qt
-5.5, call the package with
-<literal>qt55Libs.callPackage</literal>.</para>
-
-<para>Several environment variables must be set at runtime for Qt
-applications to function correctly, including:</para>
-
-<itemizedlist>
-  <listitem><para><envar>QT_PLUGIN_PATH</envar></para></listitem>
-  <listitem><para><envar>QML_IMPORT_PATH</envar></para></listitem>
-  <listitem><para><envar>QML2_IMPORT_PATH</envar></para></listitem>
-  <listitem><para><envar>XDG_DATA_DIRS</envar></para></listitem>
-</itemizedlist>
-
-<para>To ensure that these are set correctly, the program must be wrapped by
-invoking <literal>wrapQtProgram <replaceable>program</replaceable></literal>
-during installation (for example, during
-<literal>fixupPhase</literal>). <literal>wrapQtProgram</literal>
-accepts the same options as <literal>makeWrapper</literal>.
-</para>
-
-</section>
-
-<section xml:id="ssec-qt-kde"><title>KDE</title>
-
-<para>Many of the considerations above also apply to KDE packages,
-especially the need to set the correct environment variables at
-runtime. To ensure that this is done, invoke <literal>wrapKDEProgram
-<replaceable>program</replaceable></literal> during
-installation. <literal>wrapKDEProgram</literal> also generates a
-<literal>ksycoca</literal> database so that required data and services
-can be found. Like its Qt counterpart,
-<literal>wrapKDEProgram</literal> accepts the same options as
-<literal>makeWrapper</literal>.</para>
-
-</section>
-
-</section>
-
-<!--
-<section><title>Haskell</title>
-
-<para>TODO</para>
-
-</section>
-
-
-<section><title>TeX / LaTeX</title>
-
-<para>* Special support for building TeX documents</para>
-
-</section>
--->
-
-
-</chapter>
diff --git a/doc/languages-frameworks/coq.xml b/doc/languages-frameworks/coq.xml
new file mode 100644
index 00000000000..d16c9f3dc87
--- /dev/null
+++ b/doc/languages-frameworks/coq.xml
@@ -0,0 +1,41 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-coq">
+
+<title>Coq</title>
+  <para>
+    Coq libraries should be installed in
+    <literal>$(out)/lib/coq/${coq.coq-version}/user-contrib/</literal>.
+    Such directories are automatically added to the
+    <literal>$COQPATH</literal> environment variable by the hook defined
+    in the Coq derivation.
+  </para>
+  <para>
+    Some libraries require OCaml and sometimes also Camlp5. The exact
+    versions that were used to build Coq are saved in the
+    <literal>coq.ocaml</literal> and <literal>coq.camlp5</literal>
+    attributes.
+  </para>
+  <para>
+    Here is a simple package example. It is a pure Coq library, thus it
+    only depends on Coq. Its <literal>makefile</literal> has been
+    generated using <literal>coq_makefile</literal> so we only have to
+    set the <literal>$COQLIB</literal> variable at install time.
+  </para>
+  <programlisting>
+{stdenv, fetchurl, coq}:
+stdenv.mkDerivation {
+  src = fetchurl {
+    url = http://coq.inria.fr/pylons/contribs/files/Karatsuba/v8.4/Karatsuba.tar.gz;
+    sha256 = "0ymfpv4v49k4fm63nq6gcl1hbnnxrvjjp7yzc4973n49b853c5b1";
+  };
+
+  name = "coq-karatsuba";
+
+  buildInputs = [ coq ];
+
+  installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/";
+}
+</programlisting>
+</section>
+
diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml
new file mode 100644
index 00000000000..89908b3b8ff
--- /dev/null
+++ b/doc/languages-frameworks/go.xml
@@ -0,0 +1,124 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-go">
+
+<title>Go</title>
+
+<para>The function <varname>buildGoPackage</varname> builds
+standard Go packages.
+</para>
+
+<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
+<programlisting>
+net = buildGoPackage rec {
+  name = "go.net-${rev}";
+  goPackagePath = "golang.org/x/net"; <co xml:id='ex-buildGoPackage-1' />
+  subPackages = [ "ipv4" "ipv6" ]; <co xml:id='ex-buildGoPackage-2' />
+  rev = "e0403b4e005";
+  src = fetchFromGitHub {
+    inherit rev;
+    owner = "golang";
+    repo = "net";
+    sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
+  };
+  goPackageAliases = [ "code.google.com/p/go.net" ]; <co xml:id='ex-buildGoPackage-3' />
+  propagatedBuildInputs = [ goPackages.text ]; <co xml:id='ex-buildGoPackage-4' />
+  buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-5' />
+  disabled = isGo13;<co xml:id='ex-buildGoPackage-6' />
+};
+</programlisting>
+</example>
+
+<para><xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage,
+the following arguments are of special significance to the function:
+
+<calloutlist>
+
+  <callout arearefs='ex-buildGoPackage-1'>
+    <para>
+      <varname>goPackagePath</varname> specifies the package's canonical Go import path.
+    </para>
+  </callout>
+
+  <callout arearefs='ex-buildGoPackage-2'>
+    <para>
+      <varname>subPackages</varname> limits the builder from building child packages that
+      have not been listed. If <varname>subPackages</varname> is not specified, all child
+      packages will be built.
+    </para>
+    <para>
+      In this example only <literal>code.google.com/p/go.net/ipv4</literal> and
+      <literal>code.google.com/p/go.net/ipv6</literal> will be built.
+    </para>
+  </callout>
+
+  <callout arearefs='ex-buildGoPackage-3'>
+    <para>
+      <varname>goPackageAliases</varname> is a list of alternative import paths
+      that are valid for this library.
+      Packages that depend on this library will automatically rename
+      import paths that match any of the aliases to <literal>goPackagePath</literal>.
+    </para>
+    <para>
+      In this example imports will be renamed from
+      <literal>code.google.com/p/go.net</literal> to
+      <literal>golang.org/x/net</literal> in every package that depend on the
+      <literal>go.net</literal> library.
+    </para>
+  </callout>
+
+  <callout arearefs='ex-buildGoPackage-4'>
+    <para>
+      <varname>propagatedBuildInputs</varname> is where the dependencies of a Go library are
+      listed. Only libraries should list <varname>propagatedBuildInputs</varname>. If a standalone
+      program is being built instead, use <varname>buildInputs</varname>. If a library's tests require
+      additional dependencies that are not propagated, they should be listed in <varname>buildInputs</varname>.
+    </para>
+  </callout>
+
+  <callout arearefs='ex-buildGoPackage-5'>
+    <para>
+      <varname>buildFlags</varname> is a list of flags passed to the go build command.
+    </para>
+  </callout>
+
+  <callout arearefs='ex-buildGoPackage-6'>
+    <para>
+      If <varname>disabled</varname> is <literal>true</literal>,
+      nix will refuse to build this package.
+    </para>
+    <para>
+      In this example the package will not be built for go 1.3. The <literal>isGo13</literal>
+      is an utility function that returns <literal>true</literal> if go used to build the
+      package has version 1.3.x.
+    </para>
+  </callout>
+
+</calloutlist>
+
+</para>
+
+<para>
+Reusable Go libraries may be found in the <varname>goPackages</varname> set. You can test
+build a Go package as follows:
+
+<screen>
+$ nix-build -A goPackages.net
+</screen>
+
+</para>
+
+<para>
+You may use Go packages installed into the active Nix profiles by adding
+the following to your ~/.bashrc:
+
+<screen>
+for p in $NIX_PROFILES; do
+    GOPATH="$p/share/go:$GOPATH"
+done
+</screen>
+</para>
+
+  <para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/cstrahan/go2nix">go2nix</link>.</para>
+</section>
+
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
new file mode 100644
index 00000000000..9fd79877e83
--- /dev/null
+++ b/doc/languages-frameworks/index.xml
@@ -0,0 +1,42 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xml:id="chap-language-support">
+
+<title>Support for specific programming languages and frameworks</title>
+
+<para>The <link linkend="chap-stdenv">standard build
+environment</link> makes it easy to build typical Autotools-based
+packages with very little code.  Any other kind of package can be
+accomodated by overriding the appropriate phases of
+<literal>stdenv</literal>.  However, there are specialised functions
+in Nixpkgs to easily build packages for other programming languages,
+such as Perl or Haskell.  These are described in this chapter.</para>
+
+
+<xi:include href="perl.xml" />
+<xi:include href="python.xml" />
+<xi:include href="ruby.xml" />
+<xi:include href="go.xml" />
+<xi:include href="java.xml" />
+<xi:include href="lua.xml" />
+<xi:include href="coq.xml" />
+<xi:include href="qt.xml" />
+
+
+<!--
+<section><title>Haskell</title>
+
+<para>TODO</para>
+
+</section>
+
+
+<section><title>TeX / LaTeX</title>
+
+<para>* Special support for building TeX documents</para>
+
+</section>
+-->
+
+
+</chapter>
diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml
new file mode 100644
index 00000000000..2d40a254ced
--- /dev/null
+++ b/doc/languages-frameworks/java.xml
@@ -0,0 +1,84 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-java">
+
+<title>Java</title>
+
+<para>Ant-based Java packages are typically built from source as follows:
+
+<programlisting>
+stdenv.mkDerivation {
+  name = "...";
+  src = fetchurl { ... };
+
+  buildInputs = [ jdk ant ];
+
+  buildPhase = "ant";
+}
+</programlisting>
+
+Note that <varname>jdk</varname> is an alias for the OpenJDK.</para>
+
+<para>JAR files that are intended to be used by other packages should
+be installed in <filename>$out/share/java</filename>.  The OpenJDK has
+a stdenv setup hook that adds any JARs in the
+<filename>share/java</filename> directories of the build inputs to the
+<envar>CLASSPATH</envar> environment variable.  For instance, if the
+package <literal>libfoo</literal> installs a JAR named
+<filename>foo.jar</filename> in its <filename>share/java</filename>
+directory, and another package declares the attribute
+
+<programlisting>
+buildInputs = [ jdk libfoo ];
+</programlisting>
+
+then <envar>CLASSPATH</envar> will be set to
+<filename>/nix/store/...-libfoo/share/java/foo.jar</filename>.</para>
+
+<para>Private JARs
+should be installed in a location like
+<filename>$out/share/<replaceable>package-name</replaceable></filename>.</para>
+
+<para>If your Java package provides a program, you need to generate a
+wrapper script to run it using the OpenJRE.  You can use
+<literal>makeWrapper</literal> for this:
+
+<programlisting>
+buildInputs = [ makeWrapper ];
+
+installPhase =
+  ''
+    mkdir -p $out/bin
+    makeWrapper ${jre}/bin/java $out/bin/foo \
+      --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
+  '';
+</programlisting>
+
+Note the use of <literal>jre</literal>, which is the part of the
+OpenJDK package that contains the Java Runtime Environment.  By using
+<literal>${jre}/bin/java</literal> instead of
+<literal>${jdk}/bin/java</literal>, you prevent your package from
+depending on the JDK at runtime.</para>
+
+<para>It is possible to use a different Java compiler than
+<command>javac</command> from the OpenJDK.  For instance, to use the
+Eclipse Java Compiler:
+
+<programlisting>
+buildInputs = [ jre ant ecj ];
+</programlisting>
+
+(Note that here you don’t need the full JDK as an input, but just the
+JRE.)  The ECJ has a stdenv setup hook that sets some environment
+variables to cause Ant to use ECJ, but this doesn’t work with all Ant
+files.  Similarly, you can use the GNU Java Compiler:
+
+<programlisting>
+buildInputs = [ gcj ant ];
+</programlisting>
+
+Here, Ant will automatically use <command>gij</command> (the GNU Java
+Runtime) instead of the OpenJRE.</para>
+
+</section>
+
diff --git a/doc/languages-frameworks/lua.xml b/doc/languages-frameworks/lua.xml
new file mode 100644
index 00000000000..39b086af4cb
--- /dev/null
+++ b/doc/languages-frameworks/lua.xml
@@ -0,0 +1,51 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-lua">
+
+<title>Lua</title>
+
+<para>
+  Lua packages are built by the <varname>buildLuaPackage</varname> function.  This function is
+  implemented
+  in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix">
+  <filename>pkgs/development/lua-modules/generic/default.nix</filename></link>
+  and works similarly to <varname>buildPerlPackage</varname>. (See
+  <xref linkend="sec-language-perl"/> for details.)
+</para>
+
+<para>
+  Lua packages are defined
+  in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>.
+  Most of them are simple. For example:
+
+  <programlisting>
+fileSystem = buildLuaPackage {
+  name = "filesystem-1.6.2";
+  src = fetchurl {
+    url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz";
+    sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz";
+  };
+  meta = {
+    homepage = "https://github.com/keplerproject/luafilesystem";
+    hydraPlatforms = stdenv.lib.platforms.linux;
+    maintainers = with maintainers; [ flosse ];
+  };
+};
+  </programlisting>
+</para>
+
+<para>
+  Though, more complicated package should be placed in a seperate file in
+  <link
+  xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename>pkgs/development/lua-modules</filename></link>.
+</para>
+<para>
+  Lua packages accept additional parameter <varname>disabled</varname>, which defines
+  the condition of disabling package from luaPackages. For example, if package has
+  <varname>disabled</varname> assigned to <literal>lua.luaversion != "5.1"</literal>,
+  it will not be included in any luaPackages except lua51Packages, making it
+  only be built for lua 5.1.
+</para>
+
+</section>
+
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml
new file mode 100644
index 00000000000..54b82f4a056
--- /dev/null
+++ b/doc/languages-frameworks/perl.xml
@@ -0,0 +1,181 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-perl">
+
+<title>Perl</title>
+
+<para>Nixpkgs provides a function <varname>buildPerlPackage</varname>,
+a generic package builder function for any Perl package that has a
+standard <varname>Makefile.PL</varname>.  It’s implemented in <link
+xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.</para>
+
+<para>Perl packages from CPAN are defined in <link
+xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>,
+rather than <filename>pkgs/all-packages.nix</filename>.  Most Perl
+packages are so straight-forward to build that they are defined here
+directly, rather than having a separate function for each package
+called from <filename>perl-packages.nix</filename>.  However, more
+complicated packages should be put in a separate file, typically in
+<filename>pkgs/development/perl-modules</filename>.  Here is an
+example of the former:
+
+<programlisting>
+ClassC3 = buildPerlPackage rec {
+  name = "Class-C3-0.21";
+  src = fetchurl {
+    url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
+    sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
+  };
+};
+</programlisting>
+
+Note the use of <literal>mirror://cpan/</literal>, and the
+<literal>${name}</literal> in the URL definition to ensure that the
+name attribute is consistent with the source that we’re actually
+downloading.  Perl packages are made available in
+<filename>all-packages.nix</filename> through the variable
+<varname>perlPackages</varname>.  For instance, if you have a package
+that needs <varname>ClassC3</varname>, you would typically write
+
+<programlisting>
+foo = import ../path/to/foo.nix {
+  inherit stdenv fetchurl ...;
+  inherit (perlPackages) ClassC3;
+};
+</programlisting>
+
+in <filename>all-packages.nix</filename>.  You can test building a
+Perl package as follows:
+
+<screen>
+$ nix-build -A perlPackages.ClassC3
+</screen>
+
+<varname>buildPerlPackage</varname> adds <literal>perl-</literal> to
+the start of the name attribute, so the package above is actually
+called <literal>perl-Class-C3-0.21</literal>.  So to install it, you
+can say:
+
+<screen>
+$ nix-env -i perl-Class-C3
+</screen>
+
+(Of course you can also install using the attribute name:
+<literal>nix-env -i -A perlPackages.ClassC3</literal>.)</para>
+
+<para>So what does <varname>buildPerlPackage</varname> do?  It does
+the following:
+
+<orderedlist>
+
+  <listitem><para>In the configure phase, it calls <literal>perl
+  Makefile.PL</literal> to generate a Makefile.  You can set the
+  variable <varname>makeMakerFlags</varname> to pass flags to
+  <filename>Makefile.PL</filename></para></listitem>
+
+  <listitem><para>It adds the contents of the <envar>PERL5LIB</envar>
+  environment variable to <literal>#! .../bin/perl</literal> line of
+  Perl scripts as <literal>-I<replaceable>dir</replaceable></literal>
+  flags.  This ensures that a script can find its
+  dependencies.</para></listitem>
+
+  <listitem><para>In the fixup phase, it writes the propagated build
+  inputs (<varname>propagatedBuildInputs</varname>) to the file
+  <filename>$out/nix-support/propagated-user-env-packages</filename>.
+  <command>nix-env</command> recursively installs all packages listed
+  in this file when you install a package that has it.  This ensures
+  that a Perl package can find its dependencies.</para></listitem>
+
+</orderedlist>
+
+</para>
+
+<para><varname>buildPerlPackage</varname> is built on top of
+<varname>stdenv</varname>, so everything can be customised in the
+usual way.  For instance, the <literal>BerkeleyDB</literal> module has
+a <varname>preConfigure</varname> hook to generate a configuration
+file used by <filename>Makefile.PL</filename>:
+
+<programlisting>
+{ buildPerlPackage, fetchurl, db }:
+
+buildPerlPackage rec {
+  name = "BerkeleyDB-0.36";
+
+  src = fetchurl {
+    url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
+    sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
+  };
+
+  preConfigure = ''
+    echo "LIB = ${db}/lib" > config.in
+    echo "INCLUDE = ${db}/include" >> config.in
+  '';
+}
+</programlisting>
+
+</para>
+
+<para>Dependencies on other Perl packages can be specified in the
+<varname>buildInputs</varname> and
+<varname>propagatedBuildInputs</varname> attributes.  If something is
+exclusively a build-time dependency, use
+<varname>buildInputs</varname>; if it’s (also) a runtime dependency,
+use <varname>propagatedBuildInputs</varname>.  For instance, this
+builds a Perl module that has runtime dependencies on a bunch of other
+modules:
+
+<programlisting>
+ClassC3Componentised = buildPerlPackage rec {
+  name = "Class-C3-Componentised-1.0004";
+  src = fetchurl {
+    url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
+    sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
+  };
+  propagatedBuildInputs = [
+    ClassC3 ClassInspector TestException MROCompat
+  ];
+};
+</programlisting>
+
+</para>
+
+<section xml:id="ssec-generation-from-CPAN"><title>Generation from CPAN</title>
+
+<para>Nix expressions for Perl packages can be generated (almost)
+automatically from CPAN.  This is done by the program
+<command>nix-generate-from-cpan</command>, which can be installed
+as follows:</para>
+
+<screen>
+$ nix-env -i nix-generate-from-cpan
+</screen>
+
+<para>This program takes a Perl module name, looks it up on CPAN,
+fetches and unpacks the corresponding package, and prints a Nix
+expression on standard output.  For example:
+
+<screen>
+$ nix-generate-from-cpan XML::Simple
+  XMLSimple = buildPerlPackage {
+    name = "XML-Simple-2.20";
+    src = fetchurl {
+      url = mirror://cpan/authors/id/G/GR/GRANTM/XML-Simple-2.20.tar.gz;
+      sha256 = "5cff13d0802792da1eb45895ce1be461903d98ec97c9c953bc8406af7294434a";
+    };
+    propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
+    meta = {
+      description = "Easily read/write XML (esp config files)";
+      license = "perl";
+    };
+  };
+</screen>
+
+The output can be pasted into
+<filename>pkgs/top-level/perl-packages.nix</filename> or wherever else
+you need it.</para>
+
+</section>
+
+</section>
+
diff --git a/doc/languages-frameworks/python.xml b/doc/languages-frameworks/python.xml
new file mode 100644
index 00000000000..57aceeb4868
--- /dev/null
+++ b/doc/languages-frameworks/python.xml
@@ -0,0 +1,447 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-python">
+
+<title>Python</title>
+
+<para>
+  Currently supported interpreters are <varname>python26</varname>, <varname>python27</varname>,
+  <varname>python33</varname>, <varname>python34</varname>, <varname>python35</varname>
+  and <varname>pypy</varname>.
+</para>
+
+<para>
+  <varname>python</varname> is an alias to <varname>python27</varname> and <varname>python3</varname> is an alias to <varname>python34</varname>.
+</para>
+
+<para>
+  <varname>python26</varname> and <varname>python27</varname> do not include modules that require
+  external dependencies (to reduce dependency bloat). Following modules need to be added as
+  <varname>buildInput</varname> explicitly:
+</para>
+
+<itemizedlist>
+  <listitem><para><varname>python.modules.bsddb</varname></para></listitem>
+  <listitem><para><varname>python.modules.curses</varname></para></listitem>
+  <listitem><para><varname>python.modules.curses_panel</varname></para></listitem>
+  <listitem><para><varname>python.modules.crypt</varname></para></listitem>
+  <listitem><para><varname>python.modules.gdbm</varname></para></listitem>
+  <listitem><para><varname>python.modules.sqlite3</varname></para></listitem>
+  <listitem><para><varname>python.modules.tkinter</varname></para></listitem>
+  <listitem><para><varname>python.modules.readline</varname></para></listitem>
+</itemizedlist>
+
+<para>For convenience <varname>python27Full</varname> and <varname>python26Full</varname>
+are provided with all modules included.</para>
+
+<para>
+  Python packages that
+  use <link xlink:href="http://pypi.python.org/pypi/setuptools/"><literal>setuptools</literal></link> or <literal>distutils</literal>,
+  can be built using the <varname>buildPythonPackage</varname> function as documented below.
+</para>
+
+<para>
+ All packages depending on any Python interpreter get appended <varname>$out/${python.sitePackages}</varname>
+ to <literal>$PYTHONPATH</literal> if such directory exists.
+</para>
+
+<variablelist>
+  <title>
+     Useful attributes on interpreters packages:
+  </title>
+
+  <varlistentry>
+    <term><varname>libPrefix</varname></term>
+    <listitem><para>
+        Name of the folder in <literal>${python}/lib/</literal> for corresponding interpreter.
+    </para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><varname>interpreter</varname></term>
+    <listitem><para>
+        Alias for <literal>${python}/bin/${executable}.</literal>
+    </para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><varname>buildEnv</varname></term>
+    <listitem><para>
+        Function to build python interpreter environments with extra packages bundled together.
+        See <xref linkend="ssec-python-build-env" /> for usage and documentation.
+    </para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><varname>sitePackages</varname></term>
+    <listitem><para>
+      Alias for <literal>lib/${libPrefix}/site-packages</literal>.
+    </para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><varname>executable</varname></term>
+    <listitem><para>
+      Name of the interpreter executable, ie <literal>python3.4</literal>.
+    </para></listitem>
+  </varlistentry>
+
+</variablelist>
+<section xml:id="ssec-build-python-package"><title><varname>buildPythonPackage</varname> function</title>
+
+  <para>
+  The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/generic/default.nix">
+  <filename>pkgs/development/python-modules/generic/default.nix</filename></link>.
+  Example usage:
+
+<programlisting language="nix">
+twisted = buildPythonPackage {
+  name = "twisted-8.1.0";
+
+  src = pkgs.fetchurl {
+    url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
+    sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
+  };
+
+  propagatedBuildInputs = [ self.ZopeInterface ];
+
+  meta = {
+    homepage = http://twistedmatrix.com/;
+    description = "Twisted, an event-driven networking engine written in Python";
+    license = stdenv.lib.licenses.mit;
+  };
+};
+</programlisting>
+
+  Most of Python packages that use <varname>buildPythonPackage</varname> are defined
+  in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/python-packages.nix"><filename>pkgs/top-level/python-packages.nix</filename></link>
+  and generated for each python interpreter separately into attribute sets <varname>python26Packages</varname>,
+  <varname>python27Packages</varname>, <varname>python35Packages</varname>, <varname>python33Packages</varname>,
+  <varname>python34Packages</varname> and <varname>pypyPackages</varname>.
+  </para>
+
+  <para>
+    <function>buildPythonPackage</function> mainly does four things:
+
+    <orderedlist>
+      <listitem><para>
+        In the <varname>buildPhase</varname>, it calls
+        <literal>${python.interpreter} setup.py bdist_wheel</literal> to build a wheel binary zipfile.
+      </para></listitem>
+
+      <listitem><para>
+        In the <varname>installPhase</varname>, it installs the wheel file using
+        <literal>pip install *.whl</literal>.
+      </para></listitem>
+
+      <listitem><para>
+        In the <varname>postFixup</varname> phase, <literal>wrapPythonPrograms</literal>
+        bash function is called to wrap all programs in <filename>$out/bin/*</filename>
+        directory to include <literal>$PYTHONPATH</literal> and <literal>$PATH</literal>
+        environment variables.
+      </para></listitem>
+
+      <listitem><para>
+        In the <varname>installCheck</varname> phase, <literal>${python.interpreter} setup.py test</literal>
+        is ran.
+      </para></listitem>
+    </orderedlist>
+  </para>
+
+  <para>By default <varname>doCheck = true</varname> is set</para>
+
+  <para>
+    As in Perl, dependencies on other Python packages can be specified in the
+    <varname>buildInputs</varname> and
+    <varname>propagatedBuildInputs</varname> attributes.  If something is
+    exclusively a build-time dependency, use
+    <varname>buildInputs</varname>; if it’s (also) a runtime dependency,
+    use <varname>propagatedBuildInputs</varname>.
+  </para>
+
+  <para>
+    By default <varname>meta.platforms</varname> is set to the same value
+    as the interpreter unless overriden otherwise.
+  </para>
+
+  <variablelist>
+    <title>
+      <varname>buildPythonPackage</varname> parameters
+      (all parameters from <varname>mkDerivation</varname> function are still supported)
+    </title>
+
+    <varlistentry>
+      <term><varname>namePrefix</varname></term>
+      <listitem><para>
+        Prepended text to <varname>${name}</varname> parameter.
+        Defaults to <literal>"python3.3-"</literal> for Python 3.3, etc. Set it to
+        <literal>""</literal>
+        if you're packaging an application or a command line tool.
+      </para></listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><varname>disabled</varname></term>
+      <listitem><para>
+        If <varname>true</varname>, package is not build for
+        particular python interpreter version. Grep around
+        <filename>pkgs/top-level/python-packages.nix</filename>
+        for examples.
+      </para></listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><varname>setupPyBuildFlags</varname></term>
+      <listitem><para>
+        List of flags passed to <command>setup.py build_ext</command> command.
+      </para></listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><varname>pythonPath</varname></term>
+      <listitem><para>
+        List of packages to be added into <literal>$PYTHONPATH</literal>.
+        Packages in <varname>pythonPath</varname> are not propagated
+        (contrary to <varname>propagatedBuildInputs</varname>).
+      </para></listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><varname>preShellHook</varname></term>
+      <listitem><para>
+        Hook to execute commands before <varname>shellHook</varname>.
+      </para></listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><varname>postShellHook</varname></term>
+      <listitem><para>
+        Hook to execute commands after <varname>shellHook</varname>.
+      </para></listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><varname>makeWrapperArgs</varname></term>
+      <listitem><para>
+        A list of strings. Arguments to be passed to
+        <varname>makeWrapper</varname>, which wraps generated binaries. By
+        default, the arguments to <varname>makeWrapper</varname> set
+        <varname>PATH</varname> and <varname>PYTHONPATH</varname> environment
+        variables before calling the binary. Additional arguments here can
+        allow a developer to set environment variables which will be
+        available when the binary is run. For example,
+        <varname>makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]</varname>.
+      </para></listitem>
+    </varlistentry>
+
+  </variablelist>
+
+</section>
+
+<section xml:id="ssec-python-build-env"><title><function>python.buildEnv</function> function</title>
+  <para>
+    Create Python environments using low-level <function>pkgs.buildEnv</function> function. Example <filename>default.nix</filename>:
+
+<programlisting language="nix">
+<![CDATA[with import <nixpkgs> {};
+
+python.buildEnv.override {
+  extraLibs = [ pkgs.pythonPackages.pyramid ];
+  ignoreCollisions = true;
+}]]>
+</programlisting>
+
+    Running <command>nix-build</command> will create
+    <filename>/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env</filename>
+    with wrapped binaries in <filename>bin/</filename>.
+  </para>
+
+  <para>
+  You can also use <varname>env</varname> attribute to create local
+  environments with needed packages installed (somewhat comparable to
+  <literal>virtualenv</literal>). For example, with the following
+  <filename>shell.nix</filename>:
+
+<programlisting language="nix">
+<![CDATA[with import <nixpkgs> {};
+
+(python3.buildEnv.override {
+  extraLibs = with python3Packages;
+    [ numpy
+      requests
+    ];
+}).env]]>
+</programlisting>
+
+  Running <command>nix-shell</command> will drop you into a shell where
+  <command>python</command> will have specified packages in its path.
+  </para>
+
+  <variablelist>
+    <title>
+      <function>python.buildEnv</function> arguments
+    </title>
+
+    <varlistentry>
+      <term><varname>extraLibs</varname></term>
+      <listitem><para>
+        List of packages installed inside the environment.
+      </para></listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><varname>postBuild</varname></term>
+      <listitem><para>
+        Shell command executed after the build of environment.
+      </para></listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><varname>ignoreCollisions</varname></term>
+      <listitem><para>
+         Ignore file collisions inside the environment (default is <varname>false</varname>).
+      </para></listitem>
+    </varlistentry>
+  </variablelist>
+</section>
+
+<section xml:id="ssec-python-tools"><title>Tools</title>
+
+<para>Packages inside nixpkgs are written by hand. However many tools
+exist in community to help save time. No tool is preferred at the moment.
+</para>
+
+<itemizedlist>
+
+  <listitem><para>
+    <link xlink:href="https://github.com/proger/python2nix">python2nix</link>
+    by Vladimir Kirillov
+  </para></listitem>
+
+  <listitem><para>
+    <link xlink:href="https://github.com/garbas/pypi2nix">pypi2nix</link>
+    by Rok Garbas
+  </para></listitem>
+
+  <listitem><para>
+    <link xlink:href="https://github.com/offlinehacker/pypi2nix">pypi2nix</link>
+    by Jaka Hudoklin
+  </para></listitem>
+
+</itemizedlist>
+
+</section>
+
+<section xml:id="ssec-python-development"><title>Development</title>
+
+  <para>
+    To develop Python packages <function>buildPythonPackage</function> has
+    additional logic inside <varname>shellPhase</varname> to run
+    <command>pip install -e . --prefix $TMPDIR/</command> for the package.
+  </para>
+
+  <warning><para><varname>shellPhase</varname> is executed only if <filename>setup.py</filename>
+  exists.</para></warning>
+
+  <para>
+    Given a <filename>default.nix</filename>:
+
+<programlisting language="nix">
+<![CDATA[with import <nixpkgs> {};
+
+buildPythonPackage {
+  name = "myproject";
+
+  buildInputs = with pkgs.pythonPackages; [ pyramid ];
+
+  src = ./.;
+}]]>
+</programlisting>
+
+    Running <command>nix-shell</command> with no arguments should give you
+    the environment in which the package would be build with
+    <command>nix-build</command>.
+  </para>
+
+  <para>
+    Shortcut to setup environments with C headers/libraries and python packages:
+
+    <programlisting language="bash">$ nix-shell -p pythonPackages.pyramid zlib libjpeg git</programlisting>
+  </para>
+
+  <note><para>
+    There is a boolean value <varname>lib.inNixShell</varname> set to
+    <varname>true</varname> if nix-shell is invoked.
+  </para></note>
+
+</section>
+
+<section xml:id="ssec-python-faq"><title>FAQ</title>
+
+<variablelist>
+
+  <varlistentry>
+    <term>How to solve circular dependencies?</term>
+    <listitem><para>
+      If you have packages <varname>A</varname> and <varname>B</varname> that
+      depend on each other, when packaging <varname>B</varname> override package
+      <varname>A</varname> not to depend on <varname>B</varname> as input
+      (and also the other way around).
+    </para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><varname>install_data / data_files</varname> problems resulting into <literal>error: could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc': Permission denied</literal></term>
+    <listitem><para>
+      <link xlink:href="https://bitbucket.org/pypa/setuptools/issue/130/install_data-doesnt-respect-prefix">
+      Known bug in setuptools <varname>install_data</varname> does not respect --prefix</link>. Example of
+      such package using the feature is <filename>pkgs/tools/X11/xpra/default.nix</filename>. As workaround
+      install it as an extra <varname>preInstall</varname> step:
+
+      <programlisting>${python.interpreter} setup.py install_data --install-dir=$out --root=$out
+sed -i '/ = data_files/d' setup.py</programlisting>
+    </para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>Rationale of non-existent global site-packages</term>
+    <listitem><para>
+      There is no need to have global site-packages in Nix. Each package has isolated
+      dependency tree and installing any python package will only populate <varname>$PATH</varname>
+      inside user environment. See <xref linkend="ssec-python-build-env" /> to create self-contained
+      interpreter with a set of packages.
+    </para></listitem>
+  </varlistentry>
+
+</variablelist>
+
+</section>
+
+
+<section xml:id="ssec-python-contrib"><title>Contributing guidelines</title>
+<para>
+  Following rules are desired to be respected:
+</para>
+
+<itemizedlist>
+
+  <listitem><para>
+    Make sure package builds for all python interpreters. Use <varname>disabled</varname> argument to
+    <function>buildPythonPackage</function> to set unsupported interpreters.
+  </para></listitem>
+
+  <listitem><para>
+    If tests need to be disabled for a package, make sure you leave a comment about reasoning.
+  </para></listitem>
+
+  <listitem><para>
+    Packages in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/python-packages.nix"><filename>pkgs/top-level/python-packages.nix</filename></link>
+    are sorted quasi-alphabetically to avoid merge conflicts.
+  </para></listitem>
+
+</itemizedlist>
+
+</section>
+
+</section>
+
diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml
new file mode 100644
index 00000000000..093c33c25a1
--- /dev/null
+++ b/doc/languages-frameworks/qt.xml
@@ -0,0 +1,70 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-qt">
+
+<title>Qt</title>
+
+<para>The information in this section applies to Qt 5.5 and later.</para>
+
+<para>Qt is an application development toolkit for C++. Although it is
+not a distinct programming language, there are special considerations
+for packaging Qt-based programs and libraries. A small set of tools
+and conventions has grown out of these considerations.</para>
+
+<section xml:id="ssec-qt-libraries"><title>Libraries</title>
+
+<para>Packages that provide libraries should be listed in
+<varname>qt5LibsFun</varname> so that the library is built with each
+Qt version. A set of packages is provided for each version of Qt; for
+example, <varname>qt5Libs</varname> always provides libraries built
+with the latest version, <varname>qt55Libs</varname> provides
+libraries built with Qt 5.5, and so on. To avoid version conflicts, no
+top-level attributes are created for these packages.</para>
+
+</section>
+
+<section xml:id="ssec-qt-programs"><title>Programs</title>
+
+<para>Application packages do not need to be built with every Qt
+version. To ensure consistency between the package's dependencies,
+call the package with <literal>qt5Libs.callPackage</literal> instead
+of the usual <literal>callPackage</literal>. An older version may be
+selected in case of incompatibility. For example, to build with Qt
+5.5, call the package with
+<literal>qt55Libs.callPackage</literal>.</para>
+
+<para>Several environment variables must be set at runtime for Qt
+applications to function correctly, including:</para>
+
+<itemizedlist>
+  <listitem><para><envar>QT_PLUGIN_PATH</envar></para></listitem>
+  <listitem><para><envar>QML_IMPORT_PATH</envar></para></listitem>
+  <listitem><para><envar>QML2_IMPORT_PATH</envar></para></listitem>
+  <listitem><para><envar>XDG_DATA_DIRS</envar></para></listitem>
+</itemizedlist>
+
+<para>To ensure that these are set correctly, the program must be wrapped by
+invoking <literal>wrapQtProgram <replaceable>program</replaceable></literal>
+during installation (for example, during
+<literal>fixupPhase</literal>). <literal>wrapQtProgram</literal>
+accepts the same options as <literal>makeWrapper</literal>.
+</para>
+
+</section>
+
+<section xml:id="ssec-qt-kde"><title>KDE</title>
+
+<para>Many of the considerations above also apply to KDE packages,
+especially the need to set the correct environment variables at
+runtime. To ensure that this is done, invoke <literal>wrapKDEProgram
+<replaceable>program</replaceable></literal> during
+installation. <literal>wrapKDEProgram</literal> also generates a
+<literal>ksycoca</literal> database so that required data and services
+can be found. Like its Qt counterpart,
+<literal>wrapKDEProgram</literal> accepts the same options as
+<literal>makeWrapper</literal>.</para>
+
+</section>
+
+</section>
+
diff --git a/doc/languages-frameworks/ruby.xml b/doc/languages-frameworks/ruby.xml
new file mode 100644
index 00000000000..a2b4475a4a5
--- /dev/null
+++ b/doc/languages-frameworks/ruby.xml
@@ -0,0 +1,46 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-ruby">
+
+<title>Ruby</title>
+
+  <para>There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a <filename>Gemfile</filename>, let bundler create a <filename>Gemfile.lock</filename>, and then convert
+  this into a nix expression that contains all Gem dependencies automatically.</para>
+
+  <para>For example, to package sensu, we did:</para>
+
+<screen>
+<![CDATA[$ cd pkgs/servers/monitoring
+$ mkdir sensu
+$ cat > Gemfile
+source 'https://rubygems.org'
+gem 'sensu'
+$ bundler package --path /tmp/vendor/bundle
+$ $(nix-build '<nixpkgs>' -A bundix)/bin/bundix
+$ cat > default.nix
+{ lib, bundlerEnv, ruby }:
+
+bundlerEnv {
+  name = "sensu-0.17.1";
+
+  inherit ruby;
+  gemfile = ./Gemfile;
+  lockfile = ./Gemfile.lock;
+  gemset = ./gemset.nix;
+
+  meta = with lib; {
+    description = "A monitoring framework that aims to be simple, malleable,
+and scalable.";
+    homepage    = http://sensuapp.org/;
+    license     = with licenses; mit;
+    maintainers = with maintainers; [ theuni ];
+    platforms   = platforms.unix;
+  };
+}]]>
+</screen>
+
+<para>Please check in the <filename>Gemfile</filename>, <filename>Gemfile.lock</filename> and the <filename>gemset.nix</filename> so future updates can be run easily.
+</para>
+
+</section>
+
diff --git a/doc/manual.xml b/doc/manual.xml
index 3ffe7fbb068..b4c35d1a379 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -15,7 +15,7 @@
   <xi:include href="configuration.xml" />
   <xi:include href="functions.xml" />
   <xi:include href="meta.xml" />
-  <xi:include href="language-support.xml" />
+  <xi:include href="languages-frameworks/index.xml" />
   <xi:include href="package-notes.xml" />
   <xi:include href="coding-conventions.xml" />
   <xi:include href="submitting-changes.xml" />