[[project @ 2004-08-15 20:28:02 by panne]
panne**20040815202808
 <fanfare>Finally: Support for DocBook XML!</fanfare>
 
 After endless frustrating hours, I came to the conclusion that using (Open)Jade
 for DocBook XML is virtually impossible, there are *tons* of problems with it:
 Wildly differing paths, incorrect stylesheets, broken catalogs at funny places,
 broken wrapper scripts, missing support on Cygwin etc.  >:-P * * *
 
 So we follow the ubiquitous XSL hype and use xsltproc + DocBook XSL stylesheets
 to transform DocBook XML to HTML and FO. From FO there are two routes to PDF and
 PostScript: Either via FOP (preferred) or via PassiveTeX. Validation can be done
 via xmllint using the new make target "validate". When PassiveTeX is available,
 DVI can be generated, too.  A new make target "no-chunks-html" is available for
 generating an all-in-one HTML document. Currently there is no way to generate
 plain text or RTF, but at least the former could easily be added.
 
 Generating HTML works out-of-the-box on Cygwin now, but you will have to install
 FOP for other formats, because there seems to be no standard package for it.
 
 The HTML appearance can be controlled via CSS, but the current location of the
 master stylesheet below fptools/mk is a bit debatable. Better suggestions are
 welcome.
 
 Currently there is still support for SGML documents, but it will be dropped when
 all documents are converted to DocBook XML. The build system is complex enough
 already with the support for a *single* kind of DocBook...
] {
addfile ./mk/fptools.css
hunk ./Makefile 290
-	    echo $(MAKE) -C $$i $(MFLAGS) install-docs SGMLDocWays="$(BINDIST_DOC_WAYS)" \
+	    echo $(MAKE) -C $$i $(MFLAGS) install-docs SGMLDocWays="$(BINDIST_DOC_WAYS)" XMLDocWays="$(BINDIST_DOC_WAYS)" \
hunk ./Makefile 297
-	    $(MAKE) -C $$i $(MFLAGS) install-docs SGMLDocWays="$(BINDIST_DOC_WAYS)" \
+	    $(MAKE) -C $$i $(MFLAGS) install-docs SGMLDocWays="$(BINDIST_DOC_WAYS)" XMLDocWays="$(BINDIST_DOC_WAYS)" \
hunk ./aclocal.m4 8
-# ------------------------
+# -----------------------
hunk ./aclocal.m4 21
-# -----------------------------------------------------------------------
+# ---------------------------------------------------------------------
hunk ./aclocal.m4 79
-# -------------------
+# ---------------
hunk ./aclocal.m4 100
-# ---------------------------------------------------------
+# --------------------------------------------------------
hunk ./aclocal.m4 138
-# ---------------------------------------------------------------------------------
+# -------------------------------------------------------------------------------
hunk ./aclocal.m4 153
-# ----------------------------------
+# ---------------------------------------
hunk ./aclocal.m4 163
-# -------------------------------------------------------------------------------------
+# -----------------------------------------------------------------------------------
hunk ./aclocal.m4 832
+
+# 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_PROG_FO_PROCESSOR
+# --------------------
+# Try to find an FO processor. PassiveTeX output is sometimes a bit strange, so
+# try FOP first.  Furthermore, /usr/bin/fop is broken in SuSE 9.1, so try the
+# "real" fop.sh first. Sets the output variables FopCmd, XmltexCmd, DvipsCmd,
+# and PdfxmltexCmd.
+AC_DEFUN([FP_PROG_FO_PROCESSOR],
+[AC_PATH_PROGS([FopCmd], [fop.sh fop], [], [$PATH:/usr/share/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
+
hunk ./configure.ac 856
+
+dnl ** check for DocBook toolchain
+FP_CHECK_DOCBOOK_DTD
+FP_DIR_DOCBOOK_XSL([/usr/share/xml/docbook/stylesheet/nwalsh/current /usr/share/sgml/docbook/docbook-xsl-stylesheets* /opt/kde?/share/apps/ksgmltools2/docbook/xsl /usr/share/docbook-xsl /usr/share/sgml/docbkxsl])
+FP_PROG_FO_PROCESSOR
hunk ./mk/config.mk.in 188
+#
+# Which ways should DocBook XML documents be built?
+# options are: dvi ps pdf html
+#
+XMLDocWays=
+
hunk ./mk/config.mk.in 910
+#-----------------------------------------------------------------------------
+# DocBook XML stuff
+
+XSLTPROC		= @XsltprocCmd@
+XMLLINT			= @XmllintCmd@
+FOP			= @FopCmd@
+XMLTEX			= @XmltexCmd@
+PDFXMLTEX		= @PdfxmltexCmd@
+DVIPS			= @DvipsCmd@
+
+DIR_DOCBOOK_XSL		= @DIR_DOCBOOK_XSL@
+
hunk ./mk/fptools.css 1
+div.article div.book {
+  font-family: sans-serif;
+  color: black;
+  background: white
+}
+
+h1, h2, h3 { 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: green  }
+pre.programlisting { color: maroon }
+
+a:link    { color:      #0000C8 }
+a:hover   { background: #FFFFA8 }
+a:active  { color:      #D00000 }
+a:visited { color:      #680098 }
hunk ./mk/opts.mk 8
-# 	$Id: opts.mk,v 1.34 2003/08/18 15:45:09 panne Exp $
+# 	$Id: opts.mk,v 1.35 2004/08/15 20:28:06 panne Exp $
hunk ./mk/opts.mk 107
+XSLTPROC_OPTS      = $(WAY$(_way)_XSLTPROC_OPTS) $(EXTRA_XSLTPROC_OPTS)
+FOP_OPTS           = $(WAY$(_way)_FOP_OPTS) $(EXTRA_FOP_OPTS)
hunk ./mk/paths.mk 354
+#------------------------------------------------------------------
+
+FPTOOLS_CSS = $(FPTOOLS_TOP)/mk/fptools.css
hunk ./mk/suffix.mk 242
+#-----------------------------------------------------------------------------
+# DocBook XML suffix rules
+#
+
+%-no-chunks.html : %.xml
+	$(XSLTPROC) --output $@ \
+	            --stringparam html.stylesheet fptools.css \
+	            $(XSLTPROC_OPTS) $(DIR_DOCBOOK_XSL)/html/docbook.xsl $<
+	cp $(FPTOOLS_CSS) .
+
+%.html : %.xml
+	@$(RM) -rf $@ $(basename $@)
+	$(XSLTPROC) --stringparam base.dir $(basename $@)/ \
+	            --stringparam use.id.as.filename 1 \
+	            --stringparam root.filename '' \
+	            --stringparam html.stylesheet fptools.css \
+	            $(XSLTPROC_OPTS) $(DIR_DOCBOOK_XSL)/html/chunk.xsl $<
+	cp $(FPTOOLS_CSS) $(basename $@)
+	touch $@
+
+%.fo : %.xml
+	$(XSLTPROC) --output $@ \
+	            $(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
+
hunk ./mk/suffix.mk 299
-	dvips $< -o $@
+	$(DVIPS) $< -o $@
hunk ./mk/target.mk 805
+ifneq "$(XMLDocWays)" ""
+install-docs:: $(INSTALL_DOCS)
+	@$(INSTALL_DIR) $(datadir)	
+	for i in $(INSTALL_DOCS); do \
+		$(INSTALL_DATA) $(INSTALL_OPTS) $$i $(datadir); \
+	done
+endif
+endif
+
+# The following could be an entry for an Obfuscated Makefile Contest...
+ifneq "$(INSTALL_XML_DOC)" ""
+ifneq "$(XMLDocWays)" ""
+install-docs:: $(foreach i,$(XMLDocWays),$(INSTALL_XML_DOC)$(subst .no-chunks-html,-no-chunks.html,.$(i)))
+	@$(INSTALL_DIR) $(datadir)	
+	@for i in $(XMLDocWays); do \
+		if [ $$i = "html" ]; then \
+			$(INSTALL_DIR) $(datadir)/html; \
+			echo $(CP) -r $(INSTALL_XML_DOC) $(datadir)/html; \
+			$(CP) -r $(INSTALL_XML_DOC) $(datadir)/html; \
+		else \
+			echo $(INSTALL_DATA) $(INSTALL_OPTS) $(INSTALL_XML_DOC)`echo .$$i | sed s/\.no-chunks-html/-no-chunks.html/` $(datadir); \
+			$(INSTALL_DATA) $(INSTALL_OPTS) $(INSTALL_XML_DOC)`echo .$$i | sed s/\.no-chunks-html/-no-chunks.html/` $(datadir); \
+		fi; \
+		if [ $$i = "no-chunks-html" ]; then \
+			echo $(CP) $(FPTOOLS_CSS) $(datadir); \
+			$(CP) $(FPTOOLS_CSS) $(datadir); \
+		fi \
+	done
+endif
hunk ./mk/target.mk 979
+
+################################################################################
+#
+#			DocBook XML Documentation
+#
+################################################################################
+
+.PHONY: html no-chunks-html fo dvi ps pdf
+
+ifneq "$(XML_DOC)" ""
+
+all :: $(XMLDocWays)
+
+# 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 .html,$(XML_DOC))
+XML_NO_CHUNKS_HTML = $(addsuffix -no-chunks.html,$(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)
+no-chunks-html :: $(XML_NO_CHUNKS_HTML)
+fo             :: $(XML_FO)
+dvi            :: $(XML_DVI)
+ps             :: $(XML_PS)
+pdf            :: $(XML_PDF)
+
+CLEAN_FILES += $(XML_HTML) $(XML_NO_CHUNKS_HTML) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF)
+
+extraclean ::
+	$(RM) -rf $(XML_DOC).out $(XML_DOC)
+
+validate ::
+	$(XMLLINT) --valid --noout $(XMLLINT_OPTS) $(XML_DOC).xml
+endif
}