Building PostgreSQL Documentation on MacOS X

During the latest CommitFest i've started to use MacOS X while reviewing patches as a Round Robin Reviewer. I'm going to love OS X and its shiny GUI, but i had heavy problems to build the PostgreSQL Documentation on that platform. The core problem is, that on OS X there's no really good Docbook distribution available (at least, i haven't found one, which is usable out of the box). So i decided to go with macports, since i had some very good experience with them in the past. Please note that i'm not a DocBook hacker...i'm just using it to build at least the PostgreSQL docs. So i've started installing openjade from macports first:

$ sudo port install openjade

This installs openjade into /opt/local/share/sgml/openjade. Unfortunately, there's no Docbook SGML in macports, so i followed the PostgreSQL instructions and downloaded the following packages:

DocBook SGML DTD
DocBook DSSSL
ISO 8879 Entities

The ISO 8879 character entities can also be obtained from macports:

$ sudo port install iso8879

This is what I preferred. I went on and installed the DocBook DTD and DocBook DSSSL packages as described in the PostgreSQL Documentation. Instead of /usr/local/share/sgml i've used the already created directory /opt/local/share/sgml, used by macports. Unzipping the downloaded archives gives the following layout:

drwxr-xr-x 36 root admin 1,2K 3 Sep 23:45 docbook/
drwxr-xr-x 21 root admin 714B 3 Sep 23:34 docbook-dsssl-1.79/
drwxr-xr-x 22 root admin 748B 3 Sep 14:10 iso8879/
drwxr-xr-x 12 root admin 408B 4 Sep 10:24 openjade/

Because the ISO character entities are located outside the docbook directories, I needed to adjust the catalog file /opt/local/share/sgml/docbook/docbook.cat. I dumped the whole entity section from the file and added a CATALOG reference instead:

$ cat docbook/docbook.cat
[...]
-- ...................................................................... --
-- ISO entity sets ...................................................... --
CATALOG "../iso8879/catalog"

This references /opt/local/share/sgml/iso8879/catalog which includes all ISO character entities then. Afterwards i tried PostgreSQL configure, unfortunately that didn't work. The first problem i've encountered was that /opt/local/bin/collateindex.pl wasn't installed with executable rights:

-rw-r--r-- 2 root admin 17503 3 Sep 15:21 collateindex.pl

configure was not able to locate the script (so, what's the point in installing a script in a bin directory without executable flags??). Firing a chmod a+x /opt/local/bin/collateindex.pl fixed that issue. Another problem was, that openjade wasn't able to find the docbook DTD's. After trying around a little bit, i realized that openjade looks into /opt/local/share/sgml, not in /opt/local/share/sgml/openjade, as someone might expect. I created a symlink to openjade/catalog. At a first try this didn't work either. Foolish as i am, i forgot that the catalog file references the objects with relative paths. Creating a separate catalog file in /opt/local/share/sgml/catalog did the job finally:

$ cat /opt/local/share/sgml/catalog
PUBLIC "-//James Clark//DTD DSSSL Flow Object Tree//EN" "openjade/fot.dtd"
PUBLIC "ISO/IEC 10179:1996//DTD DSSSL Architecture//EN" "openjade/dsssl.dtd"
PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" "openjade/style-sheet.dtd"
PUBLIC "-//OpenJade//DTD DSSSL Style Sheet//EN" "openjade/style-sheet.dtd"
SYSTEM "openjade/builtins.dsl" "openjade/builtins.dsl"
CATALOG "docbook/docbook.cat"
CATALOG "docbook-dsssl-1.79/catalog"

The directory layout i'm going to work with looks as follows:

-rw-r--r-- 1 root admin 541 4 Sep 10:22 catalog
drwxr-xr-x 18 root admin 612 4 Sep 15:03 docbook/
drwxr-xr-x 21 root admin 714 3 Sep 23:34 docbook-dsssl-1.79/
drwxr-xr-x 7 root admin 238 3 Sep 14:10 html/
drwxr-xr-x 22 root admin 748 3 Sep 14:10 iso8879/
drwxr-xr-x 12 root admin 408 4 Sep 10:24 openjade/

The HTML docs are finally build by the commands

$ eval ./configure $(pg_config --configure) DOCBOOKSTYLE=/opt/local/share/sgml/
$ cd doc/src/sgml; make

Leave your comments if you have some additional suggestions or better ideas.