From 06ad1e5e0645ec84affbec05de746b9477faca32 Mon Sep 17 00:00:00 2001
From: Adam Sampson <ats@offog.org>
Date: Thu, 28 Feb 2008 14:43:53 +0000
Subject: [PATCH] Clean up the documentation hack a bit.

We now postprocess all the generated HTML using M4, so we can hide the SVG
images behind macros (and we can now use images inside the main documentation
too).
---
 Makefile.am               | 20 +++++++-------------
 docextra/description      |  7 +++++++
 docextra/description.html | 14 --------------
 docextra/tock-docs.m4     | 10 ++++++++++
 4 files changed, 24 insertions(+), 27 deletions(-)
 create mode 100644 docextra/description
 delete mode 100644 docextra/description.html
 create mode 100644 docextra/tock-docs.m4

diff --git a/Makefile.am b/Makefile.am
index 12f917b..954558a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -183,18 +183,12 @@ make-cgtests-cpp: tock cgtests/cgtest00.occ clean-cgtests
 clean-cgtests:
 	rm -f cgtests/cgtest??
 
-#Haddock does allow you to customise the description section of a file, but only with more Haskell comments
-#Since I want to use an HTML description (with links to SVG using object tags) I have to perform the following hack
-#to use my own custom HTML description.  Fixes to make the hack nicer are welcome :-)
-
+# We post-process the Haddock output with M4 so that we can include SVG images.
 haddock:
-	@mkdir -p doc
-	@echo "putmycustomdocumentationhere" > .temp-haddock-file
-	haddock -o doc --html -p .temp-haddock-file -t Tock $(tock_SOURCES_hs)
+	@MKDIR_P@ doc
+	haddock -o doc --html -p docextra/description -t Tock $(tock_SOURCES_hs)
 	cp docextra/*.svg doc/
-	@rm .temp-haddock-file
-	@grep -B 10000 putmycustomdocumentationhere doc/index.html | sed "s/putmycustomdocumentationhere//" > doc/index.html-2
-	@cat docextra/description.html >> doc/index.html-2
-	@grep -A 10000 putmycustomdocumentationhere doc/index.html | tail -n +2 >> doc/index.html-2
-	@rm doc/index.html
-	@mv doc/index.html-2 doc/index.html
+	@for x in doc/*.html; do \
+		echo ">>> Post-processing $$x"; \
+		cat docextra/tock-docs.m4 $$x | m4 -P >$${x}_ && mv $${x}_ $$x; \
+	done
diff --git a/docextra/description b/docextra/description
new file mode 100644
index 0000000..5b10d2c
--- /dev/null
+++ b/docextra/description
@@ -0,0 +1,7 @@
+This is the generated API documentation for the Tock compiler.
+
+Below is a rough diagram of the structure of Tock.  On the left are the
+front-ends, in the middle are the common passes, and on the right are the
+back-ends.
+
+_tock_svg(tock-passes, 800, 400)
diff --git a/docextra/description.html b/docextra/description.html
deleted file mode 100644
index 4c42840..0000000
--- a/docextra/description.html
+++ /dev/null
@@ -1,14 +0,0 @@
-<p>
-This is the generated API documentation for the Tock compiler.
-</p>
-
-<h3>Tock Passes</h3>
-<p>
-Below is a rough diagram of the structure of Tock.  On the left are the front-ends, in the middle are the common passes, and on the right are the back-ends.
-</p>
-<object data="tock-passes.svg" width="800" height="400">
-<p>
-<i>In order to view this image you need an SVG viewer.  The most recent versions of Firefox and Opera both have in-built SVG viewers. 
-For Internet Explorer, you will need to install the <a href="http://www.adobe.com/svg/viewer/install/">Adobe SVG Viewer</a>.</i>
-</p>
-</object>
diff --git a/docextra/tock-docs.m4 b/docextra/tock-docs.m4
new file mode 100644
index 0000000..d3a0227
--- /dev/null
+++ b/docextra/tock-docs.m4
@@ -0,0 +1,10 @@
+m4_dnl  Macros to make Tock's HTML documentation a bit nicer.
+
+m4_define(`_tock_svg',`<object data="$1.svg" width="$2" height="$3">
+<em>
+In order to view this image you need an SVG viewer.  The most recent
+versions of Firefox and Opera both have in-built SVG viewers.  For Internet
+Explorer, you will need to install the <a
+href="http://www.adobe.com/svg/viewer/install/">Adobe SVG Viewer</a>.
+</em>
+</object>')