setting up the git documentation build chain on mac os x leopard

Wincent — Software for your MacProducts

Desktop productsSynergySynergy AdvanceWinSwitch

Developer productsatosymCommand-THextrapolateInstallWalrusWalratWincent Login ToolWincent Strings UtilityWOPublicWOTest

Server productsBanssheeWikitext

BlogSnippetsTweets

WikiForumsSupportAboutSearchlog in

Home » Wiki » Setting up the Git documentation build chain on Mac OS X Leopard

Setting up the Git documentation build chain on Mac OS X LeopardCreated 21/01/2008, updated 23/08/2010 by Wincent Colaiuta

Installing the documentation build chain on Mac OS X is quite tedious, as it involves a lengthy dependency chain. For an alternative that does not involveinstalling the tools, see "Installing pre-built Git documentation from the Git repo".

These notes are an updated version of "Installing Git 1.5.2.3 on Mac OS X Tiger".

Out of the box"Out of the box", Leopard, like Tiger, doesn't have the dependencies required to build the Git documentation. If you try:

make prefix=/usr/local doc

You'll fail with a message like this:

asciidoc -b xhtml11 -d manpage -f asciidoc.conf \ -agit_version=1.5.3.6.728.gea559 -o git-add.html+ git-add.txt

make[1]: asciidoc: Command not foundmake[1]: *** [git-add.html] Error 127make: *** [doc] Error 2

Installing AsciiDocSince my last experience with AsciiDoc it has been updated from version 8.2.1 to 8.2.5.

wget http://www.methods.co.nz/asciidoc/asciidoc-8.2.5.tar.gztar xzvf asciidoc-8.2.5.tar.gzcd asciidoc-8.2.5sudo ./install.sh

# testrm doc/asciidoc.html asciidoc doc/asciidoc.txtopen doc/asciidoc.html

Note that the Git documentation expects AsciiDoc 7, not 8, so when building the Git documentation you need to pass an additional flag:

make prefix=/usr/local/ ASCIIDOC8=YesPlease doc

I later found that at least with the current version of AsciiDoc the produced documentation is flawed. The most significant problem is that all internal links arebroken, but there may be others. I spent an hour trying to work around this, without success. In the end the only solution was to uninstall 8 and overwrite itwith 7:

sudo rm -r /etc/asciidoc

wincent.com: Setting up the Git documentation build chain o... https://wincent.com/wiki/Setting_up_the_Git_documentation...

1 de 5 28/11/10 11:29

# note that AsciiDoc 7 doesn't come with an install script or Makefilesudo mkdir /etc/asciidocsudo cp -R filters *.conf /etc/asciidoc/sudo cp -R stylesheets /etc/asciidoc/

# finally, overwrite the previously installed asciidoc tool itself:sudo cp asciidoc.py /usr/local/bin/asciidoc

Since I originally wrote this article I understand that Git itself has been patched to workaround the regression in AsciiDoc 8. See 5162e69 in the main Gitrepository. I haven't bothered to change my AsciiDoc install again, however.

Installing xmltoIf you now retry building the Git doc target:

make prefix=/usr/local doc

You'll get somewhat farther; now the HTML version of the documentation will build but it may still choke on the user manual because of what I presume arenetwork connectivity issues:

xsltproc --xinclude --stringparam html.stylesheet docbook-xsl.css -o user-manual.html docbook.xsl user-manual.xmlerror : Operation in progresswarning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/common/targets.xsl"compilation error: file http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl line 35 element includexsl:include : unable to load http://docbook.sourceforge.net/release/xsl/current/common/targets.xslmake[1]: *** [user-manual.html] Error 5make: *** [doc] Error 2

Trying again yielded a slightly different error:

xsltproc --xinclude --stringparam html.stylesheet docbook-xsl.css -o user-manual.html docbook.xsl user-manual.xmlerror : Operation in progresswarning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/common/he.xml"http://docbook.sourceforge.net/release/xsl/current/common/l10n.xml:89: error: Failure to process entity he&he; ^http://docbook.sourceforge.net/release/xsl/current/common/l10n.xml:89: parser error : Entity 'he' not defined&he; ^

