From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 27 Jan 2009 20:05:06 GMT
Subject: Re: Building Documentation in Cygwin
Message-ID: <7vpri8347h.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <c115fd3c0901271127q2a7f0f58i59ff446060982fd7@mail.gmail.com>

Tim Visher <tim.visher@gmail.com> writes:

> On Tue, Jan 27, 2009 at 1:32 PM, Junio C Hamano <gitster@pobox.com> wrote:
>
>> The xml toolchain has a tendency to download dtds from the original source
>> with a way for you (typically your distribution) to tell it to use a
>> locally installed version.  "Can build online, fail when offline" is a
>> sign that it is not using the local copy.
>
> Sounds like we're on the same page.  I'm not familiar enough with any
> of these tools to know how to do anything about that.  Does anyone
> know how to explicitly inform xmlto to use a local DTD?  I have it
> installed, as far as I know, via cygwin (the docbook-xml42 package)
> but I don't know how to tell xmlto about it.
>
> Thanks in advance!

I do not know how Cygwin packages things, but here is an exchange I had
with k.org admin when they updated the machine I prepare the preformatted
documentation pages and I had similar trouble.

-- >8 -- from here -- >8 --
/usr/share/sgml/docbook/xmlcatalog on master.kernel.org is empty:

$ ls -l /usr/share/sgml/docbook/xmlcatalog
-rw-r--r-- 1 root root 236 2008-06-30 06:51 /usr/share/sgml/docbook/xmlcatalog
$ cat /usr/share/sgml/docbook/xmlcatalog
<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/>

On a good machine, however, it is much larger:

$ ls -l /usr/share/sgml/docbook/xmlcatalog
-rw-r--r-- 1 root root 7907 Jul  4 14:08 /usr/share/sgml/docbook/xmlcatalog
$ grep docbookx /usr/share/sgml/docbook/xmlcatalog
  <public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" uri="xml-dtd-4.1.2-1.0-35.fc9/docbookx.dtd"/>
  <public publicId="-//OASIS//DTD DocBook XML V4.2//EN" uri="xml-dtd-4.2-1.0-35.fc9/docbookx.dtd"/>
  <public publicId="-//OASIS//DTD DocBook XML V4.3//EN" uri="xml-dtd-4.3-1.0-35.fc9/docbookx.dtd"/>
  <public publicId="-//OASIS//DTD DocBook XML V4.4//EN" uri="xml-dtd-4.5-1.0-35.fc9/docbookx.dtd"/>

The lack of these entries seems to cause the processing to go to the
network instead of using the files locally installed.
-- 8< -- to here -- 8< --

and a response I got from them:

-- >8 -- from here -- >8 --

Hmmm tried reinstalling docbook-dtds-1.0-35.fc9.noarch.rpm and things
seem to have showed up like your expecting - clearly a bad dependency in
the rpm.  Anyway give it a whirl.

-- 8< -- to here -- 8< --

After that exchange, things did work much better.

I hope the above (words like "docbook-dtds") has enough hints for you to
find corresponding set of packages on Cygwin to additionally install or
futz with to get the formatting working.