926 lines
43 KiB
Plaintext
926 lines
43 KiB
Plaintext
|
DocBook XML/SGML Processing Using OpenJade
|
|||
|
|
|||
|
Saqib Ali
|
|||
|
|
|||
|
<EFBFBD><saqib@seagate.com><3E>
|
|||
|
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:
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>OpenJade
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>DocBook DTDs
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>ISO Entities
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>Norman Walsh's DSSSL
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>LDP DSL
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>HTMLDOC (optional)
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>Norman Walsh's XSL (optional)
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>LDP XSL (optional)
|
|||
|
|
|||
|
|
|||
|
Note Note
|
|||
|
<EFBFBD> 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.
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>gzip - available from [http://www.gnu.org/directory/] http://www.gnu.org/
|
|||
|
directory/
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>gcc and GNU make - available from [http://www.gnu.org/directory/] http://
|
|||
|
www.gnu.org/directory/
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>unzip - available from [http://www.info-zip.org/pub/infozip/] http://
|
|||
|
www.info-zip.org/pub/infozip/
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>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
|
|||
|
<EFBFBD> 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
|
|||
|
<EFBFBD> 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:
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>Command line Pre-processed Open Jade, XSLT
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>Scripting - PHP, Perl, Python
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>Application server - Tomcat + Cocoon
|
|||
|
|
|||
|
|
|||
|
Using an application server like Cocoon is the best the option.
|
|||
|
|
|||
|
Note Cocoon in Action
|
|||
|
<EFBFBD> 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
|
|||
|
<EFBFBD> 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/
|
|||
|
|
|||
|
|