Merge pull request #37749 from grahamc/nixpkgs-docs

Make Nixpkgs docs less frustrating to hack on

20 files changed, 352 insertions, 330 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 000000000000..d8e765e38c2d
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,5 @@
+*.chapter.xml
+*.section.xml
+.version
+out
+manual-full.xml
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 000000000000..52d1f4630a8e
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,74 @@
+MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md)))
+
+.PHONY: all
+all: validate out/html/index.html out/epub/manual.epub
+
+.PHONY: debug
+debug:
+	nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
+.PHONY: clean
+clean:
+	rm -f ${MD_TARGETS} .version manual-full.xml
+	rm -rf ./out/
+
+.PHONY: validate
+validate: manual-full.xml
+	jing "$$RNG" manual-full.xml
+
+out/html/index.html: manual-full.xml style.css
+	mkdir -p out/html
+	xsltproc $$xsltFlags \
+		--nonet --xinclude \
+		--output $@ \
+		"$$XSL/docbook/xhtml/docbook.xsl" \
+		./manual-full.xml
+
+	cp ./style.css out/html/style.css
+
+	mkdir -p out/html/images/callouts
+	cp "$$XSL/docbook/images/callouts/"*.gif out/html/images/callouts/
+	chmod u+w -R out/html/images/
+
+out/epub/manual.epub: manual-full.xml
+	mkdir -p out/epub/scratch
+	xsltproc $$xsltFlags --nonet \
+		--output out/epub/scratch/ \
+		"$$XSL/docbook/epub/docbook.xsl" \
+		./manual-full.xml
+
+	cp "$$XSL/docbook/images/callouts/"*.gif out/epub/scratch/OEBPS
+	echo "application/epub+zip" > mimetype
+	zip -0Xq "out/epub/manual.epub" mimetype
+	rm mimetype
+	cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" *
+	rm -rf "out/epub/scratch/"
+
+manual-full.xml: ${MD_TARGETS} .version *.xml
+	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
+
+.version:
+	nix-instantiate --eval \
+		-E '(import ../lib).nixpkgsVersion' > .version
+
+%.section.xml: %.section.md
+	pandoc $^ -w docbook+smart \
+		-f markdown+smart \
+	  | sed -e 's|<ulink url=|<link xlink:href=|' \
+	      -e 's|</ulink>|</link>|' \
+	      -e 's|<sect. id=|<section xml:id=|' \
+	      -e 's|</sect[0-9]>|</section>|' \
+	      -e '1s| id=| xml:id=|' \
+	      -e '1s|\(<[^ ]* \)|\1xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" |' \
+	| cat  > $@
+
+%.chapter.xml: %.chapter.md
+	pandoc $^ -w docbook+smart \
+		--top-level-division=chapter \
+		-f markdown+smart \
+	  | sed -e 's|<ulink url=|<link xlink:href=|' \
+	      -e 's|</ulink>|</link>|' \
+	      -e 's|<sect. id=|<section xml:id=|' \
+	      -e 's|</sect[0-9]>|</section>|' \
+	      -e '1s| id=| xml:id=|' \
+	      -e '1s|\(<[^ ]* \)|\1|' \
+	| cat  > $@
diff --git a/doc/contributing.xml b/doc/contributing.xml
index a83059aa36e6..7aa0df271ff4 100644
--- a/doc/contributing.xml
+++ b/doc/contributing.xml
@@ -6,12 +6,27 @@
 
 <para>The DocBook sources of the Nixpkgs manual are in the <filename
 xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename>
-subdirectory of the Nixpkgs repository. If you make modifications to
-the manual, it's important to build it before committing. You can do that as follows:
+subdirectory of the Nixpkgs repository.</para>
+
+<para>You can quickly check your edits with <command>make</command>:</para>
+
+<screen>
+  $ cd /path/to/nixpkgs/doc
+  $ nix-shell
+  [nix-shell]$ make
+</screen>
+
+<para>If you experience problems, run <command>make debug</command>
+to help understand the docbook errors.</para>
+
+<para>After making modifications to the manual, it's important to
+build it before committing. You can do that as follows:
 
 <screen>
-$ cd /path/to/nixpkgs
-$ nix-build doc
+  $ cd /path/to/nixpkgs/doc
+  $ nix-shell
+  [nix-shell]$ make clean
+  [nix-shell]$ nix-build .
 </screen>
 
 If the build succeeds, the manual will be in
