RR – Railroad Diagram Generator | Hacker News Reader

RR – Railroad Diagram Generator

github.com

112 pointstempodox41 comments

I like the SQLite railroad diagrams. They are generated with pikchr[1], "a PIC-like markup language for diagrams in technical documentation". See the syntax diagram under examples.

Like many accompanying tools, pikchr comes from the hand of SQLite creater Dr. Richard Hipp (and anyone can guess what that means for the quality of the program).

Now pikchr has become my "goto" tool for professional looking diagrams and sketches of all kinds. With its intuitive syntax grammar it is quick to learn - you should give it a try if not yet done!

[1] https://pikchr.org/home/doc/trunk/homepage.md

Dr. Hipp creates so much great software, and only SQLite gets talked about (Fossil, PtTCL, Lemon are some notable others).

Full exhaustive list is below (though it's missing Fossil):

https://www.hwaci.com/sw/index.html

SQLite diagrams: https://www.sqlite.org/syntaxdiagrams.html

The RR diagrams are images, while the SQLite diagrams are SVG. In my view, SVG is better: it allows copy & paste. SVG would also allow adding links directly in the diagrams, but SQLite doesn't have that (so far).

The diagrams for the H2 database [1], and Apache Jackrabbit Oak [2], do have links. (I wrote the generator for those.)

[1] https://h2database.com/html/grammar.html [2] https://jackrabbit.apache.org/oak/docs/query/grammar-sql2.ht...

Not true. RR produces SVGs.

One major caveat for the SQLite diagrams in particular - they are written by hand, not from the computer-readable parser description.

This means that there are sometimes blatant bugs and ambiguities. Test your AST assumptions against a real SQLite!

There are a few others as well.

Syntax Diagram Generator https://lukaslueg.github.io/macro_railroad_wasm_demo/

GrammKit https://dundalek.com/grammkit/

DrawGrammar https://jacquev6.github.io/DrawGrammar/

There are other kind of text-to-diagram tools which I occasionally find (usually here on HN) and add in this list https://xosh.org/text-to-diagram/

There's a Python one as well: https://github.com/tabatkins/railroad-diagrams

Ps, remember when using svg without a background in a readme that github has multiple themes including dark ones.

Also,

  <style>
    @media (prefers-color-scheme: dark) {
      .line {
        stroke: #eed;
      }
      rect, circle, polygon {
        fill: #eed;
        stroke: #eed;
      }
    }
  </style>

is valid SVG, and would fix the issue.

I work at Materialize, and we’ve used this to power the syntax diagrams in our docs since the very beginning. Example: https://materialize.com/docs/sql/create-source/kafka/

I think it’s a great tool!

CockroachDB uses it as well (and is almost certainly the reason Materialize does): https://www.cockroachlabs.com/blog/efficient-documentation-u...

Nice story: around 2016 the OP project was not yet open source, just a web app. Cockroach Labs wanted to automate using it into their docs build. I asked and was approved to donate a fairly good amount to the author. My argument was that that amount of money, though high, was less than my time to add a few other features we wanted (BNF pre-processing things).

Suspect this was posted in response to https://news.ycombinator.com/item?id=38875551

I'd love to read an article with an overview of libraries like these. There seem to be many and it would be neat to see them compared side-by-side on input syntax, output format, configuration, results, tools used, etc.

As a genuine question, why do (some) people like railroad diagrams? I always found them useless, especially because they are just duals of state transition diagrams and retain the same complexity as the original BNF grammar. In the other words, without a basic understanding of formal grammar, you can't read a railroad diagram nor a BNF anyway. The only possible difference seems to be the initial learning curve, but I doubt that overweighs the required understanding of formal grammar. (I think example-based descriptions would be much better for non-technical people.) But I might be missing something.

Compare the first image in the README to the corresponding section of the "original grammar":

  if_stmt:
      | 'if' named_expression ':' block elif_stmt 
      | 'if' named_expression ':' block [else_block] 
  elif_stmt:
      | 'elif' named_expression ':' block elif_stmt 
      | 'elif' named_expression ':' block [else_block] 
  else_block:
      | 'else' ':' block

Whilst I can read this, I need to jump around to find the definitions of labels, and it requires mental effort to remember how each label was defined. The effort would be greater for a more complex example.

The diagram essentially avoids this by inlining the definitions of `elif_stmt` and `else_block`. This makes it much faster for me to read.

That only means that the railroad diagram is not a direct translation of the original grammar. Conversely, there are more than enough BNF variants that can do the equivalent inlining. I will personally denote your example as:

    if_stmt:
        'if' named_expression ':' block
        ('elif' named_expression ':' block)*
        ('else' ':' block)?

...which is no more complex than the original diagram, and reads much easily at least for me. In fact, that "original grammar" does support the equivalent syntax because it's a direct input to Python's PEG code generator. I don't know why `if_stmt` was described in that way, but such duplication is often done for readability and hardly surprising.

While in the abstract this is true, the physicality of the railroad representation more closely fits what the brain sitting at the computer evolved to comprehend. In other words, its a more intuitive vocabulary for the same language.

I too wondered that, but at least I didn't feel so. In fact a complex enough railroad diagram was worse for me. I particularly didn't like a backward railroad, often seen when the diagram would have been too wide unless wrapped, because it doesn't look different from other forward railroads...

> without a basic understanding of formal grammar, you can't read a railroad diagram nor a BNF anyway

I had no trouble reading the ones in the back of my Pascal book when I was a 16-year-old high school student.

I certainly did not understand formal grammars back then. I didn't even know what a formal language was. (I was using one, but that doesn't mean I understood that I was.)

