[Fwd: docbook/xml -> PDF]

[John Fleck <jfleck inkstain net>]

Thought this might be of use.
Cheers,
John
-- 
John Fleck
jfleck inkstain net (h) jfleck abqjournal com (w)
http://www.inkstain.net http://www.abqjournal.com

"Sometimes, a diner is all about the mac and cheese." 
  - Zippy the Pinhead

--- Begin Message ---

• From: James Henstridge <james daa com au>
• To: gtk-doc-list gnome org
• Subject: docbook/xml -> PDF
• Date: Fri, 28 Jun 2002 10:05:54 +0800

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



_______________________________________________
gtk-doc-list mailing list
gtk-doc-list gnome org
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

--- End Message ---