* How to build manpages on OS X
@ 2006-12-28 23:32 Steven Grimm
2006-12-29 0:24 ` Junio C Hamano
2006-12-29 6:02 ` Randal L. Schwartz
0 siblings, 2 replies; 3+ messages in thread
From: Steven Grimm @ 2006-12-28 23:32 UTC (permalink / raw)
To: git
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: How to build manpages on OS X
2006-12-28 23:32 How to build manpages on OS X Steven Grimm
@ 2006-12-29 0:24 ` Junio C Hamano
2006-12-29 6:02 ` Randal L. Schwartz
1 sibling, 0 replies; 3+ messages in thread
From: Junio C Hamano @ 2006-12-29 0:24 UTC (permalink / raw)
To: Steven Grimm; +Cc: git
Steven Grimm <koreth@midwinter•com> writes:
> 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.
Sounds like a DarwinPorts bug (or lack of feature, or maybe
feature still being added but not given to the public, I dunno).
My understanding is that these catalogs are maintained
automatically by the distribution when stylesheets are
installed. For example, on Debian systems, xml-core seems to
offer the infrastructure and .postinst scripts for packages such
as docbook-xsl use update-xmlcatalog tool to make sure the
stylesheets they install are found locally on the system.
In any case, thanks for the write-up.
> Annoying that it doesn't just work, but hopefully this will save
> someone some Googling around.
I've added a pointer to your message at gmane archive on Gitwiki
page (GitDocumentation).
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: How to build manpages on OS X
2006-12-28 23:32 How to build manpages on OS X Steven Grimm
2006-12-29 0:24 ` Junio C Hamano
@ 2006-12-29 6:02 ` Randal L. Schwartz
1 sibling, 0 replies; 3+ messages in thread
From: Randal L. Schwartz @ 2006-12-29 6:02 UTC (permalink / raw)
To: Steven Grimm; +Cc: git
>>>>> "Steven" == Steven Grimm <koreth@midwinter•com> writes:
Steven> Didn't see this documented anywhere, so...
Steven> If you want to do a full build of git on OS X including the manpages, you need
Steven> the asciidoc and xmlto packages. Both of them are available from macports.org
Steven> (formerly known as DarwinPorts) but out of the box, they don't work quite
Steven> right.
I'm using the ones out of fink, and it seems to work just fine.
--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<merlyn@stonehenge•com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2006-12-29 6:03 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2006-12-28 23:32 How to build manpages on OS X Steven Grimm
2006-12-29 0:24 ` Junio C Hamano
2006-12-29 6:02 ` Randal L. Schwartz
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox