suzanne.soy/tock-mirror
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up the documentation hack a bit.

Browse Source 
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).
This commit is contained in:
Adam Sampson 2008-02-28 14:43:53 +00:00
parent 8d06c3d180
commit 06ad1e5e06
4 changed files with 24 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
Makefile.am
View File

@ -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

7
docextra/description Normal file
View File

@ -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)

14
docextra/description.html
View File

@ -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>

10
docextra/tock-docs.m4 Normal file
View File

@ -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>')