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

On Sun, Sep 08, 2019 at 10:24:24PM +0000, brian m. carlson wrote:

Trying again, I'm able to reproduce this.  I found the cause, which is
in the stylesheets.  XSLT stylesheets have the ability to specify
elements from which whitespace should be stripped (using the
xsl:strip-space directive).  In the DocBook stylesheets, listitem is
specified as such an element, so the whitespace there should be
stripped.

However, in DocBook 5, our elements are in a namespace.  Therefore, the
unnamespaced stylesheets specify only "listitem", not "d:listitem", like
the namespaced stylesheets do.  Because this happens right after the
tree has been constructed "but before it is otherwise processed by XSLT"
and isn't affected by the EXSLT extension that allows re-parsing the
modified tree, then we end up with the whitespace that we don't want.

First off, thank you again for your explanations. I dread digging into
how anything related to docbook or xml works, so having you serve it up
on a silver platter is a delight. :)

2. We can force xmlto to use a custom stylesheet with "-x" that merely
imports the DocBook 5 stylesheets using a URL.  If the user has the
DocBook 5 stylesheets installed and XML catalogs configured (the default
on Linux distributions), then everything will just work and the system
will resolve it to the local copy.  If, however, things are not properly
configured, this will result in multiple network downloads for each
manual page.

Isn't this already the case just with the docbook DTDs? I.e., if you
don't have a catalog entry, it is up to the tool (xmlto in this case) to
either fail or try to fetch it. That seems like the best we can do. And
as you note, this typically just works out of the box on modern
installs. Of course people may want to build on non-modern ones, but
IMHO we should probably be more aggressive about dropping legacy support
in the documentation and pointing people to the pre-formatted pages.

My personal preference is #2; I think that seems like the best choice
forward.  XML catalogs are well understood and well configured on Linux
distributions.  Homebrew supports them adequately, but you have to add
an environment variable to your shell configuration to enable them.  Of
course, if you're doing _anything_ with XML, you'll have them enabled.

Yeah, agreed.

-Peff