VR3 has supported Asciidoc rendering for some time, but it has not been completely satisfactory, especially when math rendering is wanted. I have been engaged in an overhaul of the design, and I want to put out some explanation of what the new code does. This is mainly for the benefit of @ekr, who will have to approve the PR to come, but it may be interesting to some others as well.
There have been two main areas of difficulty: 1) how to support several asciidoc processors, and 2) satisfactory math rendering. Let's discuss the the first one first. There are three main candidates for asciidoc processors. There are two Python ones, asciidoc and asciidoc3. And there is a Ruby processor, called asciidoctor. Asciidoctor is generally seen as the best and fastest Asciidoc processors out there. Fast is good because Asciidoc processors seem to be slow, but it has to be called as an external program, which means some additional latency as it loads and then reads an input file and writes an output file. Asciidoctor has been evolving the Asciidoc language - which is not really standardized yet - and it has been slowly adding features and syntax not shared by the two Python ones. asciidoc was the first Python processor, but until recently it could not run under Python 3. It also did not install with pip to the usual Python location but instead had to be copied to its own directory. Since this location could vary from one computer to another, it could be tricky or annoying to get it to work for everyone. Also, its version of the Asciidoc language had not evolved so it was becoming less compatible with asciidoctor. Asciidoc3 was essentially a fork originally intended to bring forth a Python 3 version of asciidoc. It was similar or identical in its api and in its language version. It was installable using pip, but on windows needed a post-install step which could go awry if not done right. Also, asciidoc3 didn't actually work with math rendering via Mathjax although it was supposed to. In the original Asciidoc support, I assumed that anyone might have one, two, or all three processors on their computer, and that they might prefer one or the other for reasons of performance or dialect. Because of the installation issues for the two Python processors, I arranged for a fallback to use them as external processors if they didn't work as internal ones. And you could specify that you preferred one or the other of the processors, but if they couldn't be found or imported, VR3 would try the others. As you can imagine, all this was tricky. In addition, the asciidoc3 API recently change in small but not quite compatible ways. Recently the situation has changed. Now asciidoc is pip-installable. The current version on PyPi is 10.0.2. Unfortunately it has a couple of bugs that keep it from working. I have written a monkeypatch for that, and conditional code to only use it if needed. I have also submitted a PR to asciidoc to fix the bugs. So now you can install asciidoc from PyPi and it will work in the new VR3 code, both now and when the bug-fixed version gets released. Also, there is an asciidoc roadmap to try to bring it up to parity with asciidoctor. It turns out that for use by VR3, you don't need run that asciidoc3 post-install step, so installation is simpler - it's just an ordinary pip install. I have written adapter code so that both asciidoc and asciidoc3 can be invoked in the same way. With this code in hand, I have eliminated support for running them as external processors if they do not import. This simplifies things. There was still the problem that asciidoc3 wouldn't render math with Mathjax. I found out I could fix this by writing a tweaked version of the "backend" configuration file. The same configuration file can be used by asciidoc, and it gives a strikingly better looking rendering. This configuation file will live in the leo/plugins/viewrendered3 directory. There remained one math-related bug, present in both asciidoc and asciidoc3. For an inline math expression, you have to add an extra backslash/space combination at the end of the expression. This is a bug in the processors, but at least such code will render correctly with asciidoctor too. So with the current state of the code, you can have any or all of the three Asciidoc processors installed. If you want to use the Ruby one, you have a setting to specify that. If you want to use an asciidocx processor, you can do that and if one doesn't work, VR3 will try the other. You have a setting to ask for one or the other to be tried first, if you care. These settings are the same ones that were present in the original version, so no one would need to change them. A few asciidoc settings have been removed because they didn't make sense any more. My plan is to wait a few days for any comments or requests here, and to do some more testing in case any tweaks are needed. I'll also test it on Linux. Then I'll put in a PR. I hope this essay will make the PR more understandable as to what it will be trying to accomplish. -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/8c72462f-1c86-4295-8a69-5829df5243d4n%40googlegroups.com.
