Subject: Re: [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>`

From: Todd Zullinger <[email-masked]>
Date: Sat, 30 Mar 2019 14:00:14 -0400

Hi,

brian m. carlson wrote:
> On Tue, Mar 26, 2019 at 09:06:03PM -0400, Todd Zullinger wrote:
>> There's still the matter of 2.0 dropping docbook45.  I'll
>> try to get around to testing 1.5.x releases with docbook5 to
>> see if they work reasonably well.  If not, we can add a
>> version check and set ASCIIDOC_DOCBOOK appropriately.
>> 
>> One other issue that crops up with docbook5 is that the
>> xmlto toolchain now outputs:
>> 
>>     Note: namesp. cut : stripped namespace before processing
>> 
>> as documented at
>> 
>>     https://docbook.org/docs/howto/howto.html#dbxsl
>> 
>> It's mostly an annoyance which we either want to strip out,
>> or pass an alternate docbook5 xsl, I think.  But I'm not
>> very familiar with the guts of the xml/docbook toolchains.
> 
> I'm quite familiar with this area, because I used DocBook and its
> stylesheets for my college papers. There are two sets of stylesheets,
> the namespaced ones (for DocBook 5) and the non-namespaced ones (for
> DocBook 4). They can be distinguished because the URLs (and typically
> the paths) use "xsl" (for non-namespaced) or "xsl-ns" (for namespaced).
> 
> xmlto by default uses the older ones, and assuming you have a reasonably
> capable XSLT processor, either set of stylesheets can be used, since
> they simply transform the document into the right type (although with a
> warning, as you've noticed).
> 
> Unfortunately, xmlto is hard-coded to use the non-namespaced stylesheets
> with no option to specify which to use, and it doesn't appear to be
> actively developed. There's an option to specify the stylesheet (-x),
> but it can't take a URL, since xmlto "helpfully" fully qualifies the
> path. That means we'd need to know the location on disk of those
> stylesheets in order to use them, since we can't rely on catalog
> resolution.

Thanks for the very useful docbook5/xmlto details!

The hard-coded use of the non-namespaced stylesheets in
xmlto is unfortunate.  I hadn't gotten far enough along to
run into that limitation of xmlto, so many thanks for saving
me from finding it myself.  I'm sure it would have taken me
far longer.

If it turns out that docbook5 causes us more pain than it's
worth, I suppose we could choose to use the builtin manpage
backend when using asciidoctor >= 2.

Or we could see about adding a docbook45 converter, which
upstream noted as a possibility in the ticket¹ which dropped
docbook45 by default.

It'll be some time before we can reasonably expect to only
support asciidoctor-2.x.  We'll have to see what method
involves the least ugly hacks to support asciidoc and the
various 1.5.x and 2.x versions of asciidoctor.

¹ https://github.com/asciidoctor/asciidoctor/issues/3005

-- 
Todd