Installing the tool chain on Mac OS X

This is what I did to make the documentation building steps of make all work:

• Install [http://developer.apple.com/tools/xcode/ XCode (Apple's developer tools)].

• Install asciidoc-8.2.5. Get it from http://www.methods.co.nz/asciidoc/asciidoc-8.2.5.tar.gz and sudo ./install.sh.

• Install GNU gettext-0.17. It provides libintl, which is required by getopt. Get it from your favorite GNU mirror and do the GNU install dance:

  ./configure
  make
  sudo make install

• Install getopt-1.1.4, which is required by xmlto. It's supposedly available from http://software.frodo.looijaard.name/getopt/files/getopt-1.1.4.tar.gz, but the link doesn't work for me in Firefox. I downloaded and installed it like this:

  curl http://software.frodo.looijaard.name/getopt/files/getopt-1.1.4.tar.gz > getopt-1.1.4.tar.gz
  tar xzvf getopt-1.1.4.tar.gz
  cd getopt-1.1.4
  LDFLAGS="-lintl" make -e
  sudo make install

• Install xmlto-0.0.19. Get it from http://cyberelk.net/tim/data/xmlto/stable/xmlto-0.0.19.tar.bz2 and install it like this:

  ./configure
  make
  sudo make install

That's it for the tools, but if you try to make all now you'll probably see warning and errors like this:

xmlto man hg.1.xml
I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
cannot parse http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
Variable $SGML_CATALOG_FILES not set

or this:

xmlto man hg.1.xml
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd
/Users/kevin/dev/hg/doc/hg.1.xml:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

Fix them with these steps:

• Install docbook-xsl-1.73.2. Get it from http://downloads.sourceforge.net/docbook/docbook-xsl-1.73.2.tar.bz2:

  cd /usr/local/share
  sudo tar xjvf docbook-xsl-1.73.tar.bz2

• Install docbook-xml-4.2. Get it from http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip:

  sudo mkdir -p /usr/local/share/docbook-xml-4.2
  cd /usr/local/share/docbook-xml-4.2
  sudo unzip docbook-xml-4.2

• Update your environment to find the stylesheets and DTDs:

  export XML_CATALOG_FILES="/usr/local/share/docbook-xsl-1.73.2/catalog.xml /usr/local/share/docbook-xml-4.2/catalog.xml"

That did the trick for me on Tiger (10.4.11). I'm running Python 2.5.1, because I've heard about problems with the shipped version (2.3.5), but I installed it long ago and I won't try to describe the installation here.