Consider removing "Block Grammar" documentation page

[ndiego]

What problem does this address?

The Block Grammar doc in the Block Editor Handbook contains code examples without any context. It's unclear what the doc is trying to convey, and it also has not been meaningfully updated since it was written in 2018.

What is your proposed solution?

In the interest of reducing the maintenance burden of the Block Editor Handbook and ensuring all pages are up-to-date and accurate, I recommend we remove this page.

However, if folks feel it is valuable, the page will need to be updated with a proper description and explanations for each code example. I am happy to create this PR, given the necessary direction.

As the original author @mcsf, I would love your insight here. Thanks! 🙏

[mcsf]

Hey, @ndiego.

The Block Grammar doc in the Block Editor Handbook contains code examples without any context. It's unclear what the doc is trying to convey, and it also has not been meaningfully updated since it was written in 2018.

I agree that it isn't clear at all, but for the record these aren't code examples :). They are production rules for Gutenberg's block-parsing grammar [Wikipedia]. The first rule represents what the parser is trying to parse: a list of blocks formatted with our special <!-- wp: syntax. All other rules are ultimately contained within the Block_List rule. This documentation page is automatically generated from our spec grammar.

This addition made sense back in 2018 when a few of us were looking for more performant parser implementations for Gutenberg: the document would act as a specification to which any contender would have to conform.

For additional context, see Overview of short-term parsing enhancements. Ultimately, we settled on a hand-coded parser in #8083. There hasn't been any need to further improve Gutenberg's parsing stack since then, so this page has long fulfilled this purpose and we can remove it. 👍

[ndiego]

Awesome, thanks for the clarification and the historical context. I will create a PR for removal. 💪

[dmsnell]

it also has not been meaningfully updated since it was written in 2018.

sometimes software is finished 😉