aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorsimonmar <simonmar@microsoft.com>2005-10-29 08:14:43 +0000
committersimonmar <simonmar@microsoft.com>2005-10-29 08:14:43 +0000
commit766cecdda0a834e2a50a6aaa36518ea6b4ac360c (patch)
treec7f45cd024fa7ba65aa028421a6b7cedf17dbe7e /doc
parent21c7ac8d714be74903755ed2d6ee3716ab77a727 (diff)
Add configure script and Makefile for the docs
Add a separate configure script and build system for building the documentation. The configure and Makefile code is stolen from fptools. This is left as a separate build system so that the main Cabal setup doesn't require a Unix build environment or DocBook XML tools.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile5
-rw-r--r--doc/README25
-rw-r--r--doc/aclocal.m4174
-rw-r--r--doc/config.mk.in15
-rw-r--r--doc/configure.ac12
-rw-r--r--doc/docbook-xml.mk130
-rw-r--r--doc/fptools.css36
7 files changed, 394 insertions, 3 deletions
diff --git a/doc/Makefile b/doc/Makefile
index dbab0ba6..5f88b708 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,7 +1,6 @@
-TOP=..
-include $(TOP)/mk/boilerplate.mk
+include config.mk
XML_DOC = haddock
INSTALL_XML_DOC = haddock
-include $(TOP)/mk/target.mk
+include docbook-xml.mk
diff --git a/doc/README b/doc/README
new file mode 100644
index 00000000..ab9c0f2f
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,25 @@
+Haddock documentation
+---------------------
+
+The documentation is in DocBook XML format. You need some tools to
+process it: at least xsltproc, and the DocBook XML DTD and XSL
+stylesheets. There's a configure script to detect the right way to
+process the documentation on your system, and a Makefile to actually
+do the processing (so, on Windows, you'll need Cygwin or MSys in
+addition to the DocBook XML tools). To build the HTML documentation:
+
+ $ ./configure
+ $ make html
+
+which leaves the HTML documentation in a haddock/ subdirectory.
+
+Printable documentation can also be produced, eg.:
+
+ $ make pdf
+
+or
+
+ $ make ps
+
+Generating the printed formats requires more tools (fop or xmltex) and
+tends to be a bit harder.
diff --git a/doc/aclocal.m4 b/doc/aclocal.m4
new file mode 100644
index 00000000..97ffcb76
--- /dev/null
+++ b/doc/aclocal.m4
@@ -0,0 +1,174 @@
+# FP_GEN_DOCBOOK_XML
+# ------------------
+# Generates a DocBook XML V4.2 document in conftest.xml.
+AC_DEFUN([FP_GEN_DOCBOOK_XML],
+[rm -f conftest.xml
+cat > conftest.xml << EOF
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<book id="test">
+ <title>A DocBook Test Document</title>
+ <chapter id="id-one">
+ <title>A Chapter Title</title>
+ <para>This is a paragraph, referencing <xref linkend="id-two"/>.</para>
+ </chapter>
+ <chapter id="id-two">
+ <title>Another Chapter Title</title>
+ <para>This is another paragraph, referencing <xref linkend="id-one"/>.</para>
+ </chapter>
+</book>
+EOF
+]) # FP_GEN_DOCBOOK_XML
+
+
+# FP_PROG_XSLTPROC
+# ----------------
+# Sets the output variable XsltprocCmd to the full path of the XSLT processor
+# xsltproc. XsltprocCmd is empty if xsltproc could not be found.
+AC_DEFUN([FP_PROG_XSLTPROC],
+[AC_PATH_PROG([XsltprocCmd], [xsltproc])
+if test -z "$XsltprocCmd"; then
+ AC_MSG_WARN([cannot find xsltproc in your PATH, you will not be able to build the documentation])
+fi
+])# FP_PROG_XSLTPROC
+
+
+# FP_DIR_DOCBOOK_XSL(XSL-DIRS)
+# ----------------------------
+# Check which of the directories XSL-DIRS contains DocBook XSL stylesheets. The
+# output variable DIR_DOCBOOK_XSL will contain the first usable directory or
+# will be empty if none could be found.
+AC_DEFUN([FP_DIR_DOCBOOK_XSL],
+[AC_REQUIRE([FP_PROG_XSLTPROC])dnl
+if test -n "$XsltprocCmd"; then
+ AC_CACHE_CHECK([for DocBook XSL stylesheet directory], fp_cv_dir_docbook_xsl,
+ [FP_GEN_DOCBOOK_XML
+ fp_cv_dir_docbook_xsl=no
+ for fp_var in $1; do
+ if $XsltprocCmd ${fp_var}/html/docbook.xsl conftest.xml > /dev/null 2>&1; then
+ fp_cv_dir_docbook_xsl=$fp_var
+ break
+ fi
+ done
+ rm -rf conftest*])
+fi
+if test x"$fp_cv_dir_docbook_xsl" = xno; then
+ AC_MSG_WARN([cannot find DocBook XSL stylesheets, you will not be able to build the documentation])
+ DIR_DOCBOOK_XSL=
+else
+ DIR_DOCBOOK_XSL=$fp_cv_dir_docbook_xsl
+fi
+AC_SUBST([DIR_DOCBOOK_XSL])
+])# FP_DIR_DOCBOOK_XSL
+
+
+# FP_PROG_XMLLINT
+# ----------------
+# Sets the output variable XmllintCmd to the full path of the XSLT processor
+# xmllint. XmllintCmd is empty if xmllint could not be found.
+AC_DEFUN([FP_PROG_XMLLINT],
+[AC_PATH_PROG([XmllintCmd], [xmllint])
+if test -z "$XmllintCmd"; then
+ AC_MSG_WARN([cannot find xmllint in your PATH, you will not be able to validate your documentation])
+fi
+])# FP_PROG_XMLLINT
+
+
+# FP_CHECK_DOCBOOK_DTD
+# --------------------
+AC_DEFUN([FP_CHECK_DOCBOOK_DTD],
+[AC_REQUIRE([FP_PROG_XMLLINT])dnl
+if test -n "$XmllintCmd"; then
+ AC_MSG_CHECKING([for DocBook DTD])
+ FP_GEN_DOCBOOK_XML
+ if $XmllintCmd --valid --noout conftest.xml > /dev/null 2>&1; then
+ AC_MSG_RESULT([ok])
+ else
+ AC_MSG_RESULT([failed])
+ AC_MSG_WARN([cannot find a DTD for DocBook XML V4.2, you will not be able to validate your documentation])
+ AC_MSG_WARN([check your XML_CATALOG_FILES environment variable and/or /etc/xml/catalog])
+ fi
+ rm -rf conftest*
+fi
+])# FP_CHECK_DOCBOOK_DTD
+
+
+# FP_GEN_FO
+# ------------------
+# Generates a formatting objects document in conftest.fo.
+AC_DEFUN([FP_GEN_FO],
+[rm -f conftest.fo
+cat > conftest.fo << EOF
+<?xml version="1.0"?>
+<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
+ <fo:layout-master-set>
+ <fo:simple-page-master master-name="blank">
+ <fo:region-body/>
+ </fo:simple-page-master>
+ </fo:layout-master-set>
+ <fo:page-sequence master-reference="blank">
+ <fo:flow flow-name="xsl-region-body">
+ <fo:block>
+ Test!
+ </fo:block>
+ </fo:flow>
+ </fo:page-sequence>
+</fo:root>
+EOF
+]) # FP_GEN_FO
+
+
+# FP_PROG_FOP
+# -----------
+# Set the output variable 'FopCmd' to the first working 'fop' in the current
+# 'PATH'. Note that /usr/bin/fop is broken in SuSE 9.1 (unpatched), so try
+# /usr/share/fop/fop.sh in that case (or no 'fop'), too.
+AC_DEFUN([FP_PROG_FOP],
+[AC_PATH_PROGS([FopCmd1], [fop])
+if test -n "$FopCmd1"; then
+ AC_CACHE_CHECK([for $FopCmd1 usability], [fp_cv_fop_usability],
+ [FP_GEN_FO
+ if "$FopCmd1" -fo conftest.fo -ps conftest.ps > /dev/null 2>&1; then
+ fp_cv_fop_usability=yes
+ else
+ fp_cv_fop_usability=no
+ fi
+ rm -rf conftest*])
+ if test x"$fp_cv_fop_usability" = xyes; then
+ FopCmd=$FopCmd1
+ fi
+fi
+if test -z "$FopCmd"; then
+ AC_PATH_PROGS([FopCmd2], [fop.sh], , [/usr/share/fop])
+ FopCmd=$FopCmd2
+fi
+AC_SUBST([FopCmd])
+])# FP_PROG_FOP
+
+
+# FP_PROG_FO_PROCESSOR
+# --------------------
+# Try to find an FO processor. PassiveTeX output is sometimes a bit strange, so
+# try FOP first. Sets the output variables FopCmd, XmltexCmd, DvipsCmd, and
+# PdfxmltexCmd.
+AC_DEFUN([FP_PROG_FO_PROCESSOR],
+[AC_REQUIRE([FP_PROG_FOP])
+AC_PATH_PROG([XmltexCmd], [xmltex])
+AC_PATH_PROG([DvipsCmd], [dvips])
+if test -z "$FopCmd"; then
+ if test -z "$XmltexCmd"; then
+ AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI or PostScript documentation])
+ else
+ if test -z "$DvipsCmd"; then
+ AC_MSG_WARN([cannot find a DVI => PS converter, you will not be able to build PostScript documentation])
+ fi
+ fi
+ AC_PATH_PROG([PdfxmltexCmd], [pdfxmltex])
+ if test -z "$PdfxmltexCmd"; then
+ AC_MSG_WARN([cannot find an FO => PDF converter, you will not be able to build PDF documentation])
+ fi
+elif test -z "$XmltexCmd"; then
+ AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI documentation])
+fi
+])# FP_PROG_FO_PROCESSOR
diff --git a/doc/config.mk.in b/doc/config.mk.in
new file mode 100644
index 00000000..e286794c
--- /dev/null
+++ b/doc/config.mk.in
@@ -0,0 +1,15 @@
+#-----------------------------------------------------------------------------
+# DocBook XML stuff
+
+XSLTPROC = @XsltprocCmd@
+XMLLINT = @XmllintCmd@
+FOP = @FopCmd@
+XMLTEX = @XmltexCmd@
+PDFXMLTEX = @PdfxmltexCmd@
+DVIPS = @DvipsCmd@
+
+DIR_DOCBOOK_XSL = @DIR_DOCBOOK_XSL@
+
+XSLTPROC_LABEL_OPTS = --stringparam toc.section.depth 3 \
+ --stringparam section.autolabel 1 \
+ --stringparam section.label.includes.component.label 1
diff --git a/doc/configure.ac b/doc/configure.ac
new file mode 100644
index 00000000..26fb8b7d
--- /dev/null
+++ b/doc/configure.ac
@@ -0,0 +1,12 @@
+
+AC_INIT([Haddock docs], [1.0], [simonmar@microsoft.com], [])
+
+AC_CONFIG_SRCDIR([Makefile])
+
+dnl ** check for DocBook toolchain
+FP_CHECK_DOCBOOK_DTD
+FP_DIR_DOCBOOK_XSL([/usr/share/xml/docbook/stylesheet/nwalsh/current /usr/share/xml/docbook/stylesheet/nwalsh /usr/share/sgml/docbook/docbook-xsl-stylesheets* /usr/share/sgml/docbook/xsl-stylesheets* /opt/kde?/share/apps/ksgmltools2/docbook/xsl /usr/share/docbook-xsl /usr/share/sgml/docbkxsl /usr/local/share/xsl/docbook /sw/share/xml/xsl/docbook-xsl])
+FP_PROG_FO_PROCESSOR
+
+AC_CONFIG_FILES([config.mk])
+AC_OUTPUT
diff --git a/doc/docbook-xml.mk b/doc/docbook-xml.mk
new file mode 100644
index 00000000..f6048187
--- /dev/null
+++ b/doc/docbook-xml.mk
@@ -0,0 +1,130 @@
+#-----------------------------------------------------------------------------
+# DocBook XML
+
+.PHONY: html html-no-chunks chm HxS fo dvi ps pdf
+
+ifneq "$(XML_DOC)" ""
+
+all :: html
+
+# multi-file XML document: main document name is specified in $(XML_DOC),
+# sub-documents (.xml files) listed in $(XML_SRCS).
+
+ifeq "$(XML_SRCS)" ""
+XML_SRCS = $(wildcard *.xml)
+endif
+
+XML_HTML = $(addsuffix /index.html,$(basename $(XML_DOC)))
+XML_HTML_NO_CHUNKS = $(addsuffix .html,$(XML_DOC))
+XML_CHM = $(addsuffix .chm,$(XML_DOC))
+XML_HxS = $(addsuffix .HxS,$(XML_DOC))
+XML_FO = $(addsuffix .fo,$(XML_DOC))
+XML_DVI = $(addsuffix .dvi,$(XML_DOC))
+XML_PS = $(addsuffix .ps,$(XML_DOC))
+XML_PDF = $(addsuffix .pdf,$(XML_DOC))
+
+$(XML_HTML) $(XML_NO_CHUNKS_HTML) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF) :: $(XML_SRCS)
+
+html :: $(XML_HTML)
+html-no-chunks :: $(XML_HTML_NO_CHUNKS)
+chm :: $(XML_CHM)
+HxS :: $(XML_HxS)
+fo :: $(XML_FO)
+dvi :: $(XML_DVI)
+ps :: $(XML_PS)
+pdf :: $(XML_PDF)
+
+CLEAN_FILES += $(XML_HTML_NO_CHUNKS) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF)
+
+FPTOOLS_CSS = fptools.css
+
+clean ::
+ $(RM) -rf $(XML_DOC).out $(basename $(XML_DOC)) $(basename $(XML_DOC))-htmlhelp
+
+validate ::
+ $(XMLLINT) --valid --noout $(XMLLINT_OPTS) $(XML_DOC).xml
+endif
+
+#-----------------------------------------------------------------------------
+# DocBook XML suffix rules
+#
+
+%.html : %.xml
+ $(XSLTPROC) --output $@ \
+ --stringparam html.stylesheet $(FPTOOLS_CSS) \
+ $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
+ $(DIR_DOCBOOK_XSL)/html/docbook.xsl $<
+
+%/index.html : %.xml
+ $(RM) -rf $(dir $@)
+ $(XSLTPROC) --stringparam base.dir $(dir $@) \
+ --stringparam use.id.as.filename 1 \
+ --stringparam html.stylesheet $(FPTOOLS_CSS) \
+ $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
+ $(DIR_DOCBOOK_XSL)/html/chunk.xsl $<
+ cp $(FPTOOLS_CSS) $(dir $@)
+
+# Note: Numeric labeling seems to be uncommon for HTML Help
+%-htmlhelp/index.html : %.xml
+ $(RM) -rf $(dir $@)
+ $(XSLTPROC) --stringparam base.dir $(dir $@) \
+ --stringparam manifest.in.base.dir 1 \
+ --stringparam htmlhelp.chm "..\\"$(basename $<).chm \
+ $(XSLTPROC_OPTS) \
+ $(DIR_DOCBOOK_XSL)/htmlhelp/htmlhelp.xsl $<
+
+%-htmlhelp2/collection.HxC : %.xml
+ $(RM) -rf $(dir $@)
+ $(XSLTPROC) --stringparam base.dir $(dir $@) \
+ --stringparam use.id.as.filename 1 \
+ --stringparam manifest.in.base.dir 1 \
+ $(XSLTPROC_OPTS) \
+ $(DIR_DOCBOOK_XSL)/htmlhelp2/htmlhelp2.xsl $<
+
+# TODO: Detect hhc & Hxcomp via autoconf
+#
+# Two obstacles here:
+#
+# * The reason for the strange "if" below is that hhc returns 0 on error and 1
+# on success, the opposite of what shells and make expect.
+#
+# * There seems to be some trouble with DocBook indices, but the *.chm looks OK,
+# anyway, therefore we pacify make by "|| true". Ugly...
+#
+%.chm : %-htmlhelp/index.html
+ ( cd $(dir $<) && if hhc htmlhelp.hhp ; then false ; else true ; fi ) || true
+
+%.HxS : %-htmlhelp2/collection.HxC
+ ( cd $(dir $<) && if Hxcomp -p collection.HxC -o ../$@ ; then false ; else true ; fi )
+
+%.fo : %.xml
+ $(XSLTPROC) --output $@ \
+ --stringparam draft.mode no \
+ $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
+ $(DIR_DOCBOOK_XSL)/fo/docbook.xsl $<
+
+ifeq "$(FOP)" ""
+ifneq "$(PDFXMLTEX)" ""
+%.pdf : %.fo
+ $(PDFXMLTEX) $<
+ if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \
+ $(PDFXMLTEX) $< ; \
+ $(PDFXMLTEX) $< ; \
+ fi
+endif
+else
+%.ps : %.fo
+ $(FOP) $(FOP_OPTS) -fo $< -ps $@
+
+%.pdf : %.fo
+ $(FOP) $(FOP_OPTS) -fo $< -pdf $@
+endif
+
+ifneq "$(XMLTEX)" ""
+%.dvi : %.fo
+ $(XMLTEX) $<
+ if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \
+ $(XMLTEX) $< ; \
+ $(XMLTEX) $< ; \
+ fi
+endif
diff --git a/doc/fptools.css b/doc/fptools.css
new file mode 100644
index 00000000..5c7fc47b
--- /dev/null
+++ b/doc/fptools.css
@@ -0,0 +1,36 @@
+div {
+ font-family: sans-serif;
+ color: black;
+ background: white
+}
+
+h1, h2, h3, h4, h5, h6, p.title { color: #005A9C }
+
+h1 { font: 170% sans-serif }
+h2 { font: 140% sans-serif }
+h3 { font: 120% sans-serif }
+h4 { font: bold 100% sans-serif }
+h5 { font: italic 100% sans-serif }
+h6 { font: small-caps 100% sans-serif }
+
+pre {
+ font-family: monospace;
+ border-width: 1px;
+ border-style: solid;
+ padding: 0.3em
+}
+
+pre.screen { color: #006400 }
+pre.programlisting { color: maroon }
+
+div.example {
+ background-color: #fffcf5;
+ margin: 1ex 0em;
+ border: solid #412e25 1px;
+ padding: 0ex 0.4em
+}
+
+a:link { color: #0000C8 }
+a:hover { background: #FFFFA8 }
+a:active { color: #D00000 }
+a:visited { color: #680098 }