LDP/LDP/howto/docbook/DocBook-OpenJade-SGML-XML-HOWTO.sgml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<article>


<artheader>

   <title>DocBook XML/SGML Processing Using OpenJade</title>

   <author>
      <firstname>Saqib</firstname>
      <surname>Ali</surname>
      <affiliation>
         <address>
            <email>saqib@seagate.com</email>
         </address>
      </affiliation>
   </author>

   <revhistory>

      <revision>
         <revnumber>v1.2</revnumber>
         <date>2002-07-23</date>
         <authorinitials>sa</authorinitials>
          <revremark>
              Added the section on converting HTML -> PDF using HTMLDOC. Thanks to Luc De Louw for the suggestion.
         </revremark>
	</revision>

	<revision>
	 <revnumber>v1.1</revnumber>
	 <date><2002-07-19</date>
	 <authorinitials>KET</authorinitials>
	 <revremark>fixed grammatical errors, numbered processes</revremark>
      </revision>

      <revision>
         <revnumber>v1.0</revnumber>
         <date>2002-06-29</date>
         <authorinitials>sa</authorinitials>
          <revremark>
              Initial public release.
         </revremark>
	</revision>


   </revhistory>

   <abstract>
      <para>This HOWTO explains setting up OpenJade to process SGML/XML DocBook documents.</para> 
   </abstract>
</artheader>


<sect1 id="intro"><title>Introduction</title>

<para> The objective of this document is to setup OpenJade to convert DocBook 3.2 and 4.2 (SGML/XML) documents to HTML, RTF, and PDF.</para>



<sect2 id="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
<ulink url="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</ulink>
</para>
</sect2>

<sect2><title>What is DocBook?</title>

<para> 
DocBook is document type definition (DTD). DocBook is a commonly used DTD for writing technical documents. A DTD defines the syntax of a document, so DocBook is a definition of a syntax for writing documents. 
</para>

</sect2>

<sect2><title>What is DSSSL?</title>
<para>A Document Style Semantics and Specification Language (DSSSL)
defines how to convert an SGML document into a human-readable format.</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>Entities</para></listitem>
      <listitem><para>Norman Walsh's DSSSL</para></listitem>
      <listitem><para>DocBook DTDs</para></listitem>
      <listitem><para>LDP DSL</para></listitem>
   </itemizedlist>

<note><title>Note</title>
	<para>All of these packages are free and are available for
	download on the net. The next chapter explains how to download these packages.</para>
</note>

<para>
The only tool that you is compiled is OpenJade. The rest of the tools
have to be extracted and placed in the right directories.
</para>

</sect2>

<sect2><title>Assumptions</title>

<para> This document assumes that you have the following already
installed on  your system.  </para>

    <itemizedlist>
       <listitem><para>gzip or gunzip - available from <ulink url="http://www.gnu.org">http://www.gnu.org</ulink></para></listitem>
       <listitem><para>gcc and GNU make - available from <ulink url="http://www.gnu.org">http://www.gnu.org</ulink></para></listitem>
    </itemizedlist>
 
</sect2>

</sect1>


<sect1 id="requirements"><title>Requirements</title>
<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>

<sect2><title>Pre-requirements</title>

<para>
Create a directory <filename class="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:
<ulink url="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 DTD</title>
<para>All the DocBook DTDs are available from The Linux Documentation Project website at <ulink url="http://www.tldp.org/authors/index.html#resources">http://www.tldp.org/authors/index.html#resources</ulink></para>

<para>I use DocBook 3.1, so we will work with 3.1 in this
document. But you can download any or all of the DTDs.  
</para>

<note><title>Note</title>
	<para>Please download the whole zip archive.</para>
</note>

</sect2>

<sect2><title>ISO Entities</title>
<para>
<ulink url="http://www.tldp.org">The Linux Documentation Project</ulink> has packaged all the Entities into one big tar file and placed it at <ulink url="http://www.tldp.org/authors/index.html#resources">http://www.tldp.org/authors/index.html#resources</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 <ulink url="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 DSL</title>
<para>
The most important requirement is the ldp.dsl ;) It can be downloaded from <ulink url="http://www.tldp.org/authors/index.html#resources">http://www.tldp.org/authors/index.html#resources</ulink>.
</para>
</sect2>

