diff --git a/doc/language-support.xml b/doc/language-support.xml
index f33202d4553..5fb123ddfc1 100644
--- a/doc/language-support.xml
+++ b/doc/language-support.xml
@@ -283,24 +283,24 @@ are provided with all modules included.</para>
   <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>
+<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>
@@ -428,16 +428,14 @@ are provided with all modules included.</para>
   <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>
+<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>
@@ -507,22 +505,23 @@ exist in community to help save time. No tool is preferred at the moment.
     <command>${python.interpreter} setup.py develop</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>
+<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
@@ -615,11 +614,11 @@ sed -i '/ = data_files/d' setup.py</programlisting>
 <section xml:id="ssec-language-ruby"><title>Ruby</title>
   <para>For example, to package yajl-ruby package, use gem-nix:</para>
   
-  <screen>
-    $ nix-env -i gem-nix
-    $ gem-nix --no-user-install --nix-file=pkgs/development/interpreters/ruby/generated.nix yajl-ruby
-    $ nix-build -A rubyPackages.yajl-ruby
-  </screen>
+<screen>
+$ nix-env -i gem-nix
+$ gem-nix --no-user-install --nix-file=pkgs/development/interpreters/ruby/generated.nix yajl-ruby
+$ nix-build -A rubyPackages.yajl-ruby
+</screen>
 </section>