But the build continued, yielding many warnings (screenfuls) like these:

No localization exists for "en" or "". Using default "en".No localization exists for "en" or "". Using default "en".No localization exists for "en" or "". Using default "en".No localization exists for "en" or "". Using default "en".No "en" localization exists.No context named "title-numbered" exists in the "en" localization.No "en" localization exists.No context named "title-numbered" exists in the "en" localization.No "en" localization exists.No context named "title-numbered" exists in the "en" localization.

And finally failing here:

xmlto -m callouts.xsl man git-add.xmlmake[1]: xmlto: Command not foundmake[1]: *** [git-add.1] Error 127rm git-add.xmlmake: *** [doc] Error 2

So, we attempt installing xmlto:

# get latest version from http://cyberelk.net/tim/data/xmlto/stable/wget http://cyberelk.net/tim/data/xmlto/stable/xmlto-0.0.18.tar.bz2tar xjvf xmlto-0.0.18.tar.bz2cd xmlto-0.0.18./configure

Configuring reveals the following prerequisite:

checking whether getopt handles long options... configure: error: no

You need getopt from <http://huizen.dds.nl/~frodol/getopt.html>, orelse some other implementation that supports --longoptions.

So:

cd ..wget http://software.frodo.looijaard.name/getopt/files/getopt-1.1.4.tar.gztar xzvf getopt-1.1.4.tar.gz cd getopt-1.1.4less README make

Dies as follows:

nls.h:35:21: error: libintl.h: No such file or directorygetopt.c: In function ‘our_malloc’:getopt.c:91: warning: implicit declaration of function ‘gettext’getopt.c:91: warning: incompatible implicit declaration of built-in function ‘gettext’getopt.c: In function ‘our_realloc’:getopt.c:101: warning: incompatible implicit declaration of built-in function ‘gettext’getopt.c: In function ‘parse_error’:


2 de 5 28/11/10 11:29

getopt.c:235: warning: incompatible implicit declaration of built-in function ‘gettext’getopt.c: In function ‘add_long_options’:getopt.c:301: warning: incompatible implicit declaration of built-in function ‘gettext’getopt.c: In function ‘set_shell’:getopt.c:321: warning: incompatible implicit declaration of built-in function ‘gettext’getopt.c: In function ‘print_help’:getopt.c:326: warning: incompatible implicit declaration of built-in function ‘gettext’getopt.c: In function ‘main’:getopt.c:378: warning: implicit declaration of function ‘setlocale’getopt.c:378: warning: nested extern declaration of ‘setlocale’getopt.c:378: error: ‘LC_ALL’ undeclared (first use in this function)getopt.c:378: error: (Each undeclared identifier is reported only oncegetopt.c:378: error: for each function it appears in.)getopt.c:379: warning: implicit declaration of function ‘bindtextdomain’getopt.c:379: warning: nested extern declaration of ‘bindtextdomain’getopt.c:380: warning: implicit declaration of function ‘textdomain’getopt.c:380: warning: nested extern declaration of ‘textdomain’getopt.c:397: warning: incompatible implicit declaration of built-in function ‘gettext’getopt.c:446: warning: incompatible implicit declaration of built-in function ‘gettext’getopt.c:458: warning: incompatible implicit declaration of built-in function ‘gettext’make: *** [getopt.o] Error 1

So off to install another prerequisite:

cd ..wget http://mirrors.kernel.org/gnu/gettext/gettext-0.17.tar.gztar xzvf gettext-0.17.tar.gz cd gettext-0.17./configuremakemake check

This failed dismally; here is a small excerpt:

