LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity
LDP/LDP/howto/docbook/DocBook-OpenJade-SGML-XML-H...

619 lines
20 KiB
Plaintext
Raw Normal View History

updated
2002-08-05 21:41:53 +00:00
<!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.3</revnumber>
<date>2002-08-02</date>
<authorinitials>sa</authorinitials>
<revremark>
Added the "Additional Reseources" section.
</revremark>
</revision>
<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 - 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>
</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>Please download DocBook SGML v4.1, DocBook SGML v3.1, and DocBook XML v4.1.2
</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 DTDs.
</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> <filename class="directory">dtd4.1</filename> <filename class="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 <filename class="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>
<screen>
<command># unzip /tmp/downloads/docbk31.zip</command>
</screen>
</listitem>
<listitem>
<para>Change directories to the <filename class="directory">dtd4.1</filename>.</para>
<screen>
<command># cd ../dtd4.1</command>
</screen>
</listitem>
<listitem>
<para>Unzip the file DocBook SGML v4.1 in this directory.</para>
<screen>
<command># unzip /tmp/downloads/docbk41.zip</command>
</screen>
</listitem>
<listitem>
<para>Change directories to the <filename class="directory">dtd4.1.2</filename>.</para>
<screen>
<command># cd ../dtd4.1.2</command>
</screen>
</listitem>
<listitem>
<para>Unzip the file DocBook SGML v4.1.2 in this directory.</para>
<screen>
<command># unzip /tmp/downloads/docbk412.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, RTF, and PDF.</para><para> You can download a sample DocBook 3.1 SGML file from <ulink url="http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.sgml">http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.sgml</ulink></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>Then run HTMLDOC to produce PDF</para>
<screen>
<command># /usr/local/dbtools/htmldoc/bin/htmldoc -f outfile.pdf input.html</command>
</screen>
</sect2>
</sect1>
<sect1><Title>Further Information</Title>
<para>This section has some pointers to the related resource on the internet.</para>
<para> If you would like to suggest additional resource for this section, please email me @ <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 <ulink url="http://www.deja.com">http://www.deja.com</ulink>)</para></listitem>
<listitem><para>comp.text.xml (easily accessible from <ulink url="http://www.deja.com">http://www.deja.com</ulink>)</para></listitem>
<listitem><para>htmldoc.general (server - nttp://news.easysw.com)</para></listitem>
</orderedlist>
</sect2>
<sect2><title>Mailing Lists</title>
<para>Here are some relevant Mailing Lists</para>
<orderedlist>
<listitem><para>DocBook mailing list @ OASIS. Visit <ulink url="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 <ulink url="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 <ulink url="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><ulink url="http://www.oasis-open.org/">http://www.oasis-open.org/</ulink> OASIS maintains various DocBook DTDs</para></listitem>
<listitem><para><ulink url="http://docbook.org/wiki/moin.cgi/">http://docbook.org/wiki/moin.cgi/</ulink>The DocBook Wiki</para></listitem>
<listitem><para><ulink url="http://www.docbook.org/tdg/en/">http://www.docbook.org/tdg/en/</ulink>Online version of DocBook: The Definitive Guide</para></listitem>
<listitem><para><ulink url="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>
</orderedlist>
</sect2>
<sect2><title>Commercial Tools</title>
<orderedlist>
<listitem><para>DocPro by Command Prompt, INC. <ulink url="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. <ulink url="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. <ulink url="http://www.logictran.com/">http://www.logictran.com/</ulink>. Word/RTF to HTML/XML</para></listitem>
<listitem><para>MajiX - Word to XML converter. <ulink url="http://tetrasys.dhs.org/">http://tetrasys.dhs.org/</ulink>
<listitem><para>XMETAL by SoftQuad <ulink url="http://www.softquad.com/">http://www.softquad.com/</ulink> </para></listitem>
</orderedlist>
</sect2>
</sect1>
</article>