Avoiding manual installation of Jsyntrax since it's available from Maven for asciidoctor-diagram-java?

[inponomarev]

Hello,

the new version of asciidoctor-diagram which utilizes jsyntrax server from asciidoctor-diagram-java works nicely and very fast!

The only thing is that it's still necessary to manually download, unzip and set DIAGRAM_JSYNTRAX_HOME environment variable. Can we avoid doing this since asciidoctor-diagram-java has jsyntrax as a transitive Maven dependency, just like PlantUML and ditaa?

Is it ok to use the provided jsyntrax implementation in case there is no DIAGRAM_JSYNTRAX_HOME?

[pepijnve]

For PlantUML and Ditaa this is done by repackaging the jars in a gem. While convenient, it's a bit tedious for me to have to track PlantUML versions and build the jar.

I don't think there's a way to express a maven dependency in a gem file, but I'll check.

[inponomarev]

Ah I see... As a maintainer of jsyntrax I can promise that I will make all the necessary PRs to AsciiDoctor projects if updates are needed. Moreover, as jsyntrax is quite a stable tool for quite a specific use case, frequent updates are not expected. If I can help you I'll be happy to.

[pepijnve]

Sorry for the delayed response, I was on vacation abroad.

For plantuml and ditaa I bundled up the full set of dependencies in a rubygem. A single Ruby file provides an Array constant containing the list of jar files. The extension code then tries to require this file in a begin/rescue block to obtain the classpath.

If a similar gem is created for jsyntrax, then I can adapt the extension code for jsyntrax to do the same thing.

[pepijnve]

@inponomarev your changes have been integrated. Just one question regarding how you would like to proceed with this going forward. Ideally, the wrapper ruby gem would be generated from the https://github.com/atp-mipt/jsyntrax and published to rubygems.org whenever you make a new release. If you would like to do that, I can add you as owner to https://rubygems.org/gems/asciidoctor-diagram-jsyntrax after which you will be able to push new versions.

Building a ruby gem is pretty straightforward. You basically run gem build in the directory containing the .gemspec file. When that's done, you run gem push <gem filename> to push the version to rubygems.org.

[pepijnve]

I was just checking the gem contents. It doesn't seem to be the release jar from the jsyntrax project. Possibly a manually created combined jar? If we keep the jar file in this repo I would prefer to be able to verify the artifact by checksum against some canonical download. Don't want another xz debacle 😬

[inponomarev]

Yeah it's a manually created jar with shaded libraries, just like I warned you, so perhaps we were a bit too quick to merge this.

But no worries, I can properly handle it as I am the maintainer of jsyntrax. What would you want? I can publish jsyntrax-shaded-X.XX.jar on Maven, for example. Alternatively, I can commit all the dependencies (Batik, apache-commons-cli and something else) into the folder. I think that the first approach is safer as it must save us from possible jar hell.

What do I have to do?

[inponomarev]

Will https://github.com/atp-mipt/jsyntrax/releases/download/1.38/jsyntrax-shaded-1.38.jar work as a "canonical download"?

[pepijnve]

I've made some improvements already. PlantUML needs Batik as well, so I split that off into a separate gem that Jsyntrax and PlantUML can share. I replaced the shaded jar with the set of jars from the Jsyntrax github release archive.

I was a bit surprised that the entire Groovy runtime is included. Seems like serious overkill for a simple parser.

[inponomarev]

I was a bit surprised that the entire Groovy runtime is included. Seems like serious overkill for a simple parser.

The story behind is that this project was created as a backwards-compatible Java reimplementation and replacement of kevinpt/syntrax. The original Syntrax scripts were Python scripts, so it seemed natural at the time to simply substitute Python with Groovy. However, as I see now, a much simpler parser could work (and be much safer, by the way).

Yes, JSyntrax is far from perfect. For example, the fonts and text styling support is buggy, and the DSL itself is not very consistent. It seems that fixing all these issues without breaking compatibility with the original Python Syntrax is not possible. Despite these flaws, JSyntrax works where it is supposed to (one publicly available example is here).

I prefer to evolve 'micro-projects' like JSyntrax through the efforts of my students. Maybe one day we will see 'JSyntrax 2.0', with a revised external DSL instead of Groovy, proper text styling support, and an improved configuration format. However, this will probably take 2-3 years. In the meantime, I would like people to enjoy the current Syntrax diagrams in their .adoc files without difficulties.

[inponomarev]

Hi @pepijnve , it is still not working as desired for us (see asciidoctor/asciidoctorj-diagram#53). Is something missing from my side? How can I help?

[pepijnve]

I'm not entirely sure how the asciidoctorj variant manages the external dependencies. It's maintained by @robertpanzer, not by me.

[inponomarev]

Hi @pepijnve I am already using the new version of asciidoctorj-diagram, and everything's working as desired. Thank you very much for your fast and friendly support!

Just one question regarding how you would like to proceed with this going forward. Ideally, the wrapper ruby gem would be generated from the https://github.com/atp-mipt/jsyntrax and published to rubygems.org whenever you make a new release. If you would like to do that, I can add you as owner to https://rubygems.org/gems/asciidoctor-diagram-jsyntrax after which you will be able to push new versions.

Let's do this. I don't expect new versions of jsyntrax soon, but sooner or later they will appear