FAIL: lang-libreptr: Illegal byte sequenceFAIL: lang-guiletr: Illegal byte sequenceFAIL: lang-smalltalktr: Illegal byte sequenceFAIL: lang-javaSkipping test: C# compiler not foundSKIP: lang-csharptr: Illegal byte sequenceFAIL: lang-gawkSkipping test: ppc386 compiler not foundSKIP: lang-pascaltr: Illegal byte sequenceFAIL: lang-ycptr: Illegal byte sequenceFAIL: lang-tcltr: Illegal byte sequenceFAIL: lang-perl-1tr: Illegal byte sequenceFAIL: lang-perl-2tr: Illegal byte sequenceFAIL: lang-phptr: Illegal byte sequenceFAIL: lang-poPASS: lang-rst=======================56 of 316 tests failed(11 tests were not run)=======================make[3]: *** [check-TESTS] Error 1make[2]: *** [check-am] Error 2make[1]: *** [check-recursive] Error 1make: *** [check-recursive] Error 1

Given that the previous version of gettext had built successfully on Tiger (see "Installing Git 1.5.2.3 on Mac OS X Tiger") I decided to try it out on Leopard:

cd ..wget http://mirrors.kernel.org/gnu/gettext/gettext-0.16.1.tar.gztar xzvf gettext-0.16.1.tar.gz cd gettext-0.16.1./configuremakemake check

There was one failure, but it looked harmless:

1c1< «Votre commande, s'il vous plait», dit le garçon.---> ?Votre commande, s'il vous plait?, dit le gar?on.FAIL: lang-bash

So I proceeded with the install:

sudo make install

Now back to building getopt:

cd ../getopt-1.1.4make

Errors out as follows:

gcc -c -DLIBCGETOPT=1 -DWITH_GETTEXT= -DLOCALEDIR=\"/usr/local/share/locale\" -DNOT_UTIL_LINUX -Wall -W -Wshadow -Wpointer-arith -Wbad-function-cast


3 de 5 28/11/10 11:29

gcc -o getopt getopt.oUndefined symbols: "_libintl_textdomain", referenced from: _main in getopt.o "_libintl_bindtextdomain", referenced from: _main in getopt.o "_libintl_gettext", referenced from: _our_malloc in getopt.o _our_realloc in getopt.o _parse_error in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _print_help in getopt.o _set_shell in getopt.o _set_shell in getopt.o _normalize in getopt.o _add_longopt in getopt.o _add_long_options in getopt.o _add_long_options in getopt.o _main in getopt.o _main in getopt.o _main in getopt.o _main in getopt.o _main in getopt.old: symbol(s) not foundcollect2: ld returned 1 exit statusmake: *** [getopt] Error 1

This is similar to what happened in Tiger; the solution is to modify the Makefile, changing

LDFLAGS=

To:

LDFLAGS=-lintl

And now the make will work:

makesudo make install

Now back to xmlto:

cd ../xmlto-0.0.18./configuremakemake checksudo make install

As was the case with Tiger, installation also fails on Leopard, although the message is slightly different:

I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xslwarning: 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.xslxmlto: input does not validate (status 1)http://www.oasis-open.org/docbook/xml/4.2/dbcentx.mod:369: parser error : Entity value required]]>^http://www.oasis-open.org/docbook/xml/4.2/dbcentx.mod:369: parser error : Space required before 'NDATA']]>^http://www.oasis-open.org/docbook/xml/4.2/dbcentx.mod:369: parser error : xmlParseEntityDecl: entity lcar not terminated]]>^http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd:127: parser warning : PEReference: %dbpool.module; not found<![ %dbpool.module; [ ^http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd:127: parser error : conditional section INCLUDE or IGNORE keyword expected<![ %dbpool.module; [ ^http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd:127: parser error : Content error in the external subset<!ENTITY % dbpool PUBLIC ^

Q: I'm trying to build xmlto on my Debian box, but it doesn't work.

