[HN Gopher] RR - Railroad Diagram Generator
___________________________________________________________________
RR - Railroad Diagram Generator
Author : tempodox
Score : 93 points
Date : 2024-01-05 09:59 UTC (13 hours ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| Already__Taken wrote:
| "js, the good parts" introduced those diagrams to me and I've
| always hoped they would show up more.
| couchand wrote:
| 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.
| umanwizard wrote:
| 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!
| mjibson wrote:
| 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).
| smartmic wrote:
| 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
| toppy wrote:
| SQLite diagrams: https://www.sqlite.org/syntaxdiagrams.html
| thomasmg wrote:
| 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...
| umanwizard wrote:
| Not true. RR produces SVGs.
| alberth wrote:
| 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
| lifthrasiir wrote:
| 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.
| sixthDot wrote:
| Docs look fancier. Well not always [1].
|
| [1]: https://www.freepascal.org/docs-html/ref/ref38x.png
| exabrial wrote:
| I really like them for sql directives and also explaining how
| regexes work. They're a useful piece of auxiliary
| documentation.
| jamessb wrote:
| 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.
| lifthrasiir wrote:
| 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.
| IIAOPSW wrote:
| 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.
| dtagames wrote:
| This tool creates the diagrams _from_ the EBNF, which is
| exactly why I like it. IBM used this technique heavily in
| mainframe language documentation.
| adrianmonk wrote:
| > _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.)
| TechPlasma wrote:
| Slightly saddened by lack of usefulness for building model
| railroads....
| unpixer wrote:
| I too was expecting the equivalent of a schema builder for
| model railroad layouts.
| euroderf wrote:
| Where is the LLM for designing layouts and specifying parts
| lists ?
| justinl33 wrote:
| Well done for finally solving the 14+ year old stack overflow
| thread
|
| https://stackoverflow.com/questions/796824/tool-for-generati...
| ranting-moth wrote:
| "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 wrote:
| 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.
| smusamashah wrote:
| 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/
| mihaitodor wrote:
| There's a Python one as well:
| https://github.com/tabatkins/railroad-diagrams
| dtagames wrote:
| This is a terrific tool I used for documenting a DSL a few years
| ago. The developer is helpful, too!
| eastern wrote:
| So this is not about railway trains?
| samstave wrote:
| 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/
| papertokyo wrote:
| 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.
| ..
| samstave wrote:
| 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
| rwoerz wrote:
| You better turn your browser's dark mode off to make sense of the
| diagrams.
| archsurface wrote:
| Ps, remember when using svg without a background in a readme that
| github has multiple themes including dark ones.
| mminer237 wrote:
| 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.
| throwitaway222 wrote:
| Make a native command line wrapper. No one wants to type java
| -jar
| robaato wrote:
| 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...
| Sleaker wrote:
| I had visions of factorio from the title. But, this looks like it
| might be useful in my workday rather than hobby time
| sib wrote:
| I was so excited to find a new tool for creating planning
| diagrams of model railroad layouts... <sadface>
___________________________________________________________________
(page generated 2024-01-05 23:01 UTC)