Jeff King <peff@xxxxxxxx> writes: > On Fri, Sep 13, 2019 at 01:52:40AM +0000, brian m. carlson wrote: > >> 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. > >> 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?). > >> 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? > >> 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/? > >> --- >> 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.
