Railroad Diagrams: a few questions

#1

I’m a big fan of the syntax diagrams generated by the RailroadDiagram plugin. But I would actually like to use them in a non-TW environment. So I will probably need an export, or an alternative way to invoke the tool. I could definitely hack this together easily enough with Developer Tools Inspect -> copy -> paste-to-file -> save. But I’m wondering about doing this in a somewhat robust way.

This leads me to several questions:

  • Does anyone have experience doing this? I usually run TW in Node, so I have the Node commands at my disposal, and might be able to do something with a static build, but I haven’t yet looked into it.

  • Is there any licensing concern? The plugin does not list its own license; does that mean its available in the same permissive license (BSD 3-clause) that TW itself uses?

  • This is a major upgrade to the tool on which which it’s based, providing links, transclusions, and, I think, a brand new syntax with its own parser. (AFAICT, the original only supplies an Abstract-syntax-tree style text input.) Has anyone already extracted these features into a stand-alone version?

#2

I think, you should use the current library, which has completely changed, since it was included into TW.

There have been some changes to the original library, to work with TW. As you wrote, there is a completely different syntax. It’s more like a TW filter syntax.

Using the original library will be much less work. The TW port will only work with TW.

#3

Maybe I misunderstood the history. But what I want is the diagram syntax that TW uses. I’m a big fan of Mermaid and similar diagramming tools. As I read the underlying library, an example would be something like, in a LISP-y syntax:

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

image


I would definitely prefer something like this:

["+"]
( name-start-char | escape )
[{ :( :name-char | escape ) }]

image

Don’t get me wrong. I love LISP. But here syntax matters, and I would definitely prefer to maintain the latter. (I’m not worried about color schemes yet. I like the look of both outputs.)

Or am I missing things? Is that syntax available in Tab Atkins’ library?

#4

No.

  • There is a wrapper.js, which contains the railroad-widget implementation.
  • parser.js contains the “parsetree-like” implementation
  • components.js contains the “widget-tree-like” implementation

You could probably use “parser.js”, which requires “components.js” as a dependency, stand alone.

The interface to render TW railroad syntax into SVG can be found at: TiddlyWiki5/plugins/tiddlywiki/railroad/wrapper.js at b90c3841c97c5d2f90fbee6b6641fcc91a187126 · Jermolene/TiddlyWiki5 · GitHub

wrapper.js is TW specific. The rest should be independent. – But I do not really know how everything exactly works.

#5

Ok, that’s what I thought, looking at it, but I wasn’t around for the development of this. I was wondering if I missed anything.

I had looked over these two. Do you know if parser is hand-crafted, or was it built from some yacc- or peg-style tool?

I’ll take a look. I hadn’t investigated that one yet.

Thank you very much for your insight!

(Do you have any insight into the licensing? Are those core plugins without their own licenses just governed by the main TW license? Or is there something more complex happening?)

1 Like
#6

The current railroad-library is MIT-licensed

The library TW used is CC0 as shown in the source code – The library implementation is 10 years old atm.

TW plugins are BSD 3-clause as defined in the TW CLA

#7

Thank you again @pmario. Was the second link supposed to be the same as the third one, to the CLA? But either way, that link covers what I need. I don’t know if I’ll spend any time on this – the process of extracting the generated SVG using the developers’ console and pasting in a stylesheet is not onerous – but I think I have all the pieces I will need if I do so.

Thanks for all the help!

#8

No. Fixed it to the right target in the source