public inbox for git@vger.kernel.org 
 help / color / mirror / Atom feed

From: Steven Grimm <koreth@midwinter•com>
To: git@vger•kernel.org
Subject: How to build manpages on OS X
Date: Thu, 28 Dec 2006 15:32:08 -0800	[thread overview]
Message-ID: <459453F8.1010200@midwinter.com> (raw)

Didn't see this documented anywhere, so...

If you want to do a full build of git on OS X including the manpages, 
you need the asciidoc and xmlto packages. Both of them are available 
from macports.org (formerly known as DarwinPorts) but out of the box, 
they don't work quite right. If you try doing a "make doc", you get the 
following error from xmlto:

I/O error : Attempt to load network entity 
http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl

The superficial reason for that error is that xmlto is calling the 
xsltproc utility with a command-line option that tells it to not fetch 
documents from the network. If you edit xmlto and remove that option, 
the doc build will work, but it will have to fetch a bunch of files from 
SourceForge for every manpage, which is dog slow.

The real solution is to use local copies of the files it's trying to 
fetch. These files are installed as part of one of the dependencies when 
you install xmlto, but the install process doesn't tell the system where 
to look for them! To use these local copies, you need to do two things.

First, create an XML catalog file. Typically it's called catalog.xml. 
The contents should be:

<?xml version='1.0'?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteURI 
uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
        rewritePrefix="file:///opt/local/share/xsl/docbook-xsl/" />
<rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.2/"
        rewritePrefix="file:///opt/local/share/xml/docbook-xml/4.3/" />
</catalog>

Yes, that second rewriteURI maps the 4.2 docbook URI to the 4.3 version 
-- blame the MacPorts packages, because that's what gets installed. The 
mismatch doesn't appear to hurt anything. (If you're reading this from 
the mailing list archive, MacPorts might have updated the packages since 
I wrote this, so adjust the paths accordingly.)

Now you need to tell the system to use the file. You do that using the 
XML_CATALOG_FILES environment variable, like so:

$ export XML_CATALOG_FILES=`pwd`/catalog.xml
$ make prefix=/opt/local doc
$ sudo make prefix=/opt/local install-doc

Annoying that it doesn't just work, but hopefully this will save someone 
some Googling around.

-Steve

next             reply	other threads:[~2006-12-28 23:32 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2006-12-28 23:32 Steven Grimm [this message]
2006-12-29  0:24 ` How to build manpages on OS X Junio C Hamano
2006-12-29  6:02 ` Randal L. Schwartz

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=459453F8.1010200@midwinter.com \
    --to=koreth@midwinter$(echo .)com \
    --cc=git@vger$(echo .)kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox