Try using a contents within each user guide chapter

Currently we have a somewhat hard-to-maintain contents just in the
introduction. This cuts that initial contents down to just link to
the chapters (plus sections within the intro), and then use an
automatically generated table of contents in the other chapters.

Also tweak the CSS because pandoc's TOC feature turns all section
headings into links and that changes the visual appearance. Use the
CSS to make it look the same as before.

(cherry picked from commit 9ecb30d4)

Cabal/Makefile

@@ -71,7 +71,10 @@ PANDOC_HTML_CSS=Cabal.css
 users-guide: $(USERGUIDE_STAMP) doc/*.markdown
 $(USERGUIDE_STAMP): doc/*.markdown
 	mkdir -p $(PANDOC_HTML_OUTDIR)
-	for file in $^; do $(PANDOC) $(PANDOC_OPTIONS) --from=markdown --to=html --output $(PANDOC_HTML_OUTDIR)/$$(basename $${file} .markdown).html $${file}; done
+	for file in $^; do \
+		[ $${file} != doc/index.markdown ] && TOC=--table-of-contents || TOC=; \
+		$(PANDOC) $(PANDOC_OPTIONS) $${TOC} --from=markdown --to=html --output $(PANDOC_HTML_OUTDIR)/$$(basename $${file} .markdown).html $${file}; \
+	done
 	cp doc/$(PANDOC_HTML_CSS) $(PANDOC_HTML_OUTDIR)
 
 docs: haddock users-guide

Cabal/doc/Cabal.css

@@ -37,3 +37,9 @@ a:link    { color:      #0000C8 }
 a:hover   { background: #FFFFA8 }
 a:active  { color:      #D00000 }
 a:visited { color:      #680098 }
+
+h1 a:link, h2 a:link, h3 a:link, h4 a:link, h5 a:link, h6 a:link,
+h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited {
+  color: #005A9C;
+  text-decoration: none
+}

Cabal/doc/index.markdown

@@ -17,56 +17,11 @@ thousands of libraries and applications in the Cabal package format.
   * [Introduction](#introduction)
       - [What's in a package](#whats-in-a-package)
       - [A tool for working with packages](#a-tool-for-working-with-packages)
-  * [Developing packages](developing-packages.html)
-      - [Package descriptions](developing-packages.html#package-descriptions)
-          + [Package properties](developing-packages.html#package-properties)
-          + [Library](developing-packages.html#library)
-          + [Executables](developing-packages.html#executables)
-          + [Test suites](developing-packages.html#test-suites)
-          + [Build information](developing-packages.html#build-information)
-          + [Configurations](developing-packages.html#configurations)
-          + [Source Repositories](developing-packages.html#source-repositories)
-      - [Accessing data files from package code](developing-packages.html#accessing-data-files-from-package-code)
-          + [Accessing the package version](developing-packages.html#accessing-the-package-version)
-      - [System-dependent parameters](developing-packages.html#system-dependent-parameters)
-      - [Conditional compilation](developing-packages.html#conditional-compilation)
-      - [More complex packages](developing-packages.html#more-complex-packages)
-  * [Building and installing packages](installing-packages.html)
-      - [Building and installing a system package](installing-packages.html#building-and-installing-a-system-package)
-      - [Building and installing a user package](installing-packages.html#building-and-installing-a-user-package)
-      - [Installing packages from Hackage](installing-packages.html#installing-packages-from-hackage)
-      - [Developing with sandboxes](installing-packages.html#developing-with-sandboxes)
-          + [Sandboxes: basic usage](installing-packages.html#sandboxes-basic-usage)
-          + [Sandboxes: advanced usage](installing-packages.html#sandboxes-advanced-usage)
-      - [Creating a binary package](installing-packages.html#creating-a-binary-package)
-      - [setup configure](installing-packages.html#setup-configure)
-          + [Programs used for building](installing-packages.html#programs-used-for-building)
-          + [Installation paths](installing-packages.html#installation-paths)
-          + [Controlling Flag Assignments](installing-packages.html#controlling-flag-assignments)
-          + [Building Test Suites](installing-packages.html#building-test-suites)
-          + [Miscellaneous options](installing-packages.html#miscellaneous-options)
-      - [setup build](installing-packages.html#setup-build)
-      - [setup haddock](installing-packages.html#setup-haddock)
-      - [setup hscolour](installing-packages.html#setup-hscolour)
-      - [setup install](installing-packages.html#setup-install)
-      - [setup copy](installing-packages.html#setup-copy)
-      - [setup register](installing-packages.html#setup-register)
-      - [setup unregister](installing-packages.html#setup-unregister)
-      - [setup clean](installing-packages.html#setup-clean)
-      - [setup test](installing-packages.html#setup-test)
-      - [setup sdist](installing-packages.html#setup-sdist)
+  * [Building, installing and managing packages](installing-packages.html)
+  * [Creating packages](developing-packages.html)
+  * [Cabal specification, design and implementation]()
   * [Reporting bugs and deficiencies](misc.html#reporting-bugs-and-deficiencies)
   * [Stability of Cabal interfaces](misc.html#stability-of-cabal-interfaces)
-      - [Cabal file format](misc.html#cabal-file-format)
-      - [Command-line interface](misc.html#command-line-interface)
-          + [Very Stable Command-line interfaces](misc.html#very-stable-command-line-interfaces)
-          + [Stable Command-line interfaces](misc.html#stable-command-line-interfaces)
-          + [Unstable command-line](misc.html#unstable-command-line)
-      - [Functions and Types](misc.html#functions-and-types)
-          + [Very Stable API](misc.html#very-stable-api)
-          + [Semi-stable API](misc.html#semi-stable-api)
-          + [Unstable API](#unstable-api)
-      - [Hackage](misc.html#hackage)
 
 # Introduction #