Syntax Diagrams - Githubissues

rust-lang / reference

The Rust Reference

https://doc.rust-lang.org/nightly/reference/

Apache License 2.0

1.22k stars 475 forks source link

Syntax Diagrams #398

Open Havvy opened 6 years ago

Havvy commented 6 years ago

A project was made to create syntax diagrams out of macro_rules!. This has reminded me how useful they were for me learning JavaScript (specifically "The Good Parts") and I feel like we should have them alongside the BNF descriptions of the grammar in the reference.

I do not have a plan to actually realize this.

ehuss commented 6 years ago

Someone created a tool to generate railroad diagrams for the rust grammar here: https://github.com/willy610/bnf2railroad

He mentioned it in rust-lang/rust#30942, but I haven't seen any recent activity.

lukaslueg commented 6 years ago

macro_railroad upstream here. The underlying library has a small DSL to create syntax diagrams (demonstrated here). A simple solution would be to transfer the EBNF to this DSL (some patching would be required, nothing too complex) and use that to (re-) generate diagrams. A slightly advanced approach would be to create a parser for the official ebnf notation and use the grammar directly (the parser in bnf2railroad seems worthy of a rewrite afaics).

Thoughts?

lukaslueg commented 6 years ago

I've just added two examples (rust_00_comments_diagram.txt and rust_04_macro_rules_diagram.txt) to the demo-page to demonstrate what I would look like. One can tinker with the CSS obviously.

Havvy commented 6 years ago

I don't have too much time to tinker with this right now. The main requirements for a first pass I have for this are:

Looks decent enough in the four themes. Doesn't have to match the themes in the first pass, but cannot clash either.
Instructions for creating and updating the syntax diagrams should be available in contributing.md
They should match what is in the reference. We do a few hacks in the reference for clarity for the reader. We also spread it across multiple pages right now.
They should be easy to update once created.
We only need one or two pages to start with, and then we can open a tracking issue for the rest.

Also, we should not create railroad diagrams that are just a long switch statement of simple things like rust_03_keywords_diagram.txt, since the BNF is just as readable for that, and they get really long.

If you or anybody else wants to tackle that, I would be ecstatic.

lukaslueg commented 6 years ago

If you were to use railroad, keep in mind that it generates SVGs, which current browsers support with all Ts crossed and all Is dotted. Older browsers may fail to render them properly, though,

Havvy commented 6 years ago

I don't remember what our browser support story is like, but we can re-render the SVGs as PNGs if necessary.