Merge branch 'nixos-unstable' of https://github.com/NixOS/nixpkgs

Conflicts:
	nixpkgs/pkgs/applications/window-managers/sway/default.nix
	nixpkgs/pkgs/build-support/go/module.nix
	nixpkgs/pkgs/build-support/rust/build-rust-package/default.nix
	nixpkgs/pkgs/development/libraries/mesa/default.nix
	nixpkgs/pkgs/servers/dict/dictd-db.nix

Link: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/issues/391

93 files changed, 1154 insertions, 1085 deletions

diff --git a/nixpkgs/doc/.gitignore b/nixpkgs/doc/.gitignore
deleted file mode 100644
index b08285995f66..000000000000
--- a/nixpkgs/doc/.gitignore
+++ /dev/null
@@ -1,11 +0,0 @@
-*.chapter.xml
-*.section.xml
-.version
-functions/library/generated
-functions/library/locations.xml
-highlightjs
-manual-full.xml
-out
-result
-result-*
-media
diff --git a/nixpkgs/doc/Makefile b/nixpkgs/doc/Makefile
deleted file mode 100644
index 208f23f5023a..000000000000
--- a/nixpkgs/doc/Makefile
+++ /dev/null
@@ -1,119 +0,0 @@
-MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))
-
-PANDOC ?= pandoc
-
-pandoc_media_dir = media
-# NOTE: Keep in sync with conversion script (/maintainers/scripts/db-to-md.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
-# Not needed:
-# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
-pandoc_flags = --extract-media=$(pandoc_media_dir) \
-	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
-	--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
-	--lua-filter=$(PANDOC_LINK_MANPAGES_FILTER) \
-	--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
-	--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
-	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
-
-.PHONY: all
-all: validate format out/html/index.html out/epub/manual.epub
-
-.PHONY: render-md
-render-md: ${MD_TARGETS}
-
-.PHONY: debug
-debug:
-	nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
-
-.PHONY: format
-format: doc-support/result
-	find . -iname '*.xml' -type f | while read f; do \
-		echo $$f ;\
-		xmlformat --config-file "doc-support/result/xmlformat.conf" -i $$f ;\
-	done
-
-.PHONY: fix-misc-xml
-fix-misc-xml:
-	find . -iname '*.xml' -type f \
-		-exec ../nixos/doc/varlistentry-fixer.rb {} ';'
-
-.PHONY: clean
-clean:
-	rm -f ${MD_TARGETS} doc-support/result .version manual-full.xml functions/library/locations.xml functions/library/generated
-	rm -rf ./out/ ./highlightjs ./media
-
-.PHONY: validate
-validate: manual-full.xml doc-support/result
-	jing doc-support/result/docbook.rng manual-full.xml
-
-out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
-	mkdir -p out/html
-	xsltproc \
-		--nonet --xinclude \
-		--output $@ \
-		doc-support/result/xhtml.xsl \
-		./manual-full.xml
-
-	mkdir -p out/html/highlightjs/
-	cp -r highlightjs out/html/
-
-	cp -r $(pandoc_media_dir) out/html/
-	cp ./overrides.css out/html/
-	cp ./style.css out/html/style.css
-
-	mkdir -p out/html/images/callouts
-	cp doc-support/result/xsl/docbook/images/callouts/*.svg out/html/images/callouts/
-	chmod u+w -R out/html/
-
-out/epub/manual.epub: manual-full.xml
-	mkdir -p out/epub/scratch
-	xsltproc --nonet \
-		--output out/epub/scratch/ \
-		doc-support/result/epub.xsl \
-		./manual-full.xml
-
-	cp -r $(pandoc_media_dir) out/epub/scratch/OEBPS
-	cp ./overrides.css out/epub/scratch/OEBPS
-	cp ./style.css out/epub/scratch/OEBPS
-	mkdir -p out/epub/scratch/OEBPS/images/callouts/
-	cp doc-support/result/xsl/docbook/images/callouts/*.svg out/epub/scratch/OEBPS/images/callouts/
-	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/"
-
-highlightjs: doc-support/result
-	mkdir -p highlightjs
-	cp -r doc-support/result/highlightjs/highlight.pack.js highlightjs/
-	cp -r doc-support/result/highlightjs/LICENSE highlightjs/
-	cp -r doc-support/result/highlightjs/mono-blue.css highlightjs/
-	cp -r doc-support/result/highlightjs/loader.js highlightjs/
-
-
-manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml functions/library/generated *.xml **/*.xml **/**/*.xml
-	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
-
-.version: doc-support/result
-	ln -rfs ./doc-support/result/version .version
-
-doc-support/result: doc-support/default.nix
-	(cd doc-support; nix-build)
-
-functions/library/locations.xml: doc-support/result
-	ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml
-
-functions/library/generated: doc-support/result
-	ln -rfs ./doc-support/result/function-docs functions/library/generated
-
-%.section.xml: %.section.md
-	$(PANDOC) $^ -t docbook \
-		$(pandoc_flags) \
-		-o $@
-
-%.chapter.xml: %.chapter.md
-	$(PANDOC) $^ -t docbook \
-		--top-level-division=chapter \
-		$(pandoc_flags) \
-		-o $@
diff --git a/nixpkgs/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua b/nixpkgs/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua
deleted file mode 100644
index 281e85af2717..000000000000
--- a/nixpkgs/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua
+++ /dev/null
@@ -1,23 +0,0 @@
---[[
-Converts Code AST nodes produced by pandoc’s DocBook reader
-from citerefentry elements into AST for corresponding role
-for reStructuredText.
-
-We use subset of MyST syntax (CommonMark with features from rST)
-so let’s use the rST AST for rST features.
-
-Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage
-]]
-
-function Code(elem)
-  elem.classes = elem.classes:map(function (x)
-    if x == 'citerefentry' then
-      elem.attributes['role'] = 'manpage'
-      return 'interpreted-text'
-    else
-      return x
-    end
-  end)
-
-  return elem
-end
diff --git a/nixpkgs/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua b/nixpkgs/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua
deleted file mode 100644
index fa97729a28bc..000000000000
--- a/nixpkgs/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua
+++ /dev/null
@@ -1,34 +0,0 @@
---[[
-Converts Link AST nodes with empty label to DocBook xref elements.
-
-This is a temporary script to be able use cross-references conveniently
-using syntax taken from MyST, while we still use docbook-xsl
-for generating the documentation.
-
-Reference: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing
-]]
-
-local function starts_with(start, str)
-  return str:sub(1, #start) == start
-end
-
-local function escape_xml_arg(arg)
-  amps = arg:gsub('&', '&')
-  amps_quotes = amps:gsub('"', '"')
-  amps_quotes_lt = amps_quotes:gsub('<', '&lt;')
-
-  return amps_quotes_lt
-end
-
-function Link(elem)
-  has_no_content = #elem.content == 0
-  targets_anchor = starts_with('#', elem.target)
-  has_no_attributes = elem.title == '' and elem.identifier == '' and #elem.classes == 0 and #elem.attributes == 0
-
-  if has_no_content and targets_anchor and has_no_attributes then
-    -- xref expects idref without the pound-sign
-    target_without_hash = elem.target:sub(2, #elem.target)
-
-    return pandoc.RawInline('docbook', '<xref linkend="' .. escape_xml_arg(target_without_hash) .. '" />')
-  end
-end
diff --git a/nixpkgs/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua b/nixpkgs/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
deleted file mode 100644
index 5c1b034d0792..000000000000
--- a/nixpkgs/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
+++ /dev/null
@@ -1,44 +0,0 @@
---[[
-Converts AST for reStructuredText roles into corresponding
-DocBook elements.
-
-Currently, only a subset of roles is supported.
-
-Reference:
-  List of roles:
-    https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
-  manpage:
-    https://tdg.docbook.org/tdg/5.1/citerefentry.html
-  file:
-    https://tdg.docbook.org/tdg/5.1/filename.html
-]]
-
-function Code(elem)
-  if elem.classes:includes('interpreted-text') then
-    local tag = nil
-    local content = elem.text
-    if elem.attributes['role'] == 'manpage' then
-      tag = 'citerefentry'
-      local title, volnum = content:match('^(.+)%((%w+)%)$')
-      if title == nil then
-        -- No volnum in parentheses.
-        title = content
-      end
-      content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '')
-    elseif elem.attributes['role'] == 'file' then
-      tag = 'filename'
-    elseif elem.attributes['role'] == 'command' then
-      tag = 'command'
-    elseif elem.attributes['role'] == 'option' then
-      tag = 'option'
-    elseif elem.attributes['role'] == 'var' then
-      tag = 'varname'
-    elseif elem.attributes['role'] == 'env' then
-      tag = 'envar'
-    end
-
-    if tag ~= nil then
-      return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>')
-    end
-  end
-end
diff --git a/nixpkgs/doc/build-aux/pandoc-filters/link-manpages.nix b/nixpkgs/doc/build-aux/pandoc-filters/link-manpages.nix
deleted file mode 100644
index 2589a7c34251..000000000000
--- a/nixpkgs/doc/build-aux/pandoc-filters/link-manpages.nix
+++ /dev/null
@@ -1,28 +0,0 @@
-{ pkgs ? import ../../.. {} }:
-let
-  inherit (pkgs) lib;
-  manpageURLs = lib.importJSON (pkgs.path + "/doc/manpage-urls.json");
-in pkgs.writeText "link-manpages.lua" ''
-  --[[
-  Adds links to known man pages that aren't already in a link.
-  ]]
-
-  local manpage_urls = {
-  ${lib.concatStringsSep "\n" (lib.mapAttrsToList (man: url:
-    "  [${builtins.toJSON man}] = ${builtins.toJSON url},") manpageURLs)}
-  }
-
-  traverse = 'topdown'
-
-  -- Returning false as the second value aborts processing of child elements.
-  function Link(elem)
-    return elem, false
-  end
-
-  function Code(elem)
-    local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
-    if is_man_role and manpage_urls[elem.text] ~= nil then
-      return pandoc.Link(elem, manpage_urls[elem.text]), false
-    end
-  end
-''
diff --git a/nixpkgs/doc/build-aux/pandoc-filters/myst-reader/roles.lua b/nixpkgs/doc/build-aux/pandoc-filters/myst-reader/roles.lua
deleted file mode 100644
index f4ef6d390b40..000000000000
--- a/nixpkgs/doc/build-aux/pandoc-filters/myst-reader/roles.lua
+++ /dev/null
@@ -1,36 +0,0 @@
---[[
-Replaces Str AST nodes containing {role}, followed by a Code node
-by a Code node with attrs that would be produced by rST reader
-from the role syntax.
-
-This is to emulate MyST syntax in Pandoc.
-(MyST is a CommonMark flavour with rST features mixed in.)
-
-Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
-]]
-
-function Inlines(inlines)
-  for i = #inlines-1,1,-1 do
-    local first = inlines[i]
-    local second = inlines[i+1]
-    local correct_tags = first.tag == 'Str' and second.tag == 'Code'
-    if correct_tags then
-      -- docutils supports alphanumeric strings separated by [-._:]
-      -- We are slightly more liberal for simplicity.
-      -- Allow preceding punctuation (eg '('), otherwise '({file}`...`)'
-      -- does not match. Also allow anything followed by a non-breaking space
-      -- since pandoc emits those after certain abbreviations (e.g. e.g.).
-      local prefix, role = first.text:match('^(.*){([-._+:%w]+)}$')
-      if role ~= nil and (prefix == '' or prefix:match("^.*[%p ]$") ~= nil) then
-        if prefix == '' then
-          inlines:remove(i)
-        else
-          first.text = prefix
-        end
-        second.attributes['role'] = role
-        second.classes:insert('interpreted-text')
-      end
-    end
-  end
-  return inlines
-end
diff --git a/nixpkgs/doc/build-aux/pandoc-filters/myst-writer/roles.lua b/nixpkgs/doc/build-aux/pandoc-filters/myst-writer/roles.lua
deleted file mode 100644
index 0136bc550652..000000000000
--- a/nixpkgs/doc/build-aux/pandoc-filters/myst-writer/roles.lua
+++ /dev/null
@@ -1,25 +0,0 @@
---[[
-Replaces Code nodes with attrs that would be produced by rST reader
-from the role syntax by a Str AST node containing {role}, followed by a Code node.
-
-This is to emulate MyST syntax in Pandoc.
-(MyST is a CommonMark flavour with rST features mixed in.)
-
-Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
-]]
-
-function Code(elem)
-  local role = elem.attributes['role']
-
-  if elem.classes:includes('interpreted-text') and role ~= nil then
-    elem.classes = elem.classes:filter(function (c)
-      return c ~= 'interpreted-text'
-    end)
-    elem.attributes['role'] = nil
-
-    return {
-      pandoc.Str('{' .. role .. '}'),
-      elem,
-    }
-  end
-end
diff --git a/nixpkgs/doc/builders.md b/nixpkgs/doc/builders.md
new file mode 100644
index 000000000000..2e959422405b
--- /dev/null
+++ b/nixpkgs/doc/builders.md
@@ -0,0 +1,12 @@
+# Builders {#part-builders}
+
+```{=include=} chapters
+builders/fetchers.chapter.md
+builders/trivial-builders.chapter.md
+builders/testers.chapter.md
+builders/special.md
+builders/images.md
+hooks/index.md
+languages-frameworks/index.md
+builders/packages/index.md
+```
diff --git a/nixpkgs/doc/builders/images.md b/nixpkgs/doc/builders/images.md
new file mode 100644
index 000000000000..5596784bfa48
--- /dev/null
+++ b/nixpkgs/doc/builders/images.md
@@ -0,0 +1,13 @@
+# Images {#chap-images}
+
+This chapter describes tools for creating various types of images.
+
+```{=include=} sections
+images/appimagetools.section.md
+images/dockertools.section.md
+images/ocitools.section.md
+images/snaptools.section.md
+images/portableservice.section.md
+images/makediskimage.section.md
+images/binarycache.section.md
+```
diff --git a/nixpkgs/doc/builders/images.xml b/nixpkgs/doc/builders/images.xml
deleted file mode 100644
index a4661ab5a7af..000000000000
--- a/nixpkgs/doc/builders/images.xml
+++ /dev/null
@@ -1,15 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-images">
- <title>Images</title>
- <para>
-  This chapter describes tools for creating various types of images.
- </para>
- <xi:include href="images/appimagetools.section.xml" />
- <xi:include href="images/dockertools.section.xml" />
- <xi:include href="images/ocitools.section.xml" />
- <xi:include href="images/snaptools.section.xml" />
- <xi:include href="images/portableservice.section.xml" />
- <xi:include href="images/makediskimage.section.xml" />
- <xi:include href="images/binarycache.section.xml" />
-</chapter>
diff --git a/nixpkgs/doc/builders/packages/dlib.section.md b/nixpkgs/doc/builders/packages/dlib.section.md
index 022195310a71..bd5b1a20a4d4 100644
--- a/nixpkgs/doc/builders/packages/dlib.section.md
+++ b/nixpkgs/doc/builders/packages/dlib.section.md
@@ -1,6 +1,6 @@
 # DLib {#dlib}
 
-[DLib](http://dlib.net/) is a modern, C++-based toolkit which provides several machine learning algorithms.
+[DLib](http://dlib.net/) is a modern, C++\-based toolkit which provides several machine learning algorithms.
 
 ## Compiling without AVX support {#compiling-without-avx-support}
 
diff --git a/nixpkgs/doc/builders/packages/ibus.section.md b/nixpkgs/doc/builders/packages/ibus.section.md
index ec78cd0c9a96..4eb74c0b6912 100644
--- a/nixpkgs/doc/builders/packages/ibus.section.md
+++ b/nixpkgs/doc/builders/packages/ibus.section.md
@@ -34,5 +34,7 @@ The `ibus-engines.typing-booster` package contains a program named `emoji-picker
 On NixOS, it can be installed using the following expression:
 
 ```nix
-{ pkgs, ... }: { fonts.fonts = with pkgs; [ noto-fonts-emoji ]; }
+{ pkgs, ... }: {
+  fonts.packages = with pkgs; [ noto-fonts-emoji ];
+}
 ```
diff --git a/nixpkgs/doc/builders/packages/index.md b/nixpkgs/doc/builders/packages/index.md
new file mode 100644
index 000000000000..1f4435702406
--- /dev/null
+++ b/nixpkgs/doc/builders/packages/index.md
@@ -0,0 +1,27 @@
+# Packages {#chap-packages}
+
+This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages, such as the Linux kernel or X.org.
+
+```{=include=} sections
+citrix.section.md
+dlib.section.md
+eclipse.section.md
+elm.section.md
+emacs.section.md
+firefox.section.md
+fish.section.md
+fuse.section.md
+ibus.section.md
+kakoune.section.md
+linux.section.md
+locales.section.md
+etc-files.section.md
+nginx.section.md
+opengl.section.md
+shell-helpers.section.md
+steam.section.md
+cataclysm-dda.section.md
+urxvt.section.md
+weechat.section.md
+xorg.section.md
+```
diff --git a/nixpkgs/doc/builders/packages/index.xml b/nixpkgs/doc/builders/packages/index.xml
deleted file mode 100644
index 206e1e49f1f8..000000000000
--- a/nixpkgs/doc/builders/packages/index.xml
+++ /dev/null
@@ -1,29 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-packages">
- <title>Packages</title>
- <para>
-  This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages, such as the Linux kernel or X.org.
- </para>
- <xi:include href="citrix.section.xml" />
- <xi:include href="dlib.section.xml" />
- <xi:include href="eclipse.section.xml" />
- <xi:include href="elm.section.xml" />
- <xi:include href="emacs.section.xml" />
- <xi:include href="firefox.section.xml" />
- <xi:include href="fish.section.xml" />
- <xi:include href="fuse.section.xml" />
- <xi:include href="ibus.section.xml" />
- <xi:include href="kakoune.section.xml" />
- <xi:include href="linux.section.xml" />
- <xi:include href="locales.section.xml" />
- <xi:include href="etc-files.section.xml" />
- <xi:include href="nginx.section.xml" />
- <xi:include href="opengl.section.xml" />
- <xi:include href="shell-helpers.section.xml" />
- <xi:include href="steam.section.xml" />
- <xi:include href="cataclysm-dda.section.xml" />
- <xi:include href="urxvt.section.xml" />
- <xi:include href="weechat.section.xml" />
- <xi:include href="xorg.section.xml" />
-</chapter>
diff --git a/nixpkgs/doc/builders/special.md b/nixpkgs/doc/builders/special.md
new file mode 100644
index 000000000000..6d07fa87f3f3
--- /dev/null
+++ b/nixpkgs/doc/builders/special.md
@@ -0,0 +1,11 @@
+# Special builders {#chap-special}
+
+This chapter describes several special builders.
+
+```{=include=} sections
+special/fhs-environments.section.md
+special/makesetuphook.section.md
+special/mkshell.section.md
+special/darwin-builder.section.md
+special/vm-tools.section.md
+```
diff --git a/nixpkgs/doc/builders/special.xml b/nixpkgs/doc/builders/special.xml
deleted file mode 100644
index 18cf6cfd39c7..000000000000
--- a/nixpkgs/doc/builders/special.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-special">
- <title>Special builders</title>
- <para>
-  This chapter describes several special builders.
- </para>
- <xi:include href="special/fhs-environments.section.xml" />
- <xi:include href="special/makesetuphook.section.xml" />
- <xi:include href="special/mkshell.section.xml" />
- <xi:include href="special/darwin-builder.section.xml" />
- <xi:include href="special/vm-tools.section.xml" />
-</chapter>
diff --git a/nixpkgs/doc/builders/special/darwin-builder.section.md b/nixpkgs/doc/builders/special/darwin-builder.section.md
index 30bf2d095102..13d01a0e3af8 100644
--- a/nixpkgs/doc/builders/special/darwin-builder.section.md
+++ b/nixpkgs/doc/builders/special/darwin-builder.section.md
@@ -1,11 +1,12 @@
-# darwin.builder {#sec-darwin-builder}
+# darwin.linux-builder {#sec-darwin-builder}
 
-`darwin.builder` provides a way to bootstrap a Linux builder on a macOS machine.
+`darwin.linux-builder` provides a way to bootstrap a Linux builder on a macOS machine.
 
 This requires macOS version 12.4 or later.
 
-This also requires that port 22 on your machine is free (since Nix does not
-permit specifying a non-default SSH port for builders).
+The builder runs on host port 31022 by default.
+You can change it by overriding `virtualisation.darwin-builder.hostPort`.
+See the [example](#sec-darwin-builder-example-flake).
 
 You will also need to be a trusted user for your Nix installation.  In other
 words, your `/etc/nix/nix.conf` should have something like:
@@ -17,7 +18,7 @@ extra-trusted-users = <your username goes here>
 To launch the builder, run the following flake:
 
 ```ShellSession
-$ nix run nixpkgs#darwin.builder
+$ nix run nixpkgs#darwin.linux-builder
 ```
 
 That will prompt you to enter your `sudo` password:
@@ -50,19 +51,28 @@ To delegate builds to the remote builder, add the following options to your
 ```
 # - Replace ${ARCH} with either aarch64 or x86_64 to match your host machine
 # - Replace ${MAX_JOBS} with the maximum number of builds (pick 4 if you're not sure)
-builders = ssh-ng://builder@localhost ${ARCH}-linux /etc/nix/builder_ed25519 ${MAX_JOBS} - - - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSUpCV2N4Yi9CbGFxdDFhdU90RStGOFFVV3JVb3RpQzVxQkorVXVFV2RWQ2Igcm9vdEBuaXhvcwo=
+builders = ssh-ng://builder@linux-builder ${ARCH}-linux /etc/nix/builder_ed25519 ${MAX_JOBS} - - - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSUpCV2N4Yi9CbGFxdDFhdU90RStGOFFVV3JVb3RpQzVxQkorVXVFV2RWQ2Igcm9vdEBuaXhvcwo=
 
 # Not strictly necessary, but this will reduce your disk utilization
 builders-use-substitutes = true
 ```
 
+To allow Nix to connect to a builder not running on port 22, you will also need to create a new file at `/etc/ssh/ssh_config.d/100-linux-builder.conf`:
+
+```
+Host linux-builder
+  Hostname localhost
+  HostKeyAlias linux-builder
+  Port 31022
+```
+
 … and then restart your Nix daemon to apply the change:
 
 ```ShellSession
 $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
 ```
 
-## Example flake usage
+## Example flake usage {#sec-darwin-builder-example-flake}
 
 ```
 {
@@ -120,7 +130,7 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
 }
 ```
 
-## Reconfiguring the builder
+## Reconfiguring the builder {#sec-darwin-builder-reconfiguring}
 
 Initially you should not change the builder configuration else you will not be
 able to use the binary cache. However, after you have the builder running locally
diff --git a/nixpkgs/doc/builders/special/fhs-environments.section.md b/nixpkgs/doc/builders/special/fhs-environments.section.md
index 5a248e4ead92..8145fbd730f7 100644
--- a/nixpkgs/doc/builders/special/fhs-environments.section.md
+++ b/nixpkgs/doc/builders/special/fhs-environments.section.md
@@ -11,6 +11,8 @@ Accepted arguments are:
         Packages to be installed for the main host's architecture (i.e. x86_64 on x86_64 installations). Along with libraries binaries are also installed.
 - `multiPkgs`
         Packages to be installed for all architectures supported by a host (i.e. i686 and x86_64 on x86_64 installations). Only libraries are installed by default.
+- `multiArch`
+        Whether to install 32bit multiPkgs into the FHSEnv in 64bit environments
 - `extraBuildCommands`
         Additional commands to be executed for finalizing the directory structure.
 - `extraBuildCommandsMulti`
diff --git a/nixpkgs/doc/builders/special/makesetuphook.section.md b/nixpkgs/doc/builders/special/makesetuphook.section.md
index fee508dc29c2..eb042412137b 100644
--- a/nixpkgs/doc/builders/special/makesetuphook.section.md
+++ b/nixpkgs/doc/builders/special/makesetuphook.section.md
@@ -12,7 +12,7 @@ pkgs.makeSetupHook {
 } ./script.sh
 ```
 
-#### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example}
+### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example}
 
 ```nix
 pkgs.makeSetupHook {
diff --git a/nixpkgs/doc/builders/special/vm-tools.section.md b/nixpkgs/doc/builders/special/vm-tools.section.md
index 3b6fb0d2556b..8feab04902d8 100644
--- a/nixpkgs/doc/builders/special/vm-tools.section.md
+++ b/nixpkgs/doc/builders/special/vm-tools.section.md
@@ -6,7 +6,7 @@ A set of VM related utilities, that help in building some packages in more advan
 
 A bash script fragment that produces a disk image at `destination`.
 
-### Attributes
+### Attributes {#vm-tools-createEmptyImage-attributes}
 
 * `size`. The disk size, in MiB.
 * `fullName`. Name that will be written to `${destination}/nix-support/full-name`.
@@ -20,14 +20,14 @@ Thus, any pure Nix derivation should run unmodified.
 
 If the build fails and Nix is run with the `-K/--keep-failed` option, a script `run-vm` will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively.
 
-### Attributes
+### Attributes {#vm-tools-runInLinuxVM-attributes}
 
 * `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host).
 * `memSize` (optional, default `512`). The memory size of the VM in MiB.
 * `diskImage` (optional). A file system image to be attached to `/dev/sda`.
   Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
 
-### Examples
+### Examples {#vm-tools-runInLinuxVM-examples}
 
 Build the derivation hello inside a VM:
 ```nix
@@ -56,13 +56,13 @@ runInLinuxVM (hello.overrideAttrs (_: {
 
 Takes a file, such as an ISO, and extracts its contents into the store.
 
-### Attributes
+### Attributes {#vm-tools-extractFs-attributes}
 
 * `file`. Path to the file to be extracted.
   Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
 * `fs` (optional). Filesystem of the contents of the file.
 
-### Examples
+### Examples {#vm-tools-extractFs-examples}
 
 Extract the contents of an ISO file:
 ```nix
@@ -82,7 +82,7 @@ Like [](#vm-tools-runInLinuxVM), but instead of using `stdenv` from the Nix stor
 
 Generate a script that can be used to run an interactive session in the given image.
 
-### Examples
+### Examples {#vm-tools-makeImageTestScript-examples}
 
 Create a script for running a Fedora 27 VM:
 ```nix
@@ -100,7 +100,7 @@ makeImageTestScript diskImages.ubuntu2004x86_64
 
 A set of functions that build a predefined set of minimal Linux distributions images.
 
-### Images
+### Images {#vm-tools-diskImageFuns-images}
 
 * Fedora
   * `fedora26x86_64`
@@ -126,12 +126,12 @@ A set of functions that build a predefined set of minimal Linux distributions im
   * `debian11i386`
   * `debian11x86_64`
 
-### Attributes
+### Attributes {#vm-tools-diskImageFuns-attributes}
 
 * `size` (optional, defaults to `4096`). The size of the image, in MiB.
 * `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image.
 
-### Examples
+### Examples {#vm-tools-diskImageFuns-examples}
 
 8GiB image containing Firefox in addition to the default packages:
 ```nix
diff --git a/nixpkgs/doc/builders/testers.chapter.md b/nixpkgs/doc/builders/testers.chapter.md
index 928a57673e77..fb6a28b7ee4b 100644
--- a/nixpkgs/doc/builders/testers.chapter.md
+++ b/nixpkgs/doc/builders/testers.chapter.md
@@ -1,5 +1,5 @@
 # Testers {#chap-testers}
-This chapter describes several testing builders which are available in the <literal>testers</literal> namespace.
+This chapter describes several testing builders which are available in the `testers` namespace.
 
 ## `hasPkgConfigModule` {#tester-hasPkgConfigModule}
 
diff --git a/nixpkgs/doc/common.nix b/nixpkgs/doc/common.nix
new file mode 100644
index 000000000000..56f723eb6bd7
--- /dev/null
+++ b/nixpkgs/doc/common.nix
@@ -0,0 +1,4 @@
+{
+  outputPath = "share/doc/nixpkgs";
+  indexPath = "manual.html";
+}
diff --git a/nixpkgs/doc/contributing.md b/nixpkgs/doc/contributing.md
new file mode 100644
index 000000000000..3215dbe32bec
--- /dev/null
+++ b/nixpkgs/doc/contributing.md
@@ -0,0 +1,10 @@
+# Contributing to Nixpkgs {#part-contributing}
+
+```{=include=} chapters
+contributing/quick-start.chapter.md
+contributing/coding-conventions.chapter.md
+contributing/submitting-changes.chapter.md
+contributing/vulnerability-roundup.chapter.md
+contributing/reviewing-contributions.chapter.md
+contributing/contributing-to-documentation.chapter.md
+```
diff --git a/nixpkgs/doc/contributing/coding-conventions.chapter.md b/nixpkgs/doc/contributing/coding-conventions.chapter.md
index 03cd3dd458c8..eb9932d48b68 100644
--- a/nixpkgs/doc/contributing/coding-conventions.chapter.md
+++ b/nixpkgs/doc/contributing/coding-conventions.chapter.md
@@ -456,7 +456,7 @@ In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these
     owner = "NixOS";
     repo = "nix";
     rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-    hash = "ha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
+    hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
   }
   ```
 
diff --git a/nixpkgs/doc/contributing/contributing-to-documentation.chapter.md b/nixpkgs/doc/contributing/contributing-to-documentation.chapter.md
index a732eee4b962..557473555f8a 100644
--- a/nixpkgs/doc/contributing/contributing-to-documentation.chapter.md
+++ b/nixpkgs/doc/contributing/contributing-to-documentation.chapter.md
@@ -1,27 +1,23 @@
 # Contributing to this documentation {#chap-contributing}
 
-The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository. The manual is still partially written in DocBook but it is progressively being converted to [Markdown](#sec-contributing-markup).
+The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository.
 
-You can quickly check your edits with `make`:
+You can quickly check your edits with `nix-build`:
 
 ```ShellSession
-$ cd /path/to/nixpkgs/doc
-$ nix-shell
-[nix-shell]$ make
+$ cd /path/to/nixpkgs
+$ nix-build doc
 ```
 
-If you experience problems, run `make debug` to help understand the docbook errors.
-
-After making modifications to the manual, it's important to build it before committing. You can do that as follows:
+If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
 
-```ShellSession
-$ cd /path/to/nixpkgs/doc
-$ nix-shell
-[nix-shell]$ make clean
-[nix-shell]$ nix-build .
-```
+## devmode {#sec-contributing-devmode}
 
-If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
+The shell in the manual source directory makes available a command, `devmode`.
+It is a daemon, that:
+1. watches the manual's source for changes and when they occur — rebuilds
+2. HTTP serves the manual, injecting a script that triggers reload on changes
+3. opens the manual in the default browser
 
 ## Syntax {#sec-contributing-markup}
 
@@ -114,5 +110,3 @@ Additional syntax extensions are available, all of which can be used in NixOS op
   >
   > watermelon
   > :   green fruit with red flesh
-
-For contributing to the legacy parts, please see [DocBook: The Definitive Guide](https://tdg.docbook.org/) or the [DocBook rocks! primer](https://web.archive.org/web/20200816233747/https://docbook.rocks/).
diff --git a/nixpkgs/doc/contributing/reviewing-contributions.chapter.md b/nixpkgs/doc/contributing/reviewing-contributions.chapter.md
index b4caf11f6d4b..10c72fe3d13e 100644
--- a/nixpkgs/doc/contributing/reviewing-contributions.chapter.md
+++ b/nixpkgs/doc/contributing/reviewing-contributions.chapter.md
@@ -62,6 +62,8 @@ Sample template for a package update review is provided below.
 - [ ] package build on ARCHITECTURE
 - [ ] executables tested on ARCHITECTURE
 - [ ] all depending packages build
+- [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed
+- [ ] patches that are remotely available are fetched rather than vendored
 
 ##### Possible improvements
 
@@ -105,7 +107,8 @@ Sample template for a new package review is provided below.
 - [ ] source is fetched using the appropriate function
 - [ ] the list of `phases` is not overridden
 - [ ] when a phase (like `installPhase`) is overridden it starts with `runHook preInstall` and ends with `runHook postInstall`.
-- [ ] patches that are remotely available are fetched with `fetchpatch`
+- [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed
+- [ ] patches that are remotely available are fetched rather than vendored
 
 ##### Possible improvements
 
diff --git a/nixpkgs/doc/contributing/staging-workflow.dot b/nixpkgs/doc/contributing/staging-workflow.dot
new file mode 100644
index 000000000000..faca7a1cad4c
--- /dev/null
+++ b/nixpkgs/doc/contributing/staging-workflow.dot
@@ -0,0 +1,16 @@
+digraph {
+    "small changes" [shape=none]
+    "mass-rebuilds and other large changes" [shape=none]
+    "critical security fixes" [shape=none]
+    "broken staging-next fixes" [shape=none]
+
+    "small changes" -> master
+    "mass-rebuilds and other large changes" -> staging
+    "critical security fixes" -> master
+    "broken staging-next fixes" -> "staging-next"
+
+    "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"]
+    "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"]
+
+    master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"]
+}
diff --git a/nixpkgs/doc/contributing/staging-workflow.svg b/nixpkgs/doc/contributing/staging-workflow.svg
new file mode 100644
index 000000000000..1a174a78830e
--- /dev/null
+++ b/nixpkgs/doc/contributing/staging-workflow.svg
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 7.1.0 (0)
+ -->
+<!-- Pages: 1 -->
+<svg width="743pt" height="291pt"
+ viewBox="0.00 0.00 743.00 291.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 287)">
+<polygon fill="white" stroke="none" points="-4,4 -4,-287 739,-287 739,4 -4,4"/>
+<!-- small changes -->
+<g id="node1" class="node">
+<title>small changes</title>
+<text text-anchor="middle" x="59" y="-261.3" font-family="Times,serif" font-size="14.00">small changes</text>
+</g>
+<!-- master -->
+<g id="node5" class="node">
+<title>master</title>
+<ellipse fill="none" stroke="black" cx="139" cy="-192" rx="43.59" ry="18"/>
+<text text-anchor="middle" x="139" y="-188.3" font-family="Times,serif" font-size="14.00">master</text>
+</g>
+<!-- small changes&#45;&gt;master -->
+<g id="edge1" class="edge">
+<title>small changes&#45;&gt;master</title>
+<path fill="none" stroke="black" d="M77.96,-247.17C88.42,-237.89 101.55,-226.23 112.96,-216.11"/>
+<polygon fill="black" stroke="black" points="114.99,-218.99 120.14,-209.74 110.34,-213.76 114.99,-218.99"/>
+</g>
+<!-- mass&#45;rebuilds and other large changes -->
+<g id="node2" class="node">
+<title>mass&#45;rebuilds and other large changes</title>
+<text text-anchor="middle" x="588" y="-101.3" font-family="Times,serif" font-size="14.00">mass&#45;rebuilds and other large changes</text>
+</g>
+<!-- staging -->
+<g id="node6" class="node">
+<title>staging</title>
+<ellipse fill="none" stroke="black" cx="438" cy="-18" rx="45.49" ry="18"/>
+<text text-anchor="middle" x="438" y="-14.3" font-family="Times,serif" font-size="14.00">staging</text>
+</g>
+<!-- mass&#45;rebuilds and other large changes&#45;&gt;staging -->
+<g id="edge2" class="edge">
+<title>mass&#45;rebuilds and other large changes&#45;&gt;staging</title>
+<path fill="none" stroke="black" d="M587.48,-87.47C586.26,-76.55 582.89,-62.7 574,-54 553.19,-33.63 522.2,-24.65 495.05,-20.86"/>
+<polygon fill="black" stroke="black" points="495.53,-17.39 485.2,-19.71 494.72,-24.35 495.53,-17.39"/>
+</g>
+<!-- critical security fixes -->
+<g id="node3" class="node">
+<title>critical security fixes</title>
+<text text-anchor="middle" x="219" y="-261.3" font-family="Times,serif" font-size="14.00">critical security fixes</text>
+</g>
+<!-- critical security fixes&#45;&gt;master -->
+<g id="edge3" class="edge">
+<title>critical security fixes&#45;&gt;master</title>
+<path fill="none" stroke="black" d="M200.04,-247.17C189.58,-237.89 176.45,-226.23 165.04,-216.11"/>
+<polygon fill="black" stroke="black" points="167.66,-213.76 157.86,-209.74 163.01,-218.99 167.66,-213.76"/>
+</g>
+<!-- broken staging&#45;next fixes -->
+<g id="node4" class="node">
+<title>broken staging&#45;next fixes</title>
+<text text-anchor="middle" x="414" y="-188.3" font-family="Times,serif" font-size="14.00">broken staging&#45;next fixes</text>
+</g>
+<!-- staging&#45;next -->
+<g id="node7" class="node">
+<title>staging&#45;next</title>
+<ellipse fill="none" stroke="black" cx="272" cy="-105" rx="68.79" ry="18"/>
+<text text-anchor="middle" x="272" y="-101.3" font-family="Times,serif" font-size="14.00">staging&#45;next</text>
+</g>
+<!-- broken staging&#45;next fixes&#45;&gt;staging&#45;next -->
+<g id="edge4" class="edge">
+<title>broken staging&#45;next fixes&#45;&gt;staging&#45;next</title>
+<path fill="none" stroke="black" d="M410.2,-174.42C406.88,-163.48 400.98,-149.62 391,-141 377.77,-129.56 360.96,-121.86 344.17,-116.67"/>
+<polygon fill="black" stroke="black" points="345.21,-113.33 334.63,-114.02 343.33,-120.07 345.21,-113.33"/>
+</g>
+<!-- master&#45;&gt;staging&#45;next -->
+<g id="edge7" class="edge">
+<title>master&#45;&gt;staging&#45;next</title>
+<path fill="none" stroke="#5f5ee8" d="M96.55,-187.26C53.21,-181.83 -4.5,-169.14 20,-141 41.99,-115.74 126.36,-108.13 191.48,-106.11"/>
+<polygon fill="#5f5ee8" stroke="#5f5ee8" points="191.57,-109.61 201.47,-105.85 191.38,-102.62 191.57,-109.61"/>
+<text text-anchor="middle" x="133" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#5f5ee8">every six hours (GitHub Action)</text>
+</g>
+<!-- staging&#45;&gt;staging&#45;next -->
+<g id="edge6" class="edge">
+<title>staging&#45;&gt;staging&#45;next</title>
+<path fill="none" stroke="#e85eb0" d="M434.55,-36.2C431.48,-47.12 425.89,-60.72 416,-69 397.61,-84.41 373.51,-93.23 350.31,-98.23"/>
+<polygon fill="#e85eb0" stroke="#e85eb0" points="349.67,-94.79 340.5,-100.1 350.98,-101.66 349.67,-94.79"/>
+<text text-anchor="middle" x="493.5" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#e85eb0">stabilization starts</text>
+</g>
+<!-- staging&#45;next&#45;&gt;master -->
+<g id="edge5" class="edge">
+<title>staging&#45;next&#45;&gt;master</title>
+<path fill="none" stroke="#e85eb0" d="M268.22,-123.46C265.05,-134.22 259.46,-147.52 250,-156 233.94,-170.4 211.98,-178.87 191.83,-183.86"/>
+<polygon fill="#e85eb0" stroke="#e85eb0" points="191.35,-180.38 182.34,-185.96 192.86,-187.22 191.35,-180.38"/>
+<text text-anchor="middle" x="323.5" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#e85eb0">stabilization ends</text>
+</g>
+<!-- staging&#45;next&#45;&gt;staging -->
+<g id="edge8" class="edge">
+<title>staging&#45;next&#45;&gt;staging</title>
+<path fill="none" stroke="#5f5ee8" d="M221.07,-92.46C194.72,-84.14 170.92,-71.32 186,-54 210.78,-25.54 314.74,-19.48 381.15,-18.6"/>
+<polygon fill="#5f5ee8" stroke="#5f5ee8" points="380.79,-22.1 390.76,-18.51 380.73,-15.1 380.79,-22.1"/>
+<text text-anchor="middle" x="299" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#5f5ee8">every six hours (GitHub Action)</text>
+</g>
+</g>
+</svg>
diff --git a/nixpkgs/doc/contributing/submitting-changes.chapter.md b/nixpkgs/doc/contributing/submitting-changes.chapter.md
index 30fe4fa47d0d..5a3d269569f0 100644
--- a/nixpkgs/doc/contributing/submitting-changes.chapter.md
+++ b/nixpkgs/doc/contributing/submitting-changes.chapter.md
@@ -214,39 +214,81 @@ The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blo
 - Hydra builds for master and staging should not be used as testing platform, it’s a build farm for changes that have been already tested.
 - When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people’s installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra.
 
+### Branches {#submitting-changes-branches}
+
+The `nixpkgs` repository has three major branches:
+- `master`
+- `staging`
+- `staging-next`
+
+The most important distinction between them is that `staging`
+(colored red in the diagram below) can receive commits which cause
+a mass-rebuild (for example, anything that changes the `drvPath` of
+`stdenv`).  The other two branches `staging-next` and `master`
+(colored green in the diagram below) can *not* receive commits which
+cause a mass-rebuild.
+
+Arcs between the branches show possible merges into these branches,
+either from other branches or from independently submitted PRs.  The
+colors of these edges likewise show whether or not they could
+trigger a mass rebuild (red) or must not trigger a mass rebuild
+(green).
+
+Hydra runs automatic builds for the green branches.
+
+Notice that the automatic merges are all green arrows.  This is by
+design.  Any merge which might cause a mass rebuild on a branch
+which has automatic builds (`staging-next`, `master`) will be a
+manual merge to make sure it is good use of compute power.
+
+Nixpkgs has two branches so that there is one branch (`staging`)
+which accepts mass-rebuilding commits, and one fast-rebuilding
+branch which accepts independent PRs (`master`).  The `staging-next`
+branch allows the Hydra operators to batch groups of commits to
+`staging` to be built.  By keeping the `staging-next` branch
+separate from `staging`, this batching does not block
+developers from merging changes into `staging`.
+
 ```{.graphviz caption="Staging workflow"}
 digraph {
-    "small changes" [shape=none]
-    "mass-rebuilds and other large changes" [shape=none]
-    "critical security fixes" [shape=none]
-    "broken staging-next fixes" [shape=none]
+    master [color="green" fontcolor=green]
+    "staging-next" [color="green" fontcolor=green]
+    staging [color="red" fontcolor=red]
+
+    "small changes" [fontcolor=green shape=none]
+    "small changes" -> master [color=green]
+
+    "mass-rebuilds and other large changes" [fontcolor=red shape=none]
+    "mass-rebuilds and other large changes" -> staging [color=red]
+
+    "critical security fixes" [fontcolor=green shape=none]
+    "critical security fixes" -> master [color=green]
 
-    "small changes" -> master
-    "mass-rebuilds and other large changes" -> staging
-    "critical security fixes" -> master
-    "broken staging-next fixes" -> "staging-next"
+    "staging fixes which do not cause staging to mass-rebuild" [fontcolor=green shape=none]
+    "staging fixes which do not cause staging to mass-rebuild" -> "staging-next" [color=green]
 
-    "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"]
-    "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"]
+    "staging-next" -> master [color="red"] [label="manual merge"] [fontcolor="red"]
+    "staging" -> "staging-next" [color="red"] [label="manual merge"] [fontcolor="red"]
 
-    master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"]
+    master -> "staging-next" [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]
+    "staging-next" -> staging [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]
 }
 ```
 
-[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the blue arrows in the diagram above.  The purple arrows in the diagram above are done manually and much less frequently.  You can get an idea of how often these merges occur by looking at the git history.
+[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the green arrows in the diagram above.  The red arrows in the diagram above are done manually and much less frequently.  You can get an idea of how often these merges occur by looking at the git history.
 
 
-### Master branch {#submitting-changes-master-branch}
+#### Master branch {#submitting-changes-master-branch}
 
 The `master` branch is the main development branch. It should only see non-breaking commits that do not cause mass rebuilds.
 
-### Staging branch {#submitting-changes-staging-branch}
+#### Staging branch {#submitting-changes-staging-branch}
 
 The `staging` branch is a development branch where mass-rebuilds go. Mass rebuilds are commits that cause rebuilds for many packages, like more than 500 (or perhaps, if it's 'light' packages, 1000). It should only see non-breaking mass-rebuild commits. That means it is not to be used for testing, and changes must have been well tested already. If the branch is already in a broken state, please refrain from adding extra new breakages.
 
 During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.
 
-### Staging-next branch {#submitting-changes-staging-next-branch}
+#### Staging-next branch {#submitting-changes-staging-next-branch}
 
 The `staging-next` branch is for stabilizing mass-rebuilds submitted to the `staging` branch prior to merging them into `master`. Mass-rebuilds must go via the `staging` branch. It must only see non-breaking commits that are fixing issues blocking it from being merged into the `master` branch.
 
@@ -254,7 +296,7 @@ If the branch is already in a broken state, please refrain from adding extra new
 
 During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.
 
-### Stable release branches {#submitting-changes-stable-release-branches}
+#### Stable release branches {#submitting-changes-stable-release-branches}
 
 The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`.
 
diff --git a/nixpkgs/doc/default.nix b/nixpkgs/doc/default.nix
index 4f55c95a04c1..f4270ae856d5 100644
--- a/nixpkgs/doc/default.nix
+++ b/nixpkgs/doc/default.nix
@@ -1,43 +1,148 @@
 { pkgs ? (import ./.. { }), nixpkgs ? { }}:
 let
-  doc-support = import ./doc-support { inherit pkgs nixpkgs; };
+  inherit (pkgs) lib;
+  inherit (lib) hasPrefix removePrefix;
+
+  common = import ./common.nix;
+
+  lib-docs = import ./doc-support/lib-function-docs.nix {
+    inherit pkgs nixpkgs;
+    libsets = [
+      { name = "asserts"; description = "assertion functions"; }
+      { name = "attrsets"; description = "attribute set functions"; }
+      { name = "strings"; description = "string manipulation functions"; }
+      { name = "versions"; description = "version string functions"; }
+      { name = "trivial"; description = "miscellaneous functions"; }
+      { name = "fixedPoints"; baseName = "fixed-points"; description = "explicit recursion functions"; }
+      { name = "lists"; description = "list manipulation functions"; }
+      { name = "debug"; description = "debugging functions"; }
+      { name = "options"; description = "NixOS / nixpkgs option handling"; }
+      { name = "path"; description = "path functions"; }
+      { name = "filesystem"; description = "filesystem functions"; }
+      { name = "sources"; description = "source filtering functions"; }
+      { name = "cli"; description = "command-line serialization functions"; }
+    ];
+  };
+
+  epub = pkgs.runCommand "manual.epub" {
+    nativeBuildInputs = with pkgs; [ libxslt zip ];
+
+    epub = ''
+      <book xmlns="http://docbook.org/ns/docbook"
+            xmlns:xlink="http://www.w3.org/1999/xlink"
+            version="5.0"
+            xml:id="nixpkgs-manual">
+        <info>
+          <title>Nixpkgs Manual</title>
+          <subtitle>Version ${pkgs.lib.version}</subtitle>
+        </info>
+        <chapter>
+          <title>Temporarily unavailable</title>
+          <para>
+            The Nixpkgs manual is currently not available in EPUB format,
+            please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>
+            instead.
+          </para>
+          <para>
+            If you've used the EPUB manual in the past and it has been useful to you, please
+            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
+          </para>
+        </chapter>
+      </book>
+    '';
+
+    passAsFile = [ "epub" ];
+  } ''
+    mkdir scratch
+    xsltproc \
+      --param chapter.autolabel 0 \
+      --nonet \
+      --output scratch/ \
+      ${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
+      $epubPath
+
+    echo "application/epub+zip" > mimetype
+    zip -0Xq "$out" mimetype
+    cd scratch && zip -Xr9D "$out" *
+  '';
+
+  # NB: This file describes the Nixpkgs manual, which happens to use module
+  #     docs infra originally developed for NixOS.
+  optionsDoc = pkgs.nixosOptionsDoc {
+    inherit (pkgs.lib.evalModules {
+      modules = [ ../pkgs/top-level/config.nix ];
+      class = "nixpkgsConfig";
+    }) options;
+    documentType = "none";
+    transformOptions = opt:
+      opt // {
+        declarations =
+          map
+            (decl:
+              if hasPrefix (toString ../..) (toString decl)
+              then
+                let subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl));
+                in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
+              else decl)
+            opt.declarations;
+        };
+  };
 in pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
   nativeBuildInputs = with pkgs; [
-    pandoc
-    graphviz
-    libxml2
-    libxslt
-    zip
-    jing
-    xmlformat
+    nixos-render-docs
   ];
 
-  src = pkgs.nix-gitignore.gitignoreSource [] ./.;
+  src = ./.;
 
   postPatch = ''
-    ln -s ${doc-support} ./doc-support/result
+    ln -s ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./config-options.json
   '';
 
-  preBuild = ''
-    make -j$NIX_BUILD_CORES render-md
+  buildPhase = ''
+    cat \
+      ./functions/library.md.in \
+      ${lib-docs}/index.md \
+      > ./functions/library.md
+    substitute ./manual.md.in ./manual.md \
+      --replace '@MANUAL_VERSION@' '${pkgs.lib.version}'
+
+    mkdir -p out/media
+
+    mkdir -p out/highlightjs
+    cp -t out/highlightjs \
+      ${pkgs.documentation-highlighter}/highlight.pack.js \
+      ${pkgs.documentation-highlighter}/LICENSE \
+      ${pkgs.documentation-highlighter}/mono-blue.css \
+      ${pkgs.documentation-highlighter}/loader.js
+
+    cp -t out ./overrides.css ./style.css
+
+    nixos-render-docs manual html \
+      --manpage-urls ./manpage-urls.json \
+      --revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \
+      --stylesheet style.css \
+      --stylesheet overrides.css \
+      --stylesheet highlightjs/mono-blue.css \
+      --script ./highlightjs/highlight.pack.js \
+      --script ./highlightjs/loader.js \
+      --toc-depth 1 \
+      --section-toc-depth 1 \
+      manual.md \
+      out/index.html
   '';
 
   installPhase = ''
-    dest="$out/share/doc/nixpkgs"
+    dest="$out/${common.outputPath}"
     mkdir -p "$(dirname "$dest")"
-    mv out/html "$dest"
-    mv "$dest/index.html" "$dest/manual.html"
+    mv out "$dest"
+    mv "$dest/index.html" "$dest/${common.indexPath}"
 
-    mv out/epub/manual.epub "$dest/nixpkgs-manual.epub"
+    cp ${epub} "$dest/nixpkgs-manual.epub"
 
     mkdir -p $out/nix-support/
-    echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products
+    echo "doc manual $dest ${common.indexPath}" >> $out/nix-support/hydra-build-products
     echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products
   '';
-
-  # Environment variables
-  PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";
-  PANDOC_LINK_MANPAGES_FILTER = import build-aux/pandoc-filters/link-manpages.nix { inherit pkgs; };
 }
diff --git a/nixpkgs/doc/doc-support/default.nix b/nixpkgs/doc/doc-support/default.nix
deleted file mode 100644
index cfa7cbdc8283..000000000000
--- a/nixpkgs/doc/doc-support/default.nix
+++ /dev/null
@@ -1,87 +0,0 @@
-{ pkgs ? (import ../.. {}), nixpkgs ? { }}:
-let
-  inherit (pkgs) lib;
-  inherit (lib) hasPrefix removePrefix;
-
-  libsets = [
-    { name = "asserts"; description = "assertion functions"; }
-    { name = "attrsets"; description = "attribute set functions"; }
-    { name = "strings"; description = "string manipulation functions"; }
-    { name = "versions"; description = "version string functions"; }
-    { name = "trivial"; description = "miscellaneous functions"; }
-    { name = "lists"; description = "list manipulation functions"; }
-    { name = "debug"; description = "debugging functions"; }
-    { name = "options"; description = "NixOS / nixpkgs option handling"; }
-    { name = "path"; description = "path functions"; }
-    { name = "filesystem"; description = "filesystem functions"; }
-    { name = "sources"; description = "source filtering functions"; }
-    { name = "cli"; description = "command-line serialization functions"; }
-  ];
-
-  locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };
-  functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs libsets; };
-  version = pkgs.lib.version;
-
-  epub-xsl = pkgs.writeText "epub.xsl" ''
-    <?xml version='1.0'?>
-    <xsl:stylesheet
-      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-      version="1.0">
-      <xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl" />
-      <xsl:import href="${./parameters.xml}"/>
-    </xsl:stylesheet>
-  '';
-
-  xhtml-xsl = pkgs.writeText "xhtml.xsl" ''
-    <?xml version='1.0'?>
-    <xsl:stylesheet
-      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-      version="1.0">
-      <xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/xhtml/docbook.xsl" />
-      <xsl:import href="${./parameters.xml}"/>
-    </xsl:stylesheet>
-  '';
-
-  # NB: This file describes the Nixpkgs manual, which happens to use module
-  #     docs infra originally developed for NixOS.
-  optionsDoc = pkgs.nixosOptionsDoc {
-    inherit (pkgs.lib.evalModules {
-      modules = [ ../../pkgs/top-level/config.nix ];
-      class = "nixpkgsConfig";
-    }) options;
-    documentType = "none";
-    transformOptions = opt:
-      opt // {
-        declarations =
-          map
-            (decl:
-              if hasPrefix (toString ../..) (toString decl)
-              then
-                let subpath = removePrefix "/" (removePrefix (toString ../..) (toString decl));
-                in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
-              else decl)
-            opt.declarations;
-        };
-  };
-
-in pkgs.runCommand "doc-support" {}
-''
-  mkdir result
-  (
-    cd result
-    ln -s ${locationsXml} ./function-locations.xml
-    ln -s ${functionDocs} ./function-docs
-    ln -s ${optionsDoc.optionsDocBook} ./config-options.docbook.xml
-
-    ln -s ${pkgs.docbook5}/xml/rng/docbook/docbook.rng ./docbook.rng
-    ln -s ${pkgs.docbook_xsl_ns}/xml/xsl ./xsl
-    ln -s ${epub-xsl} ./epub.xsl
-    ln -s ${xhtml-xsl} ./xhtml.xsl
-
-    ln -s ${./xmlformat.conf} ./xmlformat.conf
-    ln -s ${pkgs.documentation-highlighter} ./highlightjs
-
-    echo -n "${version}" > ./version
-  )
-  mv result $out
-''
diff --git a/nixpkgs/doc/doc-support/lib-function-docs.nix b/nixpkgs/doc/doc-support/lib-function-docs.nix
index cf218fa70401..8592fafbbd15 100644
--- a/nixpkgs/doc/doc-support/lib-function-docs.nix
+++ b/nixpkgs/doc/doc-support/lib-function-docs.nix
@@ -1,36 +1,41 @@
 # Generates the documentation for library functions via nixdoc.
 
-{ pkgs, locationsXml, libsets }:
+{ pkgs, nixpkgs, libsets }:
 
-with pkgs; stdenv.mkDerivation {
+with pkgs;
+
+let
+  locationsJSON = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };
+in
+stdenv.mkDerivation {
   name = "nixpkgs-lib-docs";
   src = ../../lib;
 
   buildInputs = [ nixdoc ];
   installPhase = ''
     function docgen {
-      # TODO: wrap lib.$1 in <literal>, make nixdoc not escape it
-      if [[ -e "../lib/$1.nix" ]]; then
-        nixdoc -c "$1" -d "lib.$1: $2" -f "$1.nix" > "$out/$1.xml"
+      name=$1
+      baseName=$2
+      description=$3
+      # TODO: wrap lib.$name in <literal>, make nixdoc not escape it
+      if [[ -e "../lib/$baseName.nix" ]]; then
+        nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName.nix" > "$out/$name.md"
       else
-        nixdoc -c "$1" -d "lib.$1: $2" -f "$1/default.nix" > "$out/$1.xml"
+        nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName/default.nix" > "$out/$name.md"
       fi
-      echo "<xi:include href='$1.xml' />" >> "$out/index.xml"
+      echo "$out/$name.md" >> "$out/index.md"
     }
 
     mkdir -p "$out"
 
-    cat > "$out/index.xml" << 'EOF'
-    <?xml version="1.0" encoding="utf-8"?>
-    <root xmlns:xi="http://www.w3.org/2001/XInclude">
+    cat > "$out/index.md" << 'EOF'
+    ```{=include=} sections
     EOF
 
-    ${lib.concatMapStrings ({ name, description }: ''
-      docgen ${name} ${lib.escapeShellArg description}
+    ${lib.concatMapStrings ({ name, baseName ? name, description }: ''
+      docgen ${name} ${baseName} ${lib.escapeShellArg description}
     '') libsets}
 
-    echo "</root>" >> "$out/index.xml"
-
-    ln -s ${locationsXml} $out/locations.xml
+    echo '```' >> "$out/index.md"
   '';
 }
diff --git a/nixpkgs/doc/doc-support/lib-function-locations.nix b/nixpkgs/doc/doc-support/lib-function-locations.nix
index 1ee59648330a..e6794617fdd8 100644
--- a/nixpkgs/doc/doc-support/lib-function-locations.nix
+++ b/nixpkgs/doc/doc-support/lib-function-locations.nix
@@ -58,28 +58,18 @@ let
     [ "-prime" ];
 
   urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";
-  xmlstrings = (nixpkgsLib.strings.concatMapStrings
-      ({ name, value }:
-      ''
-      <section><title>${name}</title>
-        <para xml:id="${sanitizeId name}">
-        Located at
-        <link
-          xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link>
-        in  <literal>&lt;nixpkgs&gt;</literal>.
-        </para>
-        </section>
-      '')
-      relativeLocs);
+  jsonLocs = builtins.listToAttrs
+    (builtins.map
+      ({ name, value }: {
+        name = sanitizeId name;
+        value =
+          let
+            text = "${value.file}:${builtins.toString value.line}";
+            target = "${urlPrefix}/${value.file}#L${builtins.toString value.line}";
+          in
+            "[${text}](${target}) in `<nixpkgs>`";
+      })
+    relativeLocs);
 
-in pkgs.writeText
-    "locations.xml"
-    ''
-    <section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         version="5">
-         <title>All the locations for every lib function</title>
-         <para>This file is only for inclusion by other files.</para>
-         ${xmlstrings}
-    </section>
-    ''
+in
+pkgs.writeText "locations.json" (builtins.toJSON jsonLocs)
diff --git a/nixpkgs/doc/doc-support/parameters.xml b/nixpkgs/doc/doc-support/parameters.xml
deleted file mode 100644
index 5b39d2f7f1a5..000000000000
--- a/nixpkgs/doc/doc-support/parameters.xml
+++ /dev/null
@@ -1,19 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-    version="1.0">
- <xsl:param name="chapter.autolabel" select="0" />
- <xsl:param name="part.autolabel" select="0" />
- <xsl:param name="preface.autolabel" select="0" />
- <xsl:param name="reference.autolabel" select="0" />
- <xsl:param name="section.autolabel" select="0" />
- <xsl:param name="html.stylesheet" select="'style.css overrides.css highlightjs/mono-blue.css'" />
- <xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" />
- <xsl:param name="xref.with.number.and.title" select="0" />
- <xsl:param name="use.id.as.filename" select="1" />
- <xsl:param name="generate.section.toc.level" select="1" />
- <xsl:param name="toc.section.depth" select="0" />
- <xsl:param name="admon.style" select="''" />
- <xsl:param name="callout.graphics.extension" select="'.svg'" />
- <xsl:param name="generate.consistent.ids" select="1" />
-</xsl:stylesheet>
diff --git a/nixpkgs/doc/doc-support/xmlformat.conf b/nixpkgs/doc/doc-support/xmlformat.conf
deleted file mode 100644
index c3f39c7fd81b..000000000000
--- a/nixpkgs/doc/doc-support/xmlformat.conf
+++ /dev/null
@@ -1,72 +0,0 @@
-#
-# DocBook Configuration file for "xmlformat"
-# see http://www.kitebird.com/software/xmlformat/
-# 10 Sept. 2004
-#
-
-# Only block elements
-ackno address appendix article biblioentry bibliography bibliomixed \
-biblioset blockquote book bridgehead callout calloutlist caption caution \
-chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \
-constructorsynopsis dedication destructorsynopsis entry epigraph equation example \
-figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \
-glosssee glossseealso graphic graphicco highlights imageobjectco important \
-index indexdiv indexentry indexinfo info informalequation informalexample \
-informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \
-mediaobjectco msgmain msgset note orderedlist para part preface primaryie \
-procedure qandadiv qandaentry qandaset refentry refentrytitle reference \
-refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \
-sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \
-simplesect step substeps synopfragment synopsis table term title \
-toc variablelist varlistentry warning itemizedlist listitem \
-footnote colspec partintro row simplelist subtitle tbody tgroup thead tip
-  format      block
-  normalize   no
-
-
-#appendix bibliography chapter glossary preface reference
-#  element-break   3
-
-sect1 section
-  element-break   2
-
-
-#
-para abstract
-  format       block
-  entry-break  1
-  exit-break   1
-  normalize    yes
-
-title
-  format       block
-  normalize = yes
-  entry-break = 0
-  exit-break = 0
-
-# Inline elements
-abbrev accel acronym action application citation citebiblioid citerefentry citetitle \
-classname co code command computeroutput constant country database date email emphasis \
-envar errorcode errorname errortext errortype exceptionname fax filename \
-firstname firstterm footnoteref foreignphrase funcdef funcparams function \
-glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \
-hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \
-interface interfacename \
-keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \
-menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \
-oointerface option optional otheraddr othername package paramdef parameter personname \
-phrase pob postcode productname prompt property quote refpurpose replaceable \
-returnvalue revnumber sgmltag state street structfield structname subscript \
-superscript surname symbol systemitem token trademark type ulink userinput \
-uri varargs varname void wordasword xref year mathphrase member tag
-  format       inline
-
-programlisting screen
-  format       verbatim
-  entry-break = 0
-  exit-break = 0
-
-# This is needed so that the spacing inside those tags is kept.
-term cmdsynopsis arg
-  normalize yes
-  format    block
diff --git a/nixpkgs/doc/functions.md b/nixpkgs/doc/functions.md
new file mode 100644
index 000000000000..09033c9e3c19
--- /dev/null
+++ b/nixpkgs/doc/functions.md
@@ -0,0 +1,11 @@
+# Functions reference {#chap-functions}
+
+The nixpkgs repository has several utility functions to manipulate Nix expressions.
+
+```{=include=} sections
+functions/library.md
+functions/generators.section.md
+functions/debug.section.md
+functions/prefer-remote-fetch.section.md
+functions/nix-gitignore.section.md
+```
diff --git a/nixpkgs/doc/functions.xml b/nixpkgs/doc/functions.xml
deleted file mode 100644
index 8ef530d307cd..000000000000
--- a/nixpkgs/doc/functions.xml
+++ /dev/null
@@ -1,14 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-functions">
- <title>Functions reference</title>
- <para>
-  The nixpkgs repository has several utility functions to manipulate Nix expressions.
- </para>
- <xi:include href="functions/library.xml" />
- <xi:include href="functions/generators.section.xml" />
- <xi:include href="functions/debug.section.xml" />
- <xi:include href="functions/prefer-remote-fetch.section.xml" />
- <xi:include href="functions/nix-gitignore.section.xml" />
-</chapter>
diff --git a/nixpkgs/doc/functions/library.md.in b/nixpkgs/doc/functions/library.md.in
new file mode 100644
index 000000000000..e17de86feb8a
--- /dev/null
+++ b/nixpkgs/doc/functions/library.md.in
@@ -0,0 +1,5 @@
+# Nixpkgs Library Functions {#sec-functions-library}
+
+Nixpkgs provides a standard library at `pkgs.lib`, or through `import <nixpkgs/lib>`.
+
+<!-- nixdoc-generated documentation must be appended here during build! -->
diff --git a/nixpkgs/doc/functions/library.xml b/nixpkgs/doc/functions/library.xml
deleted file mode 100644
index 788ea0b94f1f..000000000000
--- a/nixpkgs/doc/functions/library.xml
+++ /dev/null
@@ -1,14 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="sec-functions-library">
- <title>Nixpkgs Library Functions</title>
-
- <para>
-  Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import &lt;nixpkgs/lib&gt;</code>.
- </para>
-
- <!-- The index must have a root element to declare namespaces, but we
-      don't want to include it, so we select all of its children. -->
- <xi:include href="./library/generated/index.xml" xpointer="xpointer(/root/*)" />
-</section>
diff --git a/nixpkgs/doc/hooks/autoconf.section.md b/nixpkgs/doc/hooks/autoconf.section.md
index 13d75910f192..90e4681ef93f 100644
--- a/nixpkgs/doc/hooks/autoconf.section.md
+++ b/nixpkgs/doc/hooks/autoconf.section.md
@@ -1,4 +1,3 @@
-
-### Autoconf {#setup-hook-autoconf}
+# Autoconf {#setup-hook-autoconf}
 
 The `autoreconfHook` derivation adds `autoreconfPhase`, which runs autoreconf, libtoolize and automake, essentially preparing the configure script in autotools-based builds. Most autotools-based packages come with the configure script pre-generated, but this hook is necessary for a few packages and when you need to patch the package’s configure scripts.
diff --git a/nixpkgs/doc/hooks/automake.section.md b/nixpkgs/doc/hooks/automake.section.md
index 562ac18fcd93..dd0ff9c0cc09 100644
--- a/nixpkgs/doc/hooks/automake.section.md
+++ b/nixpkgs/doc/hooks/automake.section.md
@@ -1,4 +1,3 @@
-
-### Automake {#setup-hook-automake}
+# Automake {#setup-hook-automake}
 
 Adds the `share/aclocal` subdirectory of each build input to the `ACLOCAL_PATH` environment variable.
diff --git a/nixpkgs/doc/hooks/autopatchelf.section.md b/nixpkgs/doc/hooks/autopatchelf.section.md
index 9c2852ccf279..008a90d46140 100644
--- a/nixpkgs/doc/hooks/autopatchelf.section.md
+++ b/nixpkgs/doc/hooks/autopatchelf.section.md
@@ -1,5 +1,4 @@
-
-### autoPatchelfHook {#setup-hook-autopatchelfhook}
+# autoPatchelfHook {#setup-hook-autopatchelfhook}
 
 This is a special setup hook which helps in packaging proprietary software in that it automatically tries to find missing shared library dependencies of ELF files based on the given `buildInputs` and `nativeBuildInputs`.
 
diff --git a/nixpkgs/doc/hooks/breakpoint.section.md b/nixpkgs/doc/hooks/breakpoint.section.md
index 9600e06b7934..424a9424b55e 100644
--- a/nixpkgs/doc/hooks/breakpoint.section.md
+++ b/nixpkgs/doc/hooks/breakpoint.section.md
@@ -1,5 +1,4 @@
-
-### breakpointHook {#breakpointhook}
+# breakpointHook {#breakpointhook}
 
 This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`.
 
diff --git a/nixpkgs/doc/hooks/cmake.section.md b/nixpkgs/doc/hooks/cmake.section.md
index 58fbfa45a2e0..b5dc5a914434 100644
--- a/nixpkgs/doc/hooks/cmake.section.md
+++ b/nixpkgs/doc/hooks/cmake.section.md
@@ -1,4 +1,3 @@
-
-### cmake {#cmake}
+# cmake {#cmake}
 
 Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to `CMAKE_PREFIX_PATH` so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hook’s behavior by setting `configurePhase` to a custom value, or by setting `dontUseCmakeConfigure`. `cmakeFlags` controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator.
diff --git a/nixpkgs/doc/hooks/gdk-pixbuf.section.md b/nixpkgs/doc/hooks/gdk-pixbuf.section.md
index 565216560abc..cf7203dfc66f 100644
--- a/nixpkgs/doc/hooks/gdk-pixbuf.section.md
+++ b/nixpkgs/doc/hooks/gdk-pixbuf.section.md
@@ -1,4 +1,3 @@
-
-### gdk-pixbuf {#setup-hook-gdk-pixbuf}
+# gdk-pixbuf {#setup-hook-gdk-pixbuf}
 
 Exports `GDK_PIXBUF_MODULE_FILE` environment variable to the builder. Add librsvg package to `buildInputs` to get svg support. See also the [setup hook description in GNOME platform docs](#ssec-gnome-hooks-gdk-pixbuf).
diff --git a/nixpkgs/doc/hooks/ghc.section.md b/nixpkgs/doc/hooks/ghc.section.md
index a4b0841ea486..ac054b954a92 100644
--- a/nixpkgs/doc/hooks/ghc.section.md
+++ b/nixpkgs/doc/hooks/ghc.section.md
@@ -1,4 +1,3 @@
-
-### GHC {#ghc}
+# GHC {#ghc}
 
 Creates a temporary package database and registers every Haskell build input in it (TODO: how?).
diff --git a/nixpkgs/doc/hooks/gnome.section.md b/nixpkgs/doc/hooks/gnome.section.md
index 8c209d9b472c..b10e80802027 100644
--- a/nixpkgs/doc/hooks/gnome.section.md
+++ b/nixpkgs/doc/hooks/gnome.section.md
@@ -1,4 +1,3 @@
-
-### GNOME platform {#gnome-platform}
+# GNOME platform {#gnome-platform}
 
 Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in [](#sec-language-gnome).
diff --git a/nixpkgs/doc/hooks/index.md b/nixpkgs/doc/hooks/index.md
new file mode 100644
index 000000000000..602febaf9d9b
--- /dev/null
+++ b/nixpkgs/doc/hooks/index.md
@@ -0,0 +1,34 @@
+# Hooks reference {#chap-hooks}
+
+Nixpkgs has several hook packages that augment the stdenv phases.
+
+The stdenv built-in hooks are documented in [](#ssec-setup-hooks).
+
+```{=include=} sections
+autoconf.section.md
+automake.section.md
+autopatchelf.section.md
+breakpoint.section.md
+cmake.section.md
+gdk-pixbuf.section.md
+ghc.section.md
+gnome.section.md
+installShellFiles.section.md
+libiconv.section.md
+libxml2.section.md
+meson.section.md
+ninja.section.md
+patch-rc-path-hooks.section.md
+perl.section.md
+pkg-config.section.md
+postgresql-test-hook.section.md
+python.section.md
+qt-4.section.md
+scons.section.md
+tetex-tex-live.section.md
+unzip.section.md
+validatePkgConfig.section.md
+waf.section.md
+zig.section.md
+xcbuild.section.md
+```
diff --git a/nixpkgs/doc/hooks/index.xml b/nixpkgs/doc/hooks/index.xml
deleted file mode 100644
index 0917fac6c0ac..000000000000
--- a/nixpkgs/doc/hooks/index.xml
+++ /dev/null
@@ -1,37 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-hooks">
- <title>Hooks reference</title>
- <para>
-  Nixpkgs has several hook packages that augment the stdenv phases.
- </para>
- <para>
-  The stdenv built-in hooks are documented in <xref linkend="ssec-setup-hooks"/>.
- </para>
- <xi:include href="./autoconf.section.xml" />
- <xi:include href="./automake.section.xml" />
- <xi:include href="./autopatchelf.section.xml" />
- <xi:include href="./breakpoint.section.xml" />
- <xi:include href="./cmake.section.xml" />
- <xi:include href="./gdk-pixbuf.section.xml" />
- <xi:include href="./ghc.section.xml" />
- <xi:include href="./gnome.section.xml" />
- <xi:include href="./installShellFiles.section.xml" />
- <xi:include href="./libiconv.section.xml" />
- <xi:include href="./libxml2.section.xml" />
- <xi:include href="./meson.section.xml" />
- <xi:include href="./ninja.section.xml" />
- <xi:include href="./patch-rc-path-hooks.section.xml" />
- <xi:include href="./perl.section.xml" />
- <xi:include href="./pkg-config.section.xml" />
- <xi:include href="./postgresql-test-hook.section.xml" />
- <xi:include href="./python.section.xml" />
- <xi:include href="./qt-4.section.xml" />
- <xi:include href="./scons.section.xml" />
- <xi:include href="./tetex-tex-live.section.xml" />
- <xi:include href="./unzip.section.xml" />
- <xi:include href="./validatePkgConfig.section.xml" />
- <xi:include href="./waf.section.xml" />
- <xi:include href="./xcbuild.section.xml" />
-</chapter>
diff --git a/nixpkgs/doc/hooks/installShellFiles.section.md b/nixpkgs/doc/hooks/installShellFiles.section.md
index d27527503fed..84adea2fa30c 100644
--- a/nixpkgs/doc/hooks/installShellFiles.section.md
+++ b/nixpkgs/doc/hooks/installShellFiles.section.md
@@ -1,5 +1,4 @@
-
-### `installShellFiles` {#installshellfiles}
+# `installShellFiles` {#installshellfiles}
 
 This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook.
 
diff --git a/nixpkgs/doc/hooks/libiconv.section.md b/nixpkgs/doc/hooks/libiconv.section.md
index c228fe339e14..0ffa6d09b0a8 100644
--- a/nixpkgs/doc/hooks/libiconv.section.md
+++ b/nixpkgs/doc/hooks/libiconv.section.md
@@ -1,4 +1,3 @@
-
-### libiconv, libintl {#libiconv-libintl}
+# libiconv, libintl {#libiconv-libintl}
 
 A few libraries automatically add to `NIX_LDFLAGS` their library, making their symbols automatically available to the linker. This includes libiconv and libintl (gettext). This is done to provide compatibility between GNU Linux, where libiconv and libintl are bundled in, and other systems where that might not be the case. Sometimes, this behavior is not desired. To disable this behavior, set `dontAddExtraLibs`.
diff --git a/nixpkgs/doc/hooks/libxml2.section.md b/nixpkgs/doc/hooks/libxml2.section.md
index 770ef9ff3ffe..df387fb5e222 100644
--- a/nixpkgs/doc/hooks/libxml2.section.md
+++ b/nixpkgs/doc/hooks/libxml2.section.md
@@ -1,4 +1,3 @@
-
-### libxml2 {#setup-hook-libxml2}
+# libxml2 {#setup-hook-libxml2}
 
 Adds every file named `catalog.xml` found under the `xml/dtd` and `xml/xsl` subdirectories of each build input to the `XML_CATALOG_FILES` environment variable.
diff --git a/nixpkgs/doc/hooks/meson.section.md b/nixpkgs/doc/hooks/meson.section.md
index 32804b5e32f2..fd7779e6468f 100644
--- a/nixpkgs/doc/hooks/meson.section.md
+++ b/nixpkgs/doc/hooks/meson.section.md
@@ -1,26 +1,25 @@
-
-### Meson {#meson}
+# Meson {#meson}
 
 Overrides the configure phase to run meson to generate Ninja files. To run these files, you should accompany Meson with ninja. By default, `enableParallelBuilding` is enabled as Meson supports parallel building almost everywhere.
 
-#### Variables controlling Meson {#variables-controlling-meson}
+## Variables controlling Meson {#variables-controlling-meson}
 
-##### `mesonFlags` {#mesonflags}
+### `mesonFlags` {#mesonflags}
 
 Controls the flags passed to meson.
 
-##### `mesonBuildType` {#mesonbuildtype}
+### `mesonBuildType` {#mesonbuildtype}
 
 Which [`--buildtype`](https://mesonbuild.com/Builtin-options.html#core-options) to pass to Meson. We default to `plain`.
 
-##### `mesonAutoFeatures` {#mesonautofeatures}
+### `mesonAutoFeatures` {#mesonautofeatures}
 
 What value to set [`-Dauto_features=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `enabled`.
 
-##### `mesonWrapMode` {#mesonwrapmode}
+### `mesonWrapMode` {#mesonwrapmode}
 
 What value to set [`-Dwrap_mode=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `nodownload` as we disallow network access.
 
-##### `dontUseMesonConfigure` {#dontusemesonconfigure}
+### `dontUseMesonConfigure` {#dontusemesonconfigure}
 
 Disables using Meson’s `configurePhase`.
diff --git a/nixpkgs/doc/hooks/ninja.section.md b/nixpkgs/doc/hooks/ninja.section.md
index 5ea1ee87070a..4b0e33feb5c3 100644
--- a/nixpkgs/doc/hooks/ninja.section.md
+++ b/nixpkgs/doc/hooks/ninja.section.md
@@ -1,4 +1,3 @@
-
-### ninja {#ninja}
+# ninja {#ninja}
 
 Overrides the build, install, and check phase to run ninja instead of make. You can disable this behavior with the `dontUseNinjaBuild`, `dontUseNinjaInstall`, and `dontUseNinjaCheck`, respectively. Parallel building is enabled by default in Ninja.
diff --git a/nixpkgs/doc/hooks/perl.section.md b/nixpkgs/doc/hooks/perl.section.md
index 403227a9bf18..06942bd3c0e1 100644
--- a/nixpkgs/doc/hooks/perl.section.md
+++ b/nixpkgs/doc/hooks/perl.section.md
@@ -1,4 +1,3 @@
-
-### Perl {#setup-hook-perl}
+# Perl {#setup-hook-perl}
 
 Adds the `lib/site_perl` subdirectory of each build input to the `PERL5LIB` environment variable. For instance, if `buildInputs` contains Perl, then the `lib/site_perl` subdirectory of each input is added to the `PERL5LIB` environment variable.
diff --git a/nixpkgs/doc/hooks/pkg-config.section.md b/nixpkgs/doc/hooks/pkg-config.section.md
index 969c81f6d18a..c98701cf9c9d 100644
--- a/nixpkgs/doc/hooks/pkg-config.section.md
+++ b/nixpkgs/doc/hooks/pkg-config.section.md
@@ -1,4 +1,3 @@
-
-### pkg-config {#setup-hook-pkg-config}
+# pkg-config {#setup-hook-pkg-config}
 
 Adds the `lib/pkgconfig` and `share/pkgconfig` subdirectories of each build input to the `PKG_CONFIG_PATH` environment variable.
diff --git a/nixpkgs/doc/hooks/python.section.md b/nixpkgs/doc/hooks/python.section.md
index a46a727e95b1..ecaae491e994 100644
--- a/nixpkgs/doc/hooks/python.section.md
+++ b/nixpkgs/doc/hooks/python.section.md
@@ -1,4 +1,3 @@
-
-### Python {#setup-hook-python}
+# Python {#setup-hook-python}
 
 Adds the `lib/${python.libPrefix}/site-packages` subdirectory of each build input to the `PYTHONPATH` environment variable.
diff --git a/nixpkgs/doc/hooks/qt-4.section.md b/nixpkgs/doc/hooks/qt-4.section.md
index f15d858e2377..4b704df49597 100644
--- a/nixpkgs/doc/hooks/qt-4.section.md
+++ b/nixpkgs/doc/hooks/qt-4.section.md
@@ -1,4 +1,3 @@
-
-### Qt 4 {#qt-4}
+# Qt 4 {#qt-4}
 
 Sets the `QTDIR` environment variable to Qt’s path.
diff --git a/nixpkgs/doc/hooks/scons.section.md b/nixpkgs/doc/hooks/scons.section.md
index 1392269e5d55..0a7a7aa023b6 100644
--- a/nixpkgs/doc/hooks/scons.section.md
+++ b/nixpkgs/doc/hooks/scons.section.md
@@ -1,4 +1,3 @@
-
-### scons {#scons}
+# scons {#scons}
 
 Overrides the build, install, and check phases. This uses the scons build system as a replacement for make. scons does not provide a configure phase, so everything is managed at build and install time.
diff --git a/nixpkgs/doc/hooks/tetex-tex-live.section.md b/nixpkgs/doc/hooks/tetex-tex-live.section.md
index 0ecdcc12e45a..b702971d727c 100644
--- a/nixpkgs/doc/hooks/tetex-tex-live.section.md
+++ b/nixpkgs/doc/hooks/tetex-tex-live.section.md
@@ -1,4 +1,3 @@
-
-### teTeX / TeX Live {#tetex-tex-live}
+# teTeX / TeX Live {#tetex-tex-live}
 
 Adds the `share/texmf-nix` subdirectory of each build input to the `TEXINPUTS` environment variable.
diff --git a/nixpkgs/doc/hooks/unzip.section.md b/nixpkgs/doc/hooks/unzip.section.md
index 91dc072de662..5ec67e576a33 100644
--- a/nixpkgs/doc/hooks/unzip.section.md
+++ b/nixpkgs/doc/hooks/unzip.section.md
@@ -1,4 +1,3 @@
-
-### unzip {#unzip}
+# unzip {#unzip}
 
 This setup hook will allow you to unzip .zip files specified in `$src`. There are many similar packages like `unrar`, `undmg`, etc.
diff --git a/nixpkgs/doc/hooks/validatePkgConfig.section.md b/nixpkgs/doc/hooks/validatePkgConfig.section.md
index 8719ae930fcb..aa6e0c06c223 100644
--- a/nixpkgs/doc/hooks/validatePkgConfig.section.md
+++ b/nixpkgs/doc/hooks/validatePkgConfig.section.md
@@ -1,4 +1,3 @@
-
-### validatePkgConfig {#validatepkgconfig}
+# validatePkgConfig {#validatepkgconfig}
 
 The `validatePkgConfig` hook validates all pkg-config (`.pc`) files in a package. This helps catching some common errors in pkg-config files, such as undefined variables.
diff --git a/nixpkgs/doc/hooks/waf.section.md b/nixpkgs/doc/hooks/waf.section.md
index de65abde4502..ee1bccff1d0a 100644
--- a/nixpkgs/doc/hooks/waf.section.md
+++ b/nixpkgs/doc/hooks/waf.section.md
@@ -1,4 +1,3 @@
-
-### wafHook {#wafhook}
+# wafHook {#wafhook}
 
 Overrides the configure, build, and install phases. This will run the “waf” script used by many projects. If `wafPath` (default `./waf`) doesn’t exist, it will copy the version of waf available in Nixpkgs. `wafFlags` can be used to pass flags to the waf script.
diff --git a/nixpkgs/doc/hooks/xcbuild.section.md b/nixpkgs/doc/hooks/xcbuild.section.md
index 1426431f6dce..bf404b64c3f9 100644
--- a/nixpkgs/doc/hooks/xcbuild.section.md
+++ b/nixpkgs/doc/hooks/xcbuild.section.md
@@ -1,4 +1,3 @@
-
-### xcbuildHook {#xcbuildhook}
+# xcbuildHook {#xcbuildhook}
 
 Overrides the build and install phases to run the "xcbuild" command. This hook is needed when a project only comes with build files for the XCode build system. You can disable this behavior by setting buildPhase and configurePhase to a custom value. xcbuildFlags controls flags passed only to xcbuild.
diff --git a/nixpkgs/doc/hooks/zig.section.md b/nixpkgs/doc/hooks/zig.section.md
new file mode 100644
index 000000000000..78b8262f4749
--- /dev/null
+++ b/nixpkgs/doc/hooks/zig.section.md
@@ -0,0 +1,59 @@
+# zigHook {#zighook}
+
+[Zig](https://ziglang.org/) is a general-purpose programming language and toolchain for maintaining robust, optimal and reusable software.
+
+In Nixpkgs, `zigHook` overrides the default build, check and install phases.
+
+## Example code snippet {#example-code-snippet}
+
+```nix
+{ lib
+, stdenv
+, zigHook
+}:
+
+stdenv.mkDerivation {
+  # . . .
+
+  nativeBuildInputs = [
+    zigHook
+  ];
+
+  zigBuildFlags = [ "-Dman-pages=true" ];
+
+  dontUseZigCheck = true;
+
+  # . . .
+}
+```
+
+## Variables controlling zigHook {#variables-controlling-zighook}
+
+### `dontUseZigBuild` {#dontUseZigBuild}
+
+Disables using `zigBuildPhase`.
+
+### `zigBuildFlags` {#zigBuildFlags}
+
+Controls the flags passed to the build phase.
+
+### `dontUseZigCheck` {#dontUseZigCheck}
+
+Disables using `zigCheckPhase`.
+
+### `zigCheckFlags` {#zigCheckFlags}
+
+Controls the flags passed to the check phase.
+
+### `dontUseZigInstall` {#dontUseZigInstall}
+
+Disables using `zigInstallPhase`.
+
+### `zigInstallFlags` {#zigInstallFlags}
+
+Controls the flags passed to the install phase.
+
+### Variables honored by zigHook {#variablesHonoredByZigHook}
+
+- `prefixKey`
+- `dontAddPrefix`
diff --git a/nixpkgs/doc/languages-frameworks/bower.section.md b/nixpkgs/doc/languages-frameworks/bower.section.md
index f39539059c04..fceb6aaccb6d 100644
--- a/nixpkgs/doc/languages-frameworks/bower.section.md
+++ b/nixpkgs/doc/languages-frameworks/bower.section.md
@@ -41,32 +41,18 @@ The function is implemented in [pkgs/development/bower-modules/generic/default.n
 
 ### Example buildBowerComponents {#ex-buildBowerComponents}
 
-```{=docbook}
-<programlisting language="nix">
+```nix
 bowerComponents = buildBowerComponents {
   name = "my-web-app";
-  generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" />
-  src = myWebApp; <co xml:id="ex-buildBowerComponents-2" />
+  generated = ./bower-packages.nix; # note 1
+  src = myWebApp; # note 2
 };
-</programlisting>
 ```
 
 In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function:
 
-```{=docbook}
-<calloutlist>
-  <callout arearefs="ex-buildBowerComponents-1">
-    <para>
-      <varname>generated</varname> specifies the file which was created by <command>bower2nix</command>.
-    </para>
-    </callout>
-      <callout arearefs="ex-buildBowerComponents-2">
-    <para>
-      <varname>src</varname> is your project's sources. It needs to contain a <filename>bower.json</filename> file.
-    </para>
-  </callout>
-</calloutlist>
-```
+1. `generated` specifies the file which was created by {command}`bower2nix`.
+2. `src` is your project's sources. It needs to contain a {file}`bower.json` file.
 
 `buildBowerComponents` will run Bower to link together the output of `bower2nix`, resulting in a `bower_components` directory which can be used.
 
@@ -91,10 +77,9 @@ gulp.task('build', [], function () {
 
 ### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix}
 
-```{=docbook}
-<programlisting language="nix">
+```nix
 { myWebApp ? { outPath = ./.; name = "myWebApp"; }
-, pkgs ? import &lt;nixpkgs&gt; {}
+, pkgs ? import <nixpkgs> {}
 }:
 
 pkgs.stdenv.mkDerivation {
@@ -103,49 +88,29 @@ pkgs.stdenv.mkDerivation {
 
   buildInputs = [ pkgs.nodePackages.gulp ];
 
-  bowerComponents = pkgs.buildBowerComponents { <co xml:id="ex-buildBowerComponentsDefault-1" />
+  bowerComponents = pkgs.buildBowerComponents { # note 1
     name = "my-web-app";
     generated = ./bower-packages.nix;
     src = myWebApp;
   };
 
   buildPhase = ''
-    cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . <co xml:id="ex-buildBowerComponentsDefault-2" />
-    export HOME=$PWD <co xml:id="ex-buildBowerComponentsDefault-3" />
-    ${pkgs.nodePackages.gulp}/bin/gulp build <co xml:id="ex-buildBowerComponentsDefault-4" />
+    cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . # note 2
+    export HOME=$PWD # note 3
+    ${pkgs.nodePackages.gulp}/bin/gulp build # note 4
   '';
 
   installPhase = "mv gulpdist $out";
 }
-</programlisting>
 ```
 
 A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix):
 
-```{=docbook}
-<calloutlist>
-  <callout arearefs="ex-buildBowerComponentsDefault-1">
-    <para>
-      The result of <varname>buildBowerComponents</varname> is an input to the frontend build.
-    </para>
-  </callout>
-  <callout arearefs="ex-buildBowerComponentsDefault-2">
-    <para>
-      Whether to symlink or copy the <filename>bower_components</filename> directory depends on the build tool in use. In this case a copy is used to avoid <command>gulp</command> silliness with permissions.
-    </para>
-  </callout>
-  <callout arearefs="ex-buildBowerComponentsDefault-3">
-    <para>
-      <command>gulp</command> requires <varname>HOME</varname> to refer to a writeable directory.
-    </para>
-  </callout>
-  <callout arearefs="ex-buildBowerComponentsDefault-4">
-    <para>
-      The actual build command. Other tools could be used.
-    </para>
-  </callout>
-</calloutlist>
-```
+1. The result of `buildBowerComponents` is an input to the frontend build.
+2. Whether to symlink or copy the {file}`bower_components` directory depends on the build tool in use.
+   In this case a copy is used to avoid {command}`gulp` silliness with permissions.
+3. {command}`gulp` requires `HOME` to refer to a writeable directory.
+4. The actual build command in this example is {command}`gulp`. Other tools could be used instead.
 
 ## Troubleshooting {#ssec-bower2nix-troubleshooting}
 
diff --git a/nixpkgs/doc/languages-frameworks/cuda.section.md b/nixpkgs/doc/languages-frameworks/cuda.section.md
index 6b19e02e74e9..b7f1f19546a7 100644
--- a/nixpkgs/doc/languages-frameworks/cuda.section.md
+++ b/nixpkgs/doc/languages-frameworks/cuda.section.md
@@ -12,8 +12,11 @@ compatible are available as well. For example, there can be a
 
 To use one or more CUDA packages in an expression, give the expression a `cudaPackages` parameter, and in case CUDA is optional
 ```nix
-cudaSupport ? false
-cudaPackages ? {}
+{ config
+, cudaSupport ? config.cudaSupport
+, cudaPackages ? { }
+, ...
+}:
 ```
 
 When using `callPackage`, you can choose to pass in a different variant, e.g.
diff --git a/nixpkgs/doc/languages-frameworks/dotnet.section.md b/nixpkgs/doc/languages-frameworks/dotnet.section.md
index b6a622875a76..246490d67d26 100644
--- a/nixpkgs/doc/languages-frameworks/dotnet.section.md
+++ b/nixpkgs/doc/languages-frameworks/dotnet.section.md
@@ -92,7 +92,7 @@ The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given
 
 To package Dotnet applications, you can use `buildDotnetModule`. This has similar arguments to `stdenv.mkDerivation`, with the following additions:
 
-* `projectFile` is used for specifying the dotnet project file, relative to the source root. These usually have `.sln` or `.csproj` file extensions. This can be a list of multiple projects as well. Most of the time dotnet can figure this location out by itself, so this should only be set if necessary.
+* `projectFile` is used for specifying the dotnet project file, relative to the source root. These have `.sln` (entire solution) or `.csproj` (single project) file extensions. This can be a list of multiple projects as well. When omitted, will attempt to find and build the solution (`.sln`). If running into problems, make sure to set it to a file (or a list of files) with the `.csproj` extension - building applications as entire solutions is not fully supported by the .NET CLI.
 * `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. This file can also be generated manually using `nuget-to-nix` tool, which is available in nixpkgs. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.
 * `packNupkg` is used to pack project as a `nupkg`, and installs it to `$out/share`. If set to `true`, the derivation can be used as a dependency for another dotnet project by adding it to `projectReferences`.
 * `projectReferences` can be used to resolve `ProjectReference` project items. Referenced projects can be packed with `buildDotnetModule` by setting the `packNupkg = true` attribute and passing a list of derivations to `projectReferences`. Since we are sharing referenced projects as NuGets they must be added to csproj/fsproj files as `PackageReference` as well.
@@ -108,11 +108,13 @@ To package Dotnet applications, you can use `buildDotnetModule`. This has simila
 * `executables` is used to specify which executables get wrapped to `$out/bin`, relative to `$out/lib/$pname`. If this is unset, all executables generated will get installed. If you do not want to install any, set this to `[]`. This gets done in the `preFixup` phase.
 * `runtimeDeps` is used to wrap libraries into `LD_LIBRARY_PATH`. This is how dotnet usually handles runtime dependencies.
 * `buildType` is used to change the type of build. Possible values are `Release`, `Debug`, etc. By default, this is set to `Release`.
-* `selfContainedBuild` allows to enable the [self-contained](https://docs.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained) build flag. By default, it is set to false and generated applications have a dependency on the selected dotnet runtime. If enabled, the dotnet runtime is bundled into the executable and the built app has no dependency on Dotnet.
+* `selfContainedBuild` allows to enable the [self-contained](https://docs.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained) build flag. By default, it is set to false and generated applications have a dependency on the selected dotnet runtime. If enabled, the dotnet runtime is bundled into the executable and the built app has no dependency on .NET.
+* `useAppHost` will enable creation of a binary executable that runs the .NET application using the specified root. More info in [Microsoft docs](https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-framework-dependent). Enabled by default.
+* `useDotnetFromEnv` will change the binary wrapper so that it uses the .NET from the environment. The runtime specified by `dotnet-runtime` is given as a fallback in case no .NET is installed in the user's environment. This is most useful for .NET global tools and LSP servers, which often extend the .NET CLI and their runtime should match the users' .NET runtime.
 * `dotnet-sdk` is useful in cases where you need to change what dotnet SDK is being used. You can also set this to the result of `dotnetSdkPackages.combinePackages`, if the project uses multiple SDKs to build.
 * `dotnet-runtime` is useful in cases where you need to change what dotnet runtime is being used. This can be either a regular dotnet runtime, or an aspnetcore.
 * `dotnet-test-sdk` is useful in cases where unit tests expect a different dotnet SDK. By default, this is set to the `dotnet-sdk` attribute.
-* `testProjectFile` is useful in cases where the regular project file does not contain the unit tests. It gets restored and build, but not installed. You may need to regenerate your nuget lockfile after setting this.
+* `testProjectFile` is useful in cases where the regular project file does not contain the unit tests. It gets restored and build, but not installed. You may need to regenerate your nuget lockfile after setting this. Note that if set, only tests from this project are executed.
 * `disabledTests` is used to disable running specific unit tests. This gets passed as: `dotnet test --filter "FullyQualifiedName!={}"`, to ensure compatibility with all unit test frameworks.
 * `dotnetRestoreFlags` can be used to pass flags to `dotnet restore`.
 * `dotnetBuildFlags` can be used to pass flags to `dotnet build`.
@@ -121,7 +123,7 @@ To package Dotnet applications, you can use `buildDotnetModule`. This has simila
 * `dotnetPackFlags` can be used to pass flags to `dotnet pack`. Used only if `packNupkg` is set to `true`.
 * `dotnetFlags` can be used to pass flags to all of the above phases.
 
-When packaging a new application, you need to fetch its dependencies. You can run `nix-build -A package.fetch-deps` to generate a script that will build a lockfile for you. After running the script you should have the location of the generated lockfile printed to the console, which can be copied to a stable directory. Then set `nugetDeps = ./deps.nix` and you're ready to build the derivation.
+When packaging a new application, you need to fetch its dependencies. Create an empty `deps.nix`, set `nugetDeps = ./deps.nix`, then run `nix-build -A package.fetch-deps` to generate a script that will build the lockfile for you.
 
 Here is an example `default.nix`, using some of the previously discussed arguments:
 ```nix
@@ -151,3 +153,60 @@ in buildDotnetModule rec {
   runtimeDeps = [ ffmpeg ]; # This will wrap ffmpeg's library path into `LD_LIBRARY_PATH`.
 }
 ```
+
+## Dotnet global tools {#dotnet-global-tools}
+
+[.NET Global tools](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools) are a mechanism provided by the dotnet CLI to install .NET binaries from Nuget packages.
+
+They can be installed either as a global tool for the entire system, or as a local tool specific to project.
+
+The local installation is the easiest and works on NixOS in the same way as on other Linux distributions.
+[See dotnet documention](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-local-tool) to learn more.
+
+[The global installation method](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-global-tool)
+should also work most of the time. You have to remember to update the `PATH`
+value to the location the tools are installed to (the CLI will inform you about it during installation) and also set
+the `DOTNET_ROOT` value, so that the tool can find the .NET SDK package.
+You can find the path to the SDK by running `nix eval --raw nixpkgs#dotnet-sdk` (substitute the `dotnet-sdk` package for
+another if a different SDK version is needed).
+
+This method is not recommended on NixOS, since it's not declarative and involves installing binaries not made for NixOS,
+which will not always work.
+
+The third, and preferred way, is packaging the tool into a Nix derivation.
+
+### Packaging Dotnet global tools {#packaging-dotnet-global-tools}
+
+Dotnet global tools are standard .NET binaries, just made available through a special
+NuGet package. Therefore, they can be built and packaged like every .NET application,
+using `buildDotnetModule`.
+
+If however the source is not available or difficult to build, the
+`buildDotnetGlobalTool` helper can be used, which will package the tool
+straight from its NuGet package.
+
+This helper has the same arguments as `buildDotnetModule`, with a few differences:
+
+* `pname` and `version` are required, and will be used to find the NuGet package of the tool
+* `nugetName` can be used to override the NuGet package name that will be downloaded, if it's different from `pname`
+* `nugetSha256` is the hash of the fetched NuGet package. Set this to `lib.fakeHash256` for the first build, and it will error out, giving you the proper hash. Also remember to update it during version updates (it will not error out if you just change the version while having a fetched package in `/nix/store`)
+* `dotnet-runtime` is set to `dotnet-sdk` by default. When changing this, remember that .NET tools fetched from NuGet require an SDK.
+
+Here is an example of packaging `pbm`, an unfree binary without source available:
+```nix
+{ buildDotnetGlobalTool, lib }:
+
+buildDotnetGlobalTool {
+  pname = "pbm";
+  version = "1.3.1";
+
+  nugetSha256 = "sha256-ZG2HFyKYhVNVYd2kRlkbAjZJq88OADe3yjxmLuxXDUo=";
+
+  meta = with lib; {
+    homepage = "https://cmd.petabridge.com/index.html";
+    changelog = "https://cmd.petabridge.com/articles/RELEASE_NOTES.html";
+    license = licenses.unfree;
+    platforms = platforms.linux;
+  };
+}
+```
diff --git a/nixpkgs/doc/languages-frameworks/gnome.section.md b/nixpkgs/doc/languages-frameworks/gnome.section.md
index 897ebd7861fa..5208f1013cbd 100644
--- a/nixpkgs/doc/languages-frameworks/gnome.section.md
+++ b/nixpkgs/doc/languages-frameworks/gnome.section.md
@@ -137,15 +137,15 @@ Most GNOME package offer [`updateScript`](#var-passthru-updateScript), it is the
 
 ## Frequently encountered issues {#ssec-gnome-common-issues}
 
-#### `GLib-GIO-ERROR **: 06:04:50.903: No GSettings schemas are installed on the system` {#ssec-gnome-common-issues-no-schemas}
+### `GLib-GIO-ERROR **: 06:04:50.903: No GSettings schemas are installed on the system` {#ssec-gnome-common-issues-no-schemas}
 
 There are no schemas available in `XDG_DATA_DIRS`. Temporarily add a random package containing schemas like `gsettings-desktop-schemas` to `buildInputs`. [`glib`](#ssec-gnome-hooks-glib) and [`wrapGAppsHook`](#ssec-gnome-hooks-wrapgappshook) setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the [next error](#ssec-gnome-common-issues-missing-schema). Or you can try looking through the source code for the actual schemas used.
 
-#### `GLib-GIO-ERROR **: 06:04:50.903: Settings schema ‘org.gnome.foo’ is not installed` {#ssec-gnome-common-issues-missing-schema}
+### `GLib-GIO-ERROR **: 06:04:50.903: Settings schema ‘org.gnome.foo’ is not installed` {#ssec-gnome-common-issues-missing-schema}
 
 Package is missing some GSettings schemas. You can find out the package containing the schema with `nix-locate org.gnome.foo.gschema.xml` and let the hooks handle the wrapping as [above](#ssec-gnome-common-issues-no-schemas).
 
-#### When using `wrapGAppsHook` with special derivers you can end up with double wrapped binaries. {#ssec-gnome-common-issues-double-wrapped}
+### When using `wrapGAppsHook` with special derivers you can end up with double wrapped binaries. {#ssec-gnome-common-issues-double-wrapped}
 
 This is because derivers like `python.pkgs.buildPythonApplication` or `qt5.mkDerivation` have setup-hooks automatically added that produce wrappers with makeWrapper. The simplest way to workaround that is to disable the `wrapGAppsHook` automatic wrapping with `dontWrapGApps = true;` and pass the arguments it intended to pass to makeWrapper to another.
 
@@ -193,7 +193,7 @@ mkDerivation {
 }
 ```
 
-#### I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. {#ssec-gnome-common-issues-unwrappable-package}
+### I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. {#ssec-gnome-common-issues-unwrappable-package}
 
 You can rely on applications depending on the library setting the necessary environment variables but that is often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples:
 
@@ -209,6 +209,6 @@ You can rely on applications depending on the library setting the necessary envi
 
   []{#ssec-gnome-common-issues-unwrappable-package-gsettings-c} [Hard-coding GSettings schema path in C library](https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34) – nothing special other than using [Coccinelle patch](https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467) to generate the patch itself.
 
-#### I need to wrap a binary outside `bin` and `libexec` directories. {#ssec-gnome-common-issues-weird-location}
+### I need to wrap a binary outside `bin` and `libexec` directories. {#ssec-gnome-common-issues-weird-location}
 
 You can manually trigger the wrapping with `wrapGApp` in `preFixup` phase. It takes a path to a program as a first argument; the remaining arguments are passed directly to [`wrapProgram`](#fun-wrapProgram) function.
diff --git a/nixpkgs/doc/languages-frameworks/go.section.md b/nixpkgs/doc/languages-frameworks/go.section.md
index cf1808414234..7fd38a7d21c5 100644
--- a/nixpkgs/doc/languages-frameworks/go.section.md
+++ b/nixpkgs/doc/languages-frameworks/go.section.md
@@ -20,7 +20,7 @@ In the following is an example expression using `buildGoModule`, the following a
 
   To obtain the actual hash, set `vendorHash = lib.fakeSha256;` and run the build ([more details here](#sec-source-hashes)).
 - `proxyVendor`: Fetches (go mod download) and proxies the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build or if any dependency has case-insensitive conflicts which will produce platform-dependent `vendorHash` checksums.
-- `modPostBuild`: Shell commands to run after the build of the go-modules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash` (or `vendorSha256`). Note that if you change this attribute, you need to update `vendorHash` (or `vendorSha256`) attribute.
+- `modPostBuild`: Shell commands to run after the build of the goModules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash` (or `vendorSha256`). Note that if you change this attribute, you need to update `vendorHash` (or `vendorSha256`) attribute.
 
 ```nix
 pet = buildGoModule rec {
@@ -115,7 +115,7 @@ done
 
 ## Attributes used by the builders {#ssec-go-common-attributes}
 
-Many attributes [controlling the build phase](#variables-controlling-the-build-phase) are respected by both `buildGoModule` and `buildGoPackage`. Note that `buildGoModule` reads the following attributes also when building the `vendor/` go-modules fixed output derivation as well:
+Many attributes [controlling the build phase](#variables-controlling-the-build-phase) are respected by both `buildGoModule` and `buildGoPackage`. Note that `buildGoModule` reads the following attributes also when building the `vendor/` goModules fixed output derivation as well:
 
 - [`sourceRoot`](#var-stdenv-sourceRoot)
 - [`prePatch`](#var-stdenv-prePatch)
diff --git a/nixpkgs/doc/languages-frameworks/haskell.section.md b/nixpkgs/doc/languages-frameworks/haskell.section.md
index 87da2e63663a..60972331840a 100644
--- a/nixpkgs/doc/languages-frameworks/haskell.section.md
+++ b/nixpkgs/doc/languages-frameworks/haskell.section.md
@@ -23,7 +23,7 @@ installing and using them.
 
 All of these packages are originally defined in the `haskellPackages` package
 set and are re-exposed with a reduced dependency closure for convenience.
-(see `justStaticExecutables` below)
+(see `justStaticExecutables` or `separateBinOutput` below)
 
 The `haskellPackages` set includes at least one version of every package from
 Hackage as well as some manually injected packages. This amounts to a lot of
@@ -45,16 +45,17 @@ The attribute names in `haskellPackages` always correspond with their name on
 Hackage. Since Hackage allows names that are not valid Nix without escaping,
 you need to take care when handling attribute names like `3dmodels`.
 
-For packages that are part of [Stackage], we use the version prescribed by a
-Stackage solver (usually the current LTS one) as the default version. For all
-other packages we use the latest version from Hackage. See
-[below](#haskell-available-versions) to learn which versions are provided
-exactly.
+For packages that are part of [Stackage] (a curated set of known to be
+compatible packages), we use the version prescribed by a Stackage snapshot
+(usually the current LTS one) as the default version. For all other packages we
+use the latest version from [Hackage](https://hackage.org) (the repository of
+basically all open source Haskell packages). See [below](#haskell-available-
+versions) for a few more details on this.
 
-Roughly half of the 16K packages contained in `haskellPackages` don't actually
-build and are marked as broken semi-automatically. Most of those packages are
-deprecated or unmaintained, but sometimes packages that should build, do not
-build. Very often fixing them is not a lot of work.
+Roughly half of the 16K packages contained in `haskellPackages` don’t actually
+build and are [marked as broken semi-automatically](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/broken.yaml).
+Most of those packages are deprecated or unmaintained, but sometimes packages
+that should build, do not build. Very often fixing them is not a lot of work.
 
 <!--
 TODO(@sternenseemann):
@@ -126,19 +127,23 @@ Every package set also re-exposes the GHC used to build its packages as `haskell
 ### Available package versions {#haskell-available-versions}
 
 We aim for a “blessed” package set which only contains one version of each
-package, like Stackage (and based on it) but with more packages. Normally in
-nixpkgs the number of building Haskell packages is roughly two to three times
-the size of Stackage. For choosing the version to use for a certain package we
-use the following rules:
-
-1. By default, for every package `haskellPackages.foo` is the newest version
-found on Hackage (at the time of the last update of our package set).
-2. If the Stackage snapshot that we use (usually the newest LTS snapshot)
-contains a package, we use the Stackage version as default version for that
-package.
-3. For some packages, which are not on Stackage, we have manual overrides to
-set the default version to a version older than the newest on Hackage. We do
-this to get them or their reverse dependencies to compile in our package set.
+package, like [Stackage], which is a curated set of known to be compatible
+packages. We use the version information from Stackage snapshots and extend it
+with more packages. Normally in Nixpkgs the number of building Haskell packages
+is roughly two to three times the size of Stackage. For choosing the version to
+use for a certain package we use the following rules:
+
+1. By default, for `haskellPackages.foo` is the newest version of the package
+`foo` found on [Hackage](https://hackage.org), which is the central registry
+of all open source Haskell packages. Nixpkgs contains a reference to a pinned
+Hackage snapshot, thus we use the state of Hackage as of the last time we
+updated this pin.
+2. If the [Stackage] snapshot that we use (usually the newest LTS snapshot)
+contains a package, [we use instead the version in the Stackage snapshot as
+default version for that package.](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/stackage.yaml)
+3. For some packages, which are not on Stackage, we have if necessary [manual
+overrides to set the default version to a version older than the newest on
+Hackage.](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/main.yaml)
 4. For all packages, for which the newest Hackage version is not the default
 version, there will also be a `haskellPackages.foo_x_y_z` package with the
 newest version. The `x_y_z` part encodes the version with dots replaced by
@@ -146,9 +151,12 @@ underscores. When the newest version changes by a new release to Hackage the
 old package will disappear under that name and be replaced by a newer one under
 the name with the new version. The package name including the version will
 also disappear when the default version e.g. from Stackage catches up with the
-newest version from Hackage.
-5. For some packages, we also manually add other `haskellPackages.foo_x_y_z`
-versions, if they are required for a certain build.
+newest version from Hackage. E.g. if `haskellPackages.foo` gets updated from
+1.0.0 to 1.1.0 the package `haskellPackages.foo_1_1_0` becomes obsolete and
+gets dropped.
+5. For some packages, we also [manually add other `haskellPackages.foo_x_y_z`
+versions](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/main.yaml),
+if they are required for a certain build.
 
 Relying on `haskellPackages.foo_x_y_z` attributes in derivations outside
 nixpkgs is discouraged because they may change or disappear with every package
@@ -1066,6 +1074,18 @@ benchmark component.
 `dontCoverage drv`
 : Sets the `doCoverage` argument to `false` for `drv`.
 
+`enableExecutableProfiling drv`
+: Sets the `enableExecutableProfiling` argument to `true` for `drv`.
+
+`disableExecutableProfiling drv`
+: Sets the `enableExecutableProfiling` argument to `false` for `drv`.
+
+`enableLibraryProfiling drv`
+: Sets the `enableLibraryProfiling` argument to `true` for `drv`.
+
+`disableLibraryProfiling drv`
+: Sets the `enableLibraryProfiling` argument to `false` for `drv`.
+
 #### Library functions in the Haskell package sets {#haskell-package-set-lib-functions}
 
 Some library functions depend on packages from the Haskell package sets. Thus they are
@@ -1140,6 +1160,124 @@ covered in the old [haskell4nix docs](https://haskell4nix.readthedocs.io/).
 If you feel any important topic is not documented at all, feel free to comment
 on the issue linked above.
 
+### How to enable or disable profiling builds globally? {#haskell-faq-override-profiling}
+
+By default, Nixpkgs builds a profiling version of each Haskell library. The
+exception to this rule are some platforms where it is disabled due to concerns
+over output size. You may want to…
+
+* …enable profiling globally so that you can build a project you are working on
+  with profiling ability giving you insight in the time spent across your code
+  and code you depend on using [GHC's profiling feature][profiling].
+
+* …disable profiling (globally) to reduce the time spent building the profiling
+  versions of libraries which a significant amount of build time is spent on
+  (although they are not as expensive as the “normal” build of a Haskell library).
+
+::: {.note}
+The method described below affects the build of all libraries in the
+respective Haskell package set as well as GHC. If your choices differ from
+Nixpkgs' default for your (host) platform, you will lose the ability to
+substitute from the official binary cache.
+
+If you are concerned about build times and thus want to disable profiling, it
+probably makes sense to use `haskell.lib.compose.disableLibraryProfiling` (see
+[](#haskell-trivial-helpers)) on the packages you are building locally while
+continuing to substitute their dependencies and GHC.
+:::
+
+Since we need to change the profiling settings for the desired Haskell package
+set _and_ GHC (as the core libraries like `base`, `filepath` etc. are bundled
+with GHC), it is recommended to use overlays for Nixpkgs to change them.
+Since the interrelated parts, i.e. the package set and GHC, are connected
+via the Nixpkgs fixpoint, we need to modify them both in a way that preserves
+their connection (or else we'd have to wire it up again manually). This is
+achieved by changing GHC and the package set in seperate overlays to prevent
+the package set from pulling in GHC from `prev`.
+
+The result is two overlays like the ones shown below. Adjustable parts are
+annotated with comments, as are any optional or alternative ways to achieve
+the desired profiling settings without causing too many rebuilds.
+
+<!-- TODO(@sternenseemann): buildHaskellPackages != haskellPackages with this overlay,
+affected by https://github.com/NixOS/nixpkgs/issues/235960 which needs to be fixed
+properly still.
+-->
+
+```nix
+let
+  # Name of the compiler and package set you want to change. If you are using
+  # the default package set `haskellPackages`, you need to look up what version
+  # of GHC it currently uses (note that this is subject to change).
+  ghcName = "ghc92";
+  # Desired new setting
+  enableProfiling = true;
+in
+
+[
+  # The first overlay modifies the GHC derivation so that it does or does not
+  # build profiling versions of the core libraries bundled with it. It is
+  # recommended to only use such an overlay if you are enabling profiling on a
+  # platform that doesn't by default, because compiling GHC from scratch is
+  # quite expensive.
+  (final: prev:
+  let
+    inherit (final) lib;
+  in
+
+  {
+    haskell = lib.recursiveUpdate prev.haskell {
+      compiler.${ghcName} = prev.haskell.compiler.${ghcName}.override {
+        # Unfortunately, the GHC setting is named differently for historical reasons
+        enableProfiledLibs = enableProfiling;
+      };
+    };
+  })
+
+  (final: prev:
+  let
+    inherit (final) lib;
+    haskellLib = final.haskell.lib.compose;
+  in
+
+  {
+    haskell = lib.recursiveUpdate prev.haskell {
+      packages.${ghcName} = prev.haskell.packages.${ghcName}.override {
+        overrides = hfinal: hprev: {
+          mkDerivation = args: hprev.mkDerivation (args // {
+            # Since we are forcing our ideas upon mkDerivation, this change will
+            # affect every package in the package set.
+            enableLibraryProfiling = enableProfiling;
+
+            # To actually use profiling on an executable, executable profiling
+            # needs to be enabled for the executable you want to profile. You
+            # can either do this globally or…
+            enableExecutableProfiling = enableProfiling;
+          });
+
+          # …only for the package that contains an executable you want to profile.
+          # That saves on unnecessary rebuilds for packages that you only depend
+          # on for their library, but also contain executables (e.g. pandoc).
+          my-executable = haskellLib.enableExecutableProfiling hprev.my-executable;
+
+          # If you are disabling profiling to save on build time, but want to
+          # retain the ability to substitute from the binary cache. Drop the
+          # override for mkDerivation above and instead have an override like
+          # this for the specific packages you are building locally and want
+          # to make cheaper to build.
+          my-library = haskellLib.disableLibraryProfiling hprev.my-library;
+        };
+      };
+    };
+  })
+]
+```
+
+<!-- TODO(@sternenseemann): write overriding mkDerivation, overriding GHC, and
+overriding the entire package set sections and link to them from here where
+relevant.
+-->
+
 [Stackage]: https://www.stackage.org
 [cabal-project-files]: https://cabal.readthedocs.io/en/latest/cabal-project.html
 [cabal2nix]: https://github.com/nixos/cabal2nix
diff --git a/nixpkgs/doc/languages-frameworks/index.md b/nixpkgs/doc/languages-frameworks/index.md
new file mode 100644
index 000000000000..cdbf08f1791b
--- /dev/null
+++ b/nixpkgs/doc/languages-frameworks/index.md
@@ -0,0 +1,45 @@
+# Languages and frameworks {#chap-language-support}
+
+The [standard build environment](#chap-stdenv) makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accommodated by overriding the appropriate phases of `stdenv`. 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.
+
+```{=include=} sections
+agda.section.md
+android.section.md
+beam.section.md
+bower.section.md
+chicken.section.md
+coq.section.md
+crystal.section.md
+cuda.section.md
+cuelang.section.md
+dart.section.md
+dhall.section.md
+dotnet.section.md
+emscripten.section.md
+gnome.section.md
+go.section.md
+haskell.section.md
+hy.section.md
+idris.section.md
+ios.section.md
+java.section.md
+javascript.section.md
+lisp.section.md
+lua.section.md
+maven.section.md
+nim.section.md
+ocaml.section.md
+octave.section.md
+perl.section.md
+php.section.md
+pkg-config.section.md
+python.section.md
+qt.section.md
+r.section.md
+ruby.section.md
+rust.section.md
+swift.section.md
+texlive.section.md
+titanium.section.md
+vim.section.md
+```
diff --git a/nixpkgs/doc/languages-frameworks/index.xml b/nixpkgs/doc/languages-frameworks/index.xml
deleted file mode 100644
index 94c4e303027f..000000000000
--- a/nixpkgs/doc/languages-frameworks/index.xml
+++ /dev/null
@@ -1,47 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-language-support">
- <title>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 accommodated 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="agda.section.xml" />
- <xi:include href="android.section.xml" />
- <xi:include href="beam.section.xml" />
- <xi:include href="bower.section.xml" />
- <xi:include href="chicken.section.xml" />
- <xi:include href="coq.section.xml" />
- <xi:include href="crystal.section.xml" />
- <xi:include href="cuda.section.xml" />
- <xi:include href="cuelang.section.xml" />
- <xi:include href="dart.section.xml" />
- <xi:include href="dhall.section.xml" />
- <xi:include href="dotnet.section.xml" />
- <xi:include href="emscripten.section.xml" />
- <xi:include href="gnome.section.xml" />
- <xi:include href="go.section.xml" />
- <xi:include href="haskell.section.xml" />
- <xi:include href="hy.section.xml" />
- <xi:include href="idris.section.xml" />
- <xi:include href="ios.section.xml" />
- <xi:include href="java.section.xml" />
- <xi:include href="javascript.section.xml" />
- <xi:include href="lisp.section.xml" />
- <xi:include href="lua.section.xml" />
- <xi:include href="maven.section.xml" />
- <xi:include href="nim.section.xml" />
- <xi:include href="ocaml.section.xml" />
- <xi:include href="octave.section.xml" />
- <xi:include href="perl.section.xml" />
- <xi:include href="php.section.xml" />
- <xi:include href="pkg-config.section.xml" />
- <xi:include href="python.section.xml" />
- <xi:include href="qt.section.xml" />
- <xi:include href="r.section.xml" />
- <xi:include href="ruby.section.xml" />
- <xi:include href="rust.section.xml" />
- <xi:include href="swift.section.xml" />
- <xi:include href="texlive.section.xml" />
- <xi:include href="titanium.section.xml" />
- <xi:include href="vim.section.xml" />
-</chapter>
diff --git a/nixpkgs/doc/languages-frameworks/javascript.section.md b/nixpkgs/doc/languages-frameworks/javascript.section.md
index a6c5aad15c15..0a2099b0a6b1 100644
--- a/nixpkgs/doc/languages-frameworks/javascript.section.md
+++ b/nixpkgs/doc/languages-frameworks/javascript.section.md
@@ -196,10 +196,14 @@ buildNpmPackage rec {
 * `npmDepsHash`: The output hash of the dependencies for this project. Can be calculated in advance with [`prefetch-npm-deps`](#javascript-buildNpmPackage-prefetch-npm-deps).
 * `makeCacheWritable`: Whether to make the cache writable prior to installing dependencies. Don't set this unless npm tries to write to the cache directory, as it can slow down the build.
 * `npmBuildScript`: The script to run to build the project. Defaults to `"build"`.
+* `npmWorkspace`: The workspace directory within the project to build and install.
+* `dontNpmBuild`: Option to disable running the build script. Set to `true` if the package does not have a build script. Defaults to `false`. Alternatively, setting `buildPhase` explicitly also disables this.
+* `dontNpmInstall`: Option to disable running `npm install`. Defaults to `false`. Alternatively, setting `installPhase` explicitly also disables this.
 * `npmFlags`: Flags to pass to all npm commands.
-* `npmInstallFlags`: Flags to pass to `npm ci` and `npm prune`.
+* `npmInstallFlags`: Flags to pass to `npm ci`.
 * `npmBuildFlags`: Flags to pass to `npm run ${npmBuildScript}`.
 * `npmPackFlags`: Flags to pass to `npm pack`.
+* `npmPruneFlags`: Flags to pass to `npm prune`. Defaults to the value of `npmInstallFlags`.
 
 #### prefetch-npm-deps {#javascript-buildNpmPackage-prefetch-npm-deps}
 
diff --git a/nixpkgs/doc/languages-frameworks/lua.section.md b/nixpkgs/doc/languages-frameworks/lua.section.md
index 2ed02ab9d6c7..c5049326a776 100644
--- a/nixpkgs/doc/languages-frameworks/lua.section.md
+++ b/nixpkgs/doc/languages-frameworks/lua.section.md
@@ -179,7 +179,7 @@ Each interpreter has the following attributes:
 
 #### `buildLuarocksPackage` function {#buildluarockspackage-function}
 
-The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-lua-package.nix`
+The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-luarocks-package.nix`
 The following is an example:
 ```nix
 luaposix = buildLuarocksPackage {
diff --git a/nixpkgs/doc/languages-frameworks/maven.section.md b/nixpkgs/doc/languages-frameworks/maven.section.md
index cc5b4e3ed799..7e287a097c7e 100644
--- a/nixpkgs/doc/languages-frameworks/maven.section.md
+++ b/nixpkgs/doc/languages-frameworks/maven.section.md
@@ -4,6 +4,87 @@ Maven is a well-known build tool for the Java ecosystem however it has some chal
 
 The following provides a list of common patterns with how to package a Maven project (or any JVM language that can export to Maven) as a Nix package.
 
+## Building a package using `maven.buildMavenPackage` {#maven-buildmavenpackage}
+
+Consider the following package:
+
+```nix
+{ lib, fetchFromGitHub, jre, makeWrapper, maven }:
+
+maven.buildMavenPackage rec {
+  pname = "jd-cli";
+  version = "1.2.1";
+
+  src = fetchFromGitHub {
+    owner = "intoolswetrust";
+    repo = pname;
+    rev = "${pname}-${version}";
+    hash = "sha256-rRttA5H0A0c44loBzbKH7Waoted3IsOgxGCD2VM0U/Q=";
+  };
+
+  mvnHash = "sha256-kLpjMj05uC94/5vGMwMlFzLKNFOKeyNvq/vmB6pHTAo=";
+
+  nativeBuildInputs = [ makeWrapper ];
+
+  installPhase = ''
+    mkdir -p $out/bin $out/share/jd-cli
+    install -Dm644 jd-cli/target/jd-cli.jar $out/share/jd-cli
+
+    makeWrapper ${jre}/bin/java $out/bin/jd-cli \
+      --add-flags "-jar $out/share/jd-cli/jd-cli.jar"
+  '';
+
+  meta = with lib; {
+    description = "Simple command line wrapper around JD Core Java Decompiler project";
+    homepage = "https://github.com/intoolswetrust/jd-cli";
+    license = licenses.gpl3Plus;
+    maintainers = with maintainers; [ majiir ];
+  };
+}:
+```
+
+This package calls `maven.buildMavenPackage` to do its work. The primary difference from `stdenv.mkDerivation` is the `mvnHash` variable, which is a hash of all of the Maven dependencies.
+
+::: {.tip}
+After setting `maven.buildMavenPackage`, we then do standard Java `.jar` installation by saving the `.jar` to `$out/share/java` and then making a wrapper which allows executing that file; see [](#sec-language-java) for additional generic information about packaging Java applications.
+:::
+
+### Stable Maven plugins {#stable-maven-plugins}
+
+Maven defines default versions for its core plugins, e.g. `maven-compiler-plugin`. If your project does not override these versions, an upgrade of Maven will change the version of the used plugins, and therefore the derivation and hash.
+
+When `maven` is upgraded, `mvnHash` for the derivation must be updated as well: otherwise, the project will simply be built on the derivation of old plugins, and fail because the requested plugins are missing.
+
+This clearly prevents automatic upgrades of Maven: a manual effort must be made throughout nixpkgs by any maintainer wishing to push the upgrades.
+
+To make sure that your package does not add extra manual effort when upgrading Maven, explicitly define versions for all plugins. You can check if this is the case by adding the following plugin to your (parent) POM:
+
+```xml
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-enforcer-plugin</artifactId>
+  <version>3.3.0</version>
+  <executions>
+    <execution>
+      <id>enforce-plugin-versions</id>
+      <goals>
+        <goal>enforce</goal>
+      </goals>
+      <configuration>
+        <rules>
+          <requirePluginVersions />
+        </rules>
+      </configuration>
+    </execution>
+  </executions>
+</plugin>
+```
+
+## Manually using `mvn2nix` {#maven-mvn2nix}
+::: {.warning}
+This way is no longer recommended; see [](#maven-buildmavenpackage) for the simpler and preferred way.
+:::
+
 For the purposes of this example let's consider a very basic Maven project with the following `pom.xml` with a single dependency on [emoji-java](https://github.com/vdurmont/emoji-java).
 
 ```xml
@@ -41,14 +122,11 @@ public class Main {
 }
 ```
 
-You find this demo project at https://github.com/fzakaria/nixos-maven-example
-
-## Solving for dependencies {#solving-for-dependencies}
+You find this demo project at [https://github.com/fzakaria/nixos-maven-example](https://github.com/fzakaria/nixos-maven-example).
 
-### buildMaven with NixOS/mvn2nix-maven-plugin {#buildmaven-with-nixosmvn2nix-maven-plugin}
-
-> ⚠️ Although `buildMaven` is the "blessed" way within nixpkgs, as of 2020, it hasn't seen much activity in quite a while.
+### Solving for dependencies {#solving-for-dependencies}
 
+#### buildMaven with NixOS/mvn2nix-maven-plugin {#buildmaven-with-nixosmvn2nix-maven-plugin}
 `buildMaven` is an alternative method that tries to follow similar patterns of other programming languages by generating a lock file. It relies on the maven plugin [mvn2nix-maven-plugin](https://github.com/NixOS/mvn2nix-maven-plugin).
 
 First you generate a `project-info.json` file using the maven plugin.
@@ -105,9 +183,10 @@ The benefit over the _double invocation_ as we will see below, is that the _/nix
 │           ├── avalon-framework-4.1.3.jar -> /nix/store/iv5fp3955w3nq28ff9xfz86wvxbiw6n9-avalon-framework-4.1.3.jar
 ```
 
-### Double Invocation {#double-invocation}
-
-> ⚠️ This pattern is the simplest but may cause unnecessary rebuilds due to the output hash changing.
+#### Double Invocation {#double-invocation}
+::: {.note}
+This pattern is the simplest but may cause unnecessary rebuilds due to the output hash changing.
+:::
 
 The double invocation is a _simple_ way to get around the problem that `nix-build` may be sandboxed and have no Internet connectivity.
 
@@ -115,7 +194,9 @@ It treats the entire Maven repository as a single source to be downloaded, relyi
 
 The first step will be to build the Maven project as a fixed-output derivation in order to collect the Maven repository -- below is an [example](https://github.com/fzakaria/nixos-maven-example/blob/main/double-invocation-repository.nix).
 
-> Traditionally the Maven repository is at `~/.m2/repository`. We will override this to be the `$out` directory.
+::: {.note}
+Traditionally the Maven repository is at `~/.m2/repository`. We will override this to be the `$out` directory.
+:::
 
 ```nix
 { lib, stdenv, maven }:
@@ -147,7 +228,9 @@ stdenv.mkDerivation {
 
 The build will fail, and tell you the expected `outputHash` to place. When you've set the hash, the build will return with a `/nix/store` entry whose contents are the full Maven repository.
 
-> Some additional files are deleted that would cause the output hash to change potentially on subsequent runs.
+::: {.warning}
+Some additional files are deleted that would cause the output hash to change potentially on subsequent runs.
+:::
 
 ```bash
 ❯ tree $(nix-build --no-out-link double-invocation-repository.nix) | head
@@ -165,7 +248,7 @@ The build will fail, and tell you the expected `outputHash` to place. When you'v
 
 If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a strong likelihood that over-time your output hash will change since the resolved dependencies may change. Hence this method is less recommended then using `buildMaven`.
 
-## Building a JAR {#building-a-jar}
+### Building a JAR {#building-a-jar}
 
 Regardless of which strategy is chosen above, the step to build the derivation is the same.
 
@@ -191,7 +274,9 @@ in stdenv.mkDerivation rec {
 }
 ```
 
-> We place the library in `$out/share/java` since JDK package has a _stdenv setup hook_ that adds any JARs in the `share/java` directories of the build inputs to the CLASSPATH environment.
+::: {.tip}
+We place the library in `$out/share/java` since JDK package has a _stdenv setup hook_ that adds any JARs in the `share/java` directories of the build inputs to the CLASSPATH environment.
+:::
 
 ```bash
 ❯ tree $(nix-build --no-out-link build-jar.nix)
@@ -203,7 +288,7 @@ in stdenv.mkDerivation rec {
 2 directories, 1 file
 ```
 
-## Runnable JAR {#runnable-jar}
+### Runnable JAR {#runnable-jar}
 
 The previous example builds a `jar` file but that's not a file one can run.
 
@@ -215,9 +300,9 @@ We will use the same repository we built above (either _double invocation_ or _b
 
 The following two methods are more suited to Nix then building an [UberJar](https://imagej.net/Uber-JAR) which may be the more traditional approach.
 
-### CLASSPATH {#classpath}
+#### CLASSPATH {#classpath}
 
-> This is ideal if you are providing a derivation for _nixpkgs_ and don't want to patch the project's `pom.xml`.
+This method is ideal if you are providing a derivation for _nixpkgs_ and don't want to patch the project's `pom.xml`.
 
 We will read the Maven repository and flatten it to a single list. This list will then be concatenated with the _CLASSPATH_ separator to create the full classpath.
 
@@ -255,9 +340,9 @@ in stdenv.mkDerivation rec {
 }
 ```
 
-### MANIFEST file via Maven Plugin {#manifest-file-via-maven-plugin}
+#### MANIFEST file via Maven Plugin {#manifest-file-via-maven-plugin}
 
-> This is ideal if you are the project owner and want to change your `pom.xml` to set the CLASSPATH within it.
+This method is ideal if you are the project owner and want to change your `pom.xml` to set the CLASSPATH within it.
 
 Augment the `pom.xml` to create a JAR with the following manifest:
 
@@ -333,8 +418,9 @@ in stdenv.mkDerivation rec {
   '';
 }
 ```
-
-> Our script produces a dependency on `jre` rather than `jdk` to restrict the runtime closure necessary to run the application.
+::: {.note}
+Our script produces a dependency on `jre` rather than `jdk` to restrict the runtime closure necessary to run the application.
+:::
 
 This will give you an executable shell-script that launches your JAR with all the dependencies available.
 
diff --git a/nixpkgs/doc/languages-frameworks/nim.section.md b/nixpkgs/doc/languages-frameworks/nim.section.md
index 4f97c7585f33..6b0fb3df0311 100644
--- a/nixpkgs/doc/languages-frameworks/nim.section.md
+++ b/nixpkgs/doc/languages-frameworks/nim.section.md
@@ -15,32 +15,23 @@ case of packages not containing exported library code the attribute
 The following example shows a Nim program that depends only on Nim libraries:
 
 ```nix
-{ lib, nimPackages, fetchurl }:
-
-nimPackages.buildNimPackage rec {
-  pname = "hottext";
-  version = "1.4";
+{ lib, nimPackages, fetchFromGitHub }:
 
+nimPackages.buildNimPackage (finalAttrs: {
+  pname = "ttop";
+  version = "1.0.1";
   nimBinOnly = true;
 
-  src = fetchurl {
-    url = "https://git.sr.ht/~ehmry/hottext/archive/v${version}.tar.gz";
-    hash = "sha256-hIUofi81zowSMbt1lUsxCnVzfJGN3FEiTtN8CEFpwzY=";
+  src = fetchFromGitHub {
+    owner = "inv2004";
+    repo = "ttop";
+    rev = "v${finalAttrs.version}";
+    hash = "sha256-x4Uczksh6p3XX/IMrOFtBxIleVHdAPX9e8n32VAUTC4=";
   };
 
-  buildInputs = with nimPackages; [
-    bumpy
-    chroma
-    flatty
-    nimsimd
-    pixie
-    sdl2
-    typography
-    vmath
-    zippy
-  ];
-}
+  buildInputs = with nimPackages; [ asciigraph illwill parsetoml zippy ];
 
+})
 ```
 
 ## Nim library packages in Nixpkgs {#nim-library-packages-in-nixpkgs}
@@ -60,15 +51,15 @@ non-Nim package:
 ```nix
 { lib, buildNimPackage, fetchNimble, SDL2 }:
 
-buildNimPackage rec {
+buildNimPackage (finalAttrs: {
   pname = "sdl2";
   version = "2.0.4";
   src = fetchNimble {
-    inherit pname version;
-    hash = "sha256-qDtVSnf+7rTq36WAxgsUZ8XoUk4sKwHyt8EJcY5WP+o=";
+    inherit (finalAttrs) pname version;
+    hash = "sha256-Vtcj8goI4zZPQs2TbFoBFlcR5UqDtOldaXSH/+/xULk=";
   };
   propagatedBuildInputs = [ SDL2 ];
-}
+})
 ```
 
 ## `buildNimPackage` parameters {#buildnimpackage-parameters}
diff --git a/nixpkgs/doc/languages-frameworks/php.section.md b/nixpkgs/doc/languages-frameworks/php.section.md
index 8600e49d4570..6c4315f5c487 100644
--- a/nixpkgs/doc/languages-frameworks/php.section.md
+++ b/nixpkgs/doc/languages-frameworks/php.section.md
@@ -22,7 +22,7 @@ NixOS - not necessarily the latest major release from upstream.
 
 All available PHP attributes are wrappers around their respective
 binary PHP package and provide commonly used extensions this way. The
-real PHP 7.4 package, i.e. the unwrapped one, is available as
+real PHP 8.1 package, i.e. the unwrapped one, is available as
 `php81.unwrapped`; see the next section for more details.
 
 Interactive tools built on PHP are put in `php.packages`; composer is
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index 10f5e3938ce4..947ce6028659 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -512,9 +512,10 @@ when building the bindings and are therefore added as `buildInputs`.
 
 ```nix
 { lib
-, pkgs
 , buildPythonPackage
 , fetchPypi
+, libxml2
+, libxslt
 }:
 
 buildPythonPackage rec {
@@ -528,8 +529,8 @@ buildPythonPackage rec {
   };
 
   buildInputs = [
-    pkgs.libxml2
-    pkgs.libxslt
+    libxml2
+    libxslt
   ];
 
   meta = with lib; {
@@ -554,11 +555,13 @@ therefore we have to set `LDFLAGS` and `CFLAGS`.
 
 ```nix
 { lib
-, pkgs
 , buildPythonPackage
 , fetchPypi
 
 # dependencies
+, fftw
+, fftwFloat
+, fftwLongDouble
 , numpy
 , scipy
 }:
@@ -574,9 +577,9 @@ buildPythonPackage rec {
   };
 
   buildInputs = [
-    pkgs.fftw
-    pkgs.fftwFloat
-    pkgs.fftwLongDouble
+    fftw
+    fftwFloat
+    fftwLongDouble
   ];
 
   propagatedBuildInputs = [
@@ -585,8 +588,8 @@ buildPythonPackage rec {
   ];
 
   preConfigure = ''
-    export LDFLAGS="-L${pkgs.fftw.dev}/lib -L${pkgs.fftwFloat.out}/lib -L${pkgs.fftwLongDouble.out}/lib"
-    export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include"
+    export LDFLAGS="-L${fftw.dev}/lib -L${fftwFloat.out}/lib -L${fftwLongDouble.out}/lib"
+    export CFLAGS="-I${fftw.dev}/include -I${fftwFloat.dev}/include -I${fftwLongDouble.dev}/include"
   '';
 
   # Tests cannot import pyfftw. pyfftw works fine though.
@@ -995,7 +998,7 @@ and in this case the `python3` interpreter is automatically used.
 ### Interpreters {#interpreters}
 
 Versions 2.7, 3.8, 3.9, 3.10 and 3.11 of the CPython interpreter are available
-as respectively `python27`, python38`, `python39`, `python310` and `python311`.
+as respectively `python27`, `python38`, `python39`, `python310` and `python311`.
 The aliases `python2` and `python3` correspond to respectively `python27` and
 `python310`. The attribute `python` maps to `python2`. The PyPy interpreters
 compatible with Python 2.7 and 3 are available as `pypy27` and `pypy3`, with
@@ -1511,11 +1514,11 @@ Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is in
 
 ### Tools {#tools}
 
-Packages inside nixpkgs are written by hand. However many tools exist in
-community to help save time. No tool is preferred at the moment.
+Packages inside nixpkgs must use the `buildPythonPackage` or `buildPythonApplication` function directly,
+because we can only provide security support for non-vendored dependencies.
 
-- [nixpkgs-pytools](https://github.com/nix-community/nixpkgs-pytools)
-- [poetry2nix](https://github.com/nix-community/poetry2nix)
+We recommend [nix-init](https://github.com/nix-community/nix-init) for creating new python packages within nixpkgs,
+as it already prefetches the source, parses dependencies for common formats and prefills most things in `meta`.
 
 ### Deterministic builds {#deterministic-builds}
 
diff --git a/nixpkgs/doc/languages-frameworks/qt.section.md b/nixpkgs/doc/languages-frameworks/qt.section.md
index e09194e391e1..2300c5f60ede 100644
--- a/nixpkgs/doc/languages-frameworks/qt.section.md
+++ b/nixpkgs/doc/languages-frameworks/qt.section.md
@@ -10,37 +10,22 @@ pure and explicit at build-time, at the cost of introducing an extra indirection
 
 ## Nix expression for a Qt package (default.nix) {#qt-default-nix}
 
-```{=docbook}
-<programlisting>
-{ stdenv, lib, qtbase, wrapQtAppsHook }: <co xml:id='qt-default-nix-co-1' />
+```nix
+{ stdenv, lib, qtbase, wrapQtAppsHook }:
 
 stdenv.mkDerivation {
   pname = "myapp";
   version = "1.0";
 
   buildInputs = [ qtbase ];
-  nativeBuildInputs = [ wrapQtAppsHook ]; <co xml:id='qt-default-nix-co-2' />
+  nativeBuildInputs = [ wrapQtAppsHook ];
 }
-</programlisting>
-
- <calloutlist>
-  <callout arearefs='qt-default-nix-co-1'>
-   <para>
-    Import Qt modules directly, that is: <literal>qtbase</literal>, <literal>qtdeclarative</literal>, etc.
-    <emphasis>Do not</emphasis> import Qt package sets such as <literal>qt5</literal>
-    because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
-   </para>
-  </callout>
-  <callout arearefs='qt-default-nix-co-2'>
-    <para>
-      All Qt packages must include <literal>wrapQtAppsHook</literal> in
-      <literal>nativeBuildInputs</literal>, or you must explicitly set
-      <literal>dontWrapQtApps</literal>.
-    </para>
-  </callout>
- </calloutlist>
 ```
 
+It is important to import Qt modules directly, that is: `qtbase`, `qtdeclarative`, etc. *Do not* import Qt package sets such as `qt5` because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
+
+Additionally all Qt packages must include `wrapQtAppsHook` in `nativeBuildInputs`, or you must explicitly set `dontWrapQtApps`.
+
 ## Locating runtime dependencies {#qt-runtime-dependencies}
 
 Qt applications must be wrapped to find runtime dependencies.
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index 7d46bdbd4d48..08738026447a 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -39,7 +39,7 @@ rustPlatform.buildRustPackage rec {
     description = "A fast line-oriented regex search tool, similar to ag and ack";
     homepage = "https://github.com/BurntSushi/ripgrep";
     license = licenses.unlicense;
-    maintainers = [ maintainers.tailhook ];
+    maintainers = [];
   };
 }
 ```
@@ -558,7 +558,7 @@ buildPythonPackage rec {
     hash = "sha256-miW//pnOmww2i6SOGbkrAIdc/JMDT4FJLqdMFojZeoY=";
   };
 
-  sourceRoot = "source/bindings/python";
+  sourceRoot = "${src.name}/bindings/python";
 
   nativeBuildInputs = [
     cargo
@@ -926,7 +926,7 @@ rustPlatform.buildRustPackage rec {
     description = "A fast line-oriented regex search tool, similar to ag and ack";
     homepage = "https://github.com/BurntSushi/ripgrep";
     license = with licenses; [ mit unlicense ];
-    maintainers = with maintainers; [ tailhook ];
+    maintainers = with maintainers; [];
   };
 }
 ```
diff --git a/nixpkgs/doc/languages-frameworks/texlive.section.md b/nixpkgs/doc/languages-frameworks/texlive.section.md
index 72ab14126bed..a4c81daa54bb 100644
--- a/nixpkgs/doc/languages-frameworks/texlive.section.md
+++ b/nixpkgs/doc/languages-frameworks/texlive.section.md
@@ -22,7 +22,7 @@ Since release 15.09 there is a new TeX Live packaging that lives entirely under
   texlive.combine {
     # inherit (texlive) whatever-you-want;
     pkgFilter = pkg:
-      pkg.tlType == "run" || pkg.tlType == "bin" || pkg.pname == "cm-super";
+      pkg.tlType == "run" || pkg.tlType == "bin" || pkg.hasManpages || pkg.pname == "cm-super";
     # elem tlType [ "run" "bin" "doc" "source" ]
     # there are also other attributes: version, name
   }
diff --git a/nixpkgs/doc/lib.md b/nixpkgs/doc/lib.md
new file mode 100644
index 000000000000..2c3105333ed0
--- /dev/null
+++ b/nixpkgs/doc/lib.md
@@ -0,0 +1,6 @@
+# Nixpkgs `lib` {#id-1.4}
+
+```{=include=} chapters
+functions.md
+module-system/module-system.chapter.md
+```
diff --git a/nixpkgs/doc/manual.md.in b/nixpkgs/doc/manual.md.in
new file mode 100644
index 000000000000..a4a73a913097
--- /dev/null
+++ b/nixpkgs/doc/manual.md.in
@@ -0,0 +1,14 @@
+# Nixpkgs Manual {#nixpkgs-manual}
+## Version @MANUAL_VERSION@
+
+```{=include=} chapters
+preface.chapter.md
+```
+
+```{=include=} parts
+using-nixpkgs.md
+lib.md
+stdenv.md
+builders.md
+contributing.md
+```
diff --git a/nixpkgs/doc/manual.xml b/nixpkgs/doc/manual.xml
deleted file mode 100644
index de3d40f553c0..000000000000
--- a/nixpkgs/doc/manual.xml
+++ /dev/null
@@ -1,49 +0,0 @@
-<book xmlns="http://docbook.org/ns/docbook"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      xml:id="nixpkgs-manual">
- <info>
-  <title>Nixpkgs Manual</title>
-  <subtitle>Version <xi:include href=".version" parse="text" />
-  </subtitle>
- </info>
- <xi:include href="preface.chapter.xml" />
- <part xml:id="part-using">
-  <title>Using Nixpkgs</title>
-  <xi:include href="using/configuration.chapter.xml" />
-  <xi:include href="using/overlays.chapter.xml" />
-  <xi:include href="using/overrides.chapter.xml" />
- </part>
- <part>
-  <title>Nixpkgs <code>lib</code></title>
-  <xi:include href="functions.xml" />
-  <xi:include href="module-system/module-system.chapter.xml" />
- </part>
- <part xml:id="part-stdenv">
-  <title>Standard environment</title>
-  <xi:include href="stdenv/stdenv.chapter.xml" />
-  <xi:include href="stdenv/meta.chapter.xml" />
-  <xi:include href="stdenv/multiple-output.chapter.xml" />
-  <xi:include href="stdenv/cross-compilation.chapter.xml" />
-  <xi:include href="stdenv/platform-notes.chapter.xml" />
- </part>
- <part xml:id="part-builders">
-  <title>Builders</title>
-  <xi:include href="builders/fetchers.chapter.xml" />
-  <xi:include href="builders/trivial-builders.chapter.xml" />
-  <xi:include href="builders/testers.chapter.xml" />
-  <xi:include href="builders/special.xml" />
-  <xi:include href="builders/images.xml" />
-  <xi:include href="hooks/index.xml" />
-  <xi:include href="languages-frameworks/index.xml" />
-  <xi:include href="builders/packages/index.xml" />
- </part>
- <part xml:id="part-contributing">
-  <title>Contributing to Nixpkgs</title>
-  <xi:include href="contributing/quick-start.chapter.xml" />
-  <xi:include href="contributing/coding-conventions.chapter.xml" />
-  <xi:include href="contributing/submitting-changes.chapter.xml" />
-  <xi:include href="contributing/vulnerability-roundup.chapter.xml" />
-  <xi:include href="contributing/reviewing-contributions.chapter.xml" />
-  <xi:include href="contributing/contributing-to-documentation.chapter.xml" />
- </part>
-</book>
diff --git a/nixpkgs/doc/shell.nix b/nixpkgs/doc/shell.nix
index 5fa2b4424899..d71e3f3a709a 100644
--- a/nixpkgs/doc/shell.nix
+++ b/nixpkgs/doc/shell.nix
@@ -1,3 +1,20 @@
-{ pkgs ? import ../. { } }:
-(import ./default.nix { }).overrideAttrs
-(x: { buildInputs = (x.buildInputs or [ ]) ++ [ pkgs.xmloscopy pkgs.ruby ]; })
+let
+  pkgs = import ../. {
+    config = {};
+    overlays = [];
+  };
+
+  common = import ./common.nix;
+  inherit (common) outputPath indexPath;
+
+  web-devmode = import ../pkgs/tools/nix/web-devmode.nix {
+    inherit pkgs;
+    buildArgs = "./.";
+    open = "/${outputPath}/${indexPath}";
+  };
+in
+  pkgs.mkShell {
+    packages = [
+      web-devmode
+    ];
+  }
diff --git a/nixpkgs/doc/stdenv.md b/nixpkgs/doc/stdenv.md
new file mode 100644
index 000000000000..1ef81f84b514
--- /dev/null
+++ b/nixpkgs/doc/stdenv.md
@@ -0,0 +1,9 @@
+# Standard environment {#part-stdenv}
+
+```{=include=} chapters
+stdenv/stdenv.chapter.md
+stdenv/meta.chapter.md
+stdenv/multiple-output.chapter.md
+stdenv/cross-compilation.chapter.md
+stdenv/platform-notes.chapter.md
+```
diff --git a/nixpkgs/doc/stdenv/meta.chapter.md b/nixpkgs/doc/stdenv/meta.chapter.md
index 0cb2d6573dfc..f6da0bb84be0 100644
--- a/nixpkgs/doc/stdenv/meta.chapter.md
+++ b/nixpkgs/doc/stdenv/meta.chapter.md
@@ -70,7 +70,7 @@ A list of the maintainers of this Nix expression. Maintainers are defined in [`n
 
 ### `mainProgram` {#var-meta-mainProgram}
 
-The name of the main binary for the package. This affects the binary `nix run` executes and falls back to the name of the package. Example: `"rg"`
+The name of the main binary for the package. This affects the binary `nix run` executes. Example: `"rg"`
 
 ### `priority` {#var-meta-priority}
 
@@ -128,7 +128,7 @@ Prefer `passthru.tests` for tests that are introduced in nixpkgs because:
 * we can run `passthru.tests` independently
 * `installCheckPhase` adds overhead to each build
 
-For more on how to write and run package tests, see <xref linkend="sec-package-tests"/>.
+For more on how to write and run package tests, see [](#sec-package-tests).
 
 #### NixOS tests {#var-meta-tests-nixos}
 
diff --git a/nixpkgs/doc/stdenv/stdenv.chapter.md b/nixpkgs/doc/stdenv/stdenv.chapter.md
index 0b3776b530ca..4e8559467f52 100644
--- a/nixpkgs/doc/stdenv/stdenv.chapter.md
+++ b/nixpkgs/doc/stdenv/stdenv.chapter.md
@@ -464,10 +464,8 @@ The commit object contains the following values:
 
 If the returned array contains exactly one object (e.g. `[{}]`), all values are optional and will be determined automatically.
 
-```{=docbook}
-<example>
-<title>Standard output of an update script using commit feature</title>
-```
+::: {.example #var-passthru-updateScript-example-commit}
+# Standard output of an update script using commit feature
 
 ```json
 [
@@ -481,10 +479,7 @@ If the returned array contains exactly one object (e.g. `[{}]`), all values are
   }
 ]
 ```
-
-```{=docbook}
-</example>
-```
+:::
 
 ### Recursive attributes in `mkDerivation` {#mkderivation-recursive-attributes}
 
@@ -619,14 +614,19 @@ The list of source files or directories to be unpacked or copied. One of these m
 
 ##### `sourceRoot` {#var-stdenv-sourceRoot}
 
-After running `unpackPhase`, the generic builder changes the current directory to the directory created by unpacking the sources. If there are multiple source directories, you should set `sourceRoot` to the name of the intended directory. Set `sourceRoot = ".";` if you use `srcs` and control the unpack phase yourself.
+After unpacking all of `src` and `srcs`, if neither of `sourceRoot` and `setSourceRoot` are set, `unpackPhase` of the generic builder checks that the unpacking produced a single directory and moves the current working directory into it.
 
-By default the `sourceRoot` is set to `"source"`. If you want to point to a sub-directory inside your project, you therefore need to set `sourceRoot = "source/my-sub-directory"`.
+If `unpackPhase` produces multiple source directories, you should set `sourceRoot` to the name of the intended directory.
+You can also set `sourceRoot = ".";` if you want to control it yourself in a later phase.
+
+For example, if your want your build to start in a sub-directory inside your sources, and you are using `fetchzip`-derived `src` (like `fetchFromGitHub` or similar), you need to set `sourceRoot = "${src.name}/my-sub-directory"`.
 
 ##### `setSourceRoot` {#var-stdenv-setSourceRoot}
 
 Alternatively to setting `sourceRoot`, you can set `setSourceRoot` to a shell command to be evaluated by the unpack phase after the sources have been unpacked. This command must set `sourceRoot`.
 
+For example, if you are using `fetchurl` on an archive file that gets unpacked into a single directory the name of which changes between package versions, and you want your build to start in its sub-directory, you need to set `setSourceRoot = "sourceRoot=$(echo */my-sub-directory)";`, or in the case of multiple sources, you could use something more specific, like `setSourceRoot = "sourceRoot=$(echo ${pname}-*/my-sub-directory)";`.
+
 ##### `preUnpack` {#var-stdenv-preUnpack}
 
 Hook executed at the start of the unpack phase.
@@ -971,7 +971,8 @@ to `~/.gdbinit`. GDB will then be able to find debug information installed via `
 
 The installCheck phase checks whether the package was installed correctly by running its test suite against the installed directories. The default `installCheck` calls `make installcheck`.
 
-It is often better to add tests that are not part of the source distribution to `passthru.tests` (see <xref linkend="var-meta-tests"/>). This avoids adding overhead to every build and enables us to run them independently.
+It is often better to add tests that are not part of the source distribution to `passthru.tests` (see
+[](#var-meta-tests)). This avoids adding overhead to every build and enables us to run them independently.
 
 #### Variables controlling the installCheck phase {#variables-controlling-the-installcheck-phase}
 
@@ -1234,7 +1235,7 @@ This runs the strip command on installed binaries and libraries. This removes un
 
 This setup hook patches installed scripts to add Nix store paths to their shebang interpreter as found in the build environment. The [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) line tells a Unix-like operating system which interpreter to use to execute the script's contents.
 
-::: note
+::: {.note}
 The [generic builder][generic-builder] populates `PATH` from inputs of the derivation.
 :::
 
@@ -1272,7 +1273,7 @@ patchShebangs --build configure
 
 Interpreter paths that point to a valid Nix store location are not changed.
 
-::: note
+::: {.note}
 A script file must be marked as executable, otherwise it will not be
 considered.
 :::
diff --git a/nixpkgs/doc/using-nixpkgs.md b/nixpkgs/doc/using-nixpkgs.md
new file mode 100644
index 000000000000..bb222ae384fa
--- /dev/null
+++ b/nixpkgs/doc/using-nixpkgs.md
@@ -0,0 +1,7 @@
+# Using Nixpkgs {#part-using}
+
+```{=include=} chapters
+using/configuration.chapter.md
+using/overlays.chapter.md
+using/overrides.chapter.md
+```
diff --git a/nixpkgs/doc/using/configuration.chapter.md b/nixpkgs/doc/using/configuration.chapter.md
index e657cb21c295..8d246b117b05 100644
--- a/nixpkgs/doc/using/configuration.chapter.md
+++ b/nixpkgs/doc/using/configuration.chapter.md
@@ -185,8 +185,10 @@ You can define a function called `packageOverrides` in your local `~/.config/nix
 
 The following attributes can be passed in [`config`](#chap-packageconfig).
 
-```{=docbook}
-<include xmlns="http://www.w3.org/2001/XInclude" href="../doc-support/result/config-options.docbook.xml"/>
+```{=include=} options
+id-prefix: opt-
+list-id: configuration-variable-list
+source: ../config-options.json
 ```
 
 
diff --git a/nixpkgs/doc/using/overrides.chapter.md b/nixpkgs/doc/using/overrides.chapter.md
index 198b4504197d..a1ef9afb0b69 100644
--- a/nixpkgs/doc/using/overrides.chapter.md
+++ b/nixpkgs/doc/using/overrides.chapter.md
@@ -16,6 +16,12 @@ Example usages:
 pkgs.foo.override { arg1 = val1; arg2 = val2; ... }
 ```
 
+It's also possible to access the previous arguments.
+
+```nix
+pkgs.foo.override (previous: { arg1 = previous.arg1; ... })
+```
+
 <!-- TODO: move below programlisting to a new section about extending and overlays and reference it -->
 
 ```nix
@@ -36,15 +42,15 @@ In the first example, `pkgs.foo` is the result of a function call with some defa
 
 The function `overrideAttrs` allows overriding the attribute set passed to a `stdenv.mkDerivation` call, producing a new derivation based on the original one. This function is available on all derivations produced by the `stdenv.mkDerivation` function, which is most packages in the nixpkgs expression `pkgs`.
 
-Example usage:
+Example usages:
 
 ```nix
-helloWithDebug = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: {
-  separateDebugInfo = true;
+helloBar = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: {
+  pname = previousAttrs.pname + "-bar";
 });
 ```
 
-In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`, while all other attributes will be retained from the original `hello` package.
+In the above example, "-bar" is appended to the pname attribute, while all other attributes will be retained from the original `hello` package.
 
 The argument `previousAttrs` is conventionally used to refer to the attr set originally passed to `stdenv.mkDerivation`.
 
@@ -52,6 +58,16 @@ The argument `finalAttrs` refers to the final attributes passed to `mkDerivation
 
 If only a one-argument function is written, the argument has the meaning of `previousAttrs`.
 
+Function arguments can be omitted entirely if there is no need to access `previousAttrs` or `finalAttrs`.
+
+```nix
+helloWithDebug = pkgs.hello.overrideAttrs {
+  separateDebugInfo = true;
+};
+```
+
+In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`.
+
 ::: {.note}
 Note that `separateDebugInfo` is processed only by the `stdenv.mkDerivation` function, not the generated, raw Nix derivation. Thus, using `overrideDerivation` will not work in this case, as it overrides only the attributes of the final derivation. It is for this reason that `overrideAttrs` should be preferred in (almost) all cases to `overrideDerivation`, i.e. to allow using `stdenv.mkDerivation` to process input arguments, as well as the fact that it is easier to use (you can use the same attribute names you see in your Nix code, instead of the ones generated (e.g. `buildInputs` vs `nativeBuildInputs`), and it involves less typing).
 :::