<para>This HOWTO explains setting up OpenJade to process SGML/XML DocBook documents.</para>
</abstract>
</articleinfo>
<sect1id="intro">
<title>Introduction</title>
<para>Some Acronyms:</para>
<orderedlist>
<listitem>
<para>SGML - Standard Generalized Markup Language</para>
</listitem>
<listitem>
<para>XML - Extensible Markup Language</para>
</listitem>
<listitem>
<para>RTF - Rich Text Format</para>
</listitem>
<listitem>
<para>HTML - HyperText Markup Language</para>
</listitem>
<listitem>
<para>PDF - Portable Document Format</para>
</listitem>
</orderedlist>
<para> The objective of this document is to setup OpenJade to convert DocBook 3.2 and 4.2 Standard Generalized Markup Language (SGML) and Extensible Markup Language (XML) documents to HyperText Markup Language (HTML), Rich Text Format (RTF), and Portable Document Format (PDF).</para>
<sect2id="copyright">
<title>Copyright and License</title>
<para> 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 <ulinkurl="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</ulink>. </para>
</sect2>
<sect2>
<title>Credits</title>
<para>All praise is due to <emphasisrole="strong"><emphasis></emphasis>Allah</emphasis>, <emphasisrole="strong">The Lord of the Worlds</emphasis>. All credits go to <emphasisrole="strong">Allah</emphasis>. Any mistake in this document is my own fault.</para>
<para>Additionally, I would like to acknowledge the following people for their valuable contributions to this document:</para>
<orderedlist>
<listitem>
<para> Eric Safern <email>esafern (at) lrn.com</email> - For updates related to Cocoon and JRE. <ulinkurl="http://www.timebytes.com/">http://www.timebytes.com/</ulink></para>
</listitem>
<listitem>
<para>Greg Ferguson <email>gferg (at) hoop.timonium.sgi.com</email> - for very helpful hints/suggestions on the docbook mailing list</para>
</listitem>
<listitem>
<para>Kristin Thomas <email>kristint (at) us.ibm.com</email> - For the initial review of this document.</para>
</listitem>
<listitem>
<para>Luc de Louw <email>luc (@) delouw.ch</email> - For suggesting the HTMLDOC (PDF -> HTML) section.</para>
</listitem>
<listitem>
<para>Lloyd D Budd <email>ldp (@) foolswisdom.org</email> - For suggestions on improving most of the sections of the document.</para>
</listitem>
<listitem>
<para>Andrew Shugg <email>andrew (@) neep.com.au</email> - For fixing errors in the ver 2.0 of this document. <ulinkurl="http://www.neep.com.au/">Neep Consulting</ulink></para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>What is DocBook?</title>
<para> 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. </para>
<para> 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. </para>
</sect2>
<sect2>
<title>What is DSSSL?</title>
<para>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.</para>
</sect2>
<sect2>
<title>What do we need?</title>
<para>The tools needed to set up OpenJade for converting SGML and XML are: </para>
<itemizedlist>
<listitem>
<para>OpenJade</para>
</listitem>
<listitem>
<para>DocBook DTDs</para>
</listitem>
<listitem>
<para>ISO Entities</para>
</listitem>
<listitem>
<para>Norman Walsh's DSSSL</para>
</listitem>
<listitem>
<para>LDP DSL</para>
</listitem>
<listitem>
<para>HTMLDOC (optional)</para>
</listitem>
<listitem>
<para>Norman Walsh's XSL (optional)</para>
</listitem>
<listitem>
<para>LDP XSL (optional)</para>
</listitem>
</itemizedlist>
<note>
<title>Note</title>
<para>All of these packages are free and available for download on the net. The next chapter explains how to download these packages.</para>
</note>
</sect2>
<sect2>
<title>Assumptions</title>
<para> This document assumes that you have the following already installed on your system. </para>
<itemizedlist>
<listitem>
<para>gzip - available from <ulinkurl="http://www.gnu.org/directory/">http://www.gnu.org/directory/</ulink></para>
</listitem>
<listitem>
<para>gcc and GNU make - available from <ulinkurl="http://www.gnu.org/directory/">http://www.gnu.org/directory/</ulink></para>
</listitem>
<listitem>
<para>unzip - available from <ulinkurl="http://www.info-zip.org/pub/infozip/">http://www.info-zip.org/pub/infozip/</ulink></para>
<para>You'll have to download and compile only one package (OpenJade). This HOWTO will explain the compilation process, but you should be familiar with installing from source code. </para>
<para>Most of the packages that we need are located at <ulinkurl="http://www.tldp.org/authors/index.html#resources">The Linux Documentation Project (TLDP)</ulink> website.</para>
<sect2>
<title>Pre-requirements</title>
<para> Create a directory <filenameclass="directory">/tmp/downloads</filename>. We will use this directory to store the downloaded source code. </para>
</sect2>
<sect2>
<title>OpenJade</title>
<para>OpenJade will be used to process DocBook documents. OpenJade can be downloaded from: <ulinkurl="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink>. </para>
<para>At the time of writing this document OpenJade 1.3.1 was available. Download the openjade-1.3.x.tar.gz file.</para>
</sect2>
<sect2>
<title>DocBook DTDs</title>
<para>All the DocBook DTDs are available from The Linux Documentation Project website at <ulinkurl="http://www.tldp.org/authors/index.html#resources">http://www.tldp.org/authors/index.html#resources</ulink></para>
<para>Please download <ulinkurl="http://www.tldp.org/authors/tools/docbk41.zip">DocBook SGML v4.1</ulink>, <ulinkurl="http://www.tldp.org/authors/tools/docbk31.zip">DocBook SGML v3.1</ulink>, and <ulinkurl="http://www.tldp.org/authors/tools/docbkx412.zip">DocBook XML v4.1.2</ulink>. </para>
<note>
<title>Note</title>
<para>Please download all the zip archives.</para>
</note>
</sect2>
<sect2>
<title>ISO Entities</title>
<para><ulinkurl="http://www.tldp.org">The Linux Documentation Project</ulink> has packaged all the Entities into one big tar file and placed it at <ulinkurl="http://www.tldp.org/authors/tools/entities.tar.gz">http://www.tldp.org/authors/tools/entities.tar.gz</ulink> for the convenience of the users. Thanks to TLDP for this. </para>
</sect2>
<sect2>
<title>Norman Walsh's DSSSL</title>
<para>Norman Walsh's DSSSL can be downloaded from the DocBook project website at <ulinkurl="http://sourceforge.net/project/showfiles.php?group_id=21935">http://sourceforge.net/project/showfiles.php?group_id=21935</ulink>. </para>
<para> At the time of writing this document docbook-dsssl-1.7.6 was available. </para>
</sect2>
<sect2>
<title> LDP customized DSL stylesheets</title>
<para> LDP DSL is a customized style sheet used by <ulinkurl="http://www.tldp.org">The Linux Documentation Project (TLDP)</ulink>. It is an extension to Norman Walsh's DSSSL. It add things like background and Table of Contents. It can be downloaded from <ulinkurl="http://www.tldp.org/authors/tools/ldp.dsl">http://www.tldp.org/authors/tools/ldp.dsl</ulink>. </para>
<para>ldp.dsl requires Normal Walsh's DSSSL</para>
</sect2>
<sect2>
<title>HTMLDOC (Optional)</title>
<para>HTMLDOC can be used for converting the HTML to PDF. If you would like to produce PDF documents, please download HTMLDOC from <ulinkurl="http://www.easysw.com/htmldoc/software.php">http://www.easysw.com/htmldoc/software.php</ulink></para>
</sect2>
<sect2>
<title>Norman Walsh's XSL (Optional)</title>
<para>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.</para>
<para>The Style Sheets are available for download at <ulinkurl="http://sourceforge.net/projects/docbook/">http://sourceforge.net/projects/docbook/</ulink>.</para>
<para>Please download the package called docbook-xsl.</para>
<para>Recently docbook-xsl ver. 1.57.0 was released. This document is verified with the latest version, and appropriate modifications have been made. If you still encounter any errors please email me @ <email>saqib@seagate.com</email></para>
<para>Also download the LDP Customized XSL from <ulinkurl="http://my.core.com/~dhorton/docbook/tldp-xsl/">http://my.core.com/~dhorton/docbook/tldp-xsl/</ulink></para>
<para>In this section we will install all the tools in the appropriate directories. All the tools go in the <filenameclass="directory">/usr/local/dbtools/</filename> directory. Create this directory using the following command:</para>
<para>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:</para>
<orderedlist>
<listitem>
<para>Change directories to <filenameclass="directory">/tmp/downloads</filename>. </para>
<para>Run the <command>make install</command> command. After this step the OpenJade binaries will be installed under <filenameclass="directory">/usr/local/dbtools/openjade</filename>.</para>
<para>Copy the <filenameclass="directory">dsssl</filename> directory from <filenameclass="directory">/tmp/downloads/openjade-1.3.x to /usr/local/dbtools/openjade</filename></para>
<para>Create three new directories called <filenameclass="directory">dtd3.1</filename>, <filenameclass="directory">dtd4.1</filename>, and <filenameclass="directory">dtd4.1.2</filename>.</para>
<para>Copy the <filename>ldp.dsl</filename> file to the <filenameclass="directory"> /usr/local/dbtools/docbook-dsssl/print/ldp.dsl</filename> directory.</para>
<para>Copy the <filename>ldp.dsl</filename> file to the <filenameclass="directory"> /usr/local/dbtools/docbook-dsssl/html/ldp.dsl</filename> directory.</para>
<para>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.</para>
<para>Here is the error you will get while running <command>make install</command>:</para>
<para> To fix this installation issue, please edit <filename>fonts/Makefile</filename> and comment out the lines with references to ZapfChancery and ZapfDingbats fonts.</para>
<para>In this section we will use OpenJade to convert DocBook SGML/XML documents to HTML, RTF, and PDF.</para>
<sect2>
<title>Processing SGML</title>
<sect3>
<title>Setting the SGML_CATALOG_FILES Environmental Variable for SGML</title>
<para>The SGML_CATALOG_FILES variable must be set to point to appropriate catalog files. To set the variable, use the following command for the Bourne shell:</para>
<para> You can download a sample DocBook 4.1.2 XML file from <ulinkurl="http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml">http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml</ulink></para>
<sect3>
<title>Setting the SGML_CATALOG_FILES Environmental Variable for XML</title>
<para>The SGML_CATALOG_FILES variable must be set to point to appropriate catalog files. To set the variable, use the following command for the Bourne shell:</para>
<para>There are 3 ways to serve DocBook 4.1.2 XML from a web server:</para>
<itemizedlist>
<listitem>
<para>Command line Pre-processed Open Jade, XSLT</para>
</listitem>
<listitem>
<para>Scripting - PHP, Perl, Python</para>
</listitem>
<listitem>
<para>Application server - Tomcat + Cocoon</para>
</listitem>
</itemizedlist>
<para>Using an application server like Cocoon is the best the option.</para>
<note>
<title>Cocoon in Action</title>
<para>To see an example of web server running Tomcat + Cocoon serving DocBook 4.1.2 XML content, please visit <ulinkurl="http://www.xml-dev.com:8080/cocoon/mount/docbook/">http://www.xml-dev.com:8080/cocoon/mount/docbook/</ulink></para>
</note>
<para> In this section we will see how to serve DocBook 4.1.2 XML content using Tomcat + Cocoon.</para>
<sect2>
<title>Tomcat + Cocoon</title>
<para>Tomcat is the Java Servlet Container. For more information please visit <ulinkurl="http://jakarta.apache.org/tomcat/index.html">http://jakarta.apache.org/tomcat/index.html</ulink>.</para>
<para>Apache Cocoon is an XML publishing framework. For more information please visit <ulinkurl="http://xml.apache.org/cocoon/index.html">http://xml.apache.org/cocoon/index.html</ulink>.</para>
<para>This HOWTO will not go into details of setting up Tomcat + Cocoon, since it is already explained in the document <ulinkurl="http://xml.apache.org/cocoon/installing/index.html">http://xml.apache.org/cocoon/installing/index.html</ulink>. Setting up Tomcat + Cocoon is an easy process and should take less than five minutes.</para>
<para>Once you have the Cocoon + Tomcat setup and working, please follow the next the sections to server DocBook 4.1.2 XML content.</para>
<note><para>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. </para></note>
<para><emphasis>At the very least, make sure you're using the latest JRE from Sun (at this writing, 1.4.2).</emphasis></para>
<para>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.</para>
<para>To check the version currently installed, type</para>
<para>Unzip the <filename>tldp-xsl-xxxxx.tar.gz</filename> and the copy all the files to the <filenameclass="directory">/usr/local/dbtools/docbook-xsl/html</filename> directory.</para>
<screen><command># cd /tmp/downloads</command></screen>
<para>$COCOON_HOME points to the Cocoon Web Application Directory. This directory is typically <filenameclass="directory">/usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/</filename></para>
<para>Create a directory named <filenameclass="directory">docbook</filename> under the <filenameclass="directory">$COCOON_HOME/mount</filename>. This is where we will put all our DocBook XML 4.1.2 content.</para>
<title>Accessing DocBook 4.1.2 XML Content from a Web Browser</title>
<para>Place a DocBook 4.1.2 XML file in the <filenameclass="directory">$COCOON_HOME/mount/docbook/</filename> directory.</para>
<para>A sample file is available from <ulinkurl="http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml">http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml</ulink>.</para>
<para>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).</para>
</sect2>
</sect1>
<sect1>
<title>Further Information</title>
<para>This section has some pointers to related resources on the Internet.</para>
<para> If you would like to suggest additional resources for this section, please email me at <email>saqib@seagate.com</email>. Thanks.</para>
<sect2>
<title>News groups</title>
<para>Some of the news groups of interest are:</para>
<orderedlist>
<listitem>
<para>comp.text.sgml (easily accessible from <ulinkurl="http://groups.google.com/groups?group=comp.text.sgml">Google! Groups</ulink>)</para>
</listitem>
<listitem>
<para>comp.text.xml (easily accessible from <ulinkurl="http://groups.google.com/groups?group=comp.text.xml">Google! Groups</ulink>)</para>
<para>Here are some relevant mailing lists.</para>
<orderedlist>
<listitem>
<para>DocBook mailing list @ OASIS. Visit <ulinkurl="http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml">http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml</ulink> for more info.</para>
</listitem>
<listitem>
<para>DocBook mailing list @ TLDP. Visit <ulinkurl="http://www.tldp.org/mailinfo.html">http://www.tldp.org/mailinfo.html</ulink> for more info.</para>
</listitem>
<listitem>
<para>xml-doc @ Yahoo Groups. Visit <ulinkurl="http://groups.yahoo.com/group/xml-doc/">http://groups.yahoo.com/group/xml-doc/</ulink> for more info.</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>IRC</title>
<orderedlist>
<listitem>
<para>DocBook IRC Channel. #docbook on <ulinkurl="irc://irc.openprojects.net">irc://irc.openprojects.net</ulink></para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>Web Sites</title>
<orderedlist>
<listitem>
<para><ulinkurl="http://www.oasis-open.org/">http://www.oasis-open.org/</ulink> OASIS maintains various DocBook DTDs</para>
</listitem>
<listitem>
<para><ulinkurl="http://www.xml-dev.com/blog/">http://www.xml-dev.com/blog/</ulink> XML / XHTML WebLog</para>
</listitem>
<listitem>
<para><ulinkurl="http://docbook.org/wiki/moin.cgi/">http://docbook.org/wiki/moin.cgi/</ulink> The DocBook Wiki</para>
</listitem>
<listitem>
<para><ulinkurl="http://www.docbook.org/tdg/en/">http://www.docbook.org/tdg/en/</ulink> Online version of DocBook: The Definitive Guide</para>
</listitem>
<listitem>
<para><ulinkurl="http://www.bureau-cornavin.com/opensource/crash-course/index.html">http://www.bureau-cornavin.com/opensource/crash-course/index.html</ulink> Writing Documentation Using DocBook: A Crash Course</para>
</listitem>
<listitem>
<para><ulinkurl="http://www-106.ibm.com/developerworks/library/l-docbk.html">http://www-106.ibm.com/developerworks/library/l-docbk.html</ulink> A gentle guide to DocBook (very good introduction).</para>
</listitem>
<listitem>
<para><ulinkurl="http://www.tldp.org/LDP/LDP-Author-Guide/index.html">http://www.tldp.org/LDP/LDP-Author-Guide/index.html</ulink> The Linux Documentation Project (TLDP) Author Guide</para>
</listitem>
<listitem>
<para><ulinkurl="http://www.tldp.org/authors/index.html#resources">http://www.tldp.org/authors/index.html#resources</ulink> DocBook resources provided by TLDP</para>
</listitem>
<listitem>
<para><ulinkurl="http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/">http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/</ulink> Eric Raymond's DocBook Demystification HOWTO</para>
<para><emphasisrole="strong">A comprehensive list of XML editors can be found at <ulinkurl="http://www.xml-dev.com/blog/#19">http://www.xml-dev.com/blog/#19</ulink></emphasis></para>
</note>
<orderedlist>
<listitem>
<para>eXchaNGeR - The XML Browser (and XML Editor)<ulinkurl="http://xngr.org/">http://xngr.org/</ulink></para>
</listitem>
<listitem>
<para>XERLIN - XML Modeling Application<ulinkurl="http://www.xerlin.org/">http://www.xerlin.org/</ulink></para>
</listitem>
<listitem>
<para>DocPro by Command Prompt, INC. <ulinkurl="http://www.commandprompt.com/entry.lxp?lxpe=2">http://www.commandprompt.com/entry.lxp?lxpe=2</ulink></para>
</listitem>
<listitem>
<para>YAWC Pro by XML Workshop LTD. <ulinkurl="http://www.yawcpro.com/">http://www.yawcpro.com/</ulink>. Can be used for converting MS Word to Simple DocBook XML. </para>
</listitem>
<listitem>
<para>Logictran RTF Converter. <ulinkurl="http://www.logictran.com/">http://www.logictran.com/</ulink>. Word/RTF to HTML/XML.</para>
</listitem>
<listitem>
<para>MajiX - Word to XML converter. <ulinkurl="http://tetrasys.dhs.org/">http://tetrasys.dhs.org/</ulink></para>
</listitem>
<listitem>
<para>XMETAL by SoftQuad <ulinkurl="http://www.softquad.com/">http://www.softquad.com/</ulink></para>
</listitem>
<listitem>
<para>Tagless Editor by i4i (DocBook DTD not supported) <ulinkurl="http://www.i4i.com/">http://www.i4i.com/</ulink></para>
</listitem>
<listitem>
<para>XML Editor by XMLmind <ulinkurl="http://www.xmlmind.com/xmleditor/">http://www.xmlmind.com/xmleditor/</ulink></para>
</listitem>
<listitem>
<para>upCast and downCast by Inifinity Loop <ulinkurl="http://www.infinity-loop.de/en/products.html">http://www.infinity-loop.de/en/products.html</ulink></para>
</listitem>
<listitem>
<para>W2XML by DocSoft<ulinkurl="http://www.docsoft.com/w2xmlv2.htm">http://www.docsoft.com/w2xmlv2.htm</ulink></para>
</listitem>
<listitem>
<para>XMLWrite by Wattle Software<ulinkurl="http://xmlwriter.net/">http://xmlwriter.net/</ulink></para>
</listitem>
<listitem>
<para>oXygen XML Editor - Java Based<ulinkurl="http://www.oxygenxml.com/">http://www.oxygenxml.com/</ulink></para>
</listitem>
<listitem>
<para>Xeena by IBM<ulinkurl="http://www.alphaworks.ibm.com/tech/xeena">http://www.alphaworks.ibm.com/tech/xeena</ulink></para>
</listitem>
<listitem>
<para>Excosoft XML Client<ulinkurl="http://www.excosoft.se/eweb/site/exc_pd.html">http://www.excosoft.se/eweb/site/exc_pd.html</ulink></para>