NixOS
diff --git a/doc/functions/fetchers.xml → doc/builders/fetchers.xml b/doc/functions/fetchers.xml → doc/builders/fetchers.xml
@@ -1,8 +1,8 @@
-<section xmlns="http://docbook.org/ns/docbook"
+<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="sec-pkgs-fetchers">
- <title>Fetcher functions</title>
+         xml:id="chap-pkgs-fetchers">
+ <title>Fetchers</title>
 
  <para>
   When using Nix, you will frequently need to download source code and other files from the internet. Nixpkgs comes with a few helper functions that allow you to fetch fixed-output derivations in a structured way.
@@ -145,4 +145,4 @@ stdenv.mkDerivation {
    </listitem>
   </varlistentry>
  </variablelist>
-</section>
+</chapter>
diff --git a/doc/builders/images.xml b/doc/builders/images.xml
@@ -0,0 +1,12 @@
+<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.xml" />
+ <xi:include href="images/dockertools.xml" />
+ <xi:include href="images/ocitools.xml" />
+ <xi:include href="images/snaptools.xml" />
+</chapter>
diff --git a/doc/functions/appimagetools.xml → doc/builders/images/appimagetools.xml b/doc/functions/appimagetools.xml → doc/builders/images/appimagetools.xml
diff --git a/doc/functions/dockertools.xml → doc/builders/images/dockertools.xml b/doc/functions/dockertools.xml → doc/builders/images/dockertools.xml
diff --git a/doc/functions/ocitools.xml → doc/builders/images/ocitools.xml b/doc/functions/ocitools.xml → doc/builders/images/ocitools.xml
diff --git a/doc/functions/snap/example-firefox.nix → doc/builders/images/snap/example-firefox.nix b/doc/functions/snap/example-firefox.nix → doc/builders/images/snap/example-firefox.nix
diff --git a/doc/functions/snap/example-hello.nix → doc/builders/images/snap/example-hello.nix b/doc/functions/snap/example-hello.nix → doc/builders/images/snap/example-hello.nix
diff --git a/doc/functions/snaptools.xml → doc/builders/images/snaptools.xml b/doc/functions/snaptools.xml → doc/builders/images/snaptools.xml
diff --git a/doc/builders/special.xml b/doc/builders/special.xml
@@ -0,0 +1,12 @@
+<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.xml" />
+ <xi:include href="special/mkshell.xml" />
+</chapter>
+
+
diff --git a/doc/functions/fhs-environments.xml → doc/builders/special/fhs-environments.xml b/doc/functions/fhs-environments.xml → doc/builders/special/fhs-environments.xml
diff --git a/doc/functions/shell.xml → doc/builders/special/mkshell.xml b/doc/functions/shell.xml → doc/builders/special/mkshell.xml
diff --git a/doc/functions/trivial-builders.xml → doc/builders/trivial-builders.xml b/doc/functions/trivial-builders.xml → doc/builders/trivial-builders.xml
@@ -1,7 +1,7 @@
-<section xmlns="http://docbook.org/ns/docbook"
+<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="sec-trivial-builders">
+         xml:id="chap-trivial-builders">
  <title>Trivial builders</title>
 
  <para>
@@ -76,4 +76,4 @@
    </listitem>
   </varlistentry>
  </variablelist>
-</section>
+</chapter>
diff --git a/doc/contributing.xml → doc/contributing-to-documentation.xml b/doc/contributing.xml → doc/contributing-to-documentation.xml
diff --git a/doc/doc-support/parameters.xml b/doc/doc-support/parameters.xml
@@ -8,7 +8,7 @@
  <xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" />
  <xsl:param name="xref.with.number.and.title" select="1" />
  <xsl:param name="use.id.as.filename" select="1" />
- <xsl:param name="toc.section.depth" select="3" />
+ <xsl:param name="toc.section.depth" select="0" />
  <xsl:param name="admon.style" select="''" />
  <xsl:param name="callout.graphics.extension" select="'.svg'" />
 </xsl:stylesheet>
diff --git a/doc/functions.xml b/doc/functions.xml
@@ -7,17 +7,8 @@
   The nixpkgs repository has several utility functions to manipulate Nix expressions.
  </para>
  <xi:include href="functions/library.xml" />
- <xi:include href="functions/overrides.xml" />
  <xi:include href="functions/generators.xml" />
  <xi:include href="functions/debug.xml" />
- <xi:include href="functions/fetchers.xml" />
- <xi:include href="functions/trivial-builders.xml" />
- <xi:include href="functions/fhs-environments.xml" />
- <xi:include href="functions/shell.xml" />
- <xi:include href="functions/dockertools.xml" />
- <xi:include href="functions/snaptools.xml" />
- <xi:include href="functions/appimagetools.xml" />
  <xi:include href="functions/prefer-remote-fetch.xml" />
  <xi:include href="functions/nix-gitignore.xml" />
- <xi:include href="functions/ocitools.xml" />
 </chapter>
diff --git a/doc/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md
@@ -1,4 +1,4 @@
-# User's Guide to Emscripten in Nixpkgs
+# Emscripten
 
 [Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler
 

diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md
@@ -3,7 +3,7 @@ title: User's Guide for Haskell in Nixpkgs
 author: Peter Simons
 date: 2015-06-01
 ---
-# User's Guide to the Haskell Infrastructure
+# Haskell
 
 
 ## How to install Haskell packages

diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md
@@ -1,4 +1,4 @@
-# Idris packages
+# Idris
 
 ## Installing Idris
 

diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
@@ -1,14 +1,16 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xml:id="chap-language-support">
- <title>Support for specific programming languages and frameworks</title>
+ <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 accomodated 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="android.section.xml" />
  <xi:include href="beam.xml" />
  <xi:include href="bower.xml" />
  <xi:include href="coq.xml" />
+ <xi:include href="crystal.section.xml" />
+ <xi:include href="emscripten.section.xml" />
  <xi:include href="gnome.xml" />
  <xi:include href="go.xml" />
  <xi:include href="haskell.section.xml" />
@@ -27,6 +29,4 @@
  <xi:include href="texlive.xml" />
  <xi:include href="titanium.section.xml" />
  <xi:include href="vim.section.xml" />
- <xi:include href="emscripten.section.xml" />
- <xi:include href="crystal.section.xml" />
 </chapter>
diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md
@@ -1,5 +1,5 @@
-Node.js packages
-================
+Node.js
+=======
 The `pkgs/development/node-packages` folder contains a generated collection of
 [NPM packages](https://npmjs.com/) that can be installed with the Nix package
 manager.

diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md
@@ -1,5 +1,5 @@
-R packages
-==========
+R
+=
 
 ## Installation
 

diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
@@ -4,7 +4,7 @@ author: Matthias Beyer
 date: 2017-03-05
 ---
 
-# User's Guide to the Rust Infrastructure
+# Rust
 
 To install the rust compiler and cargo put
 

diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md
@@ -3,7 +3,7 @@ title: User's Guide for Vim in Nixpkgs
 author: Marc Weber
 date: 2016-06-25
 ---
-# User's Guide to Vim Plugins/Addons/Bundles/Scripts in Nixpkgs
+# Vim
 
 Both Neovim and Vim can be configured to include your favorite plugins
 and additional libraries.

diff --git a/doc/manual.xml b/doc/manual.xml
@@ -6,20 +6,36 @@
   </subtitle>
  </info>
  <xi:include href="introduction.chapter.xml" />
- <xi:include href="quick-start.xml" />
- <xi:include href="package-specific-user-notes.xml" />
- <xi:include href="stdenv.xml" />
- <xi:include href="multiple-output.xml" />
- <xi:include href="cross-compilation.xml" />
- <xi:include href="configuration.xml" />
- <xi:include href="functions.xml" />
- <xi:include href="meta.xml" />
- <xi:include href="languages-frameworks/index.xml" />
- <xi:include href="platform-notes.xml" />
- <xi:include href="package-notes.xml" />
- <xi:include href="overlays.xml" />
- <xi:include href="coding-conventions.xml" />
- <xi:include href="submitting-changes.xml" />
- <xi:include href="reviewing-contributions.xml" />
- <xi:include href="contributing.xml" />
+ <part>
+  <title>Using Nixpkgs</title>
+  <xi:include href="configuration.xml" />
+  <xi:include href="overlays.xml" />
+  <xi:include href="overrides.xml" />
+  <xi:include href="functions.xml" />
+ </part>
+ <part>
+  <title>Standard environment</title>
+  <xi:include href="stdenv.xml" />
+  <xi:include href="meta.xml" />
+  <xi:include href="multiple-output.xml" />
+  <xi:include href="cross-compilation.xml" />
+  <xi:include href="platform-notes.xml" />
+ </part>
+ <part>
+  <title>Builders</title>
+  <xi:include href="builders/fetchers.xml" />
+  <xi:include href="builders/trivial-builders.xml" />
+  <xi:include href="builders/special.xml" />
+  <xi:include href="builders/images.xml" />
+  <xi:include href="languages-frameworks/index.xml" />
+  <xi:include href="packages/index.xml" />
+ </part>
+ <part>
+  <title>Contributing to Nixpkgs</title>
+  <xi:include href="quick-start.xml" />
+  <xi:include href="coding-conventions.xml" />
+  <xi:include href="submitting-changes.xml" />
+  <xi:include href="reviewing-contributions.xml" />
+  <xi:include href="contributing-to-documentation.xml" />
+ </part>
 </book>
diff --git a/doc/functions/overrides.xml → doc/overrides.xml b/doc/functions/overrides.xml → doc/overrides.xml
@@ -1,7 +1,7 @@
-<section xmlns="http://docbook.org/ns/docbook"
+<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="sec-overrides">
+         xml:id="chap-overrides">
  <title>Overriding</title>
 
  <para>
@@ -148,4 +148,4 @@ c = lib.makeOverridable f { a = 1; b = 2; };
    The variable <varname>c</varname> however also has some additional functions, like <link linkend="sec-pkg-override">c.override</link> which can be used to override the default arguments. In this example the value of <varname>(c.override { a = 4; }).result</varname> is 6.
   </para>
  </section>
-</section>
+</chapter>