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!
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.)
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).
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.
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:
...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.)
"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!
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.
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