From 2263ba17d584c518c39d2d78009be27f8c5b4fae Mon Sep 17 00:00:00 2001
From: Duncan Coutts <duncan@community.haskell.org>
Date: Fri, 20 Sep 2013 11:34:10 +0100
Subject: [PATCH] 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 9ecb30d4dbccb07eaf342aab0dd525ec4c9cbbd0)
---
Cabal/Makefile | 5 +++-
Cabal/doc/Cabal.css | 6 +++++
Cabal/doc/index.markdown | 51 +++-------------------------------------
3 files changed, 13 insertions(+), 49 deletions(-)
diff --git a/Cabal/Makefile b/Cabal/Makefile
index 84953b53f5..4ff5ad5124 100644
--- a/Cabal/Makefile
+++ b/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
diff --git a/Cabal/doc/Cabal.css b/Cabal/doc/Cabal.css
index 97f276c8d5..a559ddff94 100644
--- a/Cabal/doc/Cabal.css
+++ b/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
+}
diff --git a/Cabal/doc/index.markdown b/Cabal/doc/index.markdown
index e23da13dac..9f0af16d0a 100644
--- a/Cabal/doc/index.markdown
+++ b/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 #
--
GitLab