A: If you get `Attempt to load network entity' errors when building xmlto, your system does not have the required support for XML Catalogs (http://www.oasis-open.org/committees/entity/spec-2001-08-06.html). In particular, Debian has no support for these. Try the Fedora Project <http://fedora.redhat.com>.make[1]: *** [man/man1/xmlif.1] Error 1make: *** [install-am] Error 2

So:


4 de 5 28/11/10 11:29

sudo mkdir -p /usr/local/etc/xmlsudo xmlcatalog --noout --create /usr/local/etc/xml/catalogsudo mkdir -p /usr/local/share/docbook/xslcd /usr/local/share/docbook/xslsudo wget http://surfnet.dl.sourceforge.net/sourceforge/docbook/docbook-xsl-1.73.2.tar.bz2sudo tar xjvf docbook-xsl-1.73.2.tar.bz2

# would have liked to install this in /usr/local/etc, but only /etc workssudo xmlcatalog --noout --add 'nextCatalog' '' 'file:///usr/local/share/docbook/docbook-xsl-1.73.2/catalog.xml' --create /etc/xml/catalog

With these changes we now see errors like the following in the make of xmlto:

Resolve: sysID http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl-1602326688 Parsing catalog file:///etc/xml/catalogfile:///etc/xml/catalog added to file hashfile:///usr/local/share/docbook/docbook-xsl-1.73.2/catalog.xml not found in file hash-1602326688 Parsing catalog file:///usr/local/share/docbook/docbook-xsl-1.73.2/catalog.xmlfile:///usr/local/share/docbook/docbook-xsl-1.73.2/catalog.xml added to file hashUsing rewriting rule http://docbook.sourceforge.net/release/xsl/current/Resolve: pubID -//OASIS//DTD DocBook XML V4.2//EN sysID http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtdResolve URI http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtdI/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd/Users/wincent/trabajo/vendor/git/xmlto-0.0.18/./doc/xmlif.xml:4: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> ^Note: meta source : no *info/productname or alternative xmlifNote: meta source : see http://docbook.sf.net/el/productname xmlifNote: meta source : no refentry/refmeta/refmiscinfo@class=source xmlifNote: meta source : see http://docbook.sf.net/el/refmiscinfo xmlifNote: meta version: no *info/productnumber or alternative xmlifNote: meta version: see http://docbook.sf.net/el/productnumber xmlifNote: meta version: no refentry/refmeta/refmiscinfo@class=version xmlifNote: meta version: see http://docbook.sf.net/el/refmiscinfo xmlifNote: meta manual : no titled ancestor of refentry xmlifNote: meta manual : no refentry/refmeta/refmiscinfo@class=manual xmlifNote: meta manual : see http://docbook.sf.net/el/refmiscinfo xmlifNote: Writing xmlif.1Catalogs cleanupFree catalog entry file:///usr/local/share/docbook/docbook-xsl-1.73.2/catalog.xmlFree catalog entry file:///etc/xml/catalogFree catalog entry http://docbook.sourceforge.net/release/xsl/current/Free catalog entry http://docbook.sourceforge.net/release/xsl/current/Free catalog entry http://docbook.sourceforge.net/release/xsl/1.73.2/Free catalog entry http://docbook.sourceforge.net/release/xsl/1.73.2/Free catalog entry file:///usr/local/share/docbook/docbook-xsl-1.73.2/catalog.xmlFree catalog entry

So, now to install the DocBook DTDs:

cd /usr/local/share/docbooksudo wget http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zipsudo unzip docbook-xml-4.2.zip -d docbook-xml-4.2sudo xmlcatalog --noout --add nextCatalog '' file:///usr/local/share/docbook/docbook-xml-4.2/catalog.xml --create /etc/xml/catalog

Now the xmlto install finally works:

cd path_to_xmltomake clean./configuremakemake checksudo make install

And we can try building the Git documentation again:

cd path_to_gitmake prefix=/usr/local docsudo make prefix=/usr/local install-doc

Alternatives to building the documentation manuallyInstalling pre-built Git documentation from the Git repo

Tags

git asciidoc docs xmltowiki index

Comments

Add a commentadd a comment

contactlegal


5 de 5 28/11/10 11:29

setting up the git documentation build chain on mac os x leopard

Documents