Add Railroad Diagrams Support
tajmone opened this issue · comments
I was looking into the various diagram tools supported by PP, and it seems that none of them allows creation of Railroad Diagrams like these:
I've tried to search for some libraries that can handle creating Railroad Diagrams images from plain text, and found these, which seems good candidates:
- https://github.com/tabatkins/railroad-diagrams (Node.js or Python)
- https://github.com/Chrriis/RRDiagram (Java)
Ideally, it would great if there was an Haskell library (or some bindable binary) that could be integrated directly in PP, without requiring external dependencies (or installing languages).
If I have understood correctly, PlantUML is integrated into PP even though is in Java (I've notice reference to .stack-work/PlantumlJar_c.c in the pp.cabal source file). Is it done via a C wrapper, or is it a different PlantUML binary version altogether?
Could the RRDiagram Java library (mentioned above) be integrated natively into PP?
What do you think about it? is this type of diagrams worth of being built into PP? or should it rely on some external tool?
Do you have some suggestions for Railroad Diagrams CLI tools or scripts?
I find railroad diagrams very useful, especially to visualize regular expressions — examples:
... and possibly they might be quite useful, in general, in the context of coding-documentation.
Interesting idea. I'm quite busy now but I'll try to integrate it.
If I have understood correctly, PlantUML is integrated into PP even though is in Java (I've notice reference to .stack-work/PlantumlJar_c.c in the pp.cabal source file). Is it done via a C wrapper, or is it a different PlantUML binary version altogether?
plantuml.jar is in the pp executable. It's just a binary blob copied to /tmp and called as an external command. No clever C wrapper ;-)
Ideally, it would great if there was an Haskell library (or some bindable binary) that could be integrated directly in PP, without requiring external dependencies (or installing languages).
There is a Haskell package that generates syntax diagrams: https://hackage.haskell.org/package/Ebnf2ps-1.0.11 (https://github.com/FranklinChen/Ebnf2ps/blob/master/doc/doc.pdf)
I'm looking at Ebnf2ps, very interesting and well documented. Pity that it only outputs EPS and FIG format images — these are both excellent formats for TeX/LaTeX documents, but for HTML-based docs formats like SVG, PNG and GIF would be more indicated.
EPS can be converted to PNG with imagemagick (which pp already uses for Asymptote images).
It reminds me that I forgot to add imagemagick (convert) to the prerequisite list.
Great choice!
I love ImageMagick and always have it up-to-date on my system via the Chocholatey package.
Chances are that anyone working with big PP/pandoc projects will also have ImageMagick on the system, or will be more than happy to install it.
I have some trouble to integrate Ebnf2ps to pp and it has some font dependencies that make it not so portable. I think with have to find a different syntax diagram generator.
What about the originally proposed RRDiagram (Java)?
I don't find any binary jar file usable on the command line. It seems to be a Java library. Generating diagrams would require to write a java program and run it.
I carried out some more searches, but haven't found any other binary CLI tools, just GUI tools or scripts.
This seems to leave only the tabatkins' railroad-diagrams, which is avialbe as Node.js or Python, but this hasn't got a CLI interface either. Also, it's probably better to leave interfacing with Node.js and Python to end users, as these libs and languages might evolve fast in backward incompatible manners, and introduce a burder in the maintainance of PP.
I'll be further looking around for some CLI binary solutions, and if I find anything I'll update this thread.
I've looked at it but it doesn't seem to support railroad diagrams natively.
Did you have in mind to leverage this tool but using some PP-native Haskell code to make the railroad diagrams?
Sadly I have nothing in mind (and no time as well currently).
I'm confident that in the future, at some point, a dedicated railroad diagrams library will appear that could be used natively by PP. Maybe is worth waiting for the right tool, after all it's not an essential feature — although a highly desirable one.
For the time being, shell script interfacing to locally installed tools might fill the gap, and if in the future this feature becomes implemented natively it's always possible to switch to it; on the other hand, switching a native implemented tools would be problematic for backward compatibility.
So, unless adding support for blockdiag would bring other benefits too, independently of railroad diagrams, we could just wait and keep an eye open for new tools.
What do you think?
Sorry for the late reply... Please keep in mind that pp is not supported anymore, it's hard to deploy. For new projects I suggest ypp which is is based on a Lua interpreter and way easier to compile and install and binaries are easier to produce (thanks to zig) and deploy (see hey).
ypp has some preconfigured image generators (like pp) and other generators can easily be added, it's just a matter of passing the right shell command.