7 files changed, 64 insertions, 31 deletions
diff --git a/doc/Makefile b/doc/Makefile
index d4f1250c4d7..1d3a0e7ccbd 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -3,6 +3,7 @@ MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$'
 PANDOC ?= pandoc
 
 pandoc_media_dir = media
+# NOTE: Keep in sync with NixOS manual (/nixos/doc/manual/md-to-db.sh).
 # TODO: Remove raw-attribute when we can get rid of DocBook altogether.
 pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
 pandoc_flags = --extract-media=$(pandoc_media_dir) \
@@ -101,10 +102,10 @@ functions/library/generated: doc-support/result
 %.section.xml: %.section.md
 	$(PANDOC) $^ -t docbook \
 		$(pandoc_flags) \
-	| cat  > $@
+		-o $@
 
 %.chapter.xml: %.chapter.md
 	$(PANDOC) $^ -t docbook \
 		--top-level-division=chapter \
 		$(pandoc_flags) \
-	| cat  > $@
+		-o $@
diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md
index 29b8ec493e7..221ba300619 100644
--- a/doc/contributing/submitting-changes.chapter.md
+++ b/doc/contributing/submitting-changes.chapter.md
@@ -62,7 +62,7 @@
 
 - Push your changes to your fork of nixpkgs.
 - Create the pull request
-- Follow [the contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md#submitting-changes).
+- Follow [the contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#submitting-changes).
 
 ## Submitting security fixes {#submitting-changes-submitting-security-fixes}
 
@@ -193,7 +193,7 @@ It’s important to test any executables generated by a build when you change or
 
 ### Meets Nixpkgs contribution standards {#submitting-changes-contribution-standards}
 
-The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md). The contributing document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc\... Everyone should read and understand the standards the community has for contributing before submitting a pull request.
+The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md). The contributing document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc\... Everyone should read and understand the standards the community has for contributing before submitting a pull request.
 
 ## Hotfixing pull requests {#submitting-changes-hotfixing-pull-requests}
 
diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix
index 5199b949e7b..f6d613cac0b 100644
--- a/doc/doc-support/lib-function-docs.nix
+++ b/doc/doc-support/lib-function-docs.nix
@@ -22,5 +22,6 @@ with pkgs; stdenv.mkDerivation {
     docgen lists 'List manipulation functions'
     docgen debug 'Debugging functions'
     docgen options 'NixOS / nixpkgs option handling'
+    docgen sources 'Source filtering functions'
   '';
 }
diff --git a/doc/functions/generators.section.md b/doc/functions/generators.section.md
index bb8426d8087..d54e5027c79 100644
--- a/doc/functions/generators.section.md
+++ b/doc/functions/generators.section.md
@@ -49,7 +49,7 @@ str\:ange:"very::strange"
 merge:"diff3"
 ```
 
-::: note
+::: {.note}
 Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`.
 :::
 
diff --git a/doc/functions/library.xml b/doc/functions/library.xml
index 6ffb944b5a6..21bcf5b88c9 100644
--- a/doc/functions/library.xml
+++ b/doc/functions/library.xml
@@ -25,4 +25,6 @@
  <xi:include href="./library/generated/debug.xml" />
 
  <xi:include href="./library/generated/options.xml" />
+
+ <xi:include href="./library/generated/sources.xml" />
 </section>
diff --git a/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md
index 9b92a80f471..5ffc23173d6 100644
--- a/doc/languages-frameworks/ocaml.section.md
+++ b/doc/languages-frameworks/ocaml.section.md
@@ -4,60 +4,83 @@ OCaml libraries should be installed in `$(out)/lib/ocaml/${ocaml.version}/site-l
 
 Given that most of the OCaml ecosystem is now built with dune, nixpkgs includes a convenience build support function called `buildDunePackage` that will build an OCaml package using dune, OCaml and findlib and any additional dependencies provided as `buildInputs` or `propagatedBuildInputs`.
 
-Here is a simple package example. It defines an (optional) attribute `minimumOCamlVersion` that will be used to throw a descriptive evaluation error if building with an older OCaml is attempted. It uses the `fetchFromGitHub` fetcher to get its source. It sets the `doCheck` (optional) attribute to `true` which means that tests will be run with `dune runtest -p angstrom` after the build (`dune build -p angstrom`) is complete. It uses `alcotest` as a build input (because it is needed to run the tests) and `bigstringaf` and `result` as propagated build inputs (thus they will also be available to libraries depending on this library). The library will be installed using the `angstrom.install` file that dune generates.
+Here is a simple package example.
+
+- It defines an (optional) attribute `minimalOCamlVersion` that will be used to
+  throw a descriptive evaluation error if building with an older OCaml is
+  attempted.
+
+- It uses the `fetchFromGitHub` fetcher to get its source.
+
+- `useDune2 = true` ensures that the latest version of Dune is used for the
+  build (this may become the default value in a future release).
+
+- It sets the optional `doCheck` attribute such that tests will be run with
+  `dune runtest -p angstrom` after the build (`dune build -p angstrom`) is
+  complete, but only if the Ocaml version is at at least `"4.05"`.
+
+- It uses the package `ocaml-syntax-shims` as a build input, `alcotest` and
+  `ppx_let` as check inputs (because they are needed to run the tests), and
+  `bigstringaf` and `result` as propagated build inputs (thus they will also be
+  available to libraries depending on this library).
+
+- The library will be installed using the `angstrom.install` file that dune
+  generates.
 
 ```nix
