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 <[EMAIL PROTECTED]>:
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
[EMAIL PROTECTED]
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