diff --git a/doc/default.nix b/doc/default.nix
index ec458634a42c..5869920415c3 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -7,116 +7,35 @@ in
 pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
-
-  buildInputs = with pkgs; [ pandoc libxml2 libxslt zip ];
-
-  xsltFlags = ''
-    --param section.autolabel 1
-    --param section.label.includes.component.label 1
-    --param html.stylesheet 'style.css'
-    --param xref.with.number.and.title 1
-    --param toc.section.depth 3
-    --param admon.style '''
-    --param callout.graphics.extension '.gif'
-  '';
-
-
-  buildCommand = let toDocbook = { useChapters ? false, inputFile, outputFile }:
-    let
-      extraHeader = lib.optionalString (!useChapters)
-        ''xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" '';
-    in ''
-      {
-        pandoc '${inputFile}' -w docbook+smart ${lib.optionalString useChapters "--top-level-division=chapter"} \
-          -f markdown+smart \
-          | sed -e 's|<ulink url=|<link xlink:href=|' \
-              -e 's|</ulink>|</link>|' \
-              -e 's|<sect. id=|<section xml:id=|' \
-              -e 's|</sect[0-9]>|</section>|' \
-              -e '1s| id=| xml:id=|' \
-              -e '1s|\(<[^ ]* \)|\1${extraHeader}|'
-      } > '${outputFile}'
-    '';
-  in
-
-  ''
-    ln -s '${sources}/'*.xml .
-    mkdir ./languages-frameworks
-    cp -s '${sources-langs}'/* ./languages-frameworks
-  ''
-  + toDocbook {
-      inputFile = ./introduction.md;
-      outputFile = "introduction.xml";
-      useChapters = true;
-    }
-  + toDocbook {
-      inputFile = ./shell.md;
-      outputFile = "shell.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/python.md;
-      outputFile = "./languages-frameworks/python.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/haskell.md;
-      outputFile = "./languages-frameworks/haskell.xml";
-    }
-  + toDocbook {
-      inputFile = ../pkgs/development/idris-modules/README.md;
-      outputFile = "languages-frameworks/idris.xml";
-    }
-  + toDocbook {
-      inputFile = ../pkgs/development/node-packages/README.md;
-      outputFile = "languages-frameworks/node.xml";
-    }
-  + toDocbook {
-      inputFile = ../pkgs/development/r-modules/README.md;
-      outputFile = "languages-frameworks/r.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/rust.md;
-      outputFile = "./languages-frameworks/rust.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/vim.md;
-      outputFile = "./languages-frameworks/vim.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/emscripten.md;
-      outputFile = "./languages-frameworks/emscripten.xml";
-    }
-  + ''
+  buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing ];
+
+  src = ./.;
+
+  XSL = "${pkgs.docbook5_xsl}/xml/xsl";
+  RNG = "${pkgs.docbook5}/xml/rng/docbook/docbook.rng";
+  xsltFlags = lib.concatStringsSep " " [
+    "--param section.autolabel 1"
+    "--param section.label.includes.component.label 1"
+    "--param html.stylesheet 'style.css'"
+    "--param xref.with.number.and.title 1"
+    "--param toc.section.depth 3"
+    "--param admon.style ''"
+    "--param callout.graphics.extension '.gif'"
+  ];
+
+  postPatch = ''
     echo ${lib.nixpkgsVersion} > .version
+  '';
 
-    # validate against relaxng schema
-    xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
-    ${pkgs.jing}/bin/jing ${pkgs.docbook5}/xml/rng/docbook/docbook.rng manual-full.xml
-
-    dst=$out/share/doc/nixpkgs
-    mkdir -p $dst
-    xsltproc $xsltFlags --nonet --xinclude \
-      --output $dst/manual.html \
-      ${pkgs.docbook5_xsl}/xml/xsl/docbook/xhtml/docbook.xsl \
-      ./manual.xml
-
-    cp ${./style.css} $dst/style.css
-
-    mkdir -p $dst/images/callouts
-    cp "${pkgs.docbook5_xsl}/xml/xsl/docbook/images/callouts/"*.gif $dst/images/callouts/
-
-    mkdir -p $out/nix-support
-    echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products
+  installPhase = ''
+    dest="$out/share/doc/nixpkgs"
+    mkdir -p "$(dirname "$dest")"
+    mv out/html "$dest"
+    mv "$dest/index.html" "$dest/manual.html"
 
-    xsltproc $xsltFlags --nonet --xinclude \
-      --output $dst/epub/ \
-      ${pkgs.docbook5_xsl}/xml/xsl/docbook/epub/docbook.xsl \
-      ./manual.xml
+    mv out/epub/manual.epub "$dest/nixpkgs-manual.epub"
 
-    cp -r $dst/images $dst/epub/OEBPS
-    echo "application/epub+zip" > mimetype
-    manual="$dst/nixpkgs-manual.epub"
-    zip -0Xq "$manual" mimetype
-    cd $dst/epub && zip -Xr9D "$manual" *
-    rm -rf $dst/epub
+    mkdir -p $out/nix-support/
+    echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products
   '';
 }
diff --git a/doc/introduction.md b/doc/introduction.chapter.md
index 8b03221c64b1..8b03221c64b1 100644
--- a/doc/introduction.md
+++ b/doc/introduction.chapter.md
diff --git a/doc/languages-frameworks/emscripten.md b/doc/languages-frameworks/emscripten.section.md
index 24c49ec1409c..24c49ec1409c 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 1623e0d276f2..1623e0d276f2 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 000000000000..005ed3602851
--- /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 6743c131201f..a1c265f67484 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 000000000000..17a203ed12be
--- /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 0f871395854c..0f871395854c 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 000000000000..c8f02bd14780
--- /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 f0498eac5b19..f0498eac5b19 100644
--- a/doc/languages-frameworks/rust.md
+++ b/doc/languages-frameworks/rust.section.md
diff --git a/doc/languages-frameworks/vim.md b/doc/languages-frameworks/vim.section.md
index 1d6a4fe8da8d..1d6a4fe8da8d 100644
--- a/doc/languages-frameworks/vim.md
+++ b/doc/languages-frameworks/vim.section.md
diff --git a/doc/manual.xml b/doc/manual.xml
index eb0a24789d44..385079eb5785 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -9,7 +9,7 @@
 
   </info>
 
-  <xi:include href="introduction.xml" />
+  <xi:include href="introduction.chapter.xml" />
   <xi:include href="quick-start.xml" />
   <xi:include href="stdenv.xml" />
   <xi:include href="multiple-output.xml" />
diff --git a/doc/shell.nix b/doc/shell.nix
new file mode 100644
index 000000000000..22590142ee1a
--- /dev/null
+++ b/doc/shell.nix
@@ -0,0 +1,4 @@
+{ pkgs ? import ../. {} }:
+(import ./default.nix).overrideAttrs (x: {
+  buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ];
+})
diff --git a/doc/shell.md b/doc/shell.section.md
index 079574d4ae86..cb8832a814fc 100644
--- a/doc/shell.md
+++ b/doc/shell.section.md
@@ -4,6 +4,8 @@ author: zimbatm
 date: 2017-10-30
 ---
 
+# mkShell
+
 pkgs.mkShell is a special kind of derivation that is only useful when using
 it combined with nix-shell. It will in fact fail to instantiate when invoked
 with nix-build.
diff --git a/pkgs/development/idris-modules/README.md b/pkgs/development/idris-modules/README.md
index 005ed3602851..80b7ccefbcfa 100644
--- a/pkgs/development/idris-modules/README.md
+++ b/pkgs/development/idris-modules/README.md
@@ -1,39 +1 @@
-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
+Moved to [/doc/languages-frameworks/idris.section.md](/doc/languages-frameworks/idris.section.md)
diff --git a/pkgs/development/node-packages/README.md b/pkgs/development/node-packages/README.md
index 17a203ed12be..9760285a915e 100644
--- a/pkgs/development/node-packages/README.md
+++ b/pkgs/development/node-packages/README.md
@@ -1,51 +1 @@
-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.
+Moved to [/doc/languages-frameworks/node.section.md](/doc/languages-frameworks/node.section.md)
diff --git a/pkgs/development/r-modules/README.md b/pkgs/development/r-modules/README.md
index c8f02bd14780..e6fd09d76471 100644
--- a/pkgs/development/r-modules/README.md
+++ b/pkgs/development/r-modules/README.md
@@ -1,120 +1 @@
-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`
+Moved to [/doc/languages-frameworks/r.section.md](/doc/languages-frameworks/r.section.md)