Better fix for handling of literallayout elements

[rrthomas]

Since dblatex 0.3.3, literallayout has worked much better.

There is one remaining problem, namely that without an explicit setting of the parameter literal.class, all literallayout elements are rendered as monospaced. I have filed a bug (with patch) about this: https://sourceforge.net/p/dblatex/bugs/116/

This patch improves the handling of literallayout as follows:

1. Remove the override for the default dblatex template, as it’s no longer needed.

2. Remove the documentation of the problems which no longer exist.

3. In asciidoc-dblatex.sty, don’t use package alltt any more, as it’s not needed.

4. In docbook45.conf, set class="normal" for verse blocks (also in tables). This is the “correct” fix.

5. In asciidoc-dblatex.xsl, set literal.class="normal". This is to work around the remaining bug mentioned above.

[elextr]

If it makes the dblatex backend now depend on a specific version (or newer) that should be clearly documented in the installation section at least.

What do dblatex backend users think of this?

[rrthomas]

I don't think this is a problem: it depends on dblatex 0.3.3, which was released in 2012. The oldest versions of Debian and Ubuntu that are available both contain 0.3.4. (The current version is 0.3.10.)

I had a look to see where to update the installation instructions. In INSTALL.txt, dblatex is only mentioned under the Windows-specific instructions. In README.asciidoc, it says that AsciiDoc was tested on Xubuntu 10.04, so I guess it would make sense to update those tests, and hence the versions of every program tested? Or did you mean that I should mention the version in some other place?

[elextr]

Ok, well, if the latest LTS versions are newer than that then thats probably fine.

To progress this needs somebody (other than the OP) to indicate interest and to test it and find that it works. Contributions welcome.

[rrthomas]

Would you accept some more formal test I agree that simply saying "it works for me!" is not great. How about some small examples?

[elextr]

Thing is I can't test it, I don't have a Latex toolchain because of its size. As there are no issues from other users about how literal layout works it makes me cautious about making changes without others testing. Asciidoc Python is a stable tool and the last thing we want to introduce is unexpected breakages.

[rrthomas]

The issues are specifically documented in dblatex/dblatex-readme.txt. A LaTeX toolchain for dblatex should be a few hundred MB at most; is that a problem?

[rrthomas]

(I can offer you access to a LaTeX system if that would help.)

[mojavelinux]

In the age of Docker, not having access to a toolchain shouldn't be a reason for not testing something. There are plenty of Docker containers available that either have latex or on which you can quickly install latex.

[elextr]

Let me be blunt, if I say I cannot install latex that means I cannot install latex, by docker or any other means.

None of you have any knowledge of my current situation and what limitations it may be subject to.

Suggesting things that may be simple in your situation "a few hundred megabytes" or "a docker image" or any other mechanism just shows you do not understand.

[mojavelinux]

I'm not saying there aren't other limitations (surely there are, time being one of them). I'm just articulating that Docker provides a clean room environment for testing on Linux distributions that does not affect your underlying system. That doesn't mean it takes 0 effort. But it does provide a path that did not previously exist.

[mojavelinux]

(but hundreds of megabytes does make testing via a CI environment quite unfriendly).

I totally understand that testing LaTeX is not easy. My personal limitation is that I don't really understand it very well. Whenever I dabble with LaTeX, I usually get failures because I'm missing something (a LaTeX package) and it liters the current directory with tons of temp files.

[rrthomas]

Sorry if this wasn't clear:

(I can offer you access to a LaTeX system if that would help.)

I meant that I can offer you a login on another system.

[elextr]

@mojavelinux and @rrthomas I apologise for snapping at you, you are not responsible for my internet woes, its just incredibly frustrating. This is also why commits only happen when they can be done via the github web interface and why I have to insist that every PR has to be perfect and third party tested first.

I meant that I can offer you a login on another system.

@rrthomas I did miss that offer, thank you very much.

Actually I had hoped that somebody who used dblatex in anger would test it and say that it caused no regressions, I now use Ascidoctor for real work, and so I would only be making a few line test document anyway.

[rrthomas]

Maybe there are not many asciidoc users left! But I am one such (in fact, a recent convert), and as well as my own personal use I'm doing work for clients who also use it, so I can't easily migrate away, and hence have an interest in its continued support (though I am entirely sympathetic to its being considered mature).

[mojavelinux]

@elextr I've done my degree of snapping this past week, so I understand that it's nothing personal. I am sorry to hear about your internet woes. I know how incredibly frustrating that can be.

rrthomas wrote: Maybe there are not many asciidoc users left! But I am one such (in fact, a recent convert)

I'm very interested to know why you choose AsciiDoc Python instead of Asciidoctor. Although @elextr, and to some degree myself, still pay attention to this repository to keep the bottom dropping out from legacy installations (and perhaps other reasons), you have essentially chosen unsupported software. We've been very clear about that. Asciidoctor has taken over the direction of AsciiDoc, and all efforts around AsciiDoc are happening there (or stemming from it in one way or another). While you cannot run Asciidoctor on Python, you can run it on 3 platforms (Ruby, Java, and JavaScript).

