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

编译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

---

主要问题是什么？

这似乎是git经常遇到的问题。在寻找解决方案的过程中（今天），我在几个论坛上偶然发现了它。（Linux、Cygwin、Mac OS）。问题总是一样的：缺少一个好的docbook目录。不幸的是，安装合适的目录在很大程度上取决于您的安装，缺少好的目录的方法不止一种

几年前发布了一个坏目录。卸载并安装更新

生成目录的包部分失败。卸下并重新安装软件包

安装目录的软件包尚未安装，软件包工具也没有照顾到您

选项3就是我的位置。我已经安装了brew，所以 sudo brew安装docbook sudo docbook寄存器 帮我解决了这个问题

---

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

派对迟到了，但在cygwin上，您需要验证的软件包是

docbook-xml45

（如OSX（Mountain Lion）上的DTD URI所示，docbook/xml/4.5/docbookx.DTD）

，我必须这样做：

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

（感谢内森提供了必要的提示）。

---

#6chars

琼西摩的回答在Mac OS X El Capitan中帮助了我

要导出XML\u CATALOG\u文件=/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

---

已解决

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

参见作者（2019年9月15日）
（于2019年10月6日合并）

文档：使用AscidActor 2修复构建 我们的文档工具链传统上是围绕DocBook 4.5构建的。
此版本的DocBook是最后一个基于DTD的DocBook版本。
2009年，DocBook 5使用名称空间引入，其语法用RELAXNG表示，RELAXNG更具表现力，并允许更广泛的语法形式

AscidActor是构建文档的备选方案之一，它在最近的2.0版本中将对DocBook 4.5的支持移出了核心，现在只在主版本中支持DocBook 5。
Docbook 4.5转换器仍然作为一个单独的组件提供，但这不是 在大多数发行版软件包中提供。
如果不是因为我们使用xmlto，这不会是一个问题，因为xmlto仍然停留在Docbook4.5时代

xmlto

在构建过程中执行DTD验证。
这对于Docbook4.5来说并没有问题，因为它有一个有效的DTD，但它显然 无法用于DocBook 5，因为没有DTD可以充分表达其完整的 语法。
此外，即使

xmlto

确实支持

RELAX NG

验证，这也不够，因为它使用基于libxml2的

xmllint

来进行验证，这在验证

RELAX NG

中的交织时存在已知问题

幸运的是，有一种简单的方法：让AscidActor使用其DocBook 5后端，并告诉

xmlto

跳过验证。
自2013年v0.1.4版以来，Asciidector一直支持DocBook 5，xmlto也支持DocBook 5 跳过验证的时间可能更长

我们还需要教授

xmlto

如何使用带名称空间的DocBook XSLT样式表，而不是它通常使用的不带名称空间的样式表。
通常，这些样式表是可以互换的，但没有名称空间的样式表有一个缺陷，导致它们在使用名称空间时不会自动从某些元素中去除空白。
这将导致列表元素开头出现额外的空白，即 刺耳难看

我们可以通过传递一个带有

-x

选项的自定义样式表来实现这一点 只需通过URL导入带名称空间的样式表。
任何支持XML目录的系统都会自动查找此URL并 请参考本地副本，而无需我们知道其位置 本地副本位于。我们知道，任何使用

xmlto

的人都会 在使用DocBook 4.5 DTD之后，是否正确设置了目录 验证也可通过目录查询。
所有主要的Linux发行版都分发必要的样式表，并具有内置的 目录支持，自制软件也支持，尽管需要 设置环境变量以启用目录支持

万一有人缺少对目录的支持，

xmlto

（通过

xmllint

）也可以从相关URL下载样式表，尽管这可能会表现得很差，足以引起注意。
人们仍然可以选择使用我们提供的预构建文档，所以令人高兴的是，这不应该成为一个障碍

最后，我们需要过滤掉在CI作业中调用dblatex时出现的其他样式表中的一些消息。
此工具剥离名称空间，与未命名的DocBook样式表非常相似，并打印类似的消息。
如果我们允许将这些消息打印为标准错误， 我们的文档CI作业将失败，因为我们检查了标准错误 意外输出。
由于

dblatex

对Python2的依赖，我们可能需要在将来重新考虑它的使用，在这种情况下，这个问题可能会消失，但这可能会延迟到将来的补丁

我们筛选的最后一条消息来自现代Debian和Linux上的

libxslt

Ubuntu。
他们用于实现可复制ID生成的补丁也会打印有关ID生成的消息。
虽然这不会影响我们当前的CI图像，因为它们使用的是Ubuntu 16.04 没有这个补丁，如果我们升级到Ubuntu 18.04或现代Debian， 这些信息是