On Sat, Sep 07, 2019 at 05:07:46PM +0000, brian m. carlson wrote:
> 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.
These messages from 'xmlto' look like these, and there are a lot of
them:
Note: namesp. cut : stripped namespace before processing Git User Manual
Note: namesp. cut : stripped namespace before processing git-sh-setup(1)
Note: namesp. cut : stripped namespace before processing
git-get-tar-commit-id(1)
Unfortunately, these messages to standard error cause our CI builds to
fail [1].
In the Documentation build job we check that there was nothing printed
to standard error during 'make doc', in order to catch warnings that
are potential signs of a mis-rendered documentation, but do not cause
any asciidoc/asciidoctor/xmlto commands (and thus 'make doc') to fail.
Now, a few recent messages to standard error that indeed were signs of
mis-rendered docs [2] looked like this:
asciidoctor: WARNING: api-config.txt: line 232: unterminated listing block
i.e. they came from Asciidoctor and were all-caps warnings.
OTOH, these "stripped namespace" messages come from 'xmlto', are not
warnings but have that "Note:" prefix, and, trusting that you did
check the results thoroughly, are apparently not a sign of any
rendering issues. So I think it's safe to ignore them and this patch
should strip them from 'make doc's output in
'ci/test-documentation.sh'.
Related: after this patch we might want to update the CI builds to use
Asciidoctor 2 instead of sticking with 1.5.8.
[1] With Asciidoctor 1.5.8:
https://travis-ci.org/szeder/git/jobs/582294090#L2085
With an additional patch on top to use Asciidoctor 2:
https://travis-ci.org/szeder/git/jobs/582294243#L2066
[2] See 'git log -3 b373e4d29b'
