Add support for Railroad diagrams about kroki HOT 32 OPEN

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

from kroki.

FYI recent versions of PlantUML are able to generate railroad diagrams and this is already available in Kroki.

from kroki.

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.

from kroki.

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.

from kroki.

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.

from kroki.

@bannmann oh wow! you are on fire 🔥

from kroki.

@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>

from kroki.

Just learned about https://github.com/dundalek/GrammKit which seems interesting!

from kroki.

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')
}

from kroki.

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

from kroki.

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 👍
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.

from kroki.

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

from kroki.

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.

from kroki.

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.

from kroki.

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 :)

from kroki.

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

from kroki.

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

Hopefully, your changes will get merged soon!

from kroki.

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.

from kroki.

So, which one?

• Railroad-diagram Generator
• JSyntrax
• Syntrax
• RR

from kroki.

I agree RR seems to be the best choice here but the maintainer didn't merge GuntherRademacher/rr#14 yet.

from kroki.

Right, I see the problem.

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

from kroki.

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

from kroki.

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.

from kroki.

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

from kroki.

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

from kroki.

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.

from kroki.

Update: the release is on Central.

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

from kroki.

@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.

from kroki.

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.

from kroki.

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

from kroki.

@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.

from kroki.

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

from kroki.