docbook/xml -> PDF

[James Henstridge <james daa com au>]

I had a go at converting the docbook/xml output from gtk-doc to PDF 
using the xmlto utility (which is a wrapper round xsltproc, similar to 
how jw is a wrapper round jade).  I used the libegg documentation as a 
source, as I already had it set up for xml -> HTML transformation.

The xmlto utility performs the conversion by first passing the document 
through Norman Walsh's DocBook -> FO XSLT transform, then passing the 
output to passivetex which is a set of TeX macros used to nicely format 
FO documents (it uses the xmltex XML parser for TeX).

The first hurdle was that xmlto was not turning on XInclude processing. 
This was easy to fix by adding --xinclude to the list of options passed 
to xsltproc.  I have emailed Tim Waugh about this, and future versions 
of xmlto will turn on XInclude processing, so this is not too big a deal.

The second problem was in the FO processing stage.  It seems that 
PassiveTeX doesn't handle the proportional table column widths that 
gtk-doc uses (to format the argument lists for functions).  The XSLT 
stylesheets convert the column widths "2*" and "8*" to 
"proportional-column-width(2)" and "proportional-column-width(8)", while 
PassiveTeX doesn't seem to handle anything other than numbers for the 
column widths.  I worked around this by generating the FO document 
first, running sed over it (I changed "proportional-column-width(2)" to 
"100pt" and "proportional-column-width(8)" to "400pt").  I then passed 
the FO to xmlto to produce PDF.  This could probably be worked around 
with a customisation layer for the FO stylesheet:
 <xsl:template name="calc.column.width">
   <xsl:param name="colwidth">1*</xsl:param>
   <xsl:choose>
     <xsl:when test="$colwidth='2*'">
       <xsl:text>100pt</xsl:text>
     </xsl:when>
     <xsl:when test="$colwidth='8*'">
       <xsl:text>400pt</xsl:text>
     </xsl:when>
     <xsl:otherwise>
       <xsl:apply-imports/>
     </xsl:otherwise>
   </xsl:choose>
 </xsl:template>
(the alterntive would be to modify gtkdoc-mkdb to not use tables for 
this ...)

Last of all, the output PDF wasn't displaying the <synopsis> sections as 
preformatted text, which didn't look very nice.  Not sure what to do 
about this one, although the template for <synopsis> doesn't look like 
it does anything special to preserve formatting.  I think this might be 
due to me using an old version of the stylesheets (1.49) -- the newer 
stylesheets look a bit different.

Anyway, here is the PDF output I managed to generate:
 http://www.daa.com.au/~james/files/libegg-docs.pdf

If we wanted to use xmlto (or FO/passivetex directly) for PDF output, we 
will probably want to have some kind of customisation layer to make it a 
little more pretty.  This isn't a big deal, as I can still process my 
docs with a command like:
 xmllint --xinclude --valid -o libegg-docs2.xml libegg-docs.xml
 docbook2pdf libegg-docs2.xml

The Jade output looks like this:
 http://www.daa.com.au/~james/files/libegg-docs2.pdf

Hope this is useful to someone.

James.

--
Email: james daa com au              | Linux.conf.au 2003 Call for Papers out
WWW:   http://www.daa.com.au/~james/ |   http://conf.linux.org.au/cfp.html