9 files changed, 303 insertions, 9 deletions
diff --git a/doc/languages-frameworks/emscripten.md b/doc/languages-frameworks/emscripten.section.md
index 24c49ec1409..24c49ec1409 100644
--- a/doc/languages-frameworks/emscripten.md
+++ b/doc/languages-frameworks/emscripten.section.md
diff --git a/doc/languages-frameworks/haskell.md b/doc/languages-frameworks/haskell.section.md
index 1623e0d276f..1623e0d276f 100644
--- a/doc/languages-frameworks/haskell.md
+++ b/doc/languages-frameworks/haskell.section.md
diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md
new file mode 100644
index 00000000000..005ed360285
--- /dev/null
+++ b/doc/languages-frameworks/idris.section.md
@@ -0,0 +1,39 @@
+Idris packages
+==============
+
+This directory contains build rules for idris packages. In addition,
+it contains several functions to build and compose those packages.
+Everything is exposed to the user via the `idrisPackages` attribute.
+
+callPackage
+------------
+
+This is like the normal nixpkgs callPackage function, specialized to
+idris packages.
+
+builtins
+---------
+
+This is a list of all of the libraries that come packaged with Idris
+itself.
+
+build-idris-package
+--------------------
+
+A function to build an idris package. Its sole argument is a set like
+you might pass to `stdenv.mkDerivation`, except `build-idris-package`
+sets several attributes for you. See `build-idris-package.nix` for
+details.
+
+build-builtin-package
+----------------------
+
+A version of `build-idris-package` specialized to builtin libraries.
+Mostly for internal use.
+
+with-packages
+-------------
+
+Bundle idris together with a list of packages. Because idris currently
+only supports a single directory in its library path, you must include
+all desired libraries here, including `prelude` and `base`.
\ No newline at end of file
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 6743c131201..a1c265f6748 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -17,20 +17,20 @@ such as Perl or Haskell.  These are described in this chapter.</para>
 <xi:include href="bower.xml" />
 <xi:include href="coq.xml" />
 <xi:include href="go.xml" />
-<xi:include href="haskell.xml" />
-<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md  -->
+<xi:include href="haskell.section.xml" />
+<xi:include href="idris.section.xml" />
 <xi:include href="java.xml" />
 <xi:include href="lua.xml" />
-<xi:include href="node.xml" /> <!-- generated from ../../pkgs/development/node-packages/README.md  -->
+<xi:include href="node.section.xml" />
 <xi:include href="perl.xml" />
-<xi:include href="python.xml" />
+<xi:include href="python.section.xml" />
 <xi:include href="qt.xml" />
-<xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md  -->
+<xi:include href="r.section.xml" />
 <xi:include href="ruby.xml" />
-<xi:include href="rust.xml" />
+<xi:include href="rust.section.xml" />
 <xi:include href="texlive.xml" />
-<xi:include href="vim.xml" />
-<xi:include href="emscripten.xml" />
+<xi:include href="vim.section.xml" />
+<xi:include href="emscripten.section.xml" />
 
 
 </chapter>
diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md
new file mode 100644
index 00000000000..17a203ed12b
--- /dev/null
+++ b/doc/languages-frameworks/node.section.md
@@ -0,0 +1,51 @@
+Node.js packages
+================
+The `pkgs/development/node-packages` folder contains a generated collection of
+[NPM packages](https://npmjs.com/) that can be installed with the Nix package
+manager.
+
+As a rule of thumb, the package set should only provide *end user* software
+packages, such as command-line utilities. Libraries should only be added to the
+package set if there is a non-NPM package that requires it.
+
+When it is desired to use NPM libraries in a development project, use the
+`node2nix` generator directly on the `package.json` configuration file of the
+project.
+
+The package set also provides support for multiple Node.js versions. The policy
+is that a new package should be added to the collection for the latest stable LTS
+release (which is currently 6.x), unless there is an explicit reason to support
+a different release.
+
+If your package uses native addons, you need to examine what kind of native
+build system it uses. Here are some examples:
+
+* `node-gyp`
+* `node-gyp-builder`
+* `node-pre-gyp`
+
+After you have identified the correct system, you need to override your package
+expression while adding in build system as a build input. For example, `dat`
+requires `node-gyp-build`, so we override its expression in `default-v6.nix`:
+
+```nix
+dat = nodePackages.dat.override (oldAttrs: {
+  buildInputs = oldAttrs.buildInputs ++ [ nodePackages.node-gyp-build ];
+});
+```
+
+To add a package from NPM to nixpkgs:
+
+ 1. Modify `pkgs/development/node-packages/node-packages-v6.json` to add, update
+    or remove package entries. (Or `pkgs/development/node-packages/node-packages-v4.json`
+    for packages depending on Node.js 4.x)
+ 2. Run the script: `(cd pkgs/development/node-packages && ./generate.sh)`.
+ 3. Build your new package to test your changes:
+    `cd /path/to/nixpkgs && nix-build -A nodePackages.<new-or-updated-package>`.
+    To build against a specific Node.js version (e.g. 4.x):
+    `nix-build -A nodePackages_4_x.<new-or-updated-package>`
+ 4. Add and commit all modified and generated files.
+
+For more information about the generation process, consult the
+[README.md](https://github.com/svanderburg/node2nix) file of the `node2nix`
+tool.
diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.section.md
index 0f871395854..0f871395854 100644
--- a/doc/languages-frameworks/python.md
+++ b/doc/languages-frameworks/python.section.md
diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md
new file mode 100644
index 00000000000..c8f02bd1478
--- /dev/null
+++ b/doc/languages-frameworks/r.section.md
@@ -0,0 +1,120 @@
+R packages
+==========
+
+## Installation
+
+Define an environment for R that contains all the libraries that you'd like to
+use by adding the following snippet to your $HOME/.config/nixpkgs/config.nix file:
+
+```nix
+{
+    packageOverrides = super: let self = super.pkgs; in
+    {
+
+        rEnv = super.rWrapper.override {
+            packages = with self.rPackages; [
+                devtools
+                ggplot2
+                reshape2
+                yaml
+                optparse
+                ];
+        };
+    };
+}
+```
+
+Then you can use `nix-env -f "<nixpkgs>" -iA rEnv` to install it into your user
+profile. The set of available libraries can be discovered by running the
+command `nix-env -f "<nixpkgs>" -qaP -A rPackages`. The first column from that
+output is the name that has to be passed to rWrapper in the code snipped above.
+
+However, if you'd like to add a file to your project source to make the
+environment available for other contributors, you can create a `default.nix`
+file like so:
+```nix
+let
+  pkgs = import <nixpkgs> {};
+  stdenv = pkgs.stdenv;
+in with pkgs; {
+  myProject = stdenv.mkDerivation {
+    name = "myProject";
+    version = "1";
+    src = if pkgs.lib.inNixShell then null else nix;
+
+    buildInputs = with rPackages; [
+      R
+      ggplot2
+      knitr
+    ];
+  };
+}
+```
+and then run `nix-shell .` to be dropped into a shell with those packages
+available.
+
+## RStudio
+
+RStudio uses a standard set of packages and ignores any custom R
+environments or installed packages you may have.  To create a custom
+environment, see `rstudioWrapper`, which functions similarly to
+`rWrapper`:
+
+```nix
+{
+    packageOverrides = super: let self = super.pkgs; in
+    {
+
+        rstudioEnv = super.rstudioWrapper.override {
+            packages = with self.rPackages; [
+                dplyr
+                ggplot2
+                reshape2
+                ];
+        };
+    };
+}
+```
+
+Then like above, `nix-env -f "<nixpkgs>" -iA rstudioEnv` will install
+this into your user profile.
+
+Alternatively, you can create a self-contained `shell.nix` without the need to
+modify any configuration files:
+
+```nix
+{ pkgs ? import <nixpkgs> {}
+}:
+
+pkgs.rstudioWrapper.override {
+  packages = with pkgs.rPackages; [ dplyr ggplot2 reshape2 ];
+}
+
+```
+
+Executing `nix-shell` will then drop you into an environment equivalent to the
+one above. If you need additional packages just add them to the list and
+re-enter the shell.
+
+## Updating the package set
+
+```bash
+nix-shell generate-shell.nix
+
+Rscript generate-r-packages.R cran  > cran-packages.nix.new
+mv cran-packages.nix.new cran-packages.nix
+
+Rscript generate-r-packages.R bioc  > bioc-packages.nix.new
+mv bioc-packages.nix.new bioc-packages.nix
+```
+
+`generate-r-packages.R <repo>` reads  `<repo>-packages.nix`, therefor the renaming.
+
+
+## Testing if the Nix-expression could be evaluated
+
+```bash
+nix-build test-evaluation.nix --dry-run
+```
+
+If this exits fine, the expression is ok. If not, you have to edit `default.nix`
diff --git a/doc/languages-frameworks/rust.md b/doc/languages-frameworks/rust.section.md
index f0498eac5b1..b77c41e9b22 100644
--- a/doc/languages-frameworks/rust.md
+++ b/doc/languages-frameworks/rust.section.md
@@ -16,6 +16,12 @@ cargo
 into the `environment.systemPackages` or bring them into
 scope with `nix-shell -p rustc cargo`.
 
+> If you are using NixOS and you want to use rust without a nix expression you
+> probably want to add the following in your `configuration.nix` to build
+> crates with C dependencies.
+>
+>     environment.systemPackages = [binutils gcc gnumake openssl pkgconfig]
+
 For daily builds (beta and nightly) use either rustup from
 nixpkgs or use the [Rust nightlies
 overlay](#using-the-rust-nightlies-overlay).
@@ -76,7 +82,7 @@ an example for a minimal `hello` crate:
      Compiling hello v0.1.0 (file:///tmp/hello)
       Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs
     $ carnix -o hello.nix --src ./. Cargo.lock --standalone
-    $ nix-build hello.nix
+    $ nix-build hello.nix -A hello_0_1_0
 
 Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
 
@@ -276,6 +282,84 @@ features, we would write:
 
 Where `diesel.nix` is the file generated by Carnix, as explained above.
 
+
+## Setting Up `nix-shell`
+Oftentimes you want to develop code from within `nix-shell`. Unfortunately
+`buildRustCrate` does not support common `nix-shell` operations directly
+(see [this issue](https://github.com/NixOS/nixpkgs/issues/37945))
+so we will use `stdenv.mkDerivation` instead.
+
+Using the example `hello` project above, we want to do the following:
+- Have access to `cargo` and `rustc`
+- Have the `openssl` library available to a crate through it's _normal_
+  compilation mechanism (`pkg-config`).
+
+A typical `shell.nix` might look like:
+
+```
+with import <nixpkgs> {};
+
+stdenv.mkDerivation {
+  name = "rust-env";
+  buildInputs = [
+    rustc cargo
+
+    # Example Additional Dependencies
+    pkgconfig openssl
+  ];
+
+  # Set Environment Variables
+  RUST_BACKTRACE = 1;
+}
+```
+
+You should now be able to run the following:
+```
+$ nix-shell --pure
+$ cargo build
+$ cargo test
+```
+
+### Controlling Rust Version Inside `nix-shell`
+To control your rust version (i.e. use nightly) from within `shell.nix` (or
+other nix expressions) you can use the following `shell.nix`
+
+```
+# Latest Nightly
+with import <nixpkgs> {};
+let src = fetchFromGitHub {
+      owner = "mozilla";
+      repo = "nixpkgs-mozilla";
+      # commit from: 2018-03-27
+      rev = "2945b0b6b2fd19e7d23bac695afd65e320efcebe";
+      sha256 = "034m1dryrzh2lmjvk3c0krgip652dql46w5yfwpvh7gavd3iypyw";
+   };
+in
+with import "${src.out}/rust-overlay.nix" pkgs pkgs;
+stdenv.mkDerivation {
+  name = "rust-env";
+  buildInputs = [
+    # Note: to use use stable, just replace `nightly` with `stable`
+    latest.rustChannels.nightly.rust
+
+    # Add some extra dependencies from `pkgs`
+    pkgconfig openssl
+  ];
+
+  # Set Environment Variables
+  RUST_BACKTRACE = 1;
+}
+```
+
+Now run:
+```
+$ rustc --version
+rustc 1.26.0-nightly (188e693b3 2018-03-26)
+```
+
+To see that you are using nightly.
+
+
 ## Using the Rust nightlies overlay
 
 Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope.
diff --git a/doc/languages-frameworks/vim.md b/doc/languages-frameworks/vim.section.md
index 1d6a4fe8da8..1d6a4fe8da8 100644
--- a/doc/languages-frameworks/vim.md
+++ b/doc/languages-frameworks/vim.section.md