Building Documentation in Cygwin

Hey Everyone,

I've asked this question here before but unfortunately I can't find the answer in any of the archives. I'm trying to build the documentation on Windows in Cygwin. Git builds fine, the html docs build fine, but when I get to the man pages, I get the following error:

    $ make install-man
    rm -f doc.dep+ doc.dep
    /usr/bin/perl ./build-docdep.perl >doc.dep+
    mv doc.dep+ doc.dep
    make -C ../ GIT-VERSION-FILE
    make[1]: Entering directory `/cygdrive/c/Documents and
Settings/tvishe01/Desktop/Projects/git'
    make[1]: `GIT-VERSION-FILE' is up to date.
    make[1]: Leaving directory `/cygdrive/c/Documents and
Settings/tvishe01/Desktop/Projects/git'
    make -C ../ GIT-VERSION-FILE
    make[1]: Entering directory `/cygdrive/c/Documents and
Settings/tvishe01/Desktop/Projects/git'
    make[1]: `GIT-VERSION-FILE' is up to date.
    make[1]: Leaving directory `/cygdrive/c/Documents and
Settings/tvishe01/Desktop/Projects/git'
    rm -f git-add.xml+ git-add.xml
    asciidoc -b docbook -d manpage -f asciidoc.conf \
                     -agit_version=1.6.1.1.230.gdfb04 -o git-add.xml+
git-add.txt
    mv git-add.xml+ git-add.xml
    rm -f git-add.1
    xmlto -m callouts.xsl man git-add.xml
    xmlto: input does not validate (status 3)
    error : Operation not permitted
    /home/tvishe01/projects/git/Documentation/git-add.xml:2: warning:
failed to load external entity
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
    D DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

            ^
    error : Operation not permitted
    warning: failed to load external entity
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
    Could not load the external subset
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
    Document /home/tvishe01/projects/git/Documentation/git-add.xml
does not validate
    make: *** [git-add.1] Error 3

I've fixed this before but I've been thwarted all morning on the Googles trying to find out what to do. I remember it having something to do with explicitly telling xmlto not to try to download doctypes or something. Also, I remember there being pre-built man pages somewhere that I could download and just manually install.

Anyway, I'm not opposed to either of those routes, I just can't figure out how to do it personally.

Thanks in advance!

--

http://five.sentenc.es/ - Spend less time on e-mail. Written using [Emacs](http://www.gnu.org/software/emacs/).

Hi,

On Tue, Jan 27, 2009 at 11:41 PM, Tim Visher <tim.visher@gmail.com> wrote:

hmm i tried running this and this rule passed for me.

try running xmlto in verbose, what does it output? here's mine:

---cut---

$ xmlto -v -m callouts.xsl man git-add.xml
Format script: /usr/share/xmlto/format/docbook/man
Convert to troff
Real stylesheet:
http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
xmllint >/dev/null --xinclude --postvalid
/cygdrive/g/temp/git/git/Documentation/git-add.xml
Stylesheet: /tmp/xmlto-xsl.nEUjsh
xsltproc --nonet --xinclude \
 -o /tmp/xmlto.MvioXw/git-add.proc \
 /tmp/xmlto-xsl.nEUjsh \
 /cygdrive/g/temp/git/git/Documentation/git-add.xml
Writing git-add.1 for refentry

---cut---

you might also want to try getting the cygwin package docbook-xml42.

On Tue, Jan 27, 2009 at 11:32 AM, Tay Ray Chuan <rctay89@gmail.com> wrote:

$ xmlto -v -m callouts.xsl man git-add.xml
Format script: /usr/share/xmlto/format/docbook/man
Convert to troff
Real stylesheet:
http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
xmllint >/dev/null --xinclude --postvalid
/home/tvishe01/projects/git/Documentation/git-add.xml
xmlto: input does not validate (status 3)
error : Operation not permitted
/home/tvishe01/projects/git/Documentation/git-add.xml:2: warning:
failed to load external entity
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
D DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
                                                                               ^
error : Operation not permitted
warning: failed to load external entity
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
Could not load the external subset
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
Document /home/tvishe01/projects/git/Documentation/git-add.xml does not validate

-- cut

It might be germane to mention that I'm attempting to build this on an offline box.

Sure enough, I didn't have that installed. Turns out I should've done that part first too, as it appears to have fixed my problem. Thanks so much!

On Tue, Jan 27, 2009 at 12:44 PM, Tim Visher <tim.visher@gmail.com> wrote:

Well, I take that back. I built the docs successfully on the machine that is connected to the net. I couldn't build them on the offline box. Currently my solution is to build them on this box and then manually move them over to the offline box. It'd be nice to not have to do this though... :\

Anyway, further help is appreciated! :)

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

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.

On Tue, Jan 27, 2009 at 1:32 PM, Junio C Hamano <gitster@pobox.com> wrote:

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!

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

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.