This document is Copyright 2001 by Saqib Ali. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html.

All praise is due to Allah, The Lord of the Worlds. All credits go to Allah. Any mistake in this document is my own fault.

Additionally, I would like to acknowledge the following people for their valuable contributions to this document:

DocBook is a document type definition (DTD). A DTD defines the syntax of a document. DocBook describes the types of structure and formats to use in technical documents. It is commonly used because of its simplicity and completeness.

A DTD defines the syntax of a document - essentially it is a 'rule book' that describes the sets of tags and attributes that will be used to describe specific kinds of content. So DocBook is a "rule book" that is used for writing documents. Every tag that is used in writing the document, must be defined very specifically and formally in the DTD.

A Document Style Semantics and Specification Language (DSSSL) defines how to convert an Standard Generalized Markup Language (SGML) document into a human-readable viewing format such as HTML, RTF and PDF.

The tools needed to set up OpenJade for converting SGML and XML are:

This document assumes that you have the following already installed on your system.

Create a directory /tmp/downloads. We will use this directory to store the downloaded source code.

OpenJade will be used to process DocBook documents. OpenJade can be downloaded from: http://openjade.sourceforge.net/.

At the time of writing this document OpenJade 1.3.1 was available. Download the openjade-1.3.x.tar.gz file.

All the DocBook DTDs are available from The Linux Documentation Project website at http://www.tldp.org/authors/index.html#resources

Please download DocBook SGML v4.1, DocBook SGML v3.1, and DocBook XML v4.1.2.

The Linux Documentation Project has packaged all the Entities into one big tar file and placed it at http://www.tldp.org/authors/tools/entities.tar.gz for the convenience of the users. Thanks to TLDP for this.

Norman Walsh's DSSSL can be downloaded from the DocBook project website at http://sourceforge.net/project/showfiles.php?group_id=21935.

At the time of writing this document docbook-dsssl-1.7.6 was available.

LDP DSL is a customized style sheet used by The Linux Documentation Project (TLDP). It is an extension to Norman Walsh's DSSSL. It add things like background and Table of Contents. It can be downloaded from http://www.tldp.org/authors/tools/ldp.dsl.

ldp.dsl requires Normal Walsh's DSSSL

HTMLDOC can be used for converting the HTML to PDF. If you would like to produce PDF documents, please download HTMLDOC from http://www.easysw.com/htmldoc/software.php

This is not necessary. But if you would like to serve DocBook 4.1.2 XML content using Tomcat + Cocoon, you will need Norman Walsh's XML Style Sheets.

The Style Sheets are available for download at http://sourceforge.net/projects/docbook/.

Please download the package called docbook-xsl.

Also download the LDP Customized XSL from http://my.core.com/~dhorton/docbook/tldp-xsl/

This process is the easy part, but the most time consuming one too. Keep in mind that OpenJade take a long time to compile. To install OpenJade, complete the following steps:

In this step we will install Norman Walsh's DSSSL in an appropriate place. The DSSSL does not have to be compiled.

In this section we will install the DocBook DTDs.

In this section we will install the ISO entities that we downloaded from the LDP website.

First we install the ISO Entities for the 3.1 SGML DTD.

Next we install the ISO Entities for the 4.1 SGML DTD.

Finally we install the customised LDP stylesheet.

This step is optional. It is only required if you want to produce PDF documents from HTML.

Change back to the downloads directory.

	# Change to /tmp/download directory

Untar the source code for HTMLDOC.

	# gzip -d htmldoc-1.8.xx-source.tar.gz 
	# tar -xvf htmldoc-1.8.xx-source.tar 
	# cd htmldoc-1.8.xx-1

Run configure to set the installation location.

	# ./configure --prefix=/usr/local/dbtools/htmldoc
	# make

At the time of writing this document HTMLDOC ver 1.8.20-1 was available. This version had a little problem in the fonts Makefile. It would complain while installing the fonts, because the correct fonts were not available on the system.

Here is the error you will get while running make install:

	# make install
Making all in htmldoc...
Making all in doc...
Installing in fonts...
Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts...
/bin/cp: cannot stat `ZapfChancery.afm': No such file or directory
/bin/cp: cannot stat `ZapfChancery.pfa': No such file or directory
/bin/cp: cannot stat `ZapfDingbats.afm': No such file or directory
/bin/cp: cannot stat `ZapfDingbats.pfa': No such file or directory
make[1]: *** [install] Error 1

To fix this installation issue, please edit fonts/Makefile and comment out the lines with references to ZapfChancery and ZapfDingbats fonts.

Then execute the install:

# make install
Making all in htmldoc...
Making all in doc...
Installing in fonts...
Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts...
Installing in data...
Installing in doc...
Installing in htmldoc...

You can download a sample DocBook 4.1.2 XML file from http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml

# export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

# setenv SGML_CATALOG_FILES /usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

# /usr/local/dbtools/openjade/bin/openjade -t xml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl DocBook-OpenJade-SGML-XML-HOWTO.xml

# /usr/local/dbtools/openjade/bin/openjade -t rtf -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl DocBook-OpenJade-SGML-XML-HOWTO.xml

To convert HTML to PDF we must use HTMLDOC. First create non-chunked HTML output of the SGML:

# /usr/local/dbtools/openjade/bin/openjade -V nochunks -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml 

Then run HTMLDOC to produce PDF.

# /usr/local/dbtools/htmldoc/bin/htmldoc -f outfile.pdf input.html

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.

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 .

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.

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

$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>

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).

Some of the news groups of interest are:

Here are some relevant mailing lists.