Re: [docbook-apps] Generating HTML from docbook in autotoolsproject

[Markus Hoenicka <markus.hoenicka@mhoenicka.de>]

Hi Brendon,

I guess your approach is not that uncommon, and there's probably a few  
success stories to learn from. I'm using two different approaches in  
three projects. These are certainly not the only ways to do it, but  
feel free to have a look at the setups.

Both libdbi (http://libdbi.sourceforge.net) and libdbi-drivers  
(http://libdbi-drivers.sourceforge.net) use DocBook SGML and OpenJade,  
but as you were asking for XML I'm not going to elaborate on that.

RefDB (http://refdb.sourceforge.net) uses DocBook XML. I've settled  
for libxslt/xsltproc to transform the documentation. xsltproc is part  
of the default installation on many platforms and simple to check for  
in your configure script, in contrast to the Java-based processors  
(you can't rely on the presence of aptly named wrapper scripts that  
would allow portable configure tests on all platforms). The  
documentation is modular. The reference section of the manual mostly  
consists of the man pages which are DocBook refentries. I use the  
DocBook stylesheets to create the man pages from these sources as  
well. A customization layer is used to make the sections of the man  
pages show up as sections in the TOC of the transformed manuals. The  
Makefile is set up to create both a chunked HTML manual and a PDF  
manual. You could certainly extend this setup and create a single-page  
HTML manual in a different subdirectory as well.

One thing to consider is how to make the documentation accessible for  
those who don't have a full XML toolchain on their computer. In my  
setup the HTML and PDF documentation as well as the man pages are  
maintainer-built and are thus included in the tarball. Users who  
attempt to build a released version don't need the XML toolchain and  
still get their documentation installed. Only those that build from  
the SVN sources need the toolchain if they want to build the  
documentation and the man pages. The configure script checks for  
--disable-docs and --disable-manpages options, so you can optionally  
switch off building the docs or manpages even if you build from the  
SVN sources.

Please check the SVN repository of RefDB for further details. The  
interesting stuff is here:

http://refdb.svn.sourceforge.net/viewvc/refdb/refdb/trunk/

You may want to have a look at the configure.in script as well as at  
the Makefile.am's of the /doc and /man folders. Let me know if you  
need further explanations of the setup.

regards,
Markus

Quoting Brendon Costa <bcosta@avdat.com.au>:

> Hi all,
>
> I have a project that uses autotools (autoconf, automake and libtool).
> I have been writing the manual for the project in docbook XML format
> instead of tex. What is a common method for generating HTML (single
> and multiple page) documentation from a docbook file within this
> environment?
>
> I am not sure which of the many tools are most commonly used, and
> which is simplest to integrate into an automake based project. I would
> think that many have at least attempted this and so was wondering if
> people have any advice?
>


-- 
Markus Hoenicka
markus.hoenicka@cats.de
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de