Note: you can find this error again in a later build (2019, seven years later), because Git starts using DocBook 5 (instead of DocBook 4.5), as Asciidoctor 2.0 no longer works with the old one.
Git 2.24 (Q4 2019) clarifies the situation.
Documentation: Fixing a build using Asciidoctor 2
Our documentation toolkit is traditionally built on DocBook 4.5.
This version of DocBook is the latest version of DocBook based on DTD.
In 2009, DocBook 5 was introduced using namespaces, and its syntax is expressed in RELAX NG, which is more expressive and allows a wider variety of syntactic forms.
Asciidoctor, one of the alternatives for building our documentation, migrated support for DocBook 4.5 from the kernel in its latest release 2.0 and now only supports DocBook 5 in the main release.
DocBoook 4.5 Converter is still available as a separate component, but it is not available on most distributions.
That would not be a problem if it were not for the fact that we are using xmlto, which is still stuck in the era of DocBook 4.5.
xmlto performs DTD validation as part of the build process.
This is not problematic for DocBook 4.5, which has a valid DTD, but it clearly cannot work for DocBook 5, since no DTD can adequately express it fully Syntax.
In addition, even if xmlto does support RELAX NG validation, this will not be enough, because it uses libxml2-based xmllint , which causes problems with validating xmllint in RELAX NG .
Fortunately, there is an easy way forward: ask Asciidoctor to use the DocBook 5 backend and ask xmlto skip the check.
Asciidoctor has supported DocBook 5 since version 0.1.4 in 2013, and xmlto supports skipping validation, probably longer than that.
We also need to teach xmlto how to use DocBook XSLT style sheets with a namespace instead of the ones it normally uses without a namespace.
Typically, these style sheets are interchangeable, but those that do not have a namespace have an error due to which they do not automatically remove spaces from certain elements when using namespaces.
This leads to additional spaces at the beginning of the list items, which are harsh and unsightly.
We can do this by passing a custom style sheet with the -x option, which simply imports the style sheets in the namespace via the URL.
Any system with XML directory support will automatically search for this URL and instead refer to a local copy without us to know where this local copy is located. We know that anyone who uses xmlto already properly xmlto up directories, since the DocBook 4.5 DTD is used while checking is also viewed in directories.
All major Linux distributions distribute the necessary stylesheets and have built-in directory support, and Homebrew does the same, although requiring the installation of an environment variable to enable directory support.
If someone does not have directory support, xmlto (via xmllint ) has the ability to download stylesheets from the URLs in question, although this will probably work poorly enough to get attention.
People still have the opportunity to use the ready-made documentation that we send, so, fortunately, this should not be an obstacle.
Finally, we need to filter out some messages from other stylesheets that appear when dblatex is called in the CI job.
This tool removes namespaces much like unused DocBook style sheets and prints similar messages.
If we allow these messages to be printed with a standard error, our CI documentation will not be executed because we are checking the standard error for unexpected output.
Due to the dependence of dblatex on Python 2, we may need to reconsider its use in the future, in which case this problem may disappear, but it may be delayed until the next patch.
The last message we are filtering is related to libxslt on modern Debian and Ubuntu.
The patch they use to implement reproducible identifier generation also prints identifier generation messages.
Although this does not affect our current CI images, since they use Ubuntu 16.04, which is missing this patch, if we upgrade to Ubuntu 18.04 or modern Debian, these messages will appear and, like the messages above, will cause a CI error.