Re: [xsl] Building a Manual with XML/XSL

Subject: Re: [xsl] Building a Manual with XML/XSL
From: S Woodside <sbwoodside@xxxxxxxxx>
Date: Sun, 7 Sep 2003 15:21:53 -0400

On Sunday, September 7, 2003, at 02:36 PM, Robert P. J. Day wrote:


On Sun, 7 Sep 2003, Antonio Gallardo wrote:

You can also use forrest:

http://xml.apache.org/forrest/

Antonio Gallardo

but forrest is for building web sites, not manuals. as for docbook,
i just went through the entire process of building a publishing
infrastructure based on XML, docbook, FOP and stylesheet customizations.

I use DocBook now for most of my writing on my site www.simonwoodside.com which runs on AxKit (also an apache project, www.axkit.org ) ... you can see an example at http://simonwoodside.com/dev/xml/alexandra/faq.html for example. If you go to the bottom, there's a link in gray Show docbook source which will pass the DocBook XML source right through inside a textarea instead of processing it.


The file is ".html" but actually it's a DocBook file with the following headers:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/xsl/docbook/local/dndbook.xsl" ?>
<?xml-stylesheet type="text/xsl" href="/xsl/docbook2page.xsl" ?>
<?xml-stylesheet type="text/xsl" href="/xsl/site.xsl" ?>


AxKit applies those stylesheets in sequential order. The first stylesheet is a wrapper for the DocBook XSLT by Normal Walsh. Here's what's in that file:

===================================================
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
                version='1.0'
                xmlns="http://www.w3.org/TR/xhtml1/transitional";
                exclude-result-prefixes="#default">

<xsl:import href="../xhtml/docbook.xsl"/>

<xsl:variable name="toc.section.depth">3</xsl:variable>
<xsl:param name="generate.toc">
appendix  toc,title
article/appendix  nop
article   toc,title,figure,table
book      toc,title,figure,table,example,equation
chapter   toc,title
part      toc,title
preface   toc,title
qandadiv  toc
qandaset  toc
reference toc,title
sect1     toc
sect2     toc
sect3     toc
sect4     toc
sect5     toc
section   toc
set       toc,title
</xsl:param>
<!-- Add other variable definitions here -->

</xsl:stylesheet>
===================================================

These are settings for the table of contents. The complete DocBook XSLT set to generate XHTML output is stored in /xsl/docbook/xhtml on the site. So the xsl:import loads up the whole shebang (and it's big ... ;-)

What follows is extensive processing by norman's XSLT and the output of that is an XHTML node-set. That's fed into the next stylesheet in the pipeline, /xsl/docbook2page.xsl which is written by me. I won't share this source code because it's kind of embarrasing ;-) but what it does it, it strips out all the norman-generated html headers because I don't want them. It just passes on the html body.

Finally the last stage in the pipeline is /xsl/site.xsl which takes the body of the html from the previous stage and wraps it up in ribbons and bows with my own site design. It adds the menu on the left, the header, the footer, an HTML header that links to my CSS files, sets the page title. That's the final product, which is output to the UA as HTML 4.01 transitional.


If it sounds like a lot of work, AxKit caches the result intelligently and serves up the cached version until the source file chnages. I hope people found that informative.


simon

--
www.simonwoodside.com :: www.openict.net :: www.semacode.org
                    99% Devil, 1% Angel


XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list



Current Thread