-{ lib
-, fetchFromGitHub
-, buildDunePackage
-, alcotest
-, result
-, bigstringaf
-}:
+{ lib,
+  fetchFromGitHub,
+  buildDunePackage,
+  ocaml,
+  ocaml-syntax-shims,
+  alcotest,
+  result,
+  bigstringaf,
+  ppx_let }:
 
 buildDunePackage rec {
   pname = "angstrom";
-  version = "0.10.0";
+  version = "0.15.0";
+  useDune2 = true;
 
-  minimumOCamlVersion = "4.03";
+  minimalOCamlVersion = "4.04";
 
   src = fetchFromGitHub {
     owner  = "inhabitedtype";
     repo   = pname;
     rev    = version;
-    sha256 = "0lh6024yf9ds0nh9i93r9m6p5psi8nvrqxl5x7jwl13zb0r9xfpw";
+    sha256 = "1hmrkdcdlkwy7rxhngf3cv3sa61cznnd9p5lmqhx20664gx2ibrh";
   };
 
-  buildInputs = [ alcotest ];
+  checkInputs = [ alcotest ppx_let ];
+  buildInputs = [ ocaml-syntax-shims ];
   propagatedBuildInputs = [ bigstringaf result ];
-  doCheck = true;
+  doCheck = lib.versionAtLeast ocaml.version "4.05";
 
-  meta = with lib; {
+  meta = {
     homepage = "https://github.com/inhabitedtype/angstrom";
     description = "OCaml parser combinators built for speed and memory efficiency";
-    license = licenses.bsd3;
-    maintainers = with maintainers; [ sternenseemann ];
+    license = lib.licenses.bsd3;
+    maintainers = with lib.maintainers; [ sternenseemann ];
   };
-}
 ```
 
 Here is a second example, this time using a source archive generated with `dune-release`. It is a good idea to use this archive when it is available as it will usually contain substituted variables such as a `%%VERSION%%` field. This library does not depend on any other OCaml library and no tests are run after building it.
 
 ```nix
-{ lib
-, fetchurl
-, buildDunePackage
-}:
+{ lib, fetchurl, buildDunePackage }:
 
 buildDunePackage rec {
   pname = "wtf8";
-  version = "1.0.1";
+  version = "1.0.2";
+
+  useDune2 = true;
 
-  minimumOCamlVersion = "4.01";
+  minimalOCamlVersion = "4.02";
 
   src = fetchurl {
-    url = "https://github.com/flowtype/ocaml-${pname}/releases/download/v${version}/${pname}-${version}.tbz";
-    sha256 = "1msg3vycd3k8qqj61sc23qks541cxpb97vrnrvrhjnqxsqnh6ygq";
+    url = "https://github.com/flowtype/ocaml-${pname}/releases/download/v${version}/${pname}-v${version}.tbz";
+    sha256 = "09ygcxxd5warkdzz17rgpidrd0pg14cy2svvnvy1hna080lzg7vp";
   };
 
   meta = with lib; {
diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md
index 4daeaf7c8c2..7219b5e80f7 100644
--- a/doc/stdenv/stdenv.chapter.md
+++ b/doc/stdenv/stdenv.chapter.md
@@ -463,6 +463,12 @@ The prefix under which the package must be installed, passed via the `--prefix`
 
 The key to use when specifying the prefix. By default, this is set to `--prefix=` as that is used by the majority of packages.
 
+##### `dontAddStaticConfigureFlags`
+
+By default, when building statically, stdenv will try to add build system appropriate configure flags to try to enable static builds.
+
+If this is undesirable, set this variable to true.
+
 ##### `dontAddDisableDepTrack` {#var-stdenv-dontAddDisableDepTrack}
 
 By default, the flag `--disable-dependency-tracking` is added to the configure flags to speed up Automake-based builds. If this is undesirable, set this variable to true.
@@ -475,7 +481,7 @@ By default, the configure phase applies some special hackery to all files called
 
 By default, when the configure script has `--enable-static`, the option `--disable-static` is added to the configure flags.
 
-If this is undesirable, set this variable to true.
+If this is undesirable, set this variable to true.  It is automatically set to true when building statically, for example through `pkgsStatic`.
 
 ##### `configurePlatforms` {#var-stdenv-configurePlatforms}