Question

编译git时出现以下错误：

make[2]: Leaving directory `/home/xxx/git-master'
    XMLTO git-add.1
xmlto: /home/xxx/git-master/Documentation/git-add.xml does not validate (status 3)
xmlto: Fix document syntax or use --skip-validation option
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
/home/xxx/git-master/Documentation/git-add.xml:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
validity error : Could not load the external subset "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
Document /home/xxx/git-master/Documentation/git-add.xml does not validate
make[1]: *** [git-add.1] Error 13
make[1]: Leaving directory `/home/xxx/git-master/Documentation'
make: *** [doc] Error 2

主要问题是什么？

Answer 1

晚会，但在cygwin上，验证所需的包是docbook-xml45（如DTD URI暗示的那样，docbook / xml / 4.5 / docbookx.dtd）

Answer 2

在OSX（Mountain Lion）上我必须这样做：

brew install asciidoc
brew install xmlto
brew install docbook   

# then (as prompted by brew...)
#
# If you intend to process AsciiDoc files through an XML stage
# (such as a2x for manpage generation) you need to add something
# like:
#
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
#
# to your shell rc file so that xmllint can find AsciiDoc's
# catalog files.

brew install docbook-xsl

（感谢Nathan提供必要的提示）。＃6chars

Answer 3

对于git来说，这似乎是一个反复出现的问题。在寻找解决方案（今天）时，我在几个论坛中遇到了它。（Linux，Cygwin，Mac OS）。问题总是一样的：缺乏一本好的docbook目录。不幸的是，安装相应的目录很大程度上取决于您的安装，并且缺少良好目录的方法不止一种。

几年前发布了一个糟糕的目录。卸载＆amp;安装更新。
构建目录的程序包部分失败。删除＆amp;重新安装包。
尚未安装安装目录的软件包，软件包工具也没有照顾您。

选项3就在我身边。我已经安装了brew，所以 sudo brew安装docbook sudo docbook-register 为我照顾这个问题。

或者，可以单独下载可用的文档。

Answer 4

jonseymour回答帮助我在Mac OS X El Capitan

导出XML_CATALOG_FILES = / usr / local / etc / xml / catalog我这样做

sudo vim ~/.bash_profile

(in an empty line insert)
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog

save & exit

. ~/.bash_profile

解决

Answer 5

注意：您可能会在较新的版本（2019年，七年后）中再次发现此错误，因为Git开始将DocBook 5（而不是DocBook 4.5）用作Asciidoctor 2.0 不再适用于较旧的版本。
Git 2.24（2019年第四季度）澄清了这种情况。

请参见commit f6461b8的brian m. carlson (bk2204)（2019年9月15日）。
^{（由Junio C Hamano -- gitster --在commit faf5576中合并，2019年10月6日）}

文档：使用Asciidoctor 2修复构建

我们的文档工具链传统上是围绕DocBook 4.5构建的。
  此版本的DocBook是DocBook的最后一个基于DTD的版本。
  2009年，使用名称空间引入了DocBook 5，它的语法以RELAX NG表示，它具有更强的表达能力，并支持多种语法形式。

Asciidoctor是构建文档的替代方法之一，在最近的2.0版本中将对DocBook 4.5的支持移出了核心，现在仅在主版本中支持DocBook 5。   DocBoook 4.5转换器仍然可以作为单独的组件使用，但是没有   大多数发行包中都可用。
  但这不是问题，而是因为我们使用了xmlto，它仍然停留在DocBook 4.5时代。

xmlto在构建过程中执行DTD验证。
  对于具有有效DTD的DocBook 4.5而言，这没有问题，但显然   无法用于DocBook 5，因为没有DTD可以充分表达其全部内容   语法。
  另外，即使xmlto支持RELAX NG验证，也还不够，因为它使用基于libxml2的xmllint进行验证，这在验证{ {1}}。

幸运的是，有一个简单的方法：让Asciidoctor使用其DocBook 5后端并告诉RELAX NG跳过验证。
  自2013年v0.1.4起，Ascidoctor已支持DocBook 5，而xmlto已支持   跳过验证的时间可能更长。

我们还需要教xmlto如何使用命名空间的DocBook XSLT样式表，而不是通常使用的非命名空间样式表。
  通常，这些样式表是可以互换的，但是未命名空间的样式表存在一个错误，导致使用命名空间时，它们不会自动从某些元素中删除空格。
  这会在列表元素的开头产生额外的空格，即   刺耳且难看。

我们可以通过传递带有xmlto选项的自定义样式表来实现此目的，   只需通过URL导入命名空间样式表即可。
  任何支持XML目录的系统都会自动查找该URL，然后   而是引用本地副本，而无需我们知道该在哪里   本地副本位于。我们知道使用-x的任何人都已经   自从DocBook 4.5 DTD在   验证也通过目录进行查找。
  所有主要的Linux发行版都分发了必要的样式表，并内置了   目录支持，而Homebrew也是如此，尽管要求   设置环境变量以启用目录支持。

在某人不支持目录的情况下，xmlto（通过xmlto）可以从所讨论的URL下载样式表，尽管这样做的效果可能很差，无法吸引注意。
  人们仍然可以选择使用我们提供的预建文档，因此，这不应该成为障碍。

最后，我们需要从CI作业中调用dblatex时发生的其他样式表中过滤掉一些消息。
  该工具会像未命名空间的DocBook样式表一样剥离名称空间，并打印类似的消息。
  如果我们允许将这些消息打印为标准错误，   我们的文档CI作业将失败，因为我们检查了以下标准错误   意外的输出。
  由于xmllint对Python 2的依赖，我们将来可能需要重新使用它，在这种情况下，这个问题可能会消失，但是可以推迟到以后的补丁程序中。

我们过滤的最终消息归因于现代Debian上的dblatex和   Ubuntu。
  他们用于实现可复制ID生成的补丁程序还会打印有关ID生成的消息。
  虽然这不会影响我们当前的CI映像，因为它们使用的是Ubuntu 16.04，   缺少此补丁，如果我们升级到Ubuntu 18.04或现代Debian，   这些消息将出现，并且与上述消息一样，会导致CI失败。

git编译：Documentation / git-add.xml不验证

5 个答案:

文档：使用Asciidoctor 2修复构建