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

From: Todd Zullinger <tmz@pobox.com>
Date: Apr 5, 2019, 02:17 UTC
Message-ID: <20190405021721.GS4047@pobox.com>
In-Reply-To: <20190330210457.GC12419@genre.crustytoothpaste.net>

brian m. carlson wrote:

Show 16 quoted lines

> On Sat, Mar 30, 2019 at 02:00:14PM -0400, Todd Zullinger wrote:
>> 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.
> 
> I suspect this will be the easiest way forward.  If we produce
> semantically equivalent manpages, then this is also a lot nicer for
> people who would prefer not to have a full XML toolchain installed.

It's a good end goal. There are a number of differences in the output when using the manpage backend directly verus docbook and then xmlto. The way links to external html documents are presented is the main one which comes to mind. Maybe we can adjust that via asciidoctor-extensions.rb or something, I don't know.

Elsewhere in this thread, Jeff made the very valid point that we're probably wise to keep using the docbook/xmlto chain as long as we're supporting both asciidoc and asciidoctor. Unless it turns out that it's more work to coax asciidoctor (and the various 1.5 and 2.0 releases in common use) to work with that same docbook/xmlto chain than it is to do it directly, that is.

Show 14 quoted lines

>> Or we could see about adding a docbook45 converter, which
>> upstream noted as a possibility in the ticket¹ which dropped
>> docbook45 by default.
> 
> Another possibility, depending on how responsive the xmlto upstream is,
> is to add some sort of DocBook 5 support to it. This shouldn't be
> terribly difficult, although we'd have to disable validation. DocBook 5
> uses RELAX NG, and libxml2/xmllint's support for this has some bugs,
> such that it will mark some valid documents using complex interleaves as
> invalid. Still, if this is the direction we want to go, I have no
> problem adding this support.
> 
> Since we'd have a quite new Asciidoctor and a new xmlto, distros should
> have both around the same time.

Good point. It can't hurt to push for improvements across the tools. (Well, other than time being a limited resource and time you may spend on doc tools being time you can't spend on the hash conversion, which I imagine is a more interesting project.)

Thanks,

-- 
Todd