Setting up the tools was the hardest part for me. The maze of catalogs, programs and acronyms is daunting to the first time (even technically minded) user. Never mind the miles of error message these tools generate, but I'll never cry RPM. I ran into a couple of snags with work arounds that I'll mention here.
First setup some handy environmental variables.
export SGMLHOME=/usr/local/sgml export DBARCHIVE=/where/you/put/your/source/downloads mkdir $SGMLHOME |
The only package that requires compiling is openjade. Openjade is a reasonable GNU autotools source build. Be sure to add openjade's lib directory to your library search path (ld.so.conf on Linux). Also, note that you have to manually copy the dsssl subdirectory as the install doesn't do it for you.
cd /usr/src
tar -xzf $DBARCHIVE/openjade-1.3.tar.gz
cd openjade-1.3
./configure --prefix=$SGMLHOME/openjade-1.3 && make && make install
cp -a dsssl $SGMLHOME/openjade-1.3
cd $SGMLHOME/openjade-1.3
mkdir lib
mv libo* lib
|
Next, you'll need to unpack all the DocTools DTDs and entities. Some of the entities need to be renamed from .ent to .gml. You can rename by hand or try my crazy one line script in your shell. Once they are all renamed, you'll get them into the 3.1sgml and 4.1sgml directories respectively . Some of the tidy people in the world like their catalog files called 'catalog'. It can't be a bad convention. So I symlinked mine.
gunzip $DBARCHIVE/iso-grk4.gml.gz
cd $SGMLHOME
mkdir docbook
cd docbook
mkdir 3.1sgml 4.1sgml 4.1.2xml
cd 3.1sgml
unzip -a $DBARCHIVE/docbk31.zip
unzip -a $DBARCHIVE/ISOEnts.zip
cp $DBARCHIVE/iso-grk4.gml .
ln -s docbook.cat catalog
cd ../4.1sgml/
unzip -a $DBARCHIVE/docbk41.zip
unzip -a $DBARCHIVE/ISOEnts.zip
cp $DBARCHIVE/iso-grk4.gml .
ln -s docbook.cat catalog
cd ../4.1.2xml/
unzip -a $DBARCHIVE/docbkx412.zip
ln -s docbook.cat catalog
mkdir /tmp/ents
cd /tmp/ents
tar -xzf $DBARCHIVE/isoENT-tar.gz
for i in `find . -type f`;do mv $i `echo $i | sed -e 's/.ent/.gml/g'`;done
cp * $SGMLHOME/docbook/3.1sgml/
cp * $SGMLHOME/docbook/4.1sgml/
|
Now, we're ready to unpack Norm Walsh's and the LDP's Styles Sheets. These are wonderfully straight forward.
cd $SGMLHOME
mkdir dsssl
cd dsssl
unzip -a $DBARCHIVE/db164.zip
cd docbook/
cp $DBARCHIVE/ldp.dsl html/
cp $DBARCHIVE/ldp.dsl print/
|
Then, well need to setup our SGML_CATALOG_FILES evironment variable. This is a list of files that openjade will use to find 'stuff'. I consolidated them all down to one file shown below. Once you get it set and working, I recommend making this a permanent fixture in your environment (.profile,.bashrc, etc.). Then when you want to change from 4.1.2 to 3.1 to compile other HOWTOS you just edit 'your' main catalog file.
export SGML_CATALOG_FILES=$SGMLHOME/catalog
|
$SGMLHOME/catalog (where /usr/local/sgml is my $SGMLHOME)
CATALOG "/usr/local/sgml/openjade-1.3/dsssl/catalog"
CATALOG "/usr/local/sgml/dsssl/docbook/catalog"
CATALOG "/usr/local/sgml/docbook/4.1sgml/catalog"
CATALOG "/usr/local/sgml/docbook/4.1.2xml/catalog"
SYSTEM "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" "docbook/4.1.2xml/docbookx.dtd"
|
The CATALOG entries list catalogs to look through. The SYSTEM entry maps the SYSTEM id, http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd to the DTD on our local system (also a SYSTEM id). I believe that this is because openjade/jade can't retrieve from URLs. Anybody have any input?
One quirk(?) of openjade is that it doesn't support DTDDECL in catalog files. Your error logs will contain LOTS of lines like this.
openjade:/usr/local/sgml/docbook/4.1sgml/catalog:22:0:W: DTDDECL catalog entries are not supported openjade:/usr/local/sgml/docbook/4.1sgml/catalog:22:0:W: DTDDECL catalog entries are not supported openjade:/usr/local/sgml/docbook/4.1sgml/catalog:22:0:W: DTDDECL catalog entries are not supported |
It is normal and acceptable, but there is a work around I've seen referenced. To remove this annoying message, Edit the Docbook SGML 4.1 catalog file. $SGMLHOME/docbook/4.1sgml/catalog. Comment out this line:
DTDDECL "-//OASIS//DTD DocBook V4.1//EN" "docbook.dcl" |
By adding two -- characters before and after as shown below. This comments out the line.
-- DTDDECL "-//OASIS//DTD DocBook V4.1//EN" "docbook.dcl" -- |
Make sure that you add $SGMLHOME/openjade-1.3/bin to your path and that you update your environment so that the loader can find the libraries located in $SGMLHOME/openjade-1.3/lib. I edited /etc/profile and /etc/ld.so.conf; YMMV.