[Haskell-cafe] haddock as a markdown preprocessor

[Duncan Coutts]

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