On Fri, 2008-02-22 at 07:21 -0800, Keith Fahlgren wrote:
On 2/21/08 3:57 PM, Duncan Coutts wrote:
Consequently there is no support in Cabal etc for those kinds of documentation. GHC, Cabal and c2hs amongst others use docbook but it's a horrible format to write and the tools to process it are very finicky (we apparently have to hard code paths to specific versions of xslt stylesheets).
Hi,
DocBook authoring tools have progressed tremendously in the past few years, and I disagree that the "tools to process it are very finicky". If there are specific questions about making DocBook more palatable for GHC, Cabal, c2hs, others, please send them to me directly or the docbook-apps list: http://www.docbook.org/help
I admit to knowing rather little about it but I've noticed that these three projects are using xsltproc directly as their docbook processor (the other two just copied GHC). Because xsltproc is a general purpose tool they have to supply a large number of parameters including a hard coded location of an xslt script (and xsltproc seems to always want to go to the network to download a dtd when it already has a version it can use offline). Currently Cabal uses: xsltproc --param use.id.as.filename 1 --param toc.section.depth 3 --stringparam base.dir dist/doc/users-guide/ --stringparam html.stylesheet doc/fptools.css /usr/share/sgml/docbook/xsl-stylesheets-1.70.1/xhtml/chunk.xsl doc/Cabal.xml Yes, that's a hard coded path to the style sheet. GHC does it slightly more cleverly by using a configure.ac test to look through a very large number of hard coded paths to try and find the above style sheet. c2hs used to use docbook2html which was easier to use in terms of specifying command lines but produced worse output and didn't seem to work on more recent distros so c2hs switched to xml docbook format rather than the previous sgml format. Basically I'd like to know what tool (that is packaged on every linux distro) do I use to convert a docbook .xml file to xhtml. I took a quick look on the FAQ linked from docbook.org/help and could not immediately find what standard tools and commands I'm supposed to use. Duncan