<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>
<para>Additionally, I would like to acknowledge following people for their valuable contributions to this document:</para>
<orderedlist>
<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 suggestions on 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>
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 verfy 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>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 DTD</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>
<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 server DocBook 4.1.2 XML content using Tomcat+Cocoon, you will need Normal Walsh's XML Style Sheets</para>
<para>The Style Sheeets are availabel 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>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>In this section we will install DocBook DTDs.
</para>
<orderedlist>
<listitem>
<para>Change directories to <filenameclass="directory">/usr/local/dbtools</filename>.</para>
<screen>
<command># cd /usr/local/dbtools</command>
</screen>
</listitem>
<listitem>
<para>Create a new directory called <filenameclass="directory">dtd3.1</filename><filenameclass="directory">dtd4.1</filename><filenameclass="directory">dtd4.1.2</filename>.</para>
<screen>
<command># mkdir dtd3.1</command>
<command># mkdir dtd4.1</command>
<command># mkdir dtd4.1.2</command>
</screen>
</listitem>
<listitem>
<para>Change directories to the <filenameclass="directory">dtd3.1</filename>.</para>
<screen>
<command># cd dtd3.1</command>
</screen>
</listitem>
<listitem>
<para>Unzip the file DocBook SGML v3.1 in this directory.</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>Here is the error you will get while running <command>make install</command></para>
<screen>
<command># make install</command>
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
</screen>
<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>Then execute the install:</para>
<screen>
<command># make install</command>
Making all in htmldoc...
Making all in doc...
Installing in fonts...
Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts...
<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:</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
catalog files. To set the variable, use the following command:</para>
<listitem><para>Application server - Cocoon</para></listitem>
</itemizedlist>
<para>Using a Application server like Cocoon is the best the option. In this section we will see how to serve DocBook 4.1.2 XML content using Cocoon+Tomcat</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 Cocoon+Tomcat, since it is already explained @ <ulinkurl="http://xml.apache.org/cocoon/installing/index.html">http://xml.apache.org/cocoon/installing/index.html</ulink>. Setting up Tomcat+Cocoon is a easy process and should take less than 5 mins.</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>
</sect2>
<sect2><title>Installing Norman Walsh's XSL</title>
<para>In this step we will install the Norman Walsh's XSL under the <filenameclass="directory">/usr/local/dbtools/</filename> directory.</para>
<para>Change to the <filenameclass="directory">/tmp/downloads</filename> directory and untar the docbook-xsl file.</para>
<screen><command># cd /tmp/downloads/</command></screen>
<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 direcotry 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 out DocBook XML 4.1.2 content.</para>
<sect2><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></para>
<para>A sample file is availble from <ulinkurl="http://docbook.sc-icc.org/sample.xml">http://docbook.sc-icc.org/sample.xml</ulink></para>
<para>Now you can access the document using a browser @ 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>
</orderedlist>
</sect2>
<sect2><title>IRC</title>
<orderedlist>
<listitem><para>DocBook IRC Channel. #docbook on irc://irc.openprojects.net</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.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-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>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>