Freitag, 4. September 2009

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.

1 Kommentar:

Florian Pflug hat gesagt…

This blog entry inspired me to get the relevant packages fixed in macports.

As of today, a new port docbook-sgml-4.2 exists, and all the SGML-related ports (docbook-dsssl, iso8879, docbook-sgml-4.2) now register their individual catalogs with the root catalog in /opt/local/etc/sgml/catalog. And yes, docbook-dsssl now installs collateindex.pl with permissions 755.

Also per today, openjade uses that catalog (well, actually it puts a reference to the root catalog into /opt/local/share/sgml/catalog).

Thus, a simple "port install docbook-sgml-4.2 openjade" should now be enough to get working docbook SGML support on Mac OS X. After that, postgres' configure script should detect openjade and collateindex.pl, and "make html" should build the documentation.

Kudos to Dan Ports (of postgres true serializability fame, and as I learned also a macports committer) for getting my patches cleaned up and committed.