Add support for Railroad diagrams

[ggrossetie]

https://github.com/tabatkins/railroad-diagrams

[ggrossetie]

One major issue with https://github.com/tabatkins/railroad-diagrams is that the library is using eval because the diagram is defined as JavaScript code.

For instance:

Diagram(Optional('+', 'skip'),
  Choice(0,
    NonTerminal('name-start char'),
    NonTerminal('escape')),
  ZeroOrMore(
    Choice(0,
      NonTerminal('name char'),
      NonTerminal('escape'))))

But using eval is dangerous and can be abused:

while(true) {
  alert('hello')
}

[mikitex70]

It seems that now there is a Python implementation. Maybe this Java implementation is more simple to adopt.

[ggrossetie]

As far as I understand the Python implementation uses the same approach, you need a Python runtime. So again, you need to evaluate unsafe Python code.

Maybe this Java implementation is more simple to adopt.

Thanks for the link :+1: It seems that they are using a grammar so it should be safe to run on the server side. My concern is that this project seems a bit stale...

I will play with it, and see if it fits.

[cben]

https://github.com/GuntherRademacher/rr parses EBNF, which is really near-ideal for this kind of diagrams.
live demo: https://bottlecaps.de/rr/ui

[ggrossetie]

GuntherRademacher/rr looks interesting, thanks for the link @cben 👍

[lorrden]

The tool by Gunther would be a very nice addition. I am documenting the grammar of a language, so from my perspective it would be advantageous to be able to produce both the W3C BNF and the diagrams from the same source.

RR currently generates HTML with embedded SVGs, or a zip-file with a HTML document with PNGs. I suppose that the model does not fit well into neither kroki, nor Asciidoctor-diagram.

[ggrossetie]

RR currently generates HTML with embedded SVGs, or a zip-file with a HTML document with PNGs. I suppose that the model does not fit well into neither kroki, nor Asciidoctor-diagram.

Indeed. Also, it seems that the jar is not published on a repository (Maven central, bintray, GitHub...). I had a quick look at the code and it would require some work to extract the convert/render logic.

Thanks for opening an issue, let's see if Gunther is willing to make some changes to ease integration with other tools.

[chtenb]

I just stumbled upon this tool: https://github.com/Chrriis/rrdiagram-js

Seems like that would be easier to integrate. I'm not sure how it compares to the other one feature-wise.

One big advantage https://github.com/tabatkins/railroad-diagrams has over the other two is that it gives control over the css classes attached with individual elements. This gives great control over how the diagram is rendered in the end result.

I think what we really want is a version of https://github.com/tabatkins/railroad-diagrams that doesn't use eval :)

[chtenb]

There are also several scripts going around that transform some DSL into an rr diagram. So under the hood it still uses rrdiagram and thus eval, but at least you're not directly writing javascript code.

Example from the author himself: https://github.com/tabatkins/bikeshed/blob/master/bikeshed/railroadparser.py

[bannmann]

it seems that the jar is not published on a repository (Maven central, bintray, GitHub...). I had a quick look at the code and it would require some work to extract the convert/render logic.

For a project unrelated to kroki, I started working on both. I already got GuntherRademacher/rr/pull/12 merged which adds the ability to push to a local Maven repo, and have submitted GuntherRademacher/rr/pull/14 which makes the generation code reusable. If/when that is merged, I'll submit a PR to publish RR to Maven Central.

[ggrossetie]

That's awesome! 👏🏻 Thanks for keeping us informed.

Hopefully, your changes will get merged soon!

[kukimik]

Just letting you know that there is a nice utility written in Haskell that generates beautiful railroad diagrams (and is at least 27 years old!): https://github.com/FranklinChen/Ebnf2ps. However, out of the box it can only produce EPS and FIG files. Regarding the input format, it supports EBNF specifications and yacc, bison, and Happy input grammars.

I suppose this won't be used, but if wrapped in some converters (eps -> svg/png/pdf), in theory it could do the job.

[Airkro]

So, which one?

• Railroad-diagram Generator
• JSyntrax
• Syntrax
• RR

[RayOffiah]

I would vote for RR because it supports EBNF notation, which we already use all over out site.

I think the others use a Python-based syntax which might be a bit too programmery.

[ggrossetie]

I agree RR seems to be the best choice here but the maintainer didn't merge https://github.com/GuntherRademacher/rr/pull/14 yet.

[RayOffiah]

Right, I see the problem.

Just a matter of 'wait and see' then, I think.

[Airkro]

Maybe Kroki can integrate other tools when waiting for the RR. Kroki already supports a lot of tools with similar purposes.

[chtenb]

We can always fork (temporarily). A year of waiting is a long time, and there is still no saying when the PR will be merged.

[RayOffiah]

I'm not sure of the protocol for this sort of thing, but a temporary fork might be an idea.

[bannmann]

I support the idea of a temporary fork and could help with getting it onto the Central repository (so it can be used easily by Maven and Gradle builds). If you want me to, I would even make the fork and "own" the respective new artifact coordinates, but all that would have to wait until next week or the week after.

[RayOffiah]

Yup, I reckon it’s okay to fork it now.

[bannmann]

I now have created my fork, renamed everything so that Gunther's project name is not "squatted", and integrated the GuntherRademacher/rr#14 PR. The result lives at https://github.com/bannmann/trako.

The initial release was submitted to OSSRH and will therefore appear on Maven Central, but there's some sync lag on their side.

As I wrote in my PR at the time, the Java API does not yet allow customizing the way files are written to disk. I have some ideas on this, but we should discuss specifics based on kroki's requirements. How about one of you guys opening an issue over at trako? That way, this issue here could concentrate on the kroki side.

[bannmann]

Update: the release is on Central.

<dependency>
    <groupId>com.github.bannmann.trako</groupId>
    <artifactId>trako</artifactId>
    <version>0.1</version>
</dependency>

[ggrossetie]

@bannmann Thanks!

As I wrote in my PR at the time, the Java API does not yet allow customizing the way files are written to disk.

I need to give it a try but it seems that we can pass an OutputStream to the Generator: https://github.com/bannmann/trako/blob/develop/src/main/java/com/github/bannmann/trako/core/TrakoGenerator.java#L150-L153

So, I think we have everything we need.

[bannmann]

I need to give it a try but it seems that we can pass an OutputStream to the Generator

Yes, but there is no OutputType yet that will send a single image - it's either a (XHTML or Markdown) document with embedded SVG or a zip file containing HTML and PNG files.

[ggrossetie]

@bannmann Do you need help to implement a SVG and/org PNG OutputType? Do you plan to contribute https://github.com/GuntherRademacher/rr/issues/5 upstream since your first pull request (https://github.com/GuntherRademacher/rr/pull/14) was merged?

[bannmann]

@Mogztter Although I would be interested in having GuntherRademacher/rr#5 as well, the project where I would use it is kind of on the back burner for the next few months due to other projects.

However, I'm thrilled that the reusable API (GuntherRademacher/rr#14) was merged, and plan to finish that job by creating a PR that allows pushing RR to Maven Central! As that's considerably less work, I expect to get around to it in the next few weeks. Hope that helps.

[bannmann]

@Mogztter, I have submitted the PR mentioned above as GuntherRademacher/rr#22.

[ggrossetie]

@bannmann oh wow! you are on fire 🔥

[bannmann]

@Mogztter: Gunther merged the PR and published the first release. 🎉

<dependency>
    <groupId>de.bottlecaps.rr</groupId>
    <artifactId>rr-lib</artifactId>
    <version>1.67</version>
</dependency>