{"thread":{"id":"6146","subject":"How to build manpages on OS X","startedAt":"2006-12-28T23:32:08Z","lastAt":"2006-12-29T06:02:55Z","messageCount":3,"participants":["Steven Grimm","Junio C Hamano","Randal L. Schwartz"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"30447","messageId":"459453F8.1010200@midwinter.com","threadId":"6146","inReplyTo":null,"subject":"How to build manpages on OS X","fromName":"Steven Grimm","fromEmail":"koreth@midwinter.com","sentAt":"2006-12-28T23:32:08Z","receivedAt":"2006-12-28T23:32:08Z","isPatch":false,"sender":{"key":"koreth@midwinter.com","avatar":"https://gravatar.com/avatar/71b4d2e8b62f168bdc9e9205341159e3567003b4f9e2127c617c5fa0a1f5bad2?d=mp&s=160"},"body":"Didn't see this documented anywhere, so...\n\nIf you want to do a full build of git on OS X including the manpages, \nyou need the asciidoc and xmlto packages. Both of them are available \nfrom macports.org (formerly known as DarwinPorts) but out of the box, \nthey don't work quite right. If you try doing a \"make doc\", you get the \nfollowing error from xmlto:\n\nI/O error : Attempt to load network entity \nhttp://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\n\nThe superficial reason for that error is that xmlto is calling the \nxsltproc utility with a command-line option that tells it to not fetch \ndocuments from the network. If you edit xmlto and remove that option, \nthe doc build will work, but it will have to fetch a bunch of files from \nSourceForge for every manpage, which is dog slow.\n\nThe real solution is to use local copies of the files it's trying to \nfetch. These files are installed as part of one of the dependencies when \nyou install xmlto, but the install process doesn't tell the system where \nto look for them! To use these local copies, you need to do two things.\n\nFirst, create an XML catalog file. Typically it's called catalog.xml. \nThe contents should be:\n\n<?xml version='1.0'?>\n<catalog xmlns=\"urn:oasis:names:tc:entity:xmlns:xml:catalog\">\n<rewriteURI \nuriStartString=\"http://docbook.sourceforge.net/release/xsl/current/\"\n        rewritePrefix=\"file:///opt/local/share/xsl/docbook-xsl/\" />\n<rewriteURI uriStartString=\"http://www.oasis-open.org/docbook/xml/4.2/\"\n        rewritePrefix=\"file:///opt/local/share/xml/docbook-xml/4.3/\" />\n</catalog>\n\nYes, that second rewriteURI maps the 4.2 docbook URI to the 4.3 version \n-- blame the MacPorts packages, because that's what gets installed. The \nmismatch doesn't appear to hurt anything. (If you're reading this from \nthe mailing list archive, MacPorts might have updated the packages since \nI wrote this, so adjust the paths accordingly.)\n\nNow you need to tell the system to use the file. You do that using the \nXML_CATALOG_FILES environment variable, like so:\n\n$ export XML_CATALOG_FILES=`pwd`/catalog.xml\n$ make prefix=/opt/local doc\n$ sudo make prefix=/opt/local install-doc\n\nAnnoying that it doesn't just work, but hopefully this will save someone \nsome Googling around.\n\n-Steve\n"},{"id":"30449","messageId":"7vtzzftuqk.fsf@assigned-by-dhcp.cox.net","threadId":"6146","inReplyTo":"459453F8.1010200@midwinter.com","subject":"Re: How to build manpages on OS X","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-12-29T00:24:03Z","receivedAt":"2006-12-29T00:24:03Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Steven Grimm <koreth@midwinter.com> writes:\n\n> The real solution is to use local copies of the files it's trying to\n> fetch. These files are installed as part of one of the dependencies\n> when you install xmlto, but the install process doesn't tell the\n> system where to look for them! To use these local copies, you need to\n> do two things.\n\nSounds like a DarwinPorts bug (or lack of feature, or maybe\nfeature still being added but not given to the public, I dunno).\n\nMy understanding is that these catalogs are maintained\nautomatically by the distribution when stylesheets are\ninstalled.  For example, on Debian systems, xml-core seems to\noffer the infrastructure and .postinst scripts for packages such\nas docbook-xsl use update-xmlcatalog tool to make sure the\nstylesheets they install are found locally on the system.\n\nIn any case, thanks for the write-up.\n\n> Annoying that it doesn't just work, but hopefully this will save\n> someone some Googling around.\n\nI've added a pointer to your message at gmane archive on Gitwiki\npage (GitDocumentation).\n"},{"id":"30466","messageId":"867iwbdysw.fsf@blue.stonehenge.com","threadId":"6146","inReplyTo":"459453F8.1010200@midwinter.com","subject":"Re: How to build manpages on OS X","fromName":"Randal L. Schwartz","fromEmail":"merlyn@stonehenge.com","sentAt":"2006-12-29T06:02:55Z","receivedAt":"2006-12-29T06:02:55Z","isPatch":false,"sender":{"key":"merlyn@stonehenge.com","avatar":"https://gravatar.com/avatar/dc528d210743ff0333e6213f9ee7b33b23f1b7bc1f3c5a8c2d819074ecd7ab19?d=mp&s=160"},"body":">>>>> \"Steven\" == Steven Grimm <koreth@midwinter.com> writes:\n\nSteven> Didn't see this documented anywhere, so...\nSteven> If you want to do a full build of git on OS X including the manpages, you need\nSteven> the asciidoc and xmlto packages. Both of them are available from macports.org\nSteven> (formerly known as DarwinPorts) but out of the box, they don't work quite\nSteven> right.\n\nI'm using the ones out of fink, and it seems to work just fine.\n\n-- \nRandal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095\n<merlyn@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>\nPerl/Unix/security consulting, Technical writing, Comedy, etc. etc.\nSee PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!\n"}]}