Hacker News Reader

Comment by lifthrasiir | Hacker News Reader

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.

View on HN

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.

Reply on news.ycombinator.com