Building Documentation in Cygwin

Building Documentation in Cygwin

[Tim Visher]

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/).

Re: Building Documentation in Cygwin

[Tay Ray Chuan]

Hi,

On Tue, Jan 27, 2009 at 11:41 PM, Tim Visher <tim.visher@gmail.com> wrote:
>    $ 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)

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.

-- 
Cheers,
Ray Chuan

Re: Building Documentation in Cygwin

[Tim Visher]

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

> try running xmlto in verbose, what does it output?

$ 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.

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

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!

-- 

In Christ,

Timmy V.

http://burningones.com/
http://five.sentenc.es/ - Spend less time on e-mail

Re: Building Documentation in Cygwin

[Tim Visher]

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

>> you might also want to try getting the cygwin package docbook-xml42.
>
> 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!

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! :)

-- 

In Christ,

Timmy V.

http://burningones.com/
http://five.sentenc.es/ - Spend less time on e-mail

Re: Building Documentation in Cygwin

[Junio C Hamano]

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

> On Tue, Jan 27, 2009 at 12:44 PM, Tim Visher <tim.visher@gmail.com> wrote:
>
>>> you might also want to try getting the cygwin package docbook-xml42.
>>
>> 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!
>
> 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! :)

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.

Re: Building Documentation in Cygwin

[Tim Visher]

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!

-- 

In Christ,

Timmy V.

http://burningones.com/
http://five.sentenc.es/ - Spend less time on e-mail

Re: Building Documentation in Cygwin

[Junio C Hamano]

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.