3.3. Jade

Jade and OpenJade are two of the programs that do most of the rendering and validation of code based on the DTD and DSSSL. One of the following is required and should be installed after the DTD and DSSSL have been installed.

3.3.1. Jade

ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz

Jade is the front-end processor for SGML and XML. It uses the DSSSL and DocBook DTD to perform the verification and rendering from SGML and XML into the target format.

3.3.1.1. Using Jade

This is the quick and dirty way that should work for all distributions, no matter what one you are using.

  1. Create a base directory to store everything such as /usr/local/sgml/. We'll call this $_toolroot from here on.

  2. Install Jade, DocBook DTD, and DSSSL such that the base of each is under $_toolroot, creating:

    • $_toolroot/jade-1.2.1

    • $_toolroot/dtd

    • $_toolroot/dsssl

  3. You'll need to set the SGML_CATALOG_FILES environment variable to the catalogs that you have under$_toolroot. You can do this with the command:

    
bash$ export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\
    $_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog
                  

  4. Now you can start using Jade. To create individual HTML files:

    
$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \
    -d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml
                  
  5. To create one large HTML file, add -V nochunks to the jade command.

3.3.1.2. Jade in XML mode

Once configured for XML, jade and openjade will work the same way as for SGML DocBook.

After extracting the XML DTD, you will want to make a symlink from the docbook.cat file to "catalog", the default filename for jade/openjade catalogs. Replace $_xml_root with the location of your XML DTD.


bash$ cd $_xml_root
bash$ ln -s docbook.cat catalog
bash$ export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\
$_toolroot/dtd/docbook/catalog (1)
bash$ jade -t sgml -i html -d style $_jade_path/pubtext/xml.dcl foo.xml (2)
            
(1)
You'll need the catalogs for XML, the DSSSL, and DocBook, respectively. $_toolroot was defined above.
(2)
Replace style with the DSSSL (ldp.dsl) you wish to use. The pointer to xml.dcl is required for jade to work, and it has to be listed immediately before the pointer to your XML document. This file may be in a different directory. Check your distribution.

You may get the following warnings when processing XML documents. They don't impact the output, and the cause is being looked into.


<xml_dtd_pth>/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
<xml_dtd_pth>/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name
              

If you want to convert your existing SGML DocBook into XML docbook, use this as your declaration (the lines at the very start of your document).


<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'>
          

If you have followed LDP guidelines, there should be no other changes required to your document. Note that there are changes between DocBook 3.x and 4.x that you may also have to take into account. You can get more information at this in Section 2.4.2.

3.3.2. OpenJade

http://openjade.sourceforge.net/

An extension of Jade written by the DSSSL community. Some applications require jade, but are being updated to support either software package.