I'm not challenging you so much as I'm curious. Why choose software that has been deprecated? Perhaps we aren't being clear enough about it's status. That's entirely possible. That's why I'm asking.

[rrthomas]

I did not know about Asciidoctor when I chose asciidoc. Asciidoc works well for me, so I have no reason to change. I chose it based on the choice of @aantonop for his book "Mastering Bitcoin". I used it successfully for a project of my own, and am now using it with another author, based on Andreas's merklebloom/bookbuilder system. This uses fop, so could use asciidoctor (but why fix what's not broken?).

Personally, I have a LaTeX background, so for my own project I used dblatex. Again, I have no particular reason to use asciidoctor to produce the DocBook.

In the event that the program is essentially unmaintained, I'd quite happily take it over or make a friendly fork, and thereby get fixes into GNU/Linux distributions; I've done this with several other program.

[mojavelinux]

I did not know about Asciidoctor when I chose asciidoc. Asciidoc works well for me,

That actually tells me what I need to know. We are not communicating well enough that Asciidoctor is AsciiDoc. By choosing Asciidoctor, you are choosing AsciiDoc. It's just the supported version of AsciiDoc as opposed to this legacy implementation.

so I have no reason to change

The reason to change is that this software is no longer supported. I guess if you don't want to use supported software, then that's fine. But that's a pretty strong reason to change, IMO.

I'd quite happily take it over or make a friendly fork

Asciidoctor is the continuation of AsciiDoc Python. It's essentially the fork. Why create another fork when a fork already exists? Unless there is something about Asciidoctor that you really don't like, I don't see any reason to go backwards and pick up a legacy project to move it forward when that's exactly what the last 5 years of Asciidoctor have been all about.

[elextr]

based on Andreas's merklebloom/bookbuilder system.

Due to the openness of the Asciidoc implementation and its flexibility people have evolved quite complex infrastructure around it. That handles todays use-case beautifully, but in doing so have tied themselves into that implementation. Unfortunately I see the same happening with Asciidoctor too.

In the case of Asciidoc Python, one of the other considerations is the end of life of Python 2, at least by the Python crew, 1 Jan 2020 has been officially declared as DDD (drop dead date) after which they will not provide any further updates or releases. There have been a couple of attempts at converting Asciidoc Python to Python 3, but the subtleties of differing regular expression handling of ASCII text and Unicode text between Python 2 and Python 3 makes it a trickier proposition than it may at first appear. To date all attempts appear to have run out of steam before getting a working (ie passes the test suite) result.

[rrthomas]

Asciidoctor is the continuation of AsciiDoc Python. It's essentially the fork. Why create another fork when a fork already exists? Unless there is something about Asciidoctor that you really don't like, I don't see any reason to go backwards and pick up a legacy project to move it forward when that's exactly what the last 5 years of Asciidoctor have been all about.

I hadn't realised this. In that case, perhaps you should be deprecating asciidoc more, asking GNU/Linux distros to remove it etc.? I did not get the impression that it was obsolescent, merely that it was mature. And I should look into switching.

[mojavelinux]

elextr wrote: Due to the openness of the Asciidoc implementation and its flexibility people have evolved quite complex infrastructure around it.

And that's why we stick around...to help them out. But anything new should not be starting with AsciiDoc Python. That's really my point.

In the case of Asciidoc Python, one of the other considerations is the end of life of Python 2

Great point.

Unfortunately I see the same happening with Asciidoctor too.

There will always be coupling to implementations. That's just the nature of software. I've seen it with every platform I've worked on. The huge difference is that the maintainers of Asciidoctor (namely myself) intend to offer long-term support for it. Stuart never signaled he had any intention to do that for AsciiDoc Python and why it ultimately faded out (and the format was only saved by Asciidoctor coming online).

rrthomas wrote: In that case, perhaps you should be deprecating asciidoc more, asking GNU/Linux distros to remove it etc.?

I don't think we're quite ready to go nuclear yet, but the 2020 deadline of Python 2 EOL will probably force the issue.

I did not get the impression that it was obsolescent, merely that it was mature.

The other issue is that AsciiDoc Python extremely slow. Asciidoctor is 100x as fast as AsciiDoc Python.

One of the main problems with AsciiDoc Python is that is has a really convoluted project structure, making it hard to work with. We still haven't figure out how to run the website build to completion, which is why the website never gets updated. It uses some obsolete build system that I just cannot understand how to use properly.

If you are looking for a replacement for a2x, you could consider using asciidoctor-fopub. It's basically a2x reimplemented using the Java stack (so less system dependencies). See https://github.com/asciidoctor/asciidoctor-fopub

But to be honest, all a2x is really is a string of commands that invokes the DocBook toolchain. You can probably just use a shell script to accomplish the same thing without being bound to AsciiDoc Python.