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 <sand...@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)
