[PATCH] Documentation: fix build with Asciidoctor 2

["brian m. carlson" <sandals@crustytoothpaste.net>]

Our documentation toolchain has traditionally been built around DocBook
4.5.  This version of DocBook is the last DTD-based version of DocBook.
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 syntax forms.

Asciidoctor, one of the alternatives for building our documentation,
dropped support for DocBook 4.5 in its recent 2.0 release and now only
supports DocBook 5.  This would not be a problem but for the fact that
we use xmlto, which is still stuck in the DocBook 4.5 era.

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 its full
syntax.  In addition, even if xmlto did support RELAX-NG validation,
that wouldn't be sufficient because it uses the libxml2-based xmllint to
do so, which has known problems with validating interleaves in RELAX-NG.

Fortunately, there's an easy way forward: ask Asciidoctor to use its
DocBook 5 backend and tell xmlto to skip validation.  Asciidoctor has
supported DocBook 5 since v0.1.4 in 2013 and xmlto has supported
skipping validation for probably longer than that.

xmlto will still use the non-namespaced DocBook XSL stylesheets (which
are designed for DocBook 4.5) for building the documentation instead of
the namespaced ones (which are designed for DocBook 5).  This isn't
really a problem, since both forms are built from the same source and
can handle both versions, but it does mean that an ugly message about
the stylesheets stripping the namespace will be printed to standard
error.

Overall, however, this message is a relatively minor price to pay and it
means that we can continue to use the aging xmlto to drive our build
process, while still supporting newer tooling like Asciidoctor 2.

The differences in output between AsciiDoc 8.6.10 on master and
Asciidoctor 2.0.10 with this patch are, with one exception, all due to
whitespace, wrapping, or quoting and do not affect substantive content.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/Makefile | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 76f2ecfc1b..485f365cbf 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -197,11 +197,12 @@ ifdef USE_ASCIIDOCTOR
 ASCIIDOC = asciidoctor
 ASCIIDOC_CONF =
 ASCIIDOC_HTML = xhtml5
-ASCIIDOC_DOCBOOK = docbook45
+ASCIIDOC_DOCBOOK = docbook5
 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
 DBLATEX_COMMON =
+XMLTO_EXTRA += --skip-validation
 endif
 
 SHELL_PATH ?= $(SHELL)