The understanding can certainly happen without realizing. I guess your first exposure to formal grammar happened to be through a railroad diagram.

I really like them for sql directives and also explaining how regexes work. They’re a useful piece of auxiliary documentation.

Docs look fancier. Well not always [1].

[1]: https://www.freepascal.org/docs-html/ref/ref38x.png

I read railroad diagrams just fine learning Pascal as a 12 year old.

This tool creates the diagrams from the EBNF, which is exactly why I like it. IBM used this technique heavily in mainframe language documentation.

Slightly saddened by lack of usefulness for building model railroads....

I too was expecting the equivalent of a schema builder for model railroad layouts.

Where is the LLM for designing layouts and specifying parts lists ?

"js, the good parts" introduced those diagrams to me and I've always hoped they would show up more.

Well done for finally solving the 14+ year old stack overflow thread

https://stackoverflow.com/questions/796824/tool-for-generati...

"Closed. This question is seeking recommendations for books, tools, software libraries, and more."

I have to say I really detest SO for making this a generic rule. These questions are often top Google results and perhaps all the answers were good 3 year ago but it's missing up to date info because it's locked.

There's a lot of reasons to detest SO. They really seem to optimize around being a place to copy-and-paste snippets of barely-understood code. SO users seem to think of software as witchcraft. It's maddening.

The title reminded me of bidding to Network Rail in UK to help them manage keeping diagrams of the railway up to date showing schematics/not-to-scale with things like: * logical track segment IDs * points * switches/controls for electricity for segments * lights * other key items

This was more about health and safety, being able to schedule maintenance etc and ensure electric rail turned off.

Fascinating to discover that the "current" (HEAD) version of the documents for certain parts of the track were from the original Victorian era (pre-1900) diagrams when things like tunnels were first created!

Fun stuff...

I had visions of factorio from the title. But, this looks like it might be useful in my workday rather than hobby time

I was so excited to find a new tool for creating planning diagrams of model railroad layouts... <sadface>

So this is not about railway trains?

Heh, I have been playing the game "RAILGRADE" recently - and its a cool little train app for making complex rails for supply lines...

It burns the CPU/GPU as its basically alpha- but its fun as heck.

I mentally instantly went there when I saw the post.

https://store.steampowered.com/app/1355090/RAILGRADE/

I can also recommend Transport Fever 2 if "train-centric logistics management game with a model railway aesthetic and precise control over lines and vehicles" appeals to you.

https://store.steampowered.com/app/1066780/Transport_Fever_2...

You are paying my child support after this.

on an IRL note - would you like to purchase a bunch of model train stuff?

(serious Q

You better turn your browser's dark mode off to make sense of the diagrams.

This is a terrific tool I used for documenting a DSL a few years ago. The developer is helpful, too!

Make a native command line wrapper. No one wants to type java -jar

Reply on news.ycombinator.com