[PATCH] and [HOWTO] Compile documentation on OSX Leopard

Hi,

Ok, after much struggling, I've finally succeded into compiling Kannel docs
on OSX Leopard.

I've found numerous problems along the way, some of them related to the
outdated DocBook version being used on Kannel source (3.1, circa 1999.
Current is 4.5 and 5.0 is already on the way) and also to the fact that
"jade" was being used. Jade project is dead and OpenJade has continued the
effort with a compatible binary, but Kannel didn't recognized it as a jade
replacement.

*Step 1: Patch configure.in.
*
I've made some changes on configure.in to look into proper MacPorts places
for the dsl files, and also to look for OpenJade if jade is not found.

After applying, autoconf must be run to rebuild ./configure

Here's the patch:

http://www.magicom-bcn.net/kannel/docbook-leopard-20080918.patch

This patch doesn't break anything on other platforms (I think! :D ), so it
should be safe to apply even on other platforms. It just search for stuff on
a couple more places before giving up.

*Step 2: Install required MacPorts:
*
You need at least this ones (I hope I'm not forgetting anything. I'm
probably adding some that are not really required as well):

ImageMagick
docbook-dsssl
docbook-xml
docbook-xsl
openjade
texi2html
texinfo
texlive
texlive_base
texlive_texmf-full
texlive_texmf-minimal
render
xmlcatmgr
transfig
psgml

*Step 3: Fix DocBook to accept 3.1 files.
*
DocBook on MacPorts has stylesheets for versions 4.1.2, 4.2, 4.3, 4.4 and
4.5. Kannel uses version 3.1, which is not available as a portfile. I've
managed to grab all necessary files from the openjade project archives and
put it all together. It must be placed somewhere on the disk (I've put it on
/opt/local/share/sgml/<docbook>, where <docbook> is the folder created by
untarring the files)

http://www.magicom-bcn.net/kannel/leopard-docbook31.tar.gz

*Step 4: Add SGML catalog to your environment.
*
Add this to your .bashrc, or run it from the command line before compiling:

export
SGML_CATALOG_FILES="/opt/local/share/sgml/docbook/docbook.cat:/opt/local/share/sgml/openjade/catalog"

Note: "/opt/local/share/sgml/docbook/" is the place where you've unzipped
the files from step 3. docbook.cat is one of the files you've just untarred
before.

*Step 5: Fix DocBook missing files on MacPort:
*
I don't know if this is by design or if the MacPort for docbook-dsssl is
really broken, but a couple of files were missing from the MacPort. I've
packed the files on the following .tar.gz:

http://www.magicom-bcn.net/kannel/docbook-dsssl-missing.tar.gz

Extract the files on:

/opt/local/share/dsssl/docbook-dsssl/

(The folder must exist beforehand, otherwise you're missing the
docbook-dsssl port). It's only 2 files after extraction: "catalog" and
"VERSION" (which is only there to avoid a stupid error on screen).

*Step 6: Build it!
*
[You've already run autoconf after patching configure.in right?] ;)

Ok, so let's build it. A regular ./configure should detect all the formerly
missing pieces. Check the ./configure's output for the following signs:

Configuring DocBook support ...
checking for jade... no
checking for openjade... openjade
checking for jadetex... jadetex
checking for pdfjadetex... pdfjadetex
checking for dvips... dvips
checking for fig2dev... fig2dev
checking for convert... /opt/local/bin/convert
checking for
/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl... no
... lots of "no's"...
checking for
/opt/local/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl... no
checking for /opt/local/share/dsssl/docbook-dsssl/html/docbook.dsl... yes
checking for
/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/print/docbook.dsl... no
... more "no's"...
checking for
/opt/local/lib/sgml/stylesheets/nwalsh-modular/print/docbook.dsl... no
checking for /opt/local/share/dsssl/docbook-dsssl/print/docbook.dsl... yes
Documentation will be built as well.

If all goes well, you'll be able to run "make" and the docs will be built
with the rest of the code.

I think the process could be made much more simpler on Leopard if the
DocBook files were updated to use the 4.x tree (which is XML based). I did a
couple of attempts on that without much success (I'm still getting into
speed with DocBook).

Hope it helps,

Alejandro