Re: [PATCH v2] Documentation: fix build with Asciidoctor 2

Jeff King [off-list ref] writes:

On Fri, Sep 13, 2019 at 01:52:40AM +0000, brian m. carlson wrote:

quoted

We also need to teach xmlto how to use the namespaced DocBook XSLT
stylesheets instead of the non-namespaced ones it usually uses.
Normally these stylesheets are interchangeable, but the non-namespaced
ones have a bug that causes them not to strip whitespace automatically
from certain elements when namespaces are in use.  This results in
additional whitespace at the beginning of list elements, which is
jarring and unsightly.

Thanks, this fixed most of the rendering problems I saw from the earlier
patch.

quoted

We can do this by passing a custom stylesheet with the -x option that
simply imports the namespaced stylesheets via a URL.  Any system with
support for XML catalogs will automatically look this URL up and
reference a local copy instead without us having to know where this
local copy is located.  We know that anyone using xmlto will already
have catalogs set up properly since the DocBook 4.5 DTD used during
validation is also looked up via catalogs.  All major Linux
distributions distribute the necessary stylesheets and have built-in
catalog support, and Homebrew does as well, albeit with a requirement to
set an environment variable to enable catalog support.

This did give me one minor hiccup: I had the debian docbook-xsl package
installed, but not docbook-xsl-ns. The error message was pretty standard
for XML: obvious if you know what catalogs are, and utterly confusing
otherwise. :)

Everything worked fine after installing docbook-xsl-ns. I wonder if
could/should provide some guidance somewhere (maybe in INSTALL, which
discusses some catalog issues?).

quoted

Finally, we need to filter out some messages from other stylesheets that
when invoking dblatex in the CI job.  This tool strips namespaces much

s/that/that occur/ or something?

quoted

like the unnamespaced DocBook stylesheets and prints similar messages.
If we permit these messages to be printed to standard error, our
documentation CI job will because we check standard error for unexpected

s/will/will fail/?

quoted

---
 Documentation/Makefile    | 4 +++-
 Documentation/manpage.xsl | 3 +++
 ci/test-documentation.sh  | 2 ++
 3 files changed, 8 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/manpage.xsl

Running with this patch on asciidoctor 2.0.10, plus Martin's recent
literal-block cleanups, plus his refmiscinfo fix, I get pretty decent
output from:

  ./doc-diff --from-asciidoc --to-asciidoctor origin HEAD

The header/footer are still a little funny (but I think Martin said that
he needs to update the refmiscinfo patches for later versions of
asciidoctor, which is probably what's going on here):
...
So overall, I think we're getting very close to parity.

Thanks, both.  Have queued with your log message typofixes.