STEM expression support

[OlivierJourdan]

Add STEM expression support to kroki.

For the record, this issue comes from this discussion: https://kroki.zulipchat.com/#narrow/stream/232085-users/topic/STEM.20expression.20support

[ggrossetie]

It might be interesting to use: https://github.com/DaveJarvis/KeenType

MathJax and KaTex both need a browser whereas KeenType is a pure Java library.

//cc @davejarvis

[ghost]

What's the actual problem you're trying to solve?

In my context (providing a tool for people who are not familiar at all with the asciidoctor toolchain install nor being able to rely on docker and using Windows in 99.9% cases) using kroki to generate the content that requires the more complex part of the installation seems to be the best solution.

KeenWrite's architecture was developed to be agnostic as to the input document format. See:

https://raw.githubusercontent.com/DaveJarvis/KeenWrite/main/docs/images/architecture/architecture.png

By mentioning "ASCII Doctor toolchain", it seems as though the toolchain is specific to ASCII Doctor (i.e., the first row in the architecture diagram), where a general solution would allow for any type of input document.

From what I experienced, I can have the STEM expressions correctly rendered w/o kroki for HTML rendering. But when it comes to PDF, from what I read in the documentation, I can't have it working on Windows (https://docs.asciidoctor.org/pdf-converter/latest/stem/#mathematical). Having kroki generate the SVG could be a solution.

Another issue that KeenWrite avoids is using a TeX-specific syntax. That is, LaTeX isn't the only way to typeset math. ConTeXt, SILE, ExTeX, and other non-LaTeX solutions exist. For this reason, KeenWrite only allows rendering of TeX-based macros, plus a few common ones.

KeenType is a port of NTS to generate SVG for rendering within a "preview" to give a "rough cut" of what the math will look like. KeenWrite uses KeenType to preview the math, but when producing a PDF file, leaves the final typesetting up to the user's TeX-based typesetter of choice: ConTeXt, LaTeX, ExTeX, etc.

On Windows, the typesetting is passed over to a containerized version of ConTeXt, using podman. Architecturally, it would take a bit of elbow grease, but not too much, to add other typesetters. On Linux, if ConTeXt is detected, it's used automatically; otherwise, users are prompted to install it either using podman or the system's package manager.

Here's a video of the installation process on Windows, which includes installing a container:

https://www.youtube.com/watch?v=8dCui_hHK6U

I don't know if it makes sense for you, my usage is probably far from the one kroki has been created for.

There's a ticket out for Mermaid diagrams to support math, which would be implemented independently of Kroki (since Kroki already supports Mermaid diagrams, this functionality would be "free").

https://github.com/mermaid-js/mermaid/issues/2776

There is a catch, though. Mermaid diagrams don't play well with pretty much any SVG renderer in existence (outside of a browser environment). This implies that no typesetting engine that generates a PDF (beyond browser-based solutions) is capable of rendering Mermaid diagrams. See:

https://github.com/mermaid-js/mermaid/issues/2485

KeenWrite uses EchoSVG, which has the best support that I know of, for rendering Mermaid diagrams as SVG. Still, it's not perfect. See version 3.3.2 where EchoSVG improvements were integrated:

https://github.com/DaveJarvis/KeenWrite/releases/tag/3.3.2

I would not advise adding STEM expression support to Kroki. It seems like solving the wrong problem.

---

In summary, why go from:

ASCII Doctor -> LaTeX -> PDF

When a more general solution could do:

ASCIIDoc/Markdown/rst/etc. -> LaTeX/ConTeXt/LuaTeX/SILE/etc. -> PDF/HTML/Plain Text

In effect:

Text Markup -> Typesetter -> Formatted Document

[OlivierJourdan]

Thanks for this very detailed reply. I don't get 100% of it because I need more comprehension of many related topics. Anyway, I'll try to explain my specific context better. I've been developing a toolkit for LabVIEW to help developers to generate text files using AsciiDoc syntax. The final goal is to create a PDF or HTML file.

The important note here is that LabVIEW developers are primarily scientists and engineers. They master LabVIEW environment and other scientific programming languages, but when it comes to dealing with ruby, JS, node, docker… It's more complicated. I include myself in this description.

The part of the toolkit that generates AsciiDoc files relies only on the LabVIEW environment. It's straightforward to make it work out of the box. When it comes to processing the Asciidoc file, that's another story… To provide a way to render the PDF/HTML file directly from LabVIEW, my toolkit installs a Ruby instance with the minimum tools needed to generate the PDF/HTML file. This is working quite well. The remaining issue was the generation of the diagrams. Installing all the layers needed to support all the diagram types is just impossible. Kroki is the best solution I found.

Kroki is my way of generalizing the process of picture generation independently of the user environment.

My original request for STEM support was made to find a more reliable way to generate STEM expression (this is currently not working with my solution when I'm generating PDFs).

That being said, I can understand that it's not the right way to fix my issue, and I'm fine if my request is declined.

Thanks again for your reply.

[ghost]

Have you tried these?

• https://github.com/asciidoctor/asciidoctor-latex
• https://github.com/asciidoctor/asciidoctor-diagram

The first one is a way of launching LaTeX to typeset ASCIIDoc files. The second one is a way of embedding diagrams as text within ASCIIDoc files.

[OlivierJourdan]

I can't remember trying asciidoctor-latex… I need to give it a try. Thanks.

[ghost]

Feel free to close the ticket, @OlivierJourdan, if this helps.