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

From: Todd Zullinger <tmz@pobox.com>
Date: Mar 23, 2019, 19:27 UTC
Message-ID: <20190323192756.GK4047@pobox.com>
In-Reply-To: <CAN0heSpJvsPm_qq63VumokmyOG6N=6fwMZRqf_9CzoCeHsdiyQ@mail.gmail.com>

Hi,

Martin Ågren wrote:

Show 18 quoted lines

> On Wed, 20 Mar 2019 at 19:17, Todd Zullinger <tmz@pobox.com> wrote:
>> Martin Ågren wrote:
>>> {litdd} now renders as &#x2d;&#x2d. We should find some other way to
>>> produce '--'. This should then be a simple change, as we're already
>>> providing this attribute inside an `ifdef USE_ASCIIDOCTOR`.
>>
>> I noticed that one and didn't work out a good fix, but it
>> sounds like you have one in mind.  That's great.
>>
>>> "+" becomes "&#43;". I didn't immediately find where we do that.
>>
>> For this one, I was working on replacing "{plus}" with `+`
>> (along with " " and "-").  That's probably not ideal though.
> 
> The "plus" and "litdd" issues seem like they can be solved by doing:
> 
>   ASCIIDOC_EXTRA += -aplus='+'
>   ASCIIDOC_EXTRA += -alitdd='\--'

Hmm, setting litdd makes the html generate an em dash followed by a zero width space (in 1.5.8 and 2.0.0)

I updated my system to asciidoctor-2.0.0 last night and now I can't even generate the man pages properly, because the docbook45 converter was removed. I'll have to see if I missed some other required update. :/

> It would probably be worthwhile to try 1.5.7+ to see how much that
> improves things. Seems like you're already underway there.

Yeah, before I knew how soon 2.0.0 was coming, I updated to 1.5.8 and built the various Fedora packages which require it to see how they handled it. Almost all of the changes were fixes to bugs in previous versions. And the one which was not is likely to be fixed in 2.0.0 according to asciidoctor maintainer Dan Allen.

Have you looked at diffing the html output as well? It seems like we'll need to check it as well to be sure any fixes to the manpage output don't have a negative impact on the html output, and vice versa.

I used 'links -dump' output for comparison of the various Fedora packages which currently build with asciidoctor. It's not perfect. It could miss visual changes which might be important when viewed in a graphical browser. But it was better than trying to diff the html files directly. :)

We probably also want to check the validity of links within the docs, as one of the changes in 1.5.8 caused breakage of cross interdocument references. (This is the change I noted above which should be fixed in 2.0.0.)

It'll be quite a while until most systems with asciidoctor 1.5.x are gone. I doubt that upgrading to even 1.5.8 is suitable for the currently released Fedora versions due to incompatible changes. I am going to try and get 2.0.0 into Fedora 30, but the deadline for changes has just passed, so I may not be able to do so. If not, it'll be 6-8 months until a released version of Fedora has an asciidoctor newer than 1.5.6.1.

All that is just to say that even if newer asciidoctor fixes many of the issues we've seen it will still be a long time before we can reasonable default to asciidoctor or drop asciidoc support.

For what it's worth, the Fedora asciidoc packages moved to python3 using https://github.com/asciidoc/asciidoc-py3. That's not very active, but it should at least keep asciidoc alive beyond the approaching python2 EOL.

-- 
Todd