5 ms·
RR – Railroad Diagram Generator
- Already__Taken 3y ago"js, the good parts" introduced those diagrams to me and I've always hoped they would show up more.
- couchand 3y agoSuspect this was posted in response to https://news.ycombinator.com/item?id=38875551 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.
- School-Cotton 3y agoI 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/ https://materialize.com/docs/sql/create-source/kafka/ I think it’s a great tool!
- mjibson 3y agoCockroachDB uses it as well (and is almost certainly the reason Materialize does): https://www.cockroachlabs.com/blog/efficient-documentation-using-sql-grammar-diagrams/ 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).
- smartmic 3y agoI 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 https://pikchr.org/home/doc/trunk/homepage.md
- toppy 3y agoSQLite diagrams: https://www.sqlite.org/syntaxdiagrams.html https://www.sqlite.org/syntaxdiagrams.html
- thomasmg 3y agoThe 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 https://h2database.com/html/grammar.html [2] https://jackrabbit.apache.org/oak/docs/query/grammar-sql2.html https://jackrabbit.apache.org/oak/docs/query/grammar-sql2.ht...
- School-Cotton 3y agoNot true. RR produces SVGs.
- o11c 3y agoOne 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!
- deleted 3y ago[deleted]
- alberth 3y agoDr. 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 https://www.hwaci.com/sw/index.html
- lifthrasiir 3y agoAs 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.
- deterministic 3y agoI read railroad diagrams just fine learning Pascal as a 12 year old.
- sixthDot 3y agoDocs look fancier. Well not always [1]. [1]: https://www.freepascal.org/docs-html/ref/ref38x.png https://www.freepascal.org/docs-html/ref/ref38x.png
- exabrial 3y agoI really like them for sql directives and also explaining how regexes work. They’re a useful piece of auxiliary documentation.
- jamessb 3y agoCompare 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.
- 3y ago
- TechPlasma 3y agoSlightly saddened by lack of usefulness for building model railroads....
- justinl33 3y agoWell done for finally solving the 14+ year old stack overflow thread https://stackoverflow.com/questions/796824/tool-for-generating-railroad-diagram-used-on-json-org https://stackoverflow.com/questions/796824/tool-for-generati...
- ranting-moth 3y ago"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.
- bigfishrunning 3y agoThere'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.
- smusamashah 3y agoThere are a few others as well. Syntax Diagram Generator https://lukaslueg.github.io/macro_railroad_wasm_demo/ https://lukaslueg.github.io/macro_railroad_wasm_demo/ GrammKit https://dundalek.com/grammkit/ https://dundalek.com/grammkit/ DrawGrammar https://jacquev6.github.io/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/ https://xosh.org/text-to-diagram/
- mihaitodor 3y agoThere's a Python one as well: https://github.com/tabatkins/railroad-diagrams https://github.com/tabatkins/railroad-diagrams
- dtagames 3y agoThis is a terrific tool I used for documenting a DSL a few years ago. The developer is helpful, too!
- eastern 3y agoSo this is not about railway trains?
- samstave 3y agoHeh, 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/ https://store.steampowered.com/app/1355090/RAILGRADE/
- papertokyo 3y agoI 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/ https://store.steampowered.com/app/1066780/Transport_Fever_2...
- samstave 3y agoYou are paying my child support after this. on an IRL note - would you like to purchase a bunch of model train stuff? (serious Q
- rwoerz 3y agoYou better turn your browser's dark mode off to make sense of the diagrams.
- archsurface 3y agoPs, remember when using svg without a background in a readme that github has multiple themes including dark ones.
- mminer237 3y agoAlso, <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.
- throwitaway222 3y agoMake a native command line wrapper. No one wants to type java -jar
- robaato 3y agoThe 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...
- Sleaker 3y agoI had visions of factorio from the title. But, this looks like it might be useful in my workday rather than hobby time
- sib 3y agoI was so excited to find a new tool for creating planning diagrams of model railroad layouts... <sadface>