doc: organize chapters into parts, and reduce toc depth

Reorganize the chapters into parts and reduce the TOC depth to make the
TOC useful again. The top-level TOC is very brief, but that is fine
because every part will have its own TOC.

Section titles of languages/frameworks are also simplified to just
the name of the language/framework.

13 files changed, 41 insertions, 29 deletions

diff --git a/doc/contributing.xml b/doc/contributing-to-documentation.xml
index b0266043775..b0266043775 100644
--- a/doc/contributing.xml
+++ b/doc/contributing-to-documentation.xml
diff --git a/doc/doc-support/parameters.xml b/doc/doc-support/parameters.xml
index bc13e2b70de..e4b33e66ee4 100644
--- 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/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md
index 24c49ec1409..80e1094809a 100644
--- 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
index 48d22831cd9..1e677450aa1 100644
--- 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
index e88015f08e3..8d7962d7fb9 100644
--- 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
index cd0b48adb14..86076085799 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -1,7 +1,7 @@
 <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>
diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md
index c6dce04c7b8..4dc95fc1dd9 100644
--- 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
index c8f02bd1478..d4e1617779c 100644
--- 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
index 83b7b159bd6..31f1abd197b 100644
--- 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
index 537e7b93e52..05a23d26cf2 100644
--- 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
index ab845e1a108..7015e18d1e9 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -6,20 +6,32 @@
   </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="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>Languages, frameworks and packages</title>
+  <xi:include href="languages-frameworks/index.xml" />
+  <xi:include href="package-specific-user-notes.xml" />
+  <xi:include href="package-notes.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/platform-notes.xml b/doc/platform-notes.xml
index d8d7692fc9a..5a266fdc0ee 100644
--- a/doc/platform-notes.xml
+++ b/doc/platform-notes.xml
@@ -1,6 +1,6 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-platform-nodes">
+         xml:id="chap-platform-notes">
  <title>Platform Notes</title>
  <section xml:id="sec-darwin">
   <title>Darwin (macOS)</title>
diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml
index 5a14684f9b1..c6fb6256781 100644
--- a/doc/reviewing-contributions.xml
+++ b/doc/reviewing-contributions.xml
@@ -2,7 +2,7 @@
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
-        xml:id="sec-reviewing-contributions">
+        xml:id="chap-reviewing-contributions">
  <title>Reviewing contributions</title>
  <warning>
   <para>