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.
$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.