<sect2><title>HTMLDOC</title>
<para>HTMLDOC can be used for converting the HTML to PDF. If you would like to produce PDF documents, please download HTMLDOC from
<ulink url="http://www.easysw.com/htmldoc/software.php">http://www.easysw.com/htmldoc/software.php</ulink>
</para>
</sect2>

</sect1>

<sect1 id="inst-openjade"> <title>Installing Processing Tools</title>
<para>In this section we will install all the tools in the appropriate
directories. All the tools go in the <filename
class="directory">/usr/local/dbtools/</filename> directory. Create
this directory using the following command:</para>
<screen>
<command>mkdir /usr/local/dbtools</command>
</screen>

<sect2><title>Installing OpenJade</title>
<para>This process is a 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 <filename
	class="directory">/tmp/downloads</filename>.
	</para>
	<screen>
	<command># cd /tmp/downloads</command>
	</screen>
	</listitem>
	<listitem>
	<para>Unzip the file.
	</para>
	<screen>
	<command># gzip -d openjade-1.3.x.tar.gz</command>
	</screen>
	</listitem>
	<listitem>
	<para>Untar the file.</para>
	<screen>
	<command># tar -xvf openjade-1.3.x.tar</command>
	</screen>
	</listitem>
	<listitem>
	<para>Change directories to <filename class="directory">openjade-1.3</filename></para>
	<screen>
	<command># cd openjade-1.3.x</command>
	</screen>
	</listitem>
	<listitem>
	<para>Run the <command>./configure</command> command.</para>
	<screen>
	<command># ./configure
	--prefix=/usr/local/dbtools/openjade</command>
	</screen>
	</listitem>
	<listitem>
	<para>Run the <command>make</command> command.</para>
	<screen>
	<command># make</command>
	</screen>
	</listitem>
	<listitem>
	<para>Run the <command>make install</command> command. After
	this step the openjade binaries will be installed under
	<filename class="directory">/usr/local/dbtools/openjade</filename>.</para>
	<screen>
	<command># make install</command>
	</screen>
	</listitem>
	<listitem>
	<para>Copy the <filename class="directory">dsssl</filename>
	directory from <filename
	class="directory">/tmp/downloads/openjade-1.3.x to
	/usr/local/dbtools/openjade</filename>
	</para>
	<screen>
	<command># cp -dpR dsssl /usr/local/dbtools/openjade/</command>
	</screen>
	</listitem>
</orderedlist>

</sect2>

<sect2><title>Installing Norman Walsh's DSSSL</title>

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

<orderedlist>
	<listitem>
	<para>Change directories to <filename class="directory">/tmp/downloads</filename></para>
	<screen>
	<command># cd /tmp/downloads</command>
	</screen>
	</listitem>
	<listitem>
	<para>Unzip the file.</para>
	<screen>
	<command># gzip -d docbook-dsssl-1.76.tar.gz</command>
	</screen>
	</listitem>
	<listitem>
	<para>Untar the file.</para>
	<screen>
	<command># tar -xvf docbook-dsssl-1.76.tar</command>
	</screen>
	</listitem>
	<listitem>
	<para>Move the file to the <filename
	class="directory">/usr/local/dbtools/docbook-dsssl</filename>.</para>
	<screen>
	<command># mv docbook-dsssl-1.76 /usr/local/dbtools/docbook-dsssl</command>
	</screen>
	</listitem>
</orderedlist>

</sect2>

<sect2><title>Installing DocBook DTDs</title>

<para>In this section we will install DocBook 3.1 (cause that is the
one that I use), but you can use whichever DTD you prefer. 
</para>

<orderedlist>
	<listitem>
	<para>Change directories to <filename class="directory">/usr/local/dbtools</filename>.</para>
	<screen>
	<command># cd /usr/local/dbtools</command>
	</screen>
	</listitem>
	<listitem>
	<para>Create a new directory called <filename
	class="directory">dtd3.1</filename>.</para>
	<screen>
	<command># mkdir dtd3.1</command>
	</screen>
	</listitem>
	<listitem>
	<para>Change directories to the new directory.</para>
	<screen>
	<command># cd dtd3.1</command>
	</screen>
	</listitem>
	<listitem>
	<para>Unzip the file.</para>
	<screen>
	<command># unzip /tmp/downloads/docbk31.zip</command>
	</screen>
	</listitem>
</orderedlist>

</sect2>

<sect2><title>Installing the ISO Entities</title>

<para>In this section we will install the ISO entities that we downloaded from the LDP website.</para>

<orderedlist>
	<listitem>
	<para>Change directories to the <filename
	class="directory">/usr/local/dbtools/dtd3.1</filename> directory.</para>
	<screen>
	<command># cd /usr/local/dbtools/dtd3.1</command>
	</screen>
	</listitem>
	<listitem>
	<para>Copy <filename>/tmp/download/entities.tar.gz</filename>
	to this directory.</para>
	<screen>
	<command># cp /tmp/download/entities.tar.gz .</command>
	</screen>
	</listitem>
	<listitem>
	<para>Unzip the file.</para>
	<screen>
	<command># gzip -d entities.tar.gz</command>
	</screen>
	</listitem>
	<listitem>
	<para>Untar the file.</para>
	<screen>
	<command># tar -xvf entities.tar</command>
	</screen>
	</listitem>
</orderedlist>

</sect2>

<sect2><title>Installing LDP DSL</title>
<para>Finally we install the ldp.dsl.</para>

<orderedlist>
	<listitem>
	<para>Change directories to the <filename
	class="directory">/tmp/download</filename> directory.</para>
	<screen>
	<command># cd /tmp/download </command>
	</screen>
	</listitem>
	<listitem>
	<para>Copy the <filename>ldp.dsl</filename> file to the
<filename class="directory">
/usr/local/dbtools/docbook-dsssl/print/ldp.dsl</filename>
directory.</para>
	<screen>
	<command># cp ldp.dsl
	/usr/local/dbtools/docbook-dsssl/print/ldp.dsl</command>
	</screen>
	</listitem>
	<listitem>
	<para>>Copy the <filename>ldp.dsl</filename> file to the
<filename class="directory">
/usr/local/dbtools/docbook-dsssl/html/ldp.dsl</filename>
directory.</para>
	<screen>
	<command># cp ldp.dsl /usr/local/dbtools/docbook-dsssl/html/ldp.dsl</command>
	</screen>
	</listitem>
</orderedlist>

</sect2>

<sect2><title>Installing HTMLDOC</title>
<para>This step is optional. It is only required if you want to produce PDF documents</para>
<para>Change back to the downloads directory<para>
<screen>
	<command># Change to /tmp/download directory</command>
</screen>
<para>Untar the source code for HTMLDOC</para>
<screen>
	<command># gzip -d htmldoc-1.8.xx-source.tar.gz </command>
	<command># tar -xvf htmldoc-1.8.xx-source.tar </command>
	<command># cd htmldoc-1.8.xx-1</command>
</screen>
<para>run configure to set the installation location</para>
<screen>
	<command># ./configure --prefix=/usr/local/dbtools/htmldoc</command>
	<command># make</command>
</screen>

<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...
Installing in data...
Installing in doc...
Installing in htmldoc...

</screen>



</sect2>



</sect1>
 


<sect1><title>Using OpenJade</title>

<para>In this section we will use OpenJade to convert SGML documents to HTML and RTF.</para>

<sect2><title>Setting the SGML_CATALOG_FILES Environmental Variable</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>
<screen>
<command># export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd3.1/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog</command>

</screen>
</sect2>

<sect2><title>SGML to HTML</title>

<para> 
To convert from SGML to HTML, use the following command:
</para>

<screen>
  <command># /usr/local/dbtools/openjade/bin/openjade -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml </command>
</screen>

<para>To create a non-chunked (all in one) output:
<screen>
  <command># /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 </command>
</screen>


</sect2>


<sect2><title>SGML to RTF</title>

<para> 
To convert from SGML to RTF, use the following command:
</para>

<screen>
  <command># /usr/local/dbtools/openjade/bin/openjade -t rtf -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print DocBook-OpenJade-SGML-XML-HOWTO.sgml </command>
</screen>

</sect2> 

<sect2><title>HTML to PDF</title>
<para>
To convert HTML to PDF we must use HTMLDOC. First create non-chunked HTML output of the SGML:</para>
<screen>
  <command># /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 </command>
</screen>

<para>The run HTMLDOC to produce PDF</para>
<screen>
	<command># /usr/local/dbtools/htmldoc/bin/htmldoc -f outfile.pdf input.html</command>
</screen> 
</sect2>


</sect1>


</article>