diff options
author | simonmar <simonmar@microsoft.com> | 2005-10-29 08:14:43 +0000 |
---|---|---|
committer | simonmar <simonmar@microsoft.com> | 2005-10-29 08:14:43 +0000 |
commit | 766cecdda0a834e2a50a6aaa36518ea6b4ac360c (patch) | |
tree | c7f45cd024fa7ba65aa028421a6b7cedf17dbe7e /doc | |
parent | 21c7ac8d714be74903755ed2d6ee3716ab77a727 (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/Makefile | 5 | ||||
-rw-r--r-- | doc/README | 25 | ||||
-rw-r--r-- | doc/aclocal.m4 | 174 | ||||
-rw-r--r-- | doc/config.mk.in | 15 | ||||
-rw-r--r-- | doc/configure.ac | 12 | ||||
-rw-r--r-- | doc/docbook-xml.mk | 130 | ||||
-rw-r--r-- | doc/fptools.css | 36 |
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 } |