Hi,
Martin Ågren wrote:
> On Wed, 20 Mar 2019 at 19:17, Todd Zullinger <tmz@xxxxxxxxx> wrote:
>> Martin Ågren wrote:
>>> {litdd} now renders as --. 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 "+". 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
