<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>
<para>All praise is due to <emphasisrole="strong">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>
<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>
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>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>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>
<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>
<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>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.
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>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 has not been tested with 1.5.7. But there should not be any issues. If you run into any issue with docbook-xsl and this document, please email me @ <email>saqib@seagate.com</email></para>
<para>Also download the LDP Customized XSL from <ulinkurl="http://www.tldp.org/authors/tools/ldp-xsl.zip">http://www.tldp.org/authors/tools/ldp-xsl.zip</ulink></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>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> 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> You can download a sample DocBook 3.1 SGML file from <ulinkurl="http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.sgml">http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.sgml</ulink></para>
<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://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.xml">http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.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
<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.sc-icc.org:8080/cocoon/mount/docbook/">http://www.sc-icc.org: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>
<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>Unzip the <filename>ldp-xs.zip</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>
<para>A sample file is available from <ulinkurl="http://www.sc-icc.org:8080/cocoon/mount/docbook/openjade.xml">http://www.sc-icc.org: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>
<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>
<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></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>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>