5. Serving DocBook 4.1.2 XML

There are 3 ways to serve DocBook 4.1.2 XML from a web server:

Command line Pre-processed Open Jade, XSLT
Scripting - PHP, Perl, Python
Application server - Tomcat + Cocoon

Using an application server like Cocoon is the best the option.

	Cocoon in Action
	To see an example of web server running Tomcat + Cocoon serving DocBook 4.1.2 XML content, please visit http://www.xml-dev.com:8080/cocoon/mount/docbook/

In this section we will see how to serve DocBook 4.1.2 XML content using Tomcat + Cocoon.

5.1. Tomcat + Cocoon

Tomcat is the Java Servlet Container. For more information please visit http://jakarta.apache.org/tomcat/index.html.

Apache Cocoon is an XML publishing framework. For more information please visit http://xml.apache.org/cocoon/index.html.

This HOWTO will not go into details of setting up Tomcat + Cocoon, since it is already explained in the document http://xml.apache.org/cocoon/installing/index.html. Setting up Tomcat + Cocoon is an easy process and should take less than five minutes.

Once you have the Cocoon + Tomcat setup and working, please follow the next the sections to server DocBook 4.1.2 XML content.

One important caveat: users in the field have experienced compatibility issues with the DocBook stylesheets and some versions of the Xalan XML parser. Xalan is the parser bundled with Sun's JRE, so that's what you're using by default.

At the very least, make sure you're using the latest JRE from Sun (at this writing, 1.4.2).

Also consider upgrading the Xalan parser to the latest release. At this writing, the latest Sun JRE, 1.4.2, is bundled with Xalan 2.4.1, while Xalan itself is up to version 2.5.1.

To check the version currently installed, type

 # java org.apache.xalan.xslt.EnvironmentCheck

For more info, visit http://xml.apache.org/xalan-j/faq.html .

5.2. Installing Norman Walsh's XSL

In this step we will install the Norman Walsh's XSL under the /usr/local/dbtools/ directory.

Change to the /tmp/downloads directory and untar the docbook-xsl file.

# cd /tmp/downloads/

# gzip -d docbook-xsl-1.53.0.tar.gz

# tar -xvf docbook-xsl-1.53.0.tar

To install the docbook-xsl please move the files to the /usr/local/dbtools.

# mv docbook-xsl-1.53.0 /usr/local/dbtool/docbook-xsl

Next install the LDP XSL.

5.3. Installing LDP XSL

Unzip the tldp-xsl-xxxxx.tar.gz and the copy all the files to the /usr/local/dbtools/docbook-xsl/html directory.

# cd /tmp/downloads

# gzip tldp-xsl-xxxxx.tar.gz

# gzip tldp-xsl-xxxxx.tar

# mv tldp-html*.xsl /usr/local/dbtools/docbook-xsl/html

5.4. Setting up sitemap.xmap

$COCOON_HOME points to the Cocoon Web Application Directory. This directory is typically /usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/

Create a directory named docbook under the $COCOON_HOME/mount. This is where we will put all our DocBook XML 4.1.2 content.

# mkdir $COCOON_HOME/mount/docbook

Create a file name sitemap.xmap in the $COCOON_HOME/mount/docbook with the following content:

# cd $COCOON_HOME/mount/docbook

# vi sitemap.xmap

<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

    <!-- use the standard components -->
    <map:components>
        <map:generators default="file"/>
        <map:transformers default="xslt"/>
        <map:readers default="resource"/>
        <map:serializers default="html"/>
        <map:selectors default="browser"/>
        <map:matchers default="wildcard"/>
        <map:transformers default="xslt"/>
    </map:components>
      
    <map:pipelines>
        <map:pipeline>

   <map:match pattern="">
    <map:generate src="samples.xml"/>
    <map:transform src="/usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/mount/editor/stylesheets/simple-page2html.xsl"/>
    <map:serialize/>
   </map:match>

            <!-- respond to *.html requests with 
                 our docs processed by .xsl -->
            <map:match pattern="*.html">
                <map:generate src="{1}.xml"/>
                <map:transform src="/usr/local/dbtools/docbook-xsl/html/tldp-html.xsl"/>
                <map:serialize type="html"/>
            </map:match>
            
            <!-- later, respond to *.pdf requests with 
                 our docs processed by doc2pdf.xsl -->
            <map:match pattern="*.pdf">
                <map:generate src="{1}.xml"/>
                <map:transform src="/usr/local/dbtools/docbook-xsl/fo/docbook.xsl"/>
                <map:serialize type="fo2pdf"/>
            </map:match>

            <map:match pattern="*.xml">
                <map:generate src="{1}.xml"/>
                <map:serialize type="xml"/>
            </map:match>


        </map:pipeline>
    </map:pipelines>
</map:sitemap>

5.5. Accessing DocBook 4.1.2 XML Content from a Web Browser

Place a DocBook 4.1.2 XML file in the $COCOON_HOME/mount/docbook/ directory.

A sample file is available from http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml.

Now you can access the document using a browser at http://localhost:8080/cocoon/mount/sample.html (HTML) or http://localhost:8080/cocoon/mount/sample.pdf (PDF).