926 lines
43 KiB
Plaintext
926 lines
43 KiB
Plaintext
DocBook XML/SGML Processing Using OpenJade
|
||
|
||
Saqib Ali
|
||
|
||
<saqib@seagate.com>
|
||
Revision History
|
||
Revision v2.2.8 2003-07-16 Revised by: es
|
||
Added info about keeping JREs up-to-date forCocoon
|
||
Revision v2.2.7 2003-07-09 Revised by: es
|
||
Fixed broken links to LDP XSL and other LDP XSL spefic filenames.
|
||
Revision v2.2.6 2003-06-16 Revised by: sa
|
||
Verified the instruction against docbook XSL 1.57.
|
||
Revision v2.2.5 2003-05-16 Revised by: sa
|
||
Fixed the broken links in the external resources section.
|
||
Revision v2.2.4 2003-04-20 Revised by: sa
|
||
Updated links to the new Demo Site. Added new links to the resources section.
|
||
Revision v2.2.3 2002-11-22 Revised by: sa
|
||
Added the suggestion made by users. Added new links to the resources section.
|
||
Revision v2.2.2 2002-10-09 Revised by: as
|
||
This update fixes a few more typos, removes a couple of spaces that make the
|
||
HTML rendering look odd.
|
||
Revision v2.2.1 2002-10-09 Revised by: sa
|
||
Fixed the URL to the Sample Files.
|
||
Revision v2.2 2002-09-29 Revised by: as
|
||
Minor corrections to the Cocoon section.
|
||
Revision v2.1 2002-09-15 Revised by: sa
|
||
Minor corrections to the Cocoon section.
|
||
Revision v2.0 2002-09-10 Revised by: sa
|
||
Added the section on serving DocBook XML 4.1.2 content using Tomcat + Cocoon.
|
||
Revision v1.5 2002-08-11 Revised by: sa
|
||
Added the XML section and the sample XML file.
|
||
Revision v1.4 2002-08-08 Revised by: sa
|
||
Many valuable modifications/corrections suggested by Lloyd D Budd. Thanks
|
||
Lloyd. :)
|
||
Revision v1.3 2002-08-02 Revised by: sa
|
||
Added the "Additional Resources" section.
|
||
Revision v1.2 2002-07-23 Revised by: sa
|
||
Added the section on converting HTML -> PDF using HTMLDOC. Thanks to Luc De
|
||
Louw for the suggestion.
|
||
Revision v1.1 2002-07-19 Revised by: KET
|
||
Fixed grammatical errors, numbered processes.
|
||
Revision v1.0 2002-06-29 Revised by: sa
|
||
Initial public release.
|
||
|
||
|
||
This HOWTO explains setting up OpenJade to process SGML/XML DocBook
|
||
documents.
|
||
|
||
-----------------------------------------------------------------------------
|
||
Table of Contents
|
||
1. Introduction
|
||
1.1. Copyright and License
|
||
1.2. Credits
|
||
1.3. What is DocBook?
|
||
1.4. What is DSSSL?
|
||
1.5. What do we need?
|
||
1.6. Assumptions
|
||
|
||
|
||
2. Requirements
|
||
2.1. Pre-requirements
|
||
2.2. OpenJade
|
||
2.3. DocBook DTDs
|
||
2.4. ISO Entities
|
||
2.5. Norman Walsh's DSSSL
|
||
2.6. LDP customized DSL stylesheets
|
||
2.7. HTMLDOC (Optional)
|
||
2.8. Norman Walsh's XSL (Optional)
|
||
2.9. LDP Customized XSL (Optional)
|
||
|
||
|
||
3. Installing Processing Tools - OpenJade
|
||
3.1. Installing OpenJade
|
||
3.2. Installing Norman Walsh's DSSSL
|
||
3.3. Installing DocBook DTDs
|
||
3.4. Installing the ISO Entities
|
||
3.5. Installing the LDP DSL
|
||
3.6. Installing HTMLDOC
|
||
|
||
|
||
4. Using OpenJade
|
||
4.1. Processing SGML
|
||
4.2. Processing XML
|
||
4.3. HTML to PDF (optional)
|
||
|
||
|
||
5. Serving DocBook 4.1.2 XML
|
||
5.1. Tomcat + Cocoon
|
||
5.2. Installing Norman Walsh's XSL
|
||
5.3. Installing LDP XSL
|
||
5.4. Setting up sitemap.xmap
|
||
5.5. Accessing DocBook 4.1.2 XML Content from a Web Browser
|
||
|
||
|
||
6. Further Information
|
||
6.1. News groups
|
||
6.2. Mailing Lists
|
||
6.3. IRC
|
||
6.4. Web Sites
|
||
6.5. XML Authoring / Modeling Applications
|
||
|
||
|
||
|
||
1. Introduction
|
||
|
||
Some Acronyms:
|
||
|
||
1. SGML - Standard Generalized Markup Language
|
||
|
||
2. XML - Extensible Markup Language
|
||
|
||
3. RTF - Rich Text Format
|
||
|
||
4. HTML - HyperText Markup Language
|
||
|
||
5. PDF - Portable Document Format
|
||
|
||
|
||
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).
|
||
-----------------------------------------------------------------------------
|
||
|
||
1.1. Copyright and License
|
||
|
||
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 [http://
|
||
www.gnu.org/copyleft/fdl.html] http://www.gnu.org/copyleft/fdl.html.
|
||
-----------------------------------------------------------------------------
|
||
|
||
1.2. Credits
|
||
|
||
All praise is due to Allah, The Lord of the Worlds. All credits go to Allah.
|
||
Any mistake in this document is my own fault.
|
||
|
||
Additionally, I would like to acknowledge the following people for their
|
||
valuable contributions to this document:
|
||
|
||
1. Eric Safern <esafern (at) lrn.com> - For updates related to Cocoon and
|
||
JRE. [http://www.timebytes.com/] http://www.timebytes.com/
|
||
|
||
2. Greg Ferguson <gferg (at) hoop.timonium.sgi.com> - for very helpful hints
|
||
/suggestions on the docbook mailing list
|
||
|
||
3. Kristin Thomas <kristint (at) us.ibm.com> - For the initial review of
|
||
this document.
|
||
|
||
4. Luc de Louw <luc (@) delouw.ch> - For suggesting the HTMLDOC (PDF ->
|
||
HTML) section.
|
||
|
||
5. Lloyd D Budd <ldp (@) foolswisdom.org> - For suggestions on improving
|
||
most of the sections of the document.
|
||
|
||
6. Andrew Shugg <andrew (@) neep.com.au> - For fixing errors in the ver 2.0
|
||
of this document. [http://www.neep.com.au/] Neep Consulting
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
1.3. What is DocBook?
|
||
|
||
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.
|
||
|
||
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.
|
||
-----------------------------------------------------------------------------
|
||
|
||
1.4. What is DSSSL?
|
||
|
||
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.
|
||
-----------------------------------------------------------------------------
|
||
|
||
1.5. What do we need?
|
||
|
||
The tools needed to set up OpenJade for converting SGML and XML are:
|
||
|
||
* OpenJade
|
||
|
||
* DocBook DTDs
|
||
|
||
* ISO Entities
|
||
|
||
* Norman Walsh's DSSSL
|
||
|
||
* LDP DSL
|
||
|
||
* HTMLDOC (optional)
|
||
|
||
* Norman Walsh's XSL (optional)
|
||
|
||
* LDP XSL (optional)
|
||
|
||
|
||
Note Note
|
||
All of these packages are free and available for download on the net.
|
||
The next chapter explains how to download these packages.
|
||
-----------------------------------------------------------------------------
|
||
|
||
1.6. Assumptions
|
||
|
||
This document assumes that you have the following already installed on your
|
||
system.
|
||
|
||
* gzip - available from [http://www.gnu.org/directory/] http://www.gnu.org/
|
||
directory/
|
||
|
||
* gcc and GNU make - available from [http://www.gnu.org/directory/] http://
|
||
www.gnu.org/directory/
|
||
|
||
* unzip - available from [http://www.info-zip.org/pub/infozip/] http://
|
||
www.info-zip.org/pub/infozip/
|
||
|
||
* Standard Unix utilities - tar, mkdir, mv ...
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
2. Requirements
|
||
|
||
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.
|
||
|
||
Most of the packages that we need are located at [http://www.tldp.org/authors
|
||
/index.html#resources] The Linux Documentation Project (TLDP) website.
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.1. Pre-requirements
|
||
|
||
Create a directory /tmp/downloads. We will use this directory to store the
|
||
downloaded source code.
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.2. OpenJade
|
||
|
||
OpenJade will be used to process DocBook documents. OpenJade can be
|
||
downloaded from: [http://openjade.sourceforge.net/] http://
|
||
openjade.sourceforge.net/.
|
||
|
||
At the time of writing this document OpenJade 1.3.1 was available. Download
|
||
the openjade-1.3.x.tar.gz file.
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.3. DocBook DTDs
|
||
|
||
All the DocBook DTDs are available from The Linux Documentation Project
|
||
website at [http://www.tldp.org/authors/index.html#resources] http://
|
||
www.tldp.org/authors/index.html#resources
|
||
|
||
Please download [http://www.tldp.org/authors/tools/docbk41.zip] DocBook SGML
|
||
v4.1, [http://www.tldp.org/authors/tools/docbk31.zip] DocBook SGML v3.1, and
|
||
[http://www.tldp.org/authors/tools/docbkx412.zip] DocBook XML v4.1.2.
|
||
|
||
Note Note
|
||
Please download all the zip archives.
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.4. ISO Entities
|
||
|
||
[http://www.tldp.org] The Linux Documentation Project has packaged all the
|
||
Entities into one big tar file and placed it at [http://www.tldp.org/authors/
|
||
tools/entities.tar.gz] http://www.tldp.org/authors/tools/entities.tar.gz for
|
||
the convenience of the users. Thanks to TLDP for this.
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.5. Norman Walsh's DSSSL
|
||
|
||
Norman Walsh's DSSSL can be downloaded from the DocBook project website at
|
||
[http://sourceforge.net/project/showfiles.php?group_id=21935] http://
|
||
sourceforge.net/project/showfiles.php?group_id=21935.
|
||
|
||
At the time of writing this document docbook-dsssl-1.7.6 was available.
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.6. LDP customized DSL stylesheets
|
||
|
||
LDP DSL is a customized style sheet used by [http://www.tldp.org] The Linux
|
||
Documentation Project (TLDP). It is an extension to Norman Walsh's DSSSL. It
|
||
add things like background and Table of Contents. It can be downloaded from
|
||
[http://www.tldp.org/authors/tools/ldp.dsl] http://www.tldp.org/authors/tools
|
||
/ldp.dsl.
|
||
|
||
ldp.dsl requires Normal Walsh's DSSSL
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.7. HTMLDOC (Optional)
|
||
|
||
HTMLDOC can be used for converting the HTML to PDF. If you would like to
|
||
produce PDF documents, please download HTMLDOC from [http://www.easysw.com/
|
||
htmldoc/software.php] http://www.easysw.com/htmldoc/software.php
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.8. Norman Walsh's XSL (Optional)
|
||
|
||
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.
|
||
|
||
The Style Sheets are available for download at [http://sourceforge.net/
|
||
projects/docbook/] http://sourceforge.net/projects/docbook/.
|
||
|
||
Please download the package called docbook-xsl.
|
||
|
||
Note Note
|
||
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 @ <saqib@seagate.com>
|
||
-----------------------------------------------------------------------------
|
||
|
||
2.9. LDP Customized XSL (Optional)
|
||
|
||
Also download the LDP Customized XSL from [http://my.core.com/~dhorton/
|
||
docbook/tldp-xsl/] http://my.core.com/~dhorton/docbook/tldp-xsl/
|
||
-----------------------------------------------------------------------------
|
||
|
||
3. Installing Processing Tools - OpenJade
|
||
|
||
In this section we will install all the tools in the appropriate directories.
|
||
All the tools go in the /usr/local/dbtools/ directory. Create this directory
|
||
using the following command:
|
||
# mkdir /usr/local/dbtools
|
||
-----------------------------------------------------------------------------
|
||
|
||
3.1. Installing OpenJade
|
||
|
||
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:
|
||
|
||
1. Change directories to /tmp/downloads.
|
||
# cd /tmp/downloads
|
||
|
||
|
||
2. Unzip the file.
|
||
# gzip -d openjade-1.3.x.tar.gz
|
||
|
||
|
||
3. Untar the file.
|
||
# tar -xvf openjade-1.3.x.tar
|
||
|
||
|
||
4. Change directories to openjade-1.3
|
||
# cd openjade-1.3.x
|
||
|
||
|
||
5. Run the ./configure command.
|
||
# ./configure --prefix=/usr/local/dbtools/openjade
|
||
|
||
|
||
6. Run the make command.
|
||
# make
|
||
|
||
|
||
7. Run the make install command. After this step the OpenJade binaries will
|
||
be installed under /usr/local/dbtools/openjade.
|
||
# make install
|
||
|
||
|
||
8. Copy the dsssl directory from /tmp/downloads/openjade-1.3.x to /usr/local
|
||
/dbtools/openjade
|
||
# cp -dpR dsssl /usr/local/dbtools/openjade/
|
||
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
3.2. Installing Norman Walsh's DSSSL
|
||
|
||
In this step we will install Norman Walsh's DSSSL in an appropriate place.
|
||
The DSSSL does not have to be compiled.
|
||
|
||
1. Change directories to /tmp/downloads
|
||
# cd /tmp/downloads
|
||
|
||
|
||
2. Unzip the file.
|
||
# gzip -d docbook-dsssl-1.76.tar.gz
|
||
|
||
|
||
3. Untar the file.
|
||
# tar -xvf docbook-dsssl-1.76.tar
|
||
|
||
|
||
4. Move the file to the /usr/local/dbtools/docbook-dsssl.
|
||
# mv docbook-dsssl-1.76 /usr/local/dbtools/docbook-dsssl
|
||
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
3.3. Installing DocBook DTDs
|
||
|
||
In this section we will install the DocBook DTDs.
|
||
|
||
1. Change directories to /usr/local/dbtools.
|
||
# cd /usr/local/dbtools
|
||
|
||
|
||
2. Create three new directories called dtd3.1, dtd4.1, and dtd4.1.2.
|
||
# mkdir dtd3.1
|
||
# mkdir dtd4.1
|
||
# mkdir dtd4.1.2
|
||
|
||
|
||
3. Change directories to the dtd3.1.
|
||
# cd dtd3.1
|
||
|
||
|
||
4. Unzip the file DocBook SGML v3.1 in this directory.
|
||
# unzip /tmp/downloads/docbk31.zip
|
||
|
||
|
||
5. Change directories to the dtd4.1.
|
||
# cd ../dtd4.1
|
||
|
||
|
||
6. Unzip the file DocBook SGML v4.1 in this directory.
|
||
# unzip /tmp/downloads/docbk41.zip
|
||
|
||
|
||
7. Change directories to the dtd4.1.2.
|
||
# cd ../dtd4.1.2
|
||
|
||
|
||
8. Unzip the file DocBook XML v4.1.2 in this directory.
|
||
# unzip /tmp/downloads/docbk412.zip
|
||
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
3.4. Installing the ISO Entities
|
||
|
||
In this section we will install the ISO entities that we downloaded from the
|
||
LDP website.
|
||
|
||
First we install the ISO Entities for the 3.1 SGML DTD.
|
||
|
||
1. Change directories to the /usr/local/dbtools/dtd3.1 directory.
|
||
# cd /usr/local/dbtools/dtd3.1
|
||
|
||
|
||
2. Copy /tmp/download/entities.tar.gz to this directory.
|
||
# cp /tmp/download/entities.tar.gz .
|
||
|
||
|
||
3. Unzip the file.
|
||
# gzip -d entities.tar.gz
|
||
|
||
|
||
4. Untar the file.
|
||
# tar -xvf entities.tar
|
||
|
||
|
||
|
||
Next we install the ISO Entities for the 4.1 SGML DTD.
|
||
|
||
1. Change directories to the /usr/local/dbtools/dtd4.1 directory.
|
||
# cd /usr/local/dbtools/dtd4.1
|
||
|
||
|
||
2. Copy /tmp/download/entities.tar.gz to this directory.
|
||
# cp /tmp/download/entities.tar.gz .
|
||
|
||
|
||
3. Unzip the file.
|
||
# gzip -d entities.tar.gz
|
||
|
||
|
||
4. Untar the file.
|
||
# tar -xvf entities.tar
|
||
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
3.5. Installing the LDP DSL
|
||
|
||
Finally we install the customised LDP stylesheet.
|
||
|
||
1. Change directories to the /tmp/download directory.
|
||
# cd /tmp/download
|
||
|
||
|
||
2. Copy the ldp.dsl file to the /usr/local/dbtools/docbook-dsssl/print/
|
||
ldp.dsl directory.
|
||
# cp ldp.dsl /usr/local/dbtools/docbook-dsssl/print/ldp.dsl
|
||
|
||
|
||
3. Copy the ldp.dsl file to the /usr/local/dbtools/docbook-dsssl/html/
|
||
ldp.dsl directory.
|
||
# cp ldp.dsl /usr/local/dbtools/docbook-dsssl/html/ldp.dsl
|
||
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
3.6. Installing HTMLDOC
|
||
|
||
This step is optional. It is only required if you want to produce PDF
|
||
documents from HTML.
|
||
|
||
Change back to the downloads directory.
|
||
# Change to /tmp/download directory
|
||
|
||
Untar the source code for HTMLDOC.
|
||
# gzip -d htmldoc-1.8.xx-source.tar.gz
|
||
# tar -xvf htmldoc-1.8.xx-source.tar
|
||
# cd htmldoc-1.8.xx-1
|
||
|
||
Run configure to set the installation location.
|
||
# ./configure --prefix=/usr/local/dbtools/htmldoc
|
||
# make
|
||
|
||
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.
|
||
|
||
Here is the error you will get while running make install:
|
||
# make install
|
||
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
|
||
|
||
|
||
To fix this installation issue, please edit fonts/Makefile and comment out
|
||
the lines with references to ZapfChancery and ZapfDingbats fonts.
|
||
|
||
Then execute the install:
|
||
# make install
|
||
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...
|
||
|
||
-----------------------------------------------------------------------------
|
||
|
||
4. Using OpenJade
|
||
|
||
In this section we will use OpenJade to convert DocBook SGML/XML documents to
|
||
HTML, RTF, and PDF.
|
||
-----------------------------------------------------------------------------
|
||
|
||
4.1. Processing SGML
|
||
|
||
4.1.1. Setting the SGML_CATALOG_FILES Environmental Variable for SGML
|
||
|
||
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:
|
||
# export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd3.1/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog
|
||
|
||
Use the following command for the C shell:
|
||
# setenv SGML_CATALOG_FILES /usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd3.1/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog
|
||
-----------------------------------------------------------------------------
|
||
|
||
4.1.2. SGML to HTML
|
||
|
||
To convert from SGML to HTML, use the following 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
|
||
|
||
To create a non-chunked (all in one) output:
|
||
# /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
|
||
-----------------------------------------------------------------------------
|
||
|
||
4.1.3. SGML to RTF
|
||
|
||
To convert from SGML to RTF, use the following 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
|
||
-----------------------------------------------------------------------------
|
||
|
||
4.2. Processing XML
|
||
|
||
You can download a sample DocBook 4.1.2 XML file from [http://
|
||
www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml] http://
|
||
www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml
|
||
-----------------------------------------------------------------------------
|
||
|
||
4.2.1. Setting the SGML_CATALOG_FILES Environmental Variable for XML
|
||
|
||
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:
|
||
# export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog
|
||
|
||
Use the following command for the C shell:
|
||
# setenv SGML_CATALOG_FILES /usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog
|
||
-----------------------------------------------------------------------------
|
||
|
||
4.2.2. XML to HTML
|
||
|
||
To convert from XML to HTML, use the following command:
|
||
# /usr/local/dbtools/openjade/bin/openjade -t xml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl DocBook-OpenJade-SGML-XML-HOWTO.xml
|
||
-----------------------------------------------------------------------------
|
||
|
||
4.2.3. XML to RTF
|
||
|
||
To convert from XML to HTML, use the following command:
|
||
# /usr/local/dbtools/openjade/bin/openjade -t rtf -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl DocBook-OpenJade-SGML-XML-HOWTO.xml
|
||
-----------------------------------------------------------------------------
|
||
|
||
4.3. HTML to PDF (optional)
|
||
|
||
To convert HTML to PDF we must use HTMLDOC. First create non-chunked HTML
|
||
output of the SGML:
|
||
# /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
|
||
|
||
Then run HTMLDOC to produce PDF.
|
||
# /usr/local/dbtools/htmldoc/bin/htmldoc -f outfile.pdf input.html
|
||
-----------------------------------------------------------------------------
|
||
|
||
5. Serving DocBook 4.1.2 XML
|
||
|
||
There are 3 ways to serve DocBook 4.1.2 XML from a web server:
|
||
|
||
* Command line Pre-processed Open Jade, XSLT
|
||
|
||
* Scripting - PHP, Perl, Python
|
||
|
||
* Application server - Tomcat + Cocoon
|
||
|
||
|
||
Using an application server like Cocoon is the best the option.
|
||
|
||
Note Cocoon in Action
|
||
To see an example of web server running Tomcat + Cocoon serving DocBook
|
||
4.1.2 XML content, please visit [http://www.xml-dev.com:8080/cocoon/
|
||
mount/docbook/] http://www.xml-dev.com:8080/cocoon/mount/docbook/
|
||
|
||
In this section we will see how to serve DocBook 4.1.2 XML content using
|
||
Tomcat + Cocoon.
|
||
-----------------------------------------------------------------------------
|
||
|
||
5.1. Tomcat + Cocoon
|
||
|
||
Tomcat is the Java Servlet Container. For more information please visit
|
||
[http://jakarta.apache.org/tomcat/index.html] http://jakarta.apache.org/
|
||
tomcat/index.html.
|
||
|
||
Apache Cocoon is an XML publishing framework. For more information please
|
||
visit [http://xml.apache.org/cocoon/index.html] http://xml.apache.org/cocoon/
|
||
index.html.
|
||
|
||
This HOWTO will not go into details of setting up Tomcat + Cocoon, since it
|
||
is already explained in the document [http://xml.apache.org/cocoon/installing
|
||
/index.html] http://xml.apache.org/cocoon/installing/index.html. Setting up
|
||
Tomcat + Cocoon is an easy process and should take less than five minutes.
|
||
|
||
Once you have the Cocoon + Tomcat setup and working, please follow the next
|
||
the sections to server DocBook 4.1.2 XML content.
|
||
|
||
Note 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.
|
||
|
||
At the very least, make sure you're using the latest JRE from Sun (at this
|
||
writing, 1.4.2).
|
||
|
||
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.
|
||
|
||
To check the version currently installed, type
|
||
# java org.apache.xalan.xslt.EnvironmentCheck
|
||
|
||
For more info, visit [http://xml.apache.org/xalan-j/faq.html] http://
|
||
xml.apache.org/xalan-j/faq.html .
|
||
-----------------------------------------------------------------------------
|
||
|
||
5.2. Installing Norman Walsh's XSL
|
||
|
||
In this step we will install the Norman Walsh's XSL under the /usr/local/
|
||
dbtools/ directory.
|
||
|
||
Change to the /tmp/downloads directory and untar the docbook-xsl file.
|
||
# cd /tmp/downloads/
|
||
# gzip -d docbook-xsl-1.53.0.tar.gz
|
||
# tar -xvf docbook-xsl-1.53.0.tar
|
||
|
||
To install the docbook-xsl please move the files to the /usr/local/dbtools.
|
||
# mv docbook-xsl-1.53.0 /usr/local/dbtool/docbook-xsl
|
||
|
||
Next install the LDP XSL.
|
||
-----------------------------------------------------------------------------
|
||
|
||
5.3. Installing LDP XSL
|
||
|
||
Unzip the tldp-xsl-xxxxx.tar.gz and the copy all the files to the /usr/local/
|
||
dbtools/docbook-xsl/html directory.
|
||
# cd /tmp/downloads
|
||
# gzip tldp-xsl-xxxxx.tar.gz
|
||
# gzip tldp-xsl-xxxxx.tar
|
||
# mv tldp-html*.xsl /usr/local/dbtools/docbook-xsl/html
|
||
-----------------------------------------------------------------------------
|
||
|
||
5.4. Setting up sitemap.xmap
|
||
|
||
$COCOON_HOME points to the Cocoon Web Application Directory. This directory
|
||
is typically /usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/
|
||
|
||
Create a directory named docbook under the $COCOON_HOME/mount. This is where
|
||
we will put all our DocBook XML 4.1.2 content.
|
||
# mkdir $COCOON_HOME/mount/docbook
|
||
|
||
Create a file name sitemap.xmap in the $COCOON_HOME/mount/docbook with the
|
||
following content:
|
||
# cd $COCOON_HOME/mount/docbook
|
||
# vi sitemap.xmap
|
||
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
|
||
|
||
<!-- use the standard components -->
|
||
<map:components>
|
||
<map:generators default="file"/>
|
||
<map:transformers default="xslt"/>
|
||
<map:readers default="resource"/>
|
||
<map:serializers default="html"/>
|
||
<map:selectors default="browser"/>
|
||
<map:matchers default="wildcard"/>
|
||
<map:transformers default="xslt"/>
|
||
</map:components>
|
||
|
||
<map:pipelines>
|
||
<map:pipeline>
|
||
|
||
<map:match pattern="">
|
||
<map:generate src="samples.xml"/>
|
||
<map:transform src="/usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/mount/editor/stylesheets/simple-page2html.xsl"/>
|
||
<map:serialize/>
|
||
</map:match>
|
||
|
||
<!-- respond to *.html requests with
|
||
our docs processed by .xsl -->
|
||
<map:match pattern="*.html">
|
||
<map:generate src="{1}.xml"/>
|
||
<map:transform src="/usr/local/dbtools/docbook-xsl/html/tldp-html.xsl"/>
|
||
<map:serialize type="html"/>
|
||
</map:match>
|
||
|
||
<!-- later, respond to *.pdf requests with
|
||
our docs processed by doc2pdf.xsl -->
|
||
<map:match pattern="*.pdf">
|
||
<map:generate src="{1}.xml"/>
|
||
<map:transform src="/usr/local/dbtools/docbook-xsl/fo/docbook.xsl"/>
|
||
<map:serialize type="fo2pdf"/>
|
||
</map:match>
|
||
|
||
<map:match pattern="*.xml">
|
||
<map:generate src="{1}.xml"/>
|
||
<map:serialize type="xml"/>
|
||
</map:match>
|
||
|
||
|
||
</map:pipeline>
|
||
</map:pipelines>
|
||
</map:sitemap>
|
||
-----------------------------------------------------------------------------
|
||
|
||
5.5. Accessing DocBook 4.1.2 XML Content from a Web Browser
|
||
|
||
Place a DocBook 4.1.2 XML file in the $COCOON_HOME/mount/docbook/ directory.
|
||
|
||
A sample file is available from [http://www.xml-dev.com:8080/cocoon/mount/
|
||
docbook/openjade.xml] http://www.xml-dev.com:8080/cocoon/mount/docbook/
|
||
openjade.xml.
|
||
|
||
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).
|
||
-----------------------------------------------------------------------------
|
||
|
||
6. Further Information
|
||
|
||
This section has some pointers to related resources on the Internet.
|
||
|
||
If you would like to suggest additional resources for this section, please
|
||
email me at <saqib@seagate.com>. Thanks.
|
||
-----------------------------------------------------------------------------
|
||
|
||
6.1. News groups
|
||
|
||
Some of the news groups of interest are:
|
||
|
||
1. comp.text.sgml (easily accessible from [http://groups.google.com/groups?
|
||
group=comp.text.sgml] Google! Groups)
|
||
|
||
2. comp.text.xml (easily accessible from [http://groups.google.com/groups?
|
||
group=comp.text.xml] Google! Groups)
|
||
|
||
3. htmldoc.general (server - [nttp://news.easysw.com] news.easysw.com)
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
6.2. Mailing Lists
|
||
|
||
Here are some relevant mailing lists.
|
||
|
||
1. DocBook mailing list @ OASIS. Visit [http://www.oasis-open.org/committees
|
||
/docbook/mailinglist/index.shtml] http://www.oasis-open.org/committees/
|
||
docbook/mailinglist/index.shtml for more info.
|
||
|
||
2. DocBook mailing list @ TLDP. Visit [http://www.tldp.org/mailinfo.html]
|
||
http://www.tldp.org/mailinfo.html for more info.
|
||
|
||
3. xml-doc @ Yahoo Groups. Visit [http://groups.yahoo.com/group/xml-doc/]
|
||
http://groups.yahoo.com/group/xml-doc/ for more info.
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
6.3. IRC
|
||
|
||
1. DocBook IRC Channel. #docbook on [irc://irc.openprojects.net] irc://
|
||
irc.openprojects.net
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
6.4. Web Sites
|
||
|
||
1. [http://www.oasis-open.org/] http://www.oasis-open.org/ OASIS maintains
|
||
various DocBook DTDs
|
||
|
||
2. [http://www.xml-dev.com/blog/] http://www.xml-dev.com/blog/ XML / XHTML
|
||
WebLog
|
||
|
||
3. [http://docbook.org/wiki/moin.cgi/] http://docbook.org/wiki/moin.cgi/ The
|
||
DocBook Wiki
|
||
|
||
4. [http://www.docbook.org/tdg/en/] http://www.docbook.org/tdg/en/ Online
|
||
version of DocBook: The Definitive Guide
|
||
|
||
5. [http://www.bureau-cornavin.com/opensource/crash-course/index.html] http:
|
||
//www.bureau-cornavin.com/opensource/crash-course/index.html Writing
|
||
Documentation Using DocBook: A Crash Course
|
||
|
||
6. [http://www-106.ibm.com/developerworks/library/l-docbk.html] http://
|
||
www-106.ibm.com/developerworks/library/l-docbk.html A gentle guide to
|
||
DocBook (very good introduction).
|
||
|
||
7. [http://www.tldp.org/LDP/LDP-Author-Guide/index.html] http://www.tldp.org
|
||
/LDP/LDP-Author-Guide/index.html The Linux Documentation Project (TLDP)
|
||
Author Guide
|
||
|
||
8. [http://www.tldp.org/authors/index.html#resources] http://www.tldp.org/
|
||
authors/index.html#resources DocBook resources provided by TLDP
|
||
|
||
9. [http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/] http://
|
||
www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/ Eric Raymond's DocBook
|
||
Demystification HOWTO
|
||
|
||
10. [http://www.xml-dev.com:8080/cocoon/mount/docbook/] http://
|
||
www.xml-dev.com:8080/cocoon/mount/docbook/Tomcat + Cocoon + DocBook Setup
|
||
Sample Site
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
6.5. XML Authoring / Modeling Applications
|
||
|
||
Note Note
|
||
A comprehensive list of XML editors can be found at [http://
|
||
www.xml-dev.com/blog/#19] http://www.xml-dev.com/blog/#19
|
||
|
||
1. eXchaNGeR - The XML Browser (and XML Editor)[http://xngr.org/] http://
|
||
xngr.org/
|
||
|
||
2. XERLIN - XML Modeling Application[http://www.xerlin.org/] http://
|
||
www.xerlin.org/
|
||
|
||
3. DocPro by Command Prompt, INC. [http://www.commandprompt.com/entry.lxp?
|
||
lxpe=2] http://www.commandprompt.com/entry.lxp?lxpe=2
|
||
|
||
4. YAWC Pro by XML Workshop LTD. [http://www.yawcpro.com/] http://
|
||
www.yawcpro.com/. Can be used for converting MS Word to Simple DocBook
|
||
XML.
|
||
|
||
5. Logictran RTF Converter. [http://www.logictran.com/] http://
|
||
www.logictran.com/. Word/RTF to HTML/XML.
|
||
|
||
6. MajiX - Word to XML converter. [http://tetrasys.dhs.org/] http://
|
||
tetrasys.dhs.org/
|
||
|
||
7. XMETAL by SoftQuad [http://www.softquad.com/] http://www.softquad.com/
|
||
|
||
8. Tagless Editor by i4i (DocBook DTD not supported) [http://www.i4i.com/]
|
||
http://www.i4i.com/
|
||
|
||
9. XML Editor by XMLmind [http://www.xmlmind.com/xmleditor/] http://
|
||
www.xmlmind.com/xmleditor/
|
||
|
||
10. upCast and downCast by Inifinity Loop [http://www.infinity-loop.de/en/
|
||
products.html] http://www.infinity-loop.de/en/products.html
|
||
|
||
11. W2XML by DocSoft[http://www.docsoft.com/w2xmlv2.htm] http://
|
||
www.docsoft.com/w2xmlv2.htm
|
||
|
||
12. XMLWrite by Wattle Software[http://xmlwriter.net/] http://xmlwriter.net/
|
||
|
||
13. oXygen XML Editor - Java Based[http://www.oxygenxml.com/] http://
|
||
www.oxygenxml.com/
|
||
|
||
14. Xeena by IBM[http://www.alphaworks.ibm.com/tech/xeena] http://
|
||
www.alphaworks.ibm.com/tech/xeena
|
||
|
||
15. Excosoft XML Client[http://www.excosoft.se/eweb/site/exc_pd.html] http://
|
||
www.excosoft.se/eweb/site/exc_pd.html
|
||
|
||
16. Timelux Xpress[http://www.timelux.lu/html/Xpress2001.html] http://
|
||
www.timelux.lu/html/Xpress2001.html
|
||
|
||
17. Morphon[http://www.morphon.com/] http://www.morphon.com/
|
||
|
||
18. Conglomerate[http://conglomerate.org/] http://conglomerate.org/
|
||
|
||
|