mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <>
To: "Ævar Arnfjörð Bjarmason" <>
Cc: "Randall S. Becker" <>,
Subject: Re: Documentation Breakage at 2.5.6
Date: Wed, 6 Dec 2017 03:48:33 -0500	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

On Wed, Dec 06, 2017 at 09:14:57AM +0100, Ævar Arnfjörð Bjarmason wrote:

> > I'm trying to upgrade the NonStop port from 2.3.7 upward eventually to
> > 2.15.1 and hit a snag on documentation. The xmlto component is a bit new to
> > me and I hit the following error:

Did it work before in v2.3.7? If so, can you bisect to the breakage?

> >     XMLTO git-remote-testgit.1
> > xmlto: /home/git/git/Documentation/git-remote-testgit.xml does not validate
> > (status 3)
> > xmlto: Fix document syntax or use --skip-validation option
> > I/O error : Attempt to load network entity
> >
> > /home/git/git/Documentation/git-remote-testgit.xml:2: warning: failed to
> > load external entity
> > ""
> > D DocBook XML V4.5//EN"
> > ""
> >
> > ^
> > I/O error : Attempt to load network entity
> >
> > warning: failed to load external entity
> > ""
> > validity error : Could not load the external subset
> >

Those URLs are the "official" names of the docbook DTDs. But normally
you'd have a local copy, along with a mapping from the official name to
your local copy. The XML term for that mapping is a "catalog", and it
looks something like this:

  $ grep oasis-open /etc/xml/catalog
  <delegateSystem systemIdStartString="" catalog="file:///etc/xml/docbook-xml.xml"/>

That just points to another local catalog, which has:

  $ grep 4.5/docbookx.dtd /etc/xml/docbook-xml.xml
  <delegateSystem systemIdStartString="" catalog="file:///usr/share/xml/docbook/schema/dtd/4.5/catalog.xml"/>
  <delegateSystem systemIdStartString="" catalog="file:///usr/share/xml/docbook/schema/dtd/4.5/catalog.xml"/>

So my guess is that your problem is one of:

  1. You don't have docbook 4.5 installed on your system.


  2. You don't have a correctly built catalog file, or xmlto isn't
     pointing to it for some reason (on Debian, this is normally built
     by the post-install script of packages that contain xml).

And xmlto (actually, probably xsltproc that it's calling) is unwilling
or unable to hit the network to pull down those entities.

Those are all somewhat vague guesses based on past troubles I've had
with broken xml setups. I'm far from an expert on xml processing (and
I'd just as soon keep it that way).

> I don't know if this helps, but here with xmlto 0.0.28 on Debian if I
> apply this the docs still build:
>     diff --git a/Documentation/texi.xsl b/Documentation/texi.xsl
>     index 0f8ff07eca..332a65558d 100644
>     --- a/Documentation/texi.xsl
>     +++ b/Documentation/texi.xsl
>     @@ -7,7 +7,7 @@
>      <xsl:output method="xml"
>                 encoding="UTF-8"
>                 doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
>     -           doctype-system="" />
>     +           doctype-system="" />
> So whatever's needing to remote fetch those resources doesn't seem to
> cause the same error for me.

I think that would come into play only if you try to build
"", which isn't one of the default targets.

The string that Randall is seeing is in git-remote-testgit.xml, so it's
probably be generated by the "docbook" backend of asciidoc.

One alternative is to try to avoid docbook entirely. The only way to get
manpages with asciidoc is to generate docbook and then process it, but:

 - you can generate HTML directly (and "make -C Documentation html" does
   this). Perhaps not as nice, but you still at least have some

 - asciidoctor can generate manpages directly. I don't think our
   Makefile supports that now, but it might not be too hard to hack in
   (we already have some basic asciidoctor support). I'm not sure how
   hard it would be to get Ruby running on NonStop

And of course one final option is to generate the manpages elsewhere and
copy them in, since they're platform-independent. In fact, that's what
quick-install-man should do (you just have to clone Junio's git-manpages
repository -- see the INSTALL file).


  reply	other threads:[~2017-12-06  8:48 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-12-06  4:12 Documentation Breakage at 2.5.6 Randall S. Becker
2017-12-06  8:14 ` Ævar Arnfjörð Bjarmason
2017-12-06  8:48   ` Jeff King [this message]
2017-12-06 15:43     ` Randall S. Becker
2017-12-08 22:29       ` Junio C Hamano
2017-12-08 22:47         ` Randall S. Becker

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).