The Open
Group Research Institute
This document describes the procedure to setup a coherent environment on a Unix machine, that enables one to verify SGML documents based on the DocBook DTD and convert them into something viewable or printable.
It lists the required tools to achieve this goal and their installation procedure so that they all integrate smoothly and finally work together seamlessly.
At least three packages have been identified as mandatory to be able to use DocBook:
The DocBook DTD comes as a set of SGML declaration files which can be installed almost anywhere.
You also have to install the ISO entities by unpacking the Zip file in the same directory. While doing so, You have to change their file names from ISOxxx to iso-xxx.gml using a script like:
for i in ISO*; do
mv $i `echo $i | sed 's/ISO/iso-/'`.gml
doneFinally, the last step to DocBook installation consists in editing the docbook.cat catalog file so that it is compliant with Jade which does not accept the DTDDECL construct. I've simply replaced the line:
DTDDECL "-//Davenport//DTD DocBook V3.0//EN" "docbook.dcl"
with:
SGMLDECL docbook.dcl
Note somewhere the path to your DocBook installation [DOCBOOKDIR].
The Jade distribution comes as a Zip file which unpacks itself in the current directory. I've created a new directory into which I've unpacked the Jade distribution.
Installing Jade is rather straightforward, except that you may have to remove any trailing ^M characters at the end of each line in each file if you install on a Unix system. From the directory where I unpacked the Jade distribution, I do this using the following commands:
find . -type f | xargs perl -pi.bak -e "s/^M//" find . -name "*.bak" | xargs rm -f
Now you just have to edit the Makefile to reflect your installation preferences and platform specificities. Then just run make and make install.
When Jade installs itself, it just copies its executable files into a specific directory for which you specified the root directory in the Makefile. I've installed additional files so that I could finally remove the whole source distribution and still have all the files I might need. Here are the directories I've copied: doc, jadedoc, pubtext and dsssl. At the end of the installation, the root directory where I've decided to put Jade contains:
% ls /afs/gr/project/adl2/tools/jade/ bin/ doc/ dsssl/ jadedoc/ pubtext/
Note somewhere the root directory of your Jade installation [JADEDIR].
The Modular DocBook Stylesheets distribution usually comes as a Zip file. When it is unpacked, a bocbook directory is created which contains all the stylesheets.
To install the stylesheets on a Unix system, you first have to remove any trailing ^M characters at the end of each line in each file. From the docbook directlry where the stylesheets were unpacked, I do this with this simple command:
find . -type f | xargs perl -pi.bak -e "s/^M//" find . -name "*.bak" | xargs rm -f
I've installed the stylesheets in the stylesheets subdirectory of the installation directory of the DocBook DTD itself:
mkdir $DOCBOOKDIR/stylesheets cp -r docbook/* $DOCBOOKDIR/stylesheets
Now that all the required tools have been installed, you can start using them. For instance, you can issue a command like:
SGML_CATALOG_FILES=$DOCBOOKDIR/docbook.cat:$JADEDIR/dsssl/catalog \ jade -t sgml -i html -d $DOCBOOKDIR/stylesheets/html/docbook.dsl \ sample.sgml
This command will create an HTML file (with suffix .htm by default).
Of course, since this is quite heavy and hard to remember, you should better create a script that will allow you to simply do db2html sample.sgml.
The following shell script can be used for instance as a db2htmlscript:
#!/bin/sh DOCBOOKDIR=<path to your DocBook DTD installation directory> JADEDIR=<path to your Jade installation directory> STYLE=$DOCBOOKDIR/stylesheets/html/docbook.dsl SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$DOCBOOKDIR/docbook.cat SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADEDIR/dsssl/catalog export SGML_CATALOG_FILES while [ $# -gt 0 ]; do $JADEDIR/bin/jade -t sgml -i html -d $STYLE $1 shift done
Obviously this is a base script that you can complexify as wanted to make it fancier, especially with respect to customization.
On the same vein, you can create a db2rtf script that would convert your SGML files to Rich Text Format. Here is an example of such a script:
#!/bin/sh DOCBOOKDIR=<path to your DocBook DTD installation directory> JADEDIR=<path to your Jade installation directory> STYLE=$DOCBOOKDIR/stylesheets/print/docbook.dsl SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$DOCBOOKDIR/docbook.cat SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADEDIR/dsssl/catalog export SGML_CATALOG_FILES while [ $# -gt 0 ]; do $JADEDIR/bin/jade -t rtf -d $STYLE $1 shift done
There are several things that can be done to customize the current stylesheets. These customizations are available as DSSSL variables that can be set to different values. These variables are described at http://nwalsh.com/docbook/dsssl/doc/custom.html for both available stylesheets (html and print).
Since they are DSSSL variables, they must be set in a DSSSL file. But instead of modifying the stylesheets you've just installed, you'd better create your own driver to the Modular DocBook Stylesheets.
By the way, you would certainly like to group in one place the customizations for both the html and print stylesheets.
I've done all this by creating a file named docbook-both.dsl in the $DOCBOOKDIR/stylesheets directory, which contains the following:
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!ENTITY % html "IGNORE"> <![%html;[ <!ENTITY % print "IGNORE"> <!ENTITY docbook.dsl SYSTEM "html/docbook.dsl" CDATA dsssl> ]]> <!ENTITY % print "INCLUDE"> <![%print;[ <!ENTITY docbook.dsl SYSTEM "print/docbook.dsl" CDATA dsssl> ]]> ]> <style-sheet> <style-specification id="print" use="docbook"> <style-specification-body> ;; customize the print stylesheet (define %paper-type% ;; Name of paper type "A4") (define %two-side% #t) (define %section-autolabel% ;; Are sections enumerated? #t) (define %visual-acuity% ;; General measure of document text size "presbyopic") </style-specification-body> </style-specification> <style-specification id="html" use="docbook"> <style-specification-body> ;; customize the html stylesheet (define %html-ext% ".html") (define %body-attr% ;; What attributes should be hung off of BODY? (list (list "BGCOLOR" "#FFFFFF"))) (define %shade-verbatim% #t) (define %use-id-as-filename% ;; Use ID attributes as name for component HTML files? #t) (define %graphic-default-extension% "gif") </style-specification-body> </style-specification> <external-specification id="docbook" document="docbook.dsl"> </style-sheet>
This sample driver redefines some parameters such as the paper type in the print stylesheet: variable %paper-type%, or the html file extension in the html stylesheet: variable %html-ext%.
Note that now that we have created a single driver for both stylesheets, our scripts have to be updated to use this driver. Apart from changing the variable which references the stylesheet so that it now refers to the created driver, I have replaced the line that reads:
$JADEDIR/bin/jade -t sgml -i html -d $STYLE $1
with the following line:
$JADEDIR/bin/jade -t sgml -i html -d $STYLE\#html $1
Obviously, for the second script, the modification is identical except that you use \#print instead of \#html.
The procedure to setup a usable SGML/DocBook environment was so painful that I had to write this document. However the good news is that we will hopefully not have to do this manually for long. The light will come again from the Linux world and the Linux Documentation Project. The guys there who are developing the next generation of SGML-tools are automating this procedure so that it can be put in a RPM package specification. One day, the only thing you will have to do to install DocBook and its companion tools could be (the name of the RPM package is still unknown):
rpm -i docbook-3.0-1.i386.rpm
But that day, you will have to be using a Linux machine...;-)
Last modified: Wed Apr 22 16:17:36 